# @gwdn/nexus-mcp 中文文档

规范地址：https://npmcn.com/package/%40gwdn/nexus-mcp/

版本：0\.10\.19
npm 元数据更新时间：2026-11-01T04:25:16.405Z
中文译文更新时间：2026-11-01T07:22:15.911Z
软件包许可：Apache-2\.0

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40gwdn/nexus-mcp
原文对照：https://npmcn.com/package/%40gwdn/nexus-mcp/?lang=original
项目主页：https://nexus.gatewarden.eu/
源码仓库：https://github.com/gwnexus/nexus-mcp

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：322 kB，135 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：2 个
- 首次发布：2026-04-20T03:08:41.082Z
- 最新版本发布：2026-11-01T04:25:16.036Z
- 已发布版本数：32（近 12 个月 32 个）

## 中文简介

用于Gatewarden Nexus平台的MCP服务器——本地代理运行时和Nexus HTTP API之间的中介层

## 安装

```sh
npm install @gwdn/nexus-mcp
```

也可以使用：`pnpm add @gwdn/nexus-mcp`、`yarn add @gwdn/nexus-mcp`、`bun add @gwdn/nexus-mcp`

## README

# Nexus MCP

[![npm](https://img.shields.io/npm/v/@gwdn/nexus-mcp)](https://www.npmjs.com/package/@gwdn/nexus-mcp) [![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://npmcn.com/package/%40gwdn/nexus-mcp/LICENSE) [![Node.js 20+](https://img.shields.io/badge/node-20%2B-green.svg)](https://nodejs.org/)

MCP服务器为 [Gatewarden联系](https://nexus.gatewarden.eu/) 平台。提供本地代理运行时和Nexus HTTP API之间的中介层 [模型上下文协议](https://modelcontextprotocol.io/) (stdio运输)。

## 安装

```bash
npx @gwdn/nexus-mcp
```

或者添加到代理的MCP配置（OpenCode, Claude Code， Cursor等）：

```json
{
  "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` 类别。

```jsonc
// 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](https://www.jetify.com/devbox) 获得一个完全可复制的、独立的开发环境，并预装了所有所需的工具（Node.js 22、git、ripgrep、tmux、lazygit等）。

**安装Devbox** (一次,系统):

```bash
curl -fsSL https://get.jetify.com/devbox | bash
```

**进入dev shell：**

```bash
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**，你仍然可以直接运行命令：

```bash
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缓存：

```bash
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联系](https://nexus.gatewarden.eu/) —平台（Next.js / Supabase）
-   [nexus-cli](https://github.com/gwnexus/nexus-cli) —Workspace CLI （Rust）
-   [nexus-link](https://github.com/gwnexus/nexus-link) 硬件代理（Rust）

## 许可证

[apache - 2.0](https://npmcn.com/package/%40gwdn/nexus-mcp/LICENSE) -版权所有(c) 2026 RelicFrog Holding UG （haftungsbeschraenkt）

## 常见问题

### @gwdn/nexus-mcp 是什么？

用于Gatewarden Nexus平台的MCP服务器——本地代理运行时和Nexus HTTP API之间的中介层

### 如何安装 @gwdn/nexus-mcp？

在项目目录运行 npm install @gwdn/nexus-mcp，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 nexus-mcp，可以用 npx nexus-mcp 直接运行。

### @gwdn/nexus-mcp 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @gwdn/nexus-mcp 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @gwdn/nexus-mcp 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @gwdn/nexus-mcp 可以商用吗？

@gwdn/nexus-mcp 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @gwdn/nexus-mcp 还在维护吗？

最新版本 0\.10\.19 发布于 2026/11/01（2 天前）；至今共发布 32 个版本，其中过去 12 个月发布了 32 个；首次发布于 2026/04/20。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。