nexus-mcp

将 Nexus/TaskBridge PM 系统暴露给 Claude Code 的 MCP 服务器，让智能体可以直接读取和更新任务，而不是由人工手动转述状态。与 claude-templates 中的两个技能搭配使用 — nexus-plan-work（面向 PM/BA/Team Lead，用于编写）和 nexus-pick-up-task（面向开发者，用于执行）。

对接的是 PM 系统的公共 /api/v1/* API — 而不是 nexus-vscode 的内部端点，后者保留给官方扩展使用。关于原因以及完整的构建历史，请参阅 DEVLOG.md。

设置（每人一次）

按顺序执行四个步骤 — 仅登录本身并不会让 Claude Code 感知到 nexus-mcp 的存在。 那是另一步（下面的第 2 步）。此列表中的任何步骤都不需要 git clone — npx 会直接从 GitHub 获取、构建并运行。

1. 登录 — 通过 Developer Portal 生成令牌，并将其存储在操作系统的钥匙串中（@napi-rs/keyring — 绝不存放在文件中）：

export NEXUS_API_URL=http://27.254.62.17:8090
npx -y -p github:tanakorncode/nexus-mcp nexus-mcp-login

它会引导你完成 $NEXUS_API_URL/developer → 创建应用 → 授予作用域 tasks:read tasks:write projects:read members:read sprints:read → 生成令牌 — 然后提示你粘贴该令牌以及你的账户邮箱。

2. 向 Claude Code 注册 — 二选一（不需要两者都做，但可以共存）：

• 针对你自己，覆盖每个仓库，只需一次（需要 claude CLI — 先执行 npm install -g @anthropic-ai/claude-code）：

  claude mcp add nexus-mcp -s user -e NEXUS_API_URL=http://27.254.62.17:8090 -- npx -y github:tanakorncode/nexus-mcp

  此后任何地方都不再需要 .mcp.json。

• 或者，如果你要打开的某个仓库根部已经提交了 .mcp.json（例如 pea-thailand-backoffice-be）— 无需任何操作，Claude Code 会在你打开该仓库时自动识别。只有在你没有执行上述步骤时才相关。

3. 重新加载 Claude Code（新窗口 / 重启会话）— 无论哪种方式都必须这样做，正在运行的会话不会自行识别新注册的服务器。首次连接较慢（npx 重新获取并全新构建）；之后会被缓存。批准一次性信任提示。

4. 验证 — 让 Claude 调用 whoami。如果它能解析出你的名字，则四个步骤全部生效。

同时安装技能（每人一次 — 详见 claude-templates/README.md）：

mkdir -p ~/.claude/skills
git clone --depth 1 https://github.com/tanakorncode/claude-templates /tmp/claude-templates
cp -r /tmp/claude-templates/skills/nexus-pick-up-task ~/.claude/skills/
cp -r /tmp/claude-templates/skills/nexus-plan-work ~/.claude/skills/

在 nexus-mcp 本身上进行开发

如果你要修改的是这个仓库自身的代码，而不仅仅是使用它，请改为克隆它，这样修改无需重新发布即可生效：

git clone https://github.com/tanakorncode/nexus-mcp
cd nexus-mcp
npm install
npm run build
npm link          # makes the `nexus-mcp` command available anywhere on this machine

在迭代期间，将 .mcp.json 指向 "command": "nexus-mcp"（不带 args），而不是 npx 形式 — 重新构建（npm run build）并重新加载 Claude Code 窗口以应用更改；否则 MCP 服务器进程会在内存中持有旧代码。

Related MCP server: project-manager

这两个技能，以及各自适用的场景

• nexus-plan-work — 将功能拆分为史诗/故事/任务。用于任务尚不存在时。这里真正要紧的纪律：每个跨仓库的功能对应一个故事，其下每个仓库对应一个任务，每个任务上都设置 repositoryId（这是最容易被跳过的字段，而且一旦遗漏，日后无法恢复）。

• nexus-pick-up-task — 查找、理解并执行任务，最终产出 PR 和状态更新。用于任务已存在、且有人（人或定时检查）准备好处理时。

完整的逐步说明请直接阅读技能文件本身 — 本 README 不再重复。

工具

身份与发现

读取任务

编写（参见 nexus-plan-work）

交接

可选：定时任务检查（仅通知）

scripts/check-my-tasks.sh 以无头模式（claude -p）运行，并定时检查 list_my_tasks，如果有任何就绪的内容就触发 macOS 通知 — 它不会自行开始编写代码（--allowedTools 被锁定为只读工具外加 Bash(osascript*)，因此即使它想编辑文件，在结构上也无法做到）。

launchctl load ~/Library/LaunchAgents/com.pea-thailand.nexus-task-check.plist   # enable, runs every 2h
launchctl unload ~/Library/LaunchAgents/com.pea-thailand.nexus-task-check.plist # disable
tail -f ~/Library/Logs/nexus-task-check.log                                     # watch it run
./scripts/check-my-tasks.sh                                                     # run once, right now

plist 本身不在这个仓库中（它是每人的本地机器配置）— 请复制 DEVLOG.md 中 2026-08-22 条目里的那份，或者询问已经配置好的人。

它只负责检查；收到通知后，仍需要人打开 Claude Code 并说“go” — 如果你想了解为什么止步于此，请参阅 DEVLOG.md。

已知限制

• 不支持评论，不支持关联提交 — 这些路由只存在于仅供扩展使用的内部 API 中，而不在 /api/v1/* 中。若要添加，需要新增 pm-system 路由。

• 无法通过 API 创建史诗 — 史诗不常创建/由负责人规划；请使用产品 UI。

• 无法通过 API 上传附件/嵌入内容（读取是没问题的 — get_task 会返回两者）— 请通过产品 UI 附上 Figma 链接/截图。

• 按仓库范围、故事范围和标签过滤的查询，只有在有人真正在任务上设置了 repositoryId/storyId/labelIds 之后才会返回结果 — 系统不会自动推断任何内容。