易协同 (Yi-Xietong) 官方 MCP Server

基于 Model Context Protocol (MCP) 规范实现的独立解耦服务端。
允许 WorkBuddy、豆包工作台、CodeX、Cursor 等 AI 助手与易协同项目管理及工时追踪系统无缝协同。

🛠️ 工具箱清单 (Tools)

遵循 Linear MCP 架构哲学：输入参数克制、响应数据采用 LLM 友好 Markdown 裁剪、包含直达 Web 的 Deep Link。

| 工具名称 | 说明 | 关键参数 | | :--- | :--- | :--- | | yi_get_my_tasks | 获取指派给当前登录用户的任务清单 | status (all / todo / doing / done / blocked) | | yi_search_tasks | 按关键词/项目/状态/优先级搜索任务看板 | query, projectId, status, priority, limit | | yi_get_task_detail | 获取指定任务完整详情、工时与子任务 | taskId (如 TASK-3001) | | yi_create_task | 在指定项目中创建新任务并指派责任人 | title, projectId, priority, planHours, deadline, assignee, description | | yi_update_task | 推进任务进度、流转看板状态或更新属性 | taskId, kanbanStatus, progress, priority, deadline | | yi_list_projects | 列出系统中当前推进中的活跃项目与目标 | 无参数 | | yi_log_work_time | 为指定任务填报实际工作耗时（强制实名） | taskId, hours, date, description | | yi_get_my_worklogs | 查询当前登录用户近期的工时填报记录与汇总 | days (默认 7 天) |

🔒 安全与防冒充：填报工时时无需且无法传操作人，系统直接根据 API Key 绑定的员工身份强制锁定真实姓名，天然继承后端权限矩阵。

🔑 环境变量与获取 API Key

MCP Server 依赖两个环境变量：

• YI_BASE_URL: 易协同 Web 系统后端地址（如 http://localhost:3000 或生产地址 https://your-domain.com/yi）
• YI_API_KEY: 用户的长效 API Key（格式为 yx_sk_...）

如何获取 API Key

1. 打开易协同 Web 端并登录账号；
2. 在左侧主导航菜单中直接点击 「🤖 MCP 协同与密钥」；
3. 点击「+ 创建新 API Key」，输入名称（如 WorkBuddy-办公电脑 或 豆包工作台）；
4. 复制生成出的完整明文 Key（请妥善保存，系统仅在创建瞬间展示一次）。页面支持一键直接复制适配目标客户端的配置代码！

🚀 客户端接入配置指南

💡 免安装零门槛推荐：通过 npm 发布的 yi-xietong-mcp 包，所有客户端均可通过 npx -y yi-xietong-mcp 极速自驱动执行，无需提前克隆源码或寻找本地相对目录。

1. WorkBuddy 接入配置 (推荐 · 团队协同)

在项目的 .workbuddy/mcp.json 或 WorkBuddy 设置 ➔ MCP 服务器中配置：

{
  "mcpServers": {
    "yi-xietong": {
      "command": "npx",
      "args": ["-y", "yi-xietong-mcp"],
      "env": {
        "YI_BASE_URL": "http://localhost:3000",
        "YI_API_KEY": "yx_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

2. 豆包工作台 (Doubao Work) 接入配置

打开豆包客户端 ➔ 设置 ➔ 开发者/MCP 插件 ➔ 添加本地 MCP 服务，选择 stdio 方式：

{
  "name": "yi-xietong-mcp",
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "yi-xietong-mcp"],
  "env": {
    "YI_BASE_URL": "http://localhost:3000",
    "YI_API_KEY": "yx_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}

3. CodeX 接入配置

在 CodeX 配置文件（如 ~/.codex/mcp.json 或项目级 CodeX 扩展配置）中添加：

{
  "mcpServers": {
    "yi-xietong": {
      "command": "npx",
      "args": ["-y", "yi-xietong-mcp"],
      "env": {
        "YI_BASE_URL": "http://localhost:3000",
        "YI_API_KEY": "yx_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

4. Cursor 接入配置

在项目的 .cursor/mcp.json 或 Cursor 设置中的 Features ➔ MCP Servers 添加：

{
  "mcpServers": {
    "yi-xietong": {
      "command": "npx",
      "args": ["-y", "yi-xietong-mcp"],
      "env": {
        "YI_BASE_URL": "http://localhost:3000",
        "YI_API_KEY": "yx_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

5. 独立启动与命令行调试 (Stdio)

通过 npx 直接启动：

export YI_BASE_URL=http://localhost:3000
export YI_API_KEY=yx_sk_your_key_here
npx -y yi-xietong-mcp

或在源码目录中调试：

cd packages/mcp-server
node index.mjs

🧪 自动化测试验证

易协同配套自动化测试套件完整覆盖了 API Key 的创建、列表脱敏、Bearer 鉴权访问、工时本人锁定、越权拦截及即时吊销：

npm run test:e2e