Easy8 MCP

Easy8 MCP 服务

将 AI 助手直接连接到 Easy8。Easy8 MCP 服务让 Claude、Cursor、GitHub Copilot 和其他任何 Model Context Protocol 客户端都能使用你自己的 Easy8 权限，在你自己的 Easy8 实例中读取和更新项目、问题与评论。

该服务内置于 Easy8 中。无需安装、托管或维护任何内容——只需在管理设置中启用它，并将 AI 客户端指向 https://your-easy8.example.com/mcp。

**状态：**早期访问。后续 Easy8 版本将扩展协议功能和工具目录。

支持的客户端

Easy8 MCP 服务通过 Streamable HTTP 使用标准 Model Context Protocol，因此任何兼容的客户端都能使用。以下提供了经过验证的配置说明：

• Claude Code——请参阅 Claude Code 配置。
• Cursor——请参阅 Cursor 配置。
• Visual Studio Code (GitHub Copilot)——请参阅 VS Code 配置。
• Claude Desktop 和其他仅支持 stdio 的客户端——通过 mcp-remote 代理使用，请参阅 stdio 客户端配置。

任何支持带自定义请求标头的远程 HTTP 服务的其他 MCP 客户端都能直接使用——将其指向 https://your-easy8.example.com/mcp，并在 X-Redmine-API-Key 标头中发送你的 Easy8 API 密钥。

开始之前

你需要准备三样东西：

1. 一个 Easy8 实例，AI 客户端能够访问它（云端或可自托管）。
2. 在 Easy8 管理设置中启用 MCP：Settings → AI → Enable MCP → Save。默认情况下，MCP 处于禁用状态。禁用时，/mcp 会返回 404 Not Found。
3. **个人 Easy8 API 密钥。**在 Easy8 用户个人资料中生成。MCP 服务使用标准 Easy8 API 身份验证，并继承你账户的所有权限和项目可见性。

就是这样。无需单独安装，无需运行额外的服务，也无需注册 OAuth 应用。

端点与发现

MCP 端点	https://your-easy8.example.com/mcp
传输方式	Streamable HTTP
身份验证	在 X-Redmine-API-Key 请求标头中提供 API 密钥
发现卡片	https://your-easy8.example.com/.well-known/mcp/server-card.json

发现卡片是用于公布传输方式和功能的公开元数据。/mcp 端点本身仍要求启用 MCP 并提供有效的 API 密钥。

AI 可以做什么

当前工具目录侧重于问题和项目工作流。

工具	功能
easy8_projects_list	列出可见项目。可按名称或自由文本查询筛选，并使用 limit / offset 分页。
easy8_issues_list	列出可见问题。可按项目、受派人、状态（open / closed）、主题、截止日期范围或自由文本查询筛选。
easy8_issues_get	按 ID 获取一个问题，包括元数据、描述和评论数量。
easy8_issues_comments_list	按时间倒序列出问题日志备注。
easy8_issues_create	创建问题。必须提供主题和项目选择器。支持跟踪器、描述、受派人、优先级、状态、日期和自定义字段。
easy8_issues_update	更新现有问题。支持编辑字段，也可通过 notes 追加新的日志备注。

工具通过标准 MCP tools/list 方法动态发现，因此客户端始终能获取实时、最新的架构。

请在 Easy8 MCP 服务官方开发者文档中查看所有工具：https://developers.easy8.com/AI/mcp-server/core-tools/

工作流示例

• “查找 Q2 marketing 项目中所有分配给我的未解决问题，并总结受阻的事项。”
• “阅读问题 #1842 的最新评论，并为客户拟一份状态更新。”
• “在 Onboarding 项目中创建一项后续任务，分配给 Petra，截止日期设为周五，并选择合适的跟踪器和优先级。”
• “列出 Helpdesk 项目中上周关闭的所有问题，并按跟踪器分组。”

客户端配置

将 https://your-easy8.example.com 替换为你的 Easy8 URL，并将 YOUR_API_KEY 替换为你的个人 Easy8 API 密钥。

Claude Code

claude mcp add --transport http easy8 https://your-easy8.example.com/mcp \
  --header "X-Redmine-API-Key: YOUR_API_KEY"

Cursor

添加到 ~/.cursor/mcp.json（或项目的 .cursor/mcp.json）：

{
  "mcpServers": {
    "easy8": {
      "url": "https://your-easy8.example.com/mcp",
      "headers": {
        "X-Redmine-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

VS Code（GitHub Copilot）

添加到工作区的 .vscode/mcp.json：

{
  "servers": {
    "easy8": {
      "type": "http",
      "url": "https://your-easy8.example.com/mcp",
      "headers": {
        "X-Redmine-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Claude Desktop（及其他仅支持 stdio 的客户端）

Claude Desktop 目前尚不原生支持远程 HTTP MCP。请使用 mcp-remote 代理。编辑 claude_desktop_config.json：

{
  "mcpServers": {
    "easy8": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://your-easy8.example.com/mcp",
        "--header",
        "X-Redmine-API-Key: YOUR_API_KEY"
      ]
    }
  }
}

编辑配置后，重启客户端。

工作原理

Easy8 MCP 服务实现了 Model Context Protocol 的标准 JSON-RPC 方法：

• initialize — 打开会话并返回服务元数据和功能。
• tools/list — 返回包含完整 JSON 架构的实时工具目录。
• tools/call — 使用结构化参数调用工具并返回结构化响应。
• ping — 健康检查。
• notifications/initialized — 接受来自客户端的标准初始化后通知。

完整的方法级参考、请求／响应示例和错误语义，请参阅 Easy8 开发者文档。

安全与权限

• 你的权限，你的数据。 每次工具调用都使用 API 密钥所有者的权限运行。MCP 服务不会绕过 Easy8 授权、可见性规则或必填字段验证。
• 传输过程中使用 TLS。 /mcp 始终使用 HTTPS。
• 将 API 密钥视同密码。 不要将其提交到源代码管理中，也不要在聊天中分享。如果密钥泄露，请在 Easy8 用户个人资料中轮换密钥。
• 默认关闭。 Easy8 管理员必须为每个实例显式启用 MCP。
• 使用专用服务账户。 创建一个仅具备集成实际所需权限（通常为只读）的 Easy8 用户，并从该账户生成 API 密钥，而不是使用个人管理员账户生成。

故障排除

/mcp 返回 404 Not Found MCP 尚未启用。前往 Easy8 管理后台的 设置 → AI → 启用 MCP 并保存。

POST /mcp 返回 401 Unauthorized 请求缺少有效的 API 密钥。请检查是否存在 X-Redmine-API-Key 标头，以及该密钥是否已被撤销或重新生成。

工具调用返回权限错误 MCP 服务会强制执行 Easy8 授权。请检查 API 密钥所有者对相关项目或问题的权限。

GET /mcp 返回 405 Method Not Allowed 这是预期行为。该端点使用 POST 传输 JSON-RPC；启用 MCP 时不支持 GET。

支持与反馈

• 产品问题和功能请求：[email protected]
• 开发者参考：developers.easy8.com/AI/mcp-server
• 关于此 README 或配置片段的问题：请在此代码库中提交 issue。

免责声明

Easy8 MCP 服务作为 Easy8 的一部分提供，适用你现有的 Easy8 许可和条款。工具行为、可用方法和协议版本可能会随 Easy8 版本而变化。在允许 AI 客户端写入生产数据之前，请务必先在你自己的非生产实例上进行测试。