团队城-mcp

Name: 团队城-mcp
Author: itcaat

作者：itcaat9 星标更新：2025-09-30

安装使用来源：spider==github.com

项目介绍

TeamCity MCP Server

一个全面的模型上下文协议（MCP）服务器，将JetBrains TeamCity作为结构化的AI准备资源和工具提供给LLM代理和IDE插件。

快速开始

IDE集成（Cursor）

TeamCity MCP服务器旨在与像Cursor这样的AI驱动IDE无缝协作。以下是配置方法：

Cursor配置

在你的Cursor MCP设置中添加以下内容：

{
  "mcpServers": {
      "teamcity": {
        "command": "docker",
        "args": [
          "run",
          "--rm",
          "-i",
          "-e",
          "TC_URL",
          "-e",
          "TC_TOKEN",
          "itcaat/teamcity-mcp:latest",
          "--transport",
          "stdio"
        ],
        "env": {
          "TC_URL": "https://your-teamcity-server.com",
          "TC_TOKEN": "your-teamcity-api-token"
        }
      }
    }
}

本地开发

1. 构建服务器

make build
# 这会创建 ./bin/teamcity-mcp 和符号链接 ./server

2. 设置环境变量

# 必需
export TC_URL="https://your-teamcity-server.com"

# 可选（启用HMAC认证）
export SERVER_SECRET="your-hmac-secret-key"

# 认证
export TC_TOKEN="your-teamcity-api-token"

3. 运行服务器

./server
# 默认情况下，服务器将在 :8123 启动

4. 测试服务器

# 健康检查
curl http://localhost:8123/healthz

# MCP协议测试
curl -X POST http://localhost:8123/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-hmac-secret-key" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{}}}'

预期结果：健康检查端点应返回 {"status":"ok"}，而MCP端点应返回初始化响应。

功能

MCP协议兼容性：完整的JSON-RPC 2.0通过HTTP/WebSocket支持
TeamCity集成：完全的REST API集成并带有认证
资源访问：项目、构建类型、构建、代理和制品
构建操作：触发、取消、固定构建、设置标签、下载制品、搜索构建
高级搜索：带有多个过滤器的综合构建搜索（状态、分支、用户、日期、标签）
生产就绪：Docker、Kubernetes、监控、缓存和全面的日志记录
基于环境的配置：无需配置文件，一切通过环境变量进行
AI时间感知：提供真实的当前日期和时间，防止AI模型使用训练数据中的日期

环境变量参考

必需变量

变量	描述	示例
`TC_URL`	TeamCity服务器URL	`https://teamcity.company.com`
`SERVER_SECRET`	客户端认证的HMAC密钥（可选）	`my-secure-secret-123`

认证变量

变量	描述	示例
`TC_TOKEN`	TeamCity API令牌	`eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...`

可选变量

变量	默认值	描述	示例
`LISTEN_ADDR`	`:8123`	服务器监听地址	`:8080` 或 `0.0.0.0:8123`
`TC_TIMEOUT`	`30s`	TeamCity API超时	`60s` 或 `2m`
`TLS_CERT`		到TLS证书的路径	`/path/to/cert.pem`
`TLS_KEY`		到TLS私钥的路径	`/path/to/key.pem`
`LOG_LEVEL`	`info`	日志级别	`debug`, `info`, `warn`, `error`
`LOG_FORMAT`	`json`	日志格式	`json` 或 `console`
`CACHE_TTL`	`10s`	API响应的缓存TTL	`30s` 或 `1m`

配置示例

开发环境

export TC_URL=http://localhost:8111
export TC_TOKEN=dev-token-123
export SERVER_SECRET=dev-secret
export LOG_LEVEL=debug
export LOG_FORMAT=console
./server

生产环境

export TC_URL=https://teamcity.company.com
export TC_TOKEN=$TEAMCITY_API_TOKEN
export SERVER_SECRET=$MCP_SERVER_SECRET
export TLS_CERT=/etc/ssl/certs/teamcity-mcp.pem
export TLS_KEY=/etc/ssl/private/teamcity-mcp.key
export LOG_LEVEL=warn
export CACHE_TTL=30s
./server

