Dakpan Topdesk MCP

TOPdesk MCP服务器

用于TOPdesk API集成的生产就绪模型上下文协议（MCP）服务器。为常见操作提供自动生成的原始API工具和精心策划的高级工具。

特性

• 两层工具策略：用于常见任务的高级策划工具+用于API全面覆盖的原始自动生成工具
• API令牌身份验证：使用TOPdesk API令牌进行安全身份验证
• 基于OpenAPI的发现：根据OpenAPI/Swagger规范自动生成工具
• 生产就绪：速率限制、重试逻辑、错误处理和并发控制
• 分页支持：所有列表操作的分页一致
• 调试模式：安全记录，不泄露秘密

安装

npm install

环境变量

创建一个 .env 文件或导出以下变量：

# Required
TOPDESK_BASE_URL=https://your-tenant.topdesk.net
TOPDESK_API_TOKEN=your-api-token-here

# Optional
TOPDESK_OPENAPI_PATH=/path/to/openapi.json  # Path to OpenAPI spec file
DEBUG=true  # Enable debug logging (default: false)

获取您的API代币

1. 以具有API访问权限的操作员身份登录TOPdesk
2. 前往“设置”>“API”
3. 创建新的应用程序密码
4. 复制令牌并将其设置为 TOPDESK_API_TOKEN

OpenAPI规范

服务器可以根据OpenAPI规范自动生成工具：

1. 从TOPdesk导出：如果您的TOPdesk实例提供了OpenAPI规范，请下载它
2. 使用提供的规范：一些TOPdesk版本在 /tas/api/swagger.json
3. 手动注册表：如果没有可用的规范，服务器将使用内置的公共端点注册表

要使用OpenAPI规范：

export TOPDESK_OPENAPI_PATH=/path/to/topdesk-openapi.json

支持的格式： .json, .yaml, .yml

运行服务器

开发模式

npm run dev

构建并运行

npm run build
npm start

可用工具

高级精选工具

这些工具为常见操作提供了干净、用户友好的界面：

门票

topdesk.tickets.my_list

列出分配给您的票或您是接线员/呼叫者的位置。

输入：

{
  "scope": "assigned_to_me",  // or "created_by_me", "operator_me", "caller_me"
  "status": ["firstLine", "secondLine"],  // optional
  "since": "2024-01-01T00:00:00Z",  // optional
  "limit": 50,  // default: 50
  "cursor": "100"  // optional, for pagination
}

输出：

{
  "items": [
    {
      "id": "abc-123",
      "number": "I 2024 0001",
      "briefDescription": "Login issue",
      "status": "firstLine",
      "priority": "normal",
      "created": "2024-01-15T10:30:00Z",
      "caller": { "name": "John Doe" },
      "operator": { "name": "Jane Smith" }
    }
  ],
  "nextCursor": "150",
  "hasMore": true
}

topdesk.tickets.get

获取特定票证的详细信息。

输入：

{
  "id": "abc-123"
}

topdesk.tickets.search

使用灵活的过滤器搜索门票。

输入：

{
  "query": "login issue",  // optional
  "status": ["firstLine"],  // optional
  "priority": "high",  // optional
  "since": "2024-01-01T00:00:00Z",  // optional
  "limit": 50,
  "cursor": "0"
}

资产

topdesk.assets.create

创建新资产。

输入：

{
  "name": "Dell Laptop",
  "type": "Laptop",  // optional
  "serialNumber": "SN12345",  // optional
  "assetTag": "AT-001",  // optional
  "location": "Office 1",  // optional
  "user": "john.doe@example.com",  // optional
  "fields": {  // optional, for custom fields
    "purchaseDate": "2024-01-01",
    "warrantyEnd": "2027-01-01"
  }
}

topdesk.assets.update

更新现有资产。

输入：

{
  "id": "asset-123",
  "name": "Dell Laptop (Updated)",
  "location": "Office 2",
  "fields": {
    "lastMaintenance": "2024-03-01"
  }
}

topdesk.assets.get

获取特定资产的详细信息。

输入：

{
  "id": "asset-123"
}

topdesk.assets.search

按各种条件搜索资产。

输入：

{
  "name": "Dell",  // optional
  "serialNumber": "SN12345",  // optional
  "assetTag": "AT-001",  // optional
  "type": "Laptop",  // optional
  "location": "Office 1",  // optional
  "user": "john.doe@example.com",  // optional
  "limit": 50,
  "cursor": "0"
}

知识项目

topdesk.knowledge.search

搜索知识库项目。

输入：

{
  "query": "password reset",  // optional
  "category": "IT",  // optional
  "lastModifiedSince": "2024-01-01T00:00:00Z",  // optional
  "limit": 50,
  "cursor": "0"
}

输出：

{
  "items": [
    {
      "id": "kb-001",
      "title": "How to reset your password",
      "category": "IT",
      "lastModified": "2024-01-15T10:30:00Z"
    }
  ],
  "nextCursor": "50",
  "hasMore": true
}

topdesk.knowledge.get

获取特定知识项的详细信息。

输入：

{
  "id": "kb-001"
}

原始生成的工具

原始工具是从OpenAPI规范或手动注册表自动生成的。它们提供对所有TOPdesk API端点的直接访问。

命名约定： topdesk.raw..

