内容
# @vorionsys/mcp-server
[](https://opensource.org/licenses/Apache-2.0)
[](https://nodejs.org)
**模型上下文协议服务器，暴露 Vorion 审计和信任基元 — 本地信任评分、证明日志和远程 Cognigate 运行时工具。**
该服务器允许 MCP 客户端（Claude Desktop、Cursor、IDE、代理框架）直接调用 Vorion 审计和信任基元：检查代理的信任等级、记录行为信号、运行操作前置检查、记录证明链决策，以及 — 当配置了已部署的 Cognigate 运行时端点时 — 提交金丝雀探测、跟踪租户审计流，并对实时运行时进行健康检查。操作前置检查返回决策；尊重该决策取决于调用客户端。
> BASIS 是 AI 代理治理的标准，就像 OAuth 是委托授权的标准一样 — 一个开放标准，允许一个系统信任的代理可以被另一个系统评估。
> **状态：源代码可用 / 参考使用。** 该仓库是 Vorion MCP 服务器的规范家园。npm 包 `@vorionsys/mcp-server` 及其运行时依赖目前 **因知识产权审查而被撤销** （参见 [安装 / 当前状态](#安装-当前状态)）。将其用作治理层通过 MCP 暴露的参考，以及在依赖链发布后构建的源代码。
---
## 快速入门（克隆 + 构建的命令）
已发布的 npm 包已被撤销（见下文），因此请从此仓库安装：
```bash
# 克隆、安装、构建 — 然后stdio入口点是dist/index.js
git clone https://github.com/voriongit/mcp-server.git && cd mcp-server && npm install && npm run build
```
构建生成一个可执行的stdio服务器 `dist/index.js` （包还将其公开为 `vorion-mcp` 二进制文件）。要直接运行它：
```bash
node dist/index.js
```
或在不构建的情况下从源代码运行（使用 `tsx`）：
```bash
npm run dev
```
服务器通过 **stdio** 讲话模型上下文协议 — 它不会向stdout打印任何内容，除了MCP帧，并且它不会打开端口。它旨在由MCP客户端启动（参见 [与Claude Desktop一起使用](#与Claude-Desktop一起使用)），而不是交互式运行。
> 在运行之前请注意：干净的公共安装还不能启动。运行时依赖于 `@vorionsys/sdk`，它拉取了一系列 `@vorionsys/*` 包，这些包因知识产权审查而被撤销 — 因此服务器当前在启动时退出，出现 `ERR_MODULE_NOT_FOUND` 错误。参见 [故障排除](#故障排除) 以了解您将看到的内容以及原因。
---
## 您获得的信任信号
当MCP客户端连接此服务器时，您的代理的工具调用可以被治理，而不是盲目执行。实际上，您获得：
- **每个代理的信任分数和等级** （`0–1000`，映射到 `T0`–`T7` 等级），因此客户端可以决定代理获得的自主权程度 — 不仅仅是单个调用是否安全。
- **飞行前允许/拒绝** （`vorion_gate_action` / `vorion_execute_governed`），在运行前检查代理的等级是否符合操作的风险。
- **行为反馈，使得分发生变化** — 成功提高信任，失败降低信任，并且高等级代理因失败而受到更多惩罚（惩罚公式 `P(T) = 3 + T`）。
- **哈希链证明日志**，记录每个允许/拒绝决策的推理，因此在事后可以审计受管辖的操作。
- **（可选，远程）租户 + 金丝雀可见性**，针对已部署的Cognigate运行时：API密钥解析为哪个租户，哈希链审计流的尾部，以及提交金丝雀探测结果的地方。
这些是客户端要采取的治理 **信号** — 它们本身不会阻止您的操作系统或网络；执行取决于使用它们的客户端。
---
## 工具列表
### 本地信任引擎工具（本地运行，无API密钥）
| 工具 | 目的 |
|---|---|
| `vorion_check_trust` | 查询代理的分数（0–1000）、等级（T0–T7）和观察等级。 |
| `vorion_record_signal` | 记录行为信号（`behavioral.success` / `behavioral.failure` / `compliance.pass` / `compliance.fail`）。 |
| `vorion_gate_action` | 操作前检查：代理是否达到操作的所需等级？ |
| `vorion_log_proof` | 将允许/拒绝决策记录到哈希链证明日志中。 |
| `vorion_execute_governed` | 门控 + 记录信号 + 记录证明，合为一步（推荐）。 |
### 远程 Cognigate 运行时工具（需要 `VORION_API_URL` + `VORION_API_KEY`）
| 工具 | 目的 |
|---|---|
| `vorion_tenant_whoami` | 将调用的API密钥解析为其租户ID、角色和功能。 |
| `vorion_tenant_list` | 列出运行时所有租户（仅限管理员）。 |
| `vorion_tenant_audit_tail` | 跟踪租户最近的哈希链审计事件。 |
| `vorion_canary_submit` | 将金丝雀探测结果（通过/失败/模糊）提交给运行时。 |
| `vorion_health_check` | 访问配置的Cognigate运行时 `/api/v1/health` 端点。 |
如果没有 `VORION_API_URL` + `VORION_API_KEY`，远程工具仍然可见，但返回结构化的 `not configured` 错误 — 本地信任引擎工具不受影响。
### 资源
- `vorion://tiers` — BASIS 8-层信任模型（分数范围、功能、惩罚乘数、惩罚公式）。
- `vorion://agents/{agentId}/trust` — 特定代理的当前信任配置文件。
---
## 遥测和隐私
阅读源代码以确认以下内容 — 所有内容都在 [`src/index.ts`](./src/index.ts) 中。
- **五个本地信任引擎工具不进行网络调用。** 它们完全在本地信任引擎和内存证明日志中运行。没有任何内容被发送到任何地方。
- **无分析、无使用遥测、无崩溃报告。** 没有Sentry/PostHog/"电话回家"代码路径。唯一写入远程服务的内容是您明确进行的远程工具调用。
- **仅当 `VORION_API_URL` 和 `VORION_API_KEY` 均已设置时，才会发出远程工具的网络调用。** 在这种情况下，服务器向 **您配置的Cognigate运行时URL** （例如您自己的部署）发出HTTPS请求，发送您的 `VORION_API_KEY` 作为 `Bearer` 令牌和您传递给工具的参数。如果这些环境变量未设置，则不会尝试发出网络请求。
- **服务器仅在stderr中记录日志** ，并且仅在致命启动错误时记录。 它不会记录工具输入/输出。
简而言之：如果没有配置环境变量，这是一个完全本地的服务器，没有遥测。任何网络流量都是对您选择的端点的显式远程工具调用。
---
## 安装 / 当前状态
**请勿执行 `npm install @vorionsys/mcp-server`。** 该包 — 以及其运行时依赖 `@vorionsys/sdk` 和 `@vorionsys/proof-plane` — 目前 **因知识产权审查而被撤销**。相反，请从此仓库安装（参见 [快速入门](#快速入门-克隆--构建的命令)）。
由于依赖链正在审查中，干净的公共克隆将安装并构建，但 **无法在运行时启动** （SDK导入被撤销的私有 `@vorionsys/*` 对等方，npm无法解析）。将此仓库视为 **参考/源代码可用**，直到发布这些包。参见 [故障排除](#故障排除)。
---
## 与Claude Desktop一起使用
由于npm包被撤销，请将Claude Desktop指向您 **本地构建** 的副本，而不是 `npx` 使用已发布的包。在运行 [快速入门](#快速入门-克隆--构建的命令) 后，将以下内容添加到 `claude_desktop_config.json` 中（使用您自己的克隆的 `dist/index.js` 的绝对路径）：
```json
{
"mcpServers": {
"vorion": {
"command": "node",
"args": ["/absolute/path/to/mcp-server/dist/index.js"]
}
}
}
```
要启用 **远程 Cognigate 运行时工具** （`vorion_tenant_whoami`、`vorion_tenant_list`、`vorion_tenant_audit_tail`、`vorion_canary_submit`、`vorion_health_check`），请添加两个环境变量，将 `VORION_API_URL` 指向 **您的运行时部署**：
```json
{
"mcpServers": {
"vorion": {
"command": "node",
"args": ["/absolute/path/to/mcp-server/dist/index.js"],
"env": {
"VORION_API_URL": "https://your-cognigate-runtime.example.com",
"VORION_API_KEY": "vrn_live_..."
}
}
}
}
```
服务器在 `vorion` 下注册，因此其工具在客户端中显示为 `vorion_*`。`VORION_API_URL` 和 `VORION_API_KEY` 是服务器读取的仅有的两个环境变量。
---
## 故障排除
最常见的三种设置失败，按可能性顺序排列：
**1. `Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@vorionsys/...'` 在启动时。**
这是当前公共安装的预期结果。`@vorionsys/sdk` 拉取了一系列 `@vorionsys/*` 包（例如 `atsf-core`、`security`、`a3i`、`runtime`），这些包 **因知识产权审查而被撤销**，因此无法从公共npm注册表中解析。构建（`npm run build`）成功，但 `node dist/index.js` 立即退出。 在这些包发布之前，没有公共解决方法 — 这就是为什么仓库目前被标记为参考/源代码可用。 如果您有权访问Vorion monorepo，请在那里安装/链接这些对等方并从该工作空间运行。
**2. 服务器启动后立即退出，或者您的客户端显示“node: command not found”/语法错误。**
检查您的Node版本：`node --version`。此服务器需要 **Node.js >= 20** （它使用原生ESM和全局 `fetch`）。在较旧的Node上，您将看到模块解析或 `fetch is not defined` 错误。确保您已运行 `npm run build` — Claude Desktop配置中的 `args` 必须指向编译后的 `dist/index.js` （或使用 `npm run dev` 使用 `tsx` 源路径），而不是直接 `src/index.ts`。
**3. 远程工具返回 `Remote Cognigate API is not configured` （或网络错误）。**
五个远程工具需要 **同时设置 `VORION_API_URL` 和 `VORION_API_KEY`**。如果其中任何一个缺失，您将收到结构化的 `not configured` 错误 — 设计如此，本地工具继续工作。如果两者都已设置但您收到网络错误，则服务器运行位置无法访问该URL；如果您收到 `vorion_tenant_list` 的 `403` 错误，则您的密钥缺少管理员角色。请注意，这是一个 **stdio** 服务器：它必须由MCP客户端（或管道JSON-RPC）启动，而不是作为交互式命令运行 — 在终端中直接运行 `node dist/index.js` 将默默等待stdin。
---
## 开发
```bash
# 安装依赖
npm install
# 构建（tsc -> dist/）
npm run build
# 运行测试（vitest）
npm test
# 仅类型检查
npm run typecheck
# 通过stdio从源代码运行（tsx）
npm run dev
```
---
## 技术栈
- **运行时：** Node.js >= 20，ES模块（`type: module`）。
- **语言：** TypeScript 5.x，严格模式，NodeNext解析。
- **MCP SDK：** `@modelcontextprotocol/sdk` ^1.28。
- **Vorion依赖：** `@vorionsys/sdk` ^0.3.1（本地信任引擎）和 `@vorionsys/proof-plane` ^0.1.4（哈希链事件日志） — **两者因知识产权审查而在npm上被撤销**；参见 [安装 / 当前状态](#安装-当前状态)。
- **模式验证：** `zod`。
- **测试运行器：** `vitest`。
- **传输：** stdio（Claude Desktop、Cursor等）。HTTP传输未实现。
---
## 来源
该包是从Vorion monorepo在提交 `3d7ed92d` （2026年4月20日 — `feat(mcp-server): add remote Cognigate Runtime tools (v0.3.0)`）中提取的。
远程运行时工作最初在现已废弃的PR [voriongit/vorion#137](https://github.com/voriongit/vorion/pull/137) 中捕获。该PR已关闭，改为此独立仓库（2026年4月24日）。
许可证从 `UNLICENSED` 规范化为 **Apache-2.0** 在提取时。
---
## 许可证
Apache-2.0 — 参见 [LICENSE](./LICENSE).
Copyright 2026 Vorion LLC. 参见 [NOTICE](./NOTICE) 以了解归属。
---
## 链接
- **Vorion：** https://vorion.org
- **BASIS 规范：** https://github.com/voriongit/basis-spec-docs
- **问题：** https://github.com/voriongit/mcp-server/issues