Docker部署

构建和运行

# 构建Docker镜像
make docker

# 使用环境变量运行
docker run -p 8123:8123 \
  -e TC_URL=https://teamcity.company.com \
  -e TC_TOKEN=your-token \
  -e SERVER_SECRET=your-secret \
  teamcity-mcp:latest

Docker Compose

# 使用docker-compose启动
docker-compose up -d

# 查看日志
docker-compose logs -f teamcity-mcp

Kubernetes部署

使用Helm

# 使用Helm部署
helm install teamcity-mcp ./helm/teamcity-mcp \
  --set teamcity.url=https://teamcity.company.com \
  --set secrets.teamcityToken=your-token \
  --set secrets.serverSecret=your-secret

手动Kubernetes部署

apiVersion: v1
kind: Secret
metadata:
  name: teamcity-mcp-secrets
type: Opaque
stringData:
  teamcity-token: "your-teamcity-token"
  server-secret: "your-server-secret"
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: teamcity-mcp
spec:
  replicas: 1
  selector:
    matchLabels:
      app: teamcity-mcp
  template:
    metadata:
      labels:
        app: teamcity-mcp
    spec:
      containers:
      - name: teamcity-mcp
        image: teamcity-mcp:latest
        ports:
        - containerPort: 8123
        env:
        - name: TC_URL
          value: "https://teamcity.company.com"
        - name: TC_TOKEN
          valueFrom:
            secretKeyRef:
              name: teamcity-mcp-secrets
              key: teamcity-token
        - name: SERVER_SECRET
          valueFrom:
            secretKeyRef:
              name: teamcity-mcp-secrets
              key: server-secret

命令行选项

标志	描述	默认值
`--help`	显示环境变量帮助
`--version`	显示版本信息
`--transport`	传输模式：http或stdio	`http`

帮助和文档

# 显示环境变量帮助
./server --help

# 显示版本
./server --version

# 显示命令行用法
./server -h

测试和验证

自动验证

使用包含的验证脚本测试所有功能：

# 运行所有测试
./scripts/verify.sh

# 可用选项：
./scripts/verify.sh help     # 显示帮助
./scripts/verify.sh start    # 仅启动服务器
./scripts/verify.sh stop     # 仅停止服务器
./scripts/verify.sh clean    # 清理进程

手动测试

# 1. 设置环境变量
export TC_URL=http://localhost:8111
export TC_TOKEN=test-token
export SERVER_SECRET=test-secret

# 2. 启动服务器
./server &

# 3. 测试健康状况
curl http://localhost:8123/healthz

# 4. 测试MCP协议
curl -X POST http://localhost:8123/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer test-secret" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{}}}'

# 5. 停止服务器
pkill -f teamcity-mcp

开发测试

# 安装依赖项
make deps

# 运行单元测试
make test

# 运行集成测试
make test-integration

# 运行负载测试
make test-load

# 运行代码检查
make lint

# 格式化代码
make format

# 清理构建工件
make clean

可用Make命令

使用make help查看所有可用命令：

# 基本命令
make build                # 构建二进制文件
make test                 # 运行测试
make clean                # 清理构建工件
make deps                 # 下载依赖项
make lint                 # 运行代码检查
make format               # 格式化代码

# Docker命令
make docker               # 构建Docker镜像
make docker-push          # 推送Docker镜像

# 运行命令
make run                  # 运行应用程序
make run-stdio            # 在STDIO模式下运行
make dev                  # 在开发模式下运行，带热重载

# Docker Compose命令
make compose-up           # 使用Docker Compose启动服务
make compose-down         # 停止服务
make compose-logs         # 显示日志

# 测试命令
make test-integration     # 使用Docker运行集成测试
make test-load            # 运行负载测试

# 开发工具
make install-tools        # 安装开发工具

# 发布命令
make release-snapshot     # 使用GoReleaser构建快照发布
make release-check        # 检查GoReleaser配置

# CI命令
make ci                   # 运行CI检查（依赖项、代码检查、测试、构建）
make check                # 运行所有检查（代码检查、测试、构建）

MCP协议测试

初始化MCP会话

curl -X POST http://localhost:8123/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": {
        "name": "test-client",
        "version": "1.0.0"
      }
    }
  }'

列出资源

curl -X POST http://localhost:8123/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "resources/list",
    "params": {}
  }'

列出工具

curl -X POST http://localhost:8123/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret" \
  -d '{
    "jsonrpc": "2.0",
    "id":  3,
    "method": "tools/list",
    "params": {}
  }'

可用工具

TeamCity MCP服务器提供了9个强大的工具来管理构建：

1. 触发构建

触发TeamCity的新构建。

参数：

buildTypeId（必需）：构建配置ID
branchName（可选）：要构建的分支名称
properties（可选）：构建属性对象

示例：

curl -X POST http://localhost:8123/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "trigger_build",
      "arguments": {
        "buildTypeId": "YourProject_BuildConfiguration",
        "branchName": "main",
        "properties": {
          "env.DEPLOY_ENV": "staging"
        }
      }
    }
  }'

2. 取消构建

取消正在运行的构建。

参数：

buildId（必需）：要取消的构建ID
comment（可选）：取消评论

示例：

curl -X POST http://localhost:8123/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret" \
  -d '{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "tools/call",
    "params": {
      "name": "cancel_build",
      "arguments": {
        "buildId": "12345",
        "comment": "由于紧急修复取消"
      }
    }
  }'

3. 固定构建

固定或解除固定构建以防止其被清理。

参数：

buildId（必需）：要固定或解除固定的构建ID
pin（必需）：true表示固定，false表示解除固定
comment（可选）：固定评论

示例：

curl -X POST http://localhost:8123/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret" \
  -d '{
    "jsonrpc": "2.0",
    "id": 6,
    "method": "tools/call",
    "params": {
      "name": "pin_build",
      "arguments": {
        "buildId": "12345",
        "pin": true,
        "comment": "候选发布构建"
      }
    }
  }'

4. 设置构建标签

向构建添加或移除标签。

参数：

buildId（必需）：构建ID
tags（可选）：要添加的标签数组
removeTags（可选）：要移除的标签数组

示例：

curl -X POST http://localhost:8123/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret" \
  -d '{
    "jsonrpc": "2.0",
    "id": 7,
    "method": "tools/call",
    "params": {
      "name": "set_build_tag",
      "arguments": {
        "buildId": "12345",
        "tags": ["release", "v1.2.3"],
        "removeTags": ["beta"]
      }
    }
  }'

5. 下载制品

下载构建制品。

参数：

buildId（必需）：构建ID
artifactPath（必需）：到制品的路径

示例：

curl -X POST http://localhost:8123/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret" \
  -d '{
    "jsonrpc": "2.0",
    "id": 8,
    "method": "tools/call",
    "params": {
      "name": "download_artifact",
      "arguments": {
        "buildId": "12345",
        "artifactPath": "dist/app.zip"
      }
    }
  }'

6. 搜索构建

使用综合筛选选项搜索构建。

参数（全部可选）：

buildTypeId：按构建配置ID筛选
status：按构建状态筛选（SUCCESS, FAILURE, ERROR, UNKNOWN）
state：按构建状态筛选（queued, running, finished）
branch：按分支名称筛选
agent：按代理名称筛选
user：按触发构建的用户筛选
sinceBuild：从这个构建ID开始搜索构建
sinceDate：从这个日期开始搜索构建（YYYYMMDDTHHMMSS+HHMM）
untilDate：到这个日期为止搜索构建（YYYYMMDDTHHMMSS+HHMM）
tags：按标签筛选的数组
personal：是否包括个人构建（布尔值）
pinned：按固定状态筛选（布尔值）
count：要返回的最大构建数（1-1000，默认：100）

示例：

搜索失败的构建：

curl -X POST http://localhost:8123/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret" \
  -d '{
    "jsonrpc": "2.0",
    "id": 9,
    "method": "tools/call",
    "params": {
      "name": "search_builds",
      "arguments": {
        "status": "FAILURE",
        "count": 10
      }
    }
  }'

搜索主分支上的最近构建：

curl -X POST http://localhost:8123/mcp \