weeek-mcp

weeek-mcp

用于 Weeek 的本地 MCP 服务，默认只读，可选择启用写入工具。

README 俄语版

weeek-mcp 通过 stdio 将 AI 客户端（Claude Desktop、Claude Code、Cursor、MCP Inspector）连接到你的 Weeek 工作区。它默认只读——默认安装只能列出项目、任务、看板、成员和标签，不能进行任何修改——只有在你选择启用 READ_ONLY=false 时，才会提供五个写入工具。 支持 Node ≥ 20；使用 npx 安装，无需克隆或构建。

为什么选择它

• 已发布到 npm。 现在就能运行 npx -y weeek-mcp——无需克隆、构建或使用绝对路径。
• 默认只读，可组合配置限制。 只有选择启用后才会注册写入工具；ENABLED_TOOLS 可将工具限制在指定子集，MAX_RESPONSE_CHARS 可限制每个负载的大小。限制由服务端执行，而非依赖客户端约定。
• 双语支持。 EN ↔ RU 文档内容完整对应。
• 细粒度错误模型。 提供九种不同的错误代码和 Agent 可读的消息，让模型无需解析说明文字，就能判断应重试还是放弃。

快速开始

推荐使用 npx 安装——无需克隆或构建。将 examples/claude_desktop.mcp.json 放入你的 MCP 客户端配置中，将 YOUR_WEEEK_TOKEN_HERE 替换为从 https://app.weeek.net/ws/_/settings/apps/api 获取的真实令牌，然后重启客户端：

{
  "mcpServers": {
    "weeek": {
      "command": "npx",
      "args": ["-y", "weeek-mcp"],
      "env": {
        "WEEEK_ACCESS_TOKEN": "YOUR_WEEEK_TOKEN_HERE"
      }
    }
  }
}

首次启动时，npx 会下载 weeek-mcp 并将其缓存。Cursor 和 Cline 使用 相同的 mcpServers 格式——参见 examples/cursor.mcp.json 和 examples/cline.mcp.json。其他环境变量均有安全的 默认值；只覆盖你需要的配置（参见配置）。如果 npx 找不到 node（使用 nvm 时很常见），请参阅 故障排除；如需零依赖冒烟测试，请参阅 docs/smoke.md。

examples/ 仅托管在 GitHub 上——npm 压缩包仅包含 dist/ + README.md + README.ru.md + LICENSE。

工具

默认提供十个读取工具。只有在 READ_ONLY=false 时才会提供全部十五个工具（参见启用写入工具）。

完整的字段级参考（输入、输出、边缘情况、截断、多位受指派人）→ docs/tools.md。

启用写入工具

默认安装无法更改工作区中的任何内容。 所有五个变更工具都由 READ_ONLY（默认为 true）隐藏——不会注册，因此不会出现在 tools/list 中。将 READ_ONLY=false 设置后，tools/list 中的工具会从十个增加到十五个，并允许 Agent 在令牌可访问的工作区中创建、编辑、移动和完成任务。服务端没有确认步骤——annotations 只是提示，MCP 客户端可以忽略。请将令牌指向一个你愿意让其内容发生变化的工作区。

"env": {
  "WEEEK_ACCESS_TOKEN": "YOUR_WEEEK_TOKEN_HERE",
  "READ_ONLY": "false"
}

从一个工具开始，而不是五个。 将 READ_ONLY=false 与 ENABLED_TOOLS 配合使用，即可启用写入，但只开放你指定的那个工具：

"env": {
  "WEEEK_ACCESS_TOKEN": "YOUR_WEEEK_TOKEN_HERE",
  "READ_ONLY": "false",
  "ENABLED_TOOLS": "weeek_complete_task"
}

READ_ONLY 是外层门槛：仅在 ENABLED_TOOLS 中列出写入工具，并不会自动启用写入。允许列表不会自动包含其他工具，因此还要一并列出所需的读取工具——examples/claude_desktop.write.mcp.json 是一个可直接编辑的配置，已经按此设置。

每个写入工具能做什么，不能做什么

三个值为 true 的行都标记为“值得由人工确认”，因为Agent 从未看到旧值，也无法将其恢复；尤其要留意 weeek_create_task——无法通过此服务撤销其效果，而且重试创建会再创建一个新任务。除非传入 custom_field_id / custom_field_name，否则 weeek_set_task_mr_link 会按名称解析自定义字段——匹配名称和歧义处理规则见docs/tools.md。

配置

启动时从环境中读取配置，并使用 zod 进行验证；无效值会使启动中止，并在 stderr 中返回非零退出码。服务本身不会读取 .env 文件——请通过 MCP 客户端的 env 块或 shell 传入变量。

两道门槛都在服务端执行：隐藏的工具不会注册，因此 Agent 无法调用它。READ_ONLY 至关重要——除非你打算让 Agent 更改工作区，否则请保留默认值。可查看 .env.example 获取可直接复制粘贴的模板。

故障排查

{ "command": "/Users/<you>/.nvm/versions/node/v20.18.0/bin/npx", "args": ["-y", "weeek-mcp"] }

错误

每个 Weeek 工具都会以相同方式失败：isError: true，并附带单行 <tool> failed (<weeek_code>): <one English sentence>。weeek_<code> 标记 是稳定且便于机器检索的约定；句子则为自我纠正提供指引。 九种代码涵盖未授权／禁止／未找到／验证／速率限制／服务／网络／超时／无效响应，每种代码均附有重试指导。

weeek_get_task failed (weeek_not_found): Weeek returned 404 for this resource. Verify the id exists in the configured workspace and was not deleted.
weeek_list_tasks failed (weeek_rate_limited): Weeek rate-limited the request (HTTP 429). Retry after a brief delay or reduce the call frequency.

包含重试语义的完整表格 → docs/errors.md。

贡献 · 安全 · 许可证

• 贡献——欢迎提交问题和功能请求；提交拉取请求前须事先达成一致 （此仓库采用严格的线性增量流程）。 请参阅 CONTRIBUTING.md。
• 安全——如果发现了泄露令牌或 stdout 中字节的方法，请勿公开提交问题；关于私密渠道和 威胁模型，请参阅 SECURITY.md。
• 许可证——MIT。
• 面向 AI 编码 Agent——入口点约定（不变量、固定依赖、合并前检查清单）位于 CLAUDE.md。

CONTRIBUTING.md、SECURITY.md 和 CLAUDE.md 仅托管在 GitHub 上——与 examples/ 一样，它们不包含在 npm 压缩包中。LICENSE 是例外：它包含在 软件包内。