示例：

• topdesk.raw.incidents.listIncidents
• topdesk.raw.incidents.getIncidentById
• topdesk.raw.assets.createAsset
• topdesk.raw.knowledge.listKnowledgeItems

原始工具格式：

所有原始工具均接受：

• path_* 路径变量的参数（例如。， path_id)
• query 查询参数的对象
• body 请求体的对象

所有原始工具返回：

{
  "status": 200,
  "headers": { "content-type": "application/json" },
  "data": { /* raw API response */ }
}

分页

所有列表操作都支持分页：

• limit：要返回的最大项目数（默认值：50）
• cursor：用于获取下一页的不透明光标
• 响应包括: items, nextCursor，以及 hasMore

分页流程示例：

// First page
const page1 = await callTool('topdesk.tickets.my_list', {
  scope: 'assigned_to_me',
  limit: 50
});

// Next page
if (page1.hasMore) {
  const page2 = await callTool('topdesk.tickets.my_list', {
    scope: 'assigned_to_me',
    limit: 50,
    cursor: page1.nextCursor
  });
}

错误处理

服务器处理各种错误情况：

• 401/403：身份验证错误
• 404：未找到资源
• 429：速率限制（指数回退的自动重试）
• 5xx：服务器错误（最多自动重试3次）
• 网络错误：使用指数回退自动重试

所有错误都以一致的格式返回，并带有描述性消息。

利率限制和退货

服务器实现了生产就绪弹性：

• 并发限制：最多10个并发请求
• 速率限制：429自动重试 Retry-After 标头支持
• 指数退避：2秒、4秒、8秒延迟，抖动±25%
• 最大重试次数：3次可重试错误的尝试
• 超时：每个请求20秒

桌面权限

确保您的API令牌具有适当的权限：

门票

• 阅读事件
• 创建/更新事件（如果使用创建/更新操作）

用于资产

• 读取资产管理数据
• 创建/更新资产（如果使用创建/更新操作）

对于知识项

• 阅读知识库项目

要检查/配置权限，请执行以下操作：

1. 前往桌面设置>操作员
2. 选择您的操作员帐户
3. 检查“功能设置”>“API”部分

MCP客户端配置

将此服务器添加到MCP客户端配置中：

{
  "mcpServers": {
    "topdesk": {
      "command": "node",
      "args": ["/path/to/topdesk-mcp-server/dist/index.js"],
      "env": {
        "TOPDESK_BASE_URL": "https://your-tenant.topdesk.net",
        "TOPDESK_API_TOKEN": "your-api-token"
      }
    }
  }
}

或用于开发：

{
  "mcpServers": {
    "topdesk": {
      "command": "npm",
      "args": ["run", "dev"],
      "cwd": "/path/to/topdesk-mcp-server",
      "env": {
        "TOPDESK_BASE_URL": "https://your-tenant.topdesk.net",
        "TOPDESK_API_TOKEN": "your-api-token"
      }
    }
  }
}

发展

项目结构

src/
├── index.ts              # MCP server entry point
├── topdesk/
│   └── client.ts         # HTTP client with auth, retries, rate limiting
├── openapi/
│   ├── loader.ts         # OpenAPI spec loader with dereferencing
│   ├── generator.ts      # OpenAPI to MCP tool generator
│   └── manualRegistry.ts # Manual endpoint registry fallback
├── tools/
│   └── highlevel.ts      # Curated high-level tools
└── utils/
    ├── errors.ts         # Error handling utilities
    └── pagination.ts     # Pagination utilities

添加手动端点

如果OpenAPI规范不完整，请将端点添加到 src/openapi/manualRegistry.ts:

{
  method: 'GET',
  path: '/tas/api/your-endpoint',
  operationId: 'yourOperation',
  summary: 'Description',
  tags: ['your-tag'],
  parameters: [
    {
      name: 'paramName',
      in: 'query',
      required: false,
      schema: { type: 'string' },
      description: 'Parameter description',
    },
  ],
  responses: {
    '200': {
      description: 'Success',
      content: {
        'application/json': {
          schema: { type: 'object' },
        },
      },
    },
  },
}

故障排除

身份验证问题

• 验证 TOPDESK_BASE_URL 正确（应包括 https://)
• 检查API令牌是否有效且未过期
• 确保操作员具有API访问权限

连接问题

• 检查TOPdesk实例的网络连接
• 验证防火墙规则是否允许出站HTTPS
• 检查代理要求

调试模式

启用调试日志记录：

export DEBUG=true
npm run dev

调试模式日志：

• 请求详细信息（无秘密）
• 响应状态和标头
• 重试尝试
• 工具注册

安全

• API令牌从未被记录（即使在调试模式下）
• 所有通信都使用HTTPS
• 机密应存储在环境变量中，而不是提交给版本控制
• 使用 .env 文件与 .gitignore 促进地方发展

许可证

麻省理工学院

支持

对于问题和疑问：

• TOPdesk API文件：https://developers.topdesk.com/
• TOPdesk支持：联系您的TOPdesk管理员

更新日志

1.0.0

• 初始版本
• 用于门票、资产和知识项目的高级策划工具
• 基于OpenAPI的原始工具生成
• 生产就绪错误处理、重试和速率限制
• 分页支持
• 调试模式