TeamDynamix MCP

🎟️ TeamDynamix MCP 服务（非官方）

一个 TypeScript 模型上下文协议（MCP）服务，将 TeamDynamix ITSM 功能封装为 Agent 可调用的工具。专为需要以结构化方式安全访问 TeamDynamix 操作的 AI Agent 和 MCP 客户端而设计。

功能

• 11 个领域网关工具，可将经过验证的操作路由到发现、工单、关系、知识库、资产、CMDB、人员、服务、项目、时间和参考数据
• 默认安全：写入、删除和管理工具默认禁用，需明确选择启用；破坏性操作必须设置 confirm: true
• 两种身份验证模式：标准模式（用户名/密码）和管理员模式（BEID/WebServicesKey）
• 涵盖 207 个 API 端点，覆盖所有 TeamDynamix 领域，并通过 SDK 路由清单验证
• 支持速率限制：SDK 内置重试机制，遇到 429 和 5xx 响应时采用指数退避
• 使用 Zod 验证输入：在发起任何 API 调用之前强制执行架构验证
• 包含 Agent 技能和提示词：提供开箱即用的技能定义，适用于 GitHub Copilot 和兼容的 Agent

MCP Registry

此服务已作为 io.github.selfagency/teamdynamix-mcp 发布到 MCP Registry。

• Registry 名称：io.github.selfagency/teamdynamix-mcp
• 通过 Registry 安装：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。

Agent 技能

此代码库提供了兼容 GitHub Copilot 的技能定义：

• 技能：skills/teamdynamix/SKILL.md — ID 优先的工作流模式、安全分支规则、操作手册、 注意事项和工具目录
• Agent 提示词： prompts/teamdynamix-agent.prompt.md — 包含 TeamDynamix 上下文的 Agent 模式系统提示词

通过 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