Teamcity MCP

🚀 TeamCity MCP Server

このTeamCity MCPサーバーは、包括的なモデルコンテキストプロトコル（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プロトコル準拠：HTTP/WebSocketを介した完全なJSON-RPC 2.0サポート
• TeamCity統合：認証付きの完全なREST API統合
• リソースアクセス：プロジェクト、ビルドタイプ、ビルド、エージェント、アーティファクト
• ビルド操作：ビルドのトリガー、キャンセル、ピン留め、タグ設定、アーティファクトのダウンロード、ビルドの検索
• 高度な検索：複数のフィルター（ステータス、ブランチ、ユーザー、日付、タグ）を使用した包括的なビルド検索
• 本番環境対応：Docker、Kubernetes、モニタリング、キャッシュ、および包括的なロギング
• 環境ベースの設定：設定ファイルは必要なく、すべて環境変数で行えます

📚 環境変数の参照

必須変数

認証変数

オプション変数

📚 設定例

開発環境

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

📋 コマンドラインオプション

ヘルプとドキュメント

# 環境変数のヘルプを表示
./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チェックを実行（deps, lint, test, build）
make check                # すべてのチェックを実行（lint, test, build）

💻 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: ビルド状態でフィルター (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 \
  -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での使用方法

設定が完了すると、以下のような自然言語コマンドを使用できます。

• "過去1週間の失敗したビルドを検索"
• "メインブランチのビルドをトリガー"
• "プロジェクトXの最近のビルドを表示"
• "最新の成功したビルドをピン留め"
• "実行中のビルド12345をキャンセル"
• "ビルド12345にリリースタグを追加"

AIは自動的に適切な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
   

   解決策: TC_TOKEN にあなたのTeamCity APIトークンを設定します。

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 を参照してください。