TeamDynamix MCP

🎟️ TeamDynamix MCP サーバー（非公式）

TeamDynamix の ITSM 機能を、エージェントから呼び出せるツールとして公開する TypeScript 製の Model Context Protocol（MCP）サーバーです。TeamDynamix の操作に構造化された、安全性を考慮したアクセスが必要な AI エージェントや MCP クライアント向けに設計されています。

機能

• 11 のドメインゲートウェイツールが、検証済みのアクションをディスカバリー、チケット、関連付け、KB、アセット、CMDB、人物、サービス、プロジェクト、時間、参照データに振り分けます
• デフォルトで安全：書き込み、削除、管理者向けのツールは明示的に有効化するまで無効です。破壊的な操作には confirm: true が必要です
• 2 つの認証モード：標準（ユーザー名／パスワード）と管理者（BEID／WebServicesKey）
• 207 の API エンドポイントをカバー：TeamDynamix のすべてのドメインに対応し、SDK のルートマニフェストに照らして検証済みです
• レート制限に対応：SDK に組み込まれたリトライ機能により、429 および 5xx の応答時に指数バックオフで再試行します
• Zod で入力を検証：API 呼び出しの前にスキーマを適用します
• エージェントスキルとプロンプトを同梱：GitHub Copilot および互換性のあるエージェントですぐに使えるスキル定義です

MCP レジストリ

このサーバーは io.github.selfagency/teamdynamix-mcp として MCP Registry に公開されています。

• レジストリ名：io.github.selfagency/teamdynamix-mcp
• レジストリ経由でインストール：mcp-install io.github.selfagency/teamdynamix-mcp（利用可能になった場合）
• 手動でインストール：以下に示す npm パッケージ @selfagency/teamdynamix-mcp を使用してください

クイックスタート（開発者向けセットアップ）

このクイックスタートは、このリポジトリのソースからサーバーを実行するコントリビューター向けです。通常の MCP クライアントユーザーは、MCP クライアントの設定に進み、npx コマンドの例を使用してください。

# 1. Clone the repository
git clone https://github.com/selfagency/teamdynamix-mcp.git
cd teamdynamix-mcp

# 2. Install dependencies
pnpm install

# 3. Configure environment
cp .env.example .env
# Edit .env with your TeamDynamix credentials and base URL

# 4. Start the development server
pnpm dev

必須の最小環境変数

TEAMDYNAMIX_BASE_URL=https://your-tenant.teamdynamix.com/TDWebApi
TEAMDYNAMIX_AUTH_MODE=standard          # or: admin
[email protected]    # standard mode
TEAMDYNAMIX_PASSWORD=your-password      # standard mode

# Optional: default application IDs (used when app_id is omitted in tool calls)
TEAMDYNAMIX_DEFAULT_TICKET_APP_ID=12345
TEAMDYNAMIX_DEFAULT_ASSET_APP_ID=23456
TEAMDYNAMIX_DEFAULT_KB_APP_ID=34567

管理者モードでは、代わりに TEAMDYNAMIX_BEID と TEAMDYNAMIX_WEB_SERVICES_KEY を使用してください。

MCP クライアントの設定

**セキュリティに関する注意：**上記の値はプレースホルダーです。実際の認証情報をソース管理にコミットしないでください。 .env ファイル（.gitignore で除外）、CI/CD のシークレット、またはシークレットマネージャーを通じて、実行時にシークレットを渡してください。

VS Code（.vscode/mcp.json）

{
  "servers": {
    "teamdynamix": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@selfagency/teamdynamix-mcp"],
      "env": {
        "TEAMDYNAMIX_BASE_URL": "https://your-tenant.teamdynamix.com/TDWebApi",
        "TEAMDYNAMIX_AUTH_MODE": "standard",
        "TEAMDYNAMIX_USERNAME": "[email protected]",
        "TEAMDYNAMIX_PASSWORD": "your-password"
      }
    }
  }
}

Claude Desktop（claude_desktop_config.json）

{
  "mcpServers": {
    "teamdynamix": {
      "command": "npx",
      "args": ["-y", "@selfagency/teamdynamix-mcp"],
      "env": {
        "TEAMDYNAMIX_BASE_URL": "https://your-tenant.teamdynamix.com/TDWebApi",
        "TEAMDYNAMIX_AUTH_MODE": "standard",
        "TEAMDYNAMIX_USERNAME": "[email protected]",
        "TEAMDYNAMIX_PASSWORD": "your-password"
      }
    }
  }
}

本番環境（ビルド済みバンドル）

pnpm build   # outputs to dist/

{
  "command": "npx",
  "args": ["-y", "@selfagency/teamdynamix-mcp"]
}

接続を確認する

MCP クライアントを接続した後、次の値を指定して teamdynamix_discovery を呼び出してください。

• action: "server_status"
• payload: {}
• response_format: "json"

成功すると、status.configured: true が表示されます。

ドメインゲートウェイツール

各ゲートウェイツールは、次の項目を受け取ります。

• action：ドメイン固有の操作名
• payload：その操作のパラメーターを含むオブジェクト
• response_format："markdown" または "json"

ドメイン	ゲートウェイツール
検出	teamdynamix_discovery
チケット	teamdynamix_tickets
チケットの関連付け	teamdynamix_ticket_relationships
ナレッジベース	teamdynamix_knowledge_base
資産	teamdynamix_assets
CMDB	teamdynamix_cmdb
人員	teamdynamix_people
サービス	teamdynamix_services
プロジェクト	teamdynamix_projects
時間	teamdynamix_time
参照データ	teamdynamix_reference_data

† 書き込みツールを有効にしたうえで、confirm: true が必要です。

すべての書き込み／変更操作には、TEAMDYNAMIX_ENABLE_WRITE_TOOLS=true が必要です。

安全性のデフォルト設定

フラグ	デフォルト	true の場合の効果
TEAMDYNAMIX_ENABLE_WRITE_TOOLS	false	すべての作成／更新／コメント／変更ツールを有効にします
TEAMDYNAMIX_ENABLE_DELETE_TOOLS	false	資産、CI、サービス、サービスカテゴリの削除を有効にします
TEAMDYNAMIX_ENABLE_ADMIN_TOOLS	false	管理者スコープの操作を有効にします

破壊的な操作では、フラグの状態にかかわらず、ツール呼び出しで confirm: true も必要です。

エージェントスキル

このリポジトリには、GitHub Copilot 対応のスキル定義が含まれています。

• スキル：skills/teamdynamix/SKILL.md — ID 優先のワークフローパターン、安全性の分岐ルール、ランブック、 注意事項、ツールカタログ
• エージェントプロンプト： prompts/teamdynamix-agent.prompt.md — TeamDynamix のコンテキストを含む、エージェントモード用のシステムプロンプト

Copilot のスキル設定でスキルをインストールしてください （詳細は skills/teamdynamix/SKILL.md を参照）。

ドキュメント

セクション	目的
チュートリアル	セットアップと最初のワークフローを段階的に説明します
ハウツーガイド	実際の操作に使えるタスク別の手順を紹介します
リファレンス	ツールカタログ、設定、安全性モデル、エラーを網羅します
解説	アーキテクチャ、認証モデル、安全性の根拠、レート制限を説明します
開発	アーキテクチャ、コントリビューション、テストについて説明します

開発

pnpm typecheck   # TypeScript strict checks
pnpm lint        # oxlint
pnpm test        # vitest (200+ tests, 90%+ coverage)
pnpm build       # tsup → dist/

ライセンス

MIT © The Self Agency LLC