Xalantis

@xalantis/mcp-server

适用于 Xalantis 的 MCP 服务。它使兼容 MCP 的 AI 客户端能够通过公开的 /api/v1 API 读取和操作 Xalantis 业务数据。

0.3.0 版本覆盖了公开 API 的全部 323 项操作（契约版本为 2.11.0）：为最常见的任务提供专用工具，并通过 4 个由随附 OpenAPI 规范驱动的通用工具处理其他所有操作。

注册目录

已列入官方 MCP Registry，名称为 io.github.xalantis-hub/xalantis-mcp，也已列入 Glama。

安装

npm install -g @xalantis/mcp-server

配置

Claude Desktop

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "xalantis": {
      "command": "npx",
      "args": ["-y", "@xalantis/mcp-server"],
      "env": {
        "XALANTIS_API_KEY": "sk_live_..."
      }
    }
  }
}

Claude Code

claude mcp add xalantis -- npx -y @xalantis/mcp-server

然后在启动 MCP 服务的 shell／会话中设置 XALANTIS_API_KEY。

Cursor

添加到 .cursor/mcp.json：

{
  "mcpServers": {
    "xalantis": {
      "command": "npx",
      "args": ["-y", "@xalantis/mcp-server"],
      "env": {
        "XALANTIS_API_KEY": "sk_live_..."
      }
    }
  }
}

覆盖的领域

专用工具：

• 支持／服务台：工单、回复、附件、报告、链接、关注者、工时记录、子任务、事件、服务请求、SLA、自动化、类别、标签、服务目录、Agent。
• CRM：客户、代表、联系人、交易、销售管道。
• 知识：文章、搜索、类别、文章草稿管理和审核。
• 计费：订阅和发票。
• 财务：仅供读取的发票和费用 API。
• 合同：合同、评论、谈判、义务、审批、签名、条款、请求、PDF 设计、资产、分配。
• 项目：项目、状态、任务（列表、读取、创建、更新、状态转换）和任务评论。

通过通用工具：公开 API 的所有其他操作，包括项目的其他功能（冲刺、里程碑、列表、标签、自定义字段、文档、工时跟踪、自动化、分析、导出、导入、客户门户）、合规案例、签名信封、合同参考数据和 CRM 导入。

通用 API 访问

4 个工具可用于调用公开 API 的任何操作，无需专用工具：

1. search_operations：按关键词（必须全部匹配，忽略重音符号；摘要为法语）、领域和 HTTP 方法查找操作。不带参数时，列出各个领域。
2. describe_operation：返回某项操作的路径、查询和标头参数、请求体架构及所需权限范围。
3. read_operation：运行 GET 操作。二进制或 CSV 响应可通过 save_to 写入本地文件。
4. call_operation：运行 POST、PUT、PATCH 或 DELETE 操作。需要 confirm: true；分段上传时，在 files 中填写本地路径。

{
  "operation_id": "post_projects_By_projectUuid_tasks_By_taskUuid_time_entries",
  "path_params": { "projectUuid": "project-uuid", "taskUuid": "task-uuid" },
  "body": { "duration_minutes": 45, "description": "Review" },
  "confirm": true
}

该规范随软件包一同发布（openapi/xalantis-openapi.json），并在每次发布时更新。超过 200 KB 的文本响应将被拒绝，并提示进行分页或使用 save_to。

每次写入都会发送一个 Idempotency-Key；每次调用都会自动生成一个，除非在 headers 中传入该键。大约有 80 个路由需要该键；重放相同的键会返回首次响应，不会产生第二次效果。

项目路由要求 API 密钥关联到工作区成员（在 Developers 设置中创建的密钥符合此要求），并具有匹配的 projects:* 权限范围。

确认机制

会修改数据或可能暴露敏感数据的工具都需要 confirm: true 参数。AI 客户端仅应在用户明确确认操作后传入该参数。

需要确认的操作示例：

• 创建、更新或删除记录；
• 发送公开的工单回复；
• 批准、拒绝、履行或重新开启服务请求；
• 合并、拆分、归档或删除工单；
• 请求合同签名；
• 下载附件或报告；
• 上传文件。

如果缺少确认参数，工具会返回错误并说明必须先确认。

文件传输工具

二进制端点可通过支持文件的工具进行处理：

{
  "ticket_uuid": "ticket-uuid",
  "file_path": "/local/path/evidence.pdf",
  "confirm": true
}

下载内容既可作为 base64 返回，也可写入本地路径：

{
  "ticket_uuid": "ticket-uuid",
  "attachment_uuid": "attachment-uuid",
  "output_path": "/tmp/evidence.pdf",
  "confirm": true
}

省略 output_path 时，工具会返回元数据和 base64 内容。

示例提示词

连接后，兼容 MCP 的助手可以回答或执行以下提示词：

• “列出未关闭的紧急工单，并总结最早的工单。”
• “查找客户端 Acme 并显示相关联系人。”
• “在知识库中搜索 SLA 配置。”
• “创建这篇知识草稿，并在我确认后提交编辑审核。”
• “更新这篇已发布的知识文章；在获批前保持线上版本不变。”
• “在我确认后，为此事件创建工单。”
• “为此工单添加内部备注。”
• “显示本月到期的合同义务。”
• “确认后提交此合同以供审批。”
• “将此工单报告下载到 /tmp/report.xlsx。”
• “列出项目 MXA 的逾期任务，并将我选中的任务移至 Done。”
• “为此任务记录 45 分钟，并显示冲刺燃尽图。”

环境变量

变量	必需	描述
XALANTIS_API_KEY	是	用于 Xalantis /api/v1 请求的租户 API 密钥。
XALANTIS_BASE_URL	否	Xalantis 实例的源地址或 API 基址，例如 https://app.example.com。默认为 https://xalantis.com/api/v1。

安全说明

• MCP 服务不会绕过 Xalantis 后端权限、计划限制、租户范围或速率限制。
• 具有破坏性或对外可见的操作需要设置 confirm: true。
• 文件下载可能包含敏感的租户数据；请谨慎使用 output_path。
• API 密钥应存储在 MCP 客户端环境配置中，而不是提示词中。

开发

npm ci
npm run lint
npm test            # compiles, then checks every tool against the bundled spec
npm run sync-openapi -- path/to/openapi.json

npm test 使用伪造的传输调用每个工具；如果某个工具针对规范未声明的路由，或在写入时未发送 Idempotency-Key，测试就会失败。发布前运行 sync-openapi（默认源文件：同级目录下的 xalantis-application/storage/app/openapi.json）。

许可证

MIT