Nexus MCP
MCP服务器为 Gatewarden联系 平台。提供本地代理运行时和Nexus HTTP API之间的中介层 模型上下文协议 (stdio运输)。
安装
npx @gwdn/nexus-mcp
或者添加到代理的MCP配置（OpenCode, Claude Code， Cursor等）：
{
"mcpServers": {
"nexus": {
"command": "npx",
"args": ["-y", "@gwdn/nexus-mcp@latest"],
"env": {
"NEXUS_API_URL": "https://nexus.gatewarden.eu",
"NEXUS_PRIVATE_TOKEN": "nxs_pat_..."
}
}
}
}
体系结构
服务器在4层公开了62个工具。所有的数据访问都通过Nexus HTTP API——MCP服务器没有直接的数据库访问。
Agent Runtime (OpenCode, Claude, Cursor, ...)
|
| stdio (MCP protocol)
v
nexus-mcp (this package)
|
| HTTPS (Bearer token auth)
v
Nexus API (nexus.gatewarden.eu)
|
v
Supabase (PostgreSQL + RLS)
第1层—知识访问（6个工具）
| 工具 | 描述 |
|---|---|
kb_search | 跨项目实体的全文、语义或混合搜索 |
kb_memory | 结构化的项目内存快照（adr、任务、会议、信函、客户文档） |
kb_get | 根据类型和ID检索特定实体 |
kb_related | 查找与给定实体相关的实体 |
project_list | 列出无障碍项目 |
project_update | 修补项目的自述和/或描述（部分更新）。 description 是一个简短的纯文本句子（列出副标题）；长篇Markdown变成 readme |
第2层—协调（48个工具）
| 集团 | 工具 |
|---|---|
| 穹窿字母 | vl_create， vl_reply， vl_inbox， vl_outbox， vl_ack |
| 分派 | dispatch_create， dispatch_reply， dispatch_inbox， dispatch_outbox， dispatch_ack， dispatch_assign， dispatch_forward， dispatch_resolve， dispatch_close， dispatch_sweep， dispatch_get， dispatch_related |
| 任务 | task_create， task_update， task_note， task_list， task_delete |
| 文档 | doc_ingest， doc_list， doc_classify， doc_update， doc_delete |
| 会话 | session_create， session_append， session_close， session_list |
| 决定的评论 | dc_add， dc_list |
| 技能 | sk_list， sk_get， sk_create， sk_update， sk_activate， sk_assign， sk_unassign， sk_export |
| 指令 | pd_list， pd_get， pd_create， pd_update， pd_delete， pd_toggle， directive_export |
指令：短绑定规则（ADR-0125）
指令是一个简短的绑定规则。 pd_list 返回每个有效列表
项目，每个条目都带有 source：
source | 起源 | 可编辑的通过 pd_update |
|---|---|---|
mandatory | 平台目录，始终处于活动状态 | 否 |
flag | 平台目录，由项目设置(nexus env set policy.<key>） | 否 |
template | 添加到项目的默认/可选目录规则 | enabled 只有 |
project | 为这个项目编写的规则 | 是 |
字段 pd_create / pd_update：
| 场 | 笔记 |
|---|---|
rule | 一个祈使句，最多240个字符。总是交给代理人。 |
rationale | 背景，最多2000字。从来没有发给过特工。 |
level | must | should |
category | commits | language | docs | security | workflow | operations | communication |
sort_order | 整数,提升 |
enabled | 布尔 |
template_slug / template_id | pd_create 仅：添加默认/可选目录规则，而不是编写自己的目录规则。不能与规则字段组合使用。 |
title， body 和 priority 不赞成使用的别名有哪些 rule， rationale 和
level （high 映射到 must）. 后端不再接受遗留
general 类别。
// project rule
{ "rule": "Write commit messages in English.", "level": "must", "category": "commits" }
// catalog rule
{ "template_slug": "<catalog-slug>" }
技能：描述和调用（ADR-0124）
sk_create 需要 description （1 ~ 500个字符，不能为空）：一行
说明该技能的作用和使用时间。特工们通过它来挑选技能。
sk_create 和 sk_update 接受可选的 invocation：
model（默认）：代理可以自己加载技能。user：只在明确要求时使用(/command）; 呈现为disable-model-invocation克劳德代码。
第3层——治理（3个工具）
| 工具 | 描述 |
|---|---|
adr_create | 在草案状态下创建新的ADR |
adr_submit | 提交ADR草案供审查 |
adr_decide | 接受或拒绝正在审查的ADR |
第4层—评审（5个工具）
| 工具 | 描述 |
|---|---|
rv_list | 列出带有可选过滤器的审查 |
rv_get | 通过ID或实体获取审查细节 |
rv_create | 为技能或代理创建一个新的评论 |
rv_decide | 转换评审状态（提交、接受、拒绝……） |
rv_comment | 向审阅添加注释 |
身份验证
身份在启动时通过 GET /api/mcp/identity 使用
NEXUS_PRIVATE_TOKEN 作为持票人令牌。所有后续的API调用都使用相同的
身份验证令牌。Nexus后端将令牌解析给用户
识别并执行项目范围的RBAC。
环境变量
| 变量 | 要求 | 描述 |
|---|---|---|
NEXUS_API_URL | 是 | Nexus API基础URL(例如： https://nexus.gatewarden.eu） |
NEXUS_PRIVATE_TOKEN | 是 | nxs_pat_* 用于身份解析的API令牌 |
NEXUS_MODEL | 否 | 会话元数据充实的模型标识符 |
NEXUS_TOOLSTACK | 否 | 工具栈标识符(例如： opencode， claude-code） |
开发
建议:Devbox
我们建议使用 Devbox 获得一个完全可复制的、独立的开发环境，并预装了所有所需的工具（Node.js 22、git、ripgrep、tmux、lazygit等）。
安装Devbox (一次,系统):
curl -fsSL https://get.jetify.com/devbox | bash
进入dev shell：
devbox shell
这将使您进入一个由nix管理的shell，每个工具都与其中声明的版本绑定在一起 devbox.json． 没有全局安装，没有版本漂移。
可用的Devbox脚本：
| 脚本 | 命令 | 描述 |
|---|---|---|
dev | devbox run dev | 通过tsx启动MCP服务器（监视模式） |
build | devbox run build | 将TypeScript编译为 dist/ |
test | devbox run test | 运行完整的测试套件 |
typecheck | devbox run typecheck | 只做TypeScript类型检查 |
validate | devbox run validate | 完整的提交前验证（typecheck + tests） |
check-local | devbox run check-local | 本地环境运行状况检查 |
sec-scan | devbox run sec-scan | 安全扫描（gitleaks + audit） |
tmux-2w | devbox run tmux-2w | 打开双窗口tmux工作区 |
tmux-3w | devbox run tmux-3w | 打开3窗口tmux工作区 |
没有Devbox，你仍然可以直接运行命令：
npm install
npm run typecheck # TypeScript check
npm test # Run tests (164 unit + 34 E2E)
npm run build # Compile to dist/
npm run dev # Run via tsx (development)
npm start # Run compiled JS (production)
项目结构
nexus-mcp/
├── src/
│ ├── server.ts # MCP server entry point (stdio transport)
│ ├── auth.ts # Token-based identity resolution via Nexus API
│ ├── nexus-api.ts # HTTP client for Nexus API (nexusGet, nexusPost)
│ ├── machine-id.ts # Machine identification for session metadata
│ ├── project-scope.ts # NEXUS_PROJECT_ID fallback for project-scoped tools
│ ├── version.ts # Package version for MCP serverInfo (read from package.json)
│ ├── tools/ # 27 tool modules (62 tools total)
│ └── __tests__/ # 17 test files (205 unit + 34 E2E)
├── LICENSE # Apache-2.0
├── SECURITY.md # Security policy
├── CONTRIBUTING.md # Contribution guidelines
└── CODE_OF_CONDUCT.md # Contributor Covenant
已知的问题
NPX缓存阻止版本升级
当使用 npx 为了运行MCP服务器，npm将解析后的包缓存到
~/.npm/_npx/． 后续调用可能会继续使用缓存
（过时的）版本，即使在新版本发布后。
症状: MCP工具报告旧版本，或缺少新工具/修复程序。
解决办法: 在启动代理之前清除该包的所有npx缓存：
find ~/.npm/_npx -path "*/node_modules/@gwdn/nexus-mcp" -type d \
-exec rm -rf {} + 2>/dev/null
提示: 销
@latest在你的MCP配置参数中总是解析最新版本：["--yes", "@gwdn/nexus-mcp@latest"]
相关
- Gatewarden联系 —平台（Next.js / Supabase）
- nexus-cli —Workspace CLI （Rust）
- nexus-link 硬件代理（Rust）
许可证
apache - 2.0 -版权所有(c) 2026 RelicFrog Holding UG （haftungsbeschraenkt）