Teamcity MCP

🚀 TeamCity MCP 服務器

TeamCity MCP 服務器是一個全面的模型上下文協議（MCP）服務器，它將 JetBrains TeamCity 作為結構化的、適用於大語言模型（LLM）代理和集成開發環境（IDE）插件的資源和工具進行公開。

🚀 快速開始

IDE 集成（Cursor）

TeamCity MCP 服務器旨在與 Cursor 等支持人工智能的 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 協議合規性：全面支持基於 HTTP/WebSocket 的 JSON-RPC 2.0 協議。
• TeamCity 集成：通過身份驗證與 TeamCity 的 REST API 進行完整集成。
• 資源訪問：可訪問項目、構建類型、構建、代理和工件等資源。
• 構建操作：支持觸發、取消、固定構建，設置標籤，下載工件以及搜索構建等操作。
• 高級搜索：提供全面的構建搜索功能，支持多種過濾條件（狀態、分支、用戶、日期、標籤等）。
• 生產就緒：支持 Docker、Kubernetes 部署，具備監控、緩存和全面的日誌記錄功能。
• 基於環境的配置：無需配置文件，所有配置均可通過環境變量完成。

🔧 技術細節

環境變量參考

必需變量

屬性	詳情	示例
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 服務器提供了 6 個強大的工具來管理構建：

1. trigger_build

在 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. cancel_build

取消正在運行的構建。 參數：

• 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": "Cancelled due to urgent hotfix"
      }
    }
  }'

3. pin_build

固定或取消固定構建，以防止其被清理。 參數：

• 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": "Release candidate build"
      }
    }
  }'

4. set_build_tag

為構建添加或移除標籤。 參數：

• 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. download_artifact

下載構建工件。 參數：

• 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. search_builds

使用全面的過濾選項搜索構建。 參數（均為可選）：

• buildTypeId：按構建配置 ID 過濾。
• status：按構建狀態過濾（SUCCESS、FAILURE、ERROR、UNKNOWN）。
• state：按構建狀態過濾（排隊、運行、完成）。
• 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 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret" \
  -d '{
    "jsonrpc": "2.0",
    "id": 10,
    "method": "tools/call",
    "params": {
      "name": "search_builds",
      "arguments": {
        "branch": "main",
        "state": "finished",
        "count": 20
      }
    }
  }'

• 搜索帶有特定標籤的構建：

curl -X POST http://localhost:8123/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret" \
  -d '{
    "jsonrpc": "2.0",
    "id": 11,
    "method": "tools/call",
    "params": {
      "name": "search_builds",
      "arguments": {
        "tags": ["release", "production"],
        "pinned": true
      }
    }
  }'

本地二進制配置

如果你更喜歡使用本地二進制文件而不是 Docker，可以使用以下配置：

{
  "teamcity": {
    "command": "/path/to/teamcity-mcp",
    "args": ["--transport", "stdio"],
    "env": {
      "TC_URL": "https://your-teamcity-server.com",
      "TC_TOKEN": "your-teamcity-api-token"
    }
  }
}

在 Cursor 中的使用

配置完成後，你可以使用自然語言命令，例如：

• “搜索上週失敗的構建”
• “觸發主分支的構建”
• “顯示項目 X 的近期構建”
• “固定最新的成功構建”
• “取消正在運行的構建 12345”
• “為構建 12345 添加發布標籤”

人工智能將自動使用相應的 TeamCity 工具來滿足你的需求。

可用資源

服務器將 TeamCity 數據作為 MCP 資源公開：

• teamcity://projects - 列出所有項目
• teamcity://buildTypes - 列出所有構建配置
• teamcity://builds - 列出近期構建
• teamcity://agents - 列出構建代理

📚 詳細文檔

故障排除

常見問題

1. 缺少必需的環境變量

Error: TC_URL environment variable is required

解決方案：設置所有必需的環境變量。

2. 身份驗證失敗

Error: TC_TOKEN environment variable is required

解決方案：使用你的 TeamCity API 令牌設置 TC_TOKEN。

3. 無效的超時格式

Error: invalid TC_TIMEOUT format

解決方案：使用有效的持續時間格式，如 30s、1m、2h。

4. 端口已被使用

Error: listen tcp :8123: bind: address already in use

解決方案：將 LISTEN_ADDR 設置為不同的端口，或停止衝突的服務。

調試模式

啟用調試日誌記錄：

export LOG_LEVEL=debug
export LOG_FORMAT=console
./server

健康檢查

服務器提供了一個健康檢查端點：

curl http://localhost:8123/healthz
# 預期結果：{"service":"teamcity-mcp","status":"ok","timestamp":"..."}

指標

可以獲取 Prometheus 指標：

curl http://localhost:8123/metrics

TeamCity 集成測試

驗證 TeamCity 連接性：

# 檢查 TeamCity 服務器的可訪問性
curl -H "Authorization: Bearer your-token" \
  http://your-teamcity-url/app/rest/projects

# 驗證身份驗證
curl -H "Authorization: Bearer your-token" \
  http://your-teamcity-url/app/rest/server

協議參考

有關詳細的 MCP 協議實現和 TeamCity API 映射，請參閱 Protocol.md。

📄 許可證

本項目採用 MIT 許可證，詳情請參閱 LICENSE。