Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 10 additions & 5 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,10 @@ on:
jobs:
test:
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
node: ['20', '22', '24']

steps:
- name: Checkout code
Expand All @@ -17,14 +21,15 @@ jobs:
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
node-version: ${{ matrix.node }}
cache: 'npm'

- name: Install dependencies
run: npm ci

- name: Run tests
run: npm test
- name: Build and run unit and protocol integration tests
run: npm run check

- name: Build project
run: npm run build
- name: Check coverage
if: matrix.node == '24'
run: npm run test:coverage
8 changes: 6 additions & 2 deletions DEVELOPMENT.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,14 +30,14 @@ cd mcps

**安装依赖:**
```bash
npm install
npm ci
```

---

## 本地开发

**开发模式(使用 ts-node 直接运行):**
**开发模式(使用 ts-node ESM loader,子进程继承 loader):**
```bash
npm run dev -- <command>
# 例如
Expand Down Expand Up @@ -94,6 +94,10 @@ npm run test:coverage
- 保持测试覆盖率在合理水平
- **TypeScript 编译必须无错误**

测试包含配置文件保护、真实 CLI 参数解析、daemon 路由、连接池并发与关闭,以及真实 SDK 服务的 stdio、Streamable HTTP、旧 SSE、新旧协议协商、OAuth 和多轮输入请求。测试启动前会编译 CLI,子进程测试使用独立配置目录和随机端口,结束时关闭自己创建的进程。

协议支持范围和可选能力见 [MCP_SUPPORT.md](docs/MCP_SUPPORT.md)。不要用测试数量代替行为验证,也不要给客户端宣告尚未实现的 sampling、roots 或扩展能力。

---

## 提交规范
Expand Down
42 changes: 30 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,19 @@ A powerful command-line interface for managing and interacting with [Model Conte
- 🔍 **Tool Filtering**: Filter tools by keywords with simple mode
- 🚨 **Verbose Logging**: Optional detailed logging for debugging

## MCP protocol support

Supports MCP **2026-07-28** with SDK v2, automatic legacy negotiation, resources, prompts, completion, manual multi-round-trip elicitation and OAuth client credentials. See [the support matrix](docs/MCP_SUPPORT.md) for tested behavior and optional host features.

```bash
mcps discover my-server
mcps resources my-server
mcps read my-server resource://document
mcps prompts my-server
mcps prompt my-server welcome name=Taipei
mcps call my-server my-tool --output-json
```

## Installation

```bash
Expand Down Expand Up @@ -292,27 +305,32 @@ You can change the storage location by setting the `MCPS_CONFIG_DIR` environment
Configuration file example:
```json
{
"servers": [
{
"name": "fetch",
"type": "stdio",
"daemonTimeout": 20000,
"mcpServers": {
"fetch": {
"command": "uvx",
"args": ["mcp-server-fetch"]
"args": ["mcp-server-fetch"],
"protocolVersion": "auto"
},
{
"name": "my-server",
"type": "stdio",
"my-server": {
"command": "node",
"args": ["./build/index.js"],
"env": {
"API_KEY": "${API_KEY}"
},
"cwd": "/workspace/my-server",
"env": { "API_KEY": "${API_KEY}" },
"disabled": false
},
"remote": {
"type": "http",
"url": "https://mcp.example.com/mcp",
"headers": { "Authorization": "Bearer ${MCP_TOKEN}" }
}
]
}
}
```


Use `mcps config path` and `mcps config validate` to inspect configuration. Root options and extension fields are preserved. Writes are atomic and refuse to overwrite malformed or invalid configuration. The legacy `servers` array is unsupported; convert it to the `mcpServers` map before modifying it.

## Environment Variables

- `MCPS_CONFIG_DIR`: Configuration file directory (default: `~/.mcps`)
Expand Down
42 changes: 30 additions & 12 deletions README.zh.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,19 @@
- 🚨 **详细日志**:可选的详细日志模式,方便调试
- ✅ **自动化测试**:完整的测试套件,确保代码质量

## MCP 协议支持

已支持 **MCP 2026-07-28** 与官方 SDK v2,包括新版自动协商和旧版回退、资源、提示词、参数补全、手动多轮 elicitation 与 OAuth 客户端凭据认证。已验证范围及可选能力见 [支持矩阵](docs/MCP_SUPPORT.md)。

```bash
mcps discover my-server
mcps resources my-server
mcps read my-server resource://document
mcps prompts my-server
mcps prompt my-server welcome name=Taipei
mcps call my-server my-tool --output-json
```

## 安装

```bash
Expand Down Expand Up @@ -293,27 +306,32 @@ mcps call my-server createUser --json params.json
配置文件示例:
```json
{
"servers": [
{
"name": "fetch",
"type": "stdio",
"daemonTimeout": 20000,
"mcpServers": {
"fetch": {
"command": "uvx",
"args": ["mcp-server-fetch"]
"args": ["mcp-server-fetch"],
"protocolVersion": "auto"
},
{
"name": "my-server",
"type": "stdio",
"my-server": {
"command": "node",
"args": ["./build/index.js"],
"env": {
"API_KEY": "${API_KEY}"
},
"cwd": "/workspace/my-server",
"env": { "API_KEY": "${API_KEY}" },
"disabled": false
},
"remote": {
"type": "http",
"url": "https://mcp.example.com/mcp",
"headers": { "Authorization": "Bearer ${MCP_TOKEN}" }
}
]
}
}
```


使用 `mcps config path` 查看实际路径,用 `mcps config validate` 检查配置。写入保留根字段和扩展字段,采用原子替换;配置损坏或条目无效时拒绝覆盖。旧 `servers` 数组格式不受支持,应先转换为以服务名为键的 `mcpServers` 对象。

## 环境变量

- `MCPS_CONFIG_DIR`: 配置文件目录(默认:`~/.mcps`)
Expand Down
82 changes: 82 additions & 0 deletions docs/MCP_SUPPORT.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
# MCP 支持范围

本次升级以 2026-10-07 核实的最新稳定规范 **2026-07-28** 为目标,运行时使用官方 `@modelcontextprotocol/client 2.3.1`。v1 SDK 仅作为开发依赖,用于和真实旧服务进行互操作测试。

规范和迁移依据:

- [MCP 2026-07-28](https://modelcontextprotocol.io/specification/2026-07-28)
- [官方变更说明](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2026-07-28/changelog.mdx)
- [SDK v2 迁移指南](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/migration/upgrade-to-v2.md)
- [新版协议启用指南](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/migration/support-2026-07-28.md)

## 已实现并验证

| 能力 | 行为与验证 |
| --- | --- |
| 新版协商与发现 | 默认 `protocolVersion: "auto"`,使用 `server/discover` 选择新版;`mcps discover <server>` 展示协商版本、能力和发现结果 |
| 旧版兼容 | 自动回退到 SDK 支持的旧协议;真实 v1 SDK 服务验证了 2025-11-25;也验证了旧 SSE,显式类型优先于 URL 路径推断 |
| 新版 stdio / Streamable HTTP | HTTP 抓取验证每次请求都携带版本与客户端能力,无 initialize、无 Session-Id;认证错误不会被当作旧版证据 |
| 工具与分页 | `tools/list` 自动汇总所有页;使用 SDK 缓存和失效机制,去掉独立的永久工具缓存 |
| JSON Schema / 结果内容 | SDK 验证 outputSchema;支持数组等任意 JSON structuredContent,以及 audio、resource_link、嵌入资源和 metadata;`--output-json` 保留完整结果 |
| 资源和模板 | `mcps resources <server>`、`--templates`、`mcps read <server> <uri>` |
| 提示词与补全 | `mcps prompts <server>`、`mcps prompt <server> <name> [KEY=VALUE...]`、`mcps complete <server> --json '<params>'` |
| 新版变更订阅 | SDK 自动使用 `subscriptions/listen` 接收工具、资源及提示词列表变更;HTTP 抓取验证订阅请求,stdio 验证新增工具可发现 |
| 新版多轮输入 | 将 input_required 完整交给 CLI 用户,通过 inputResponses 和不透明 requestState 显式续接;不会自动同意表单或 URL 请求 |
| 认证 | headers 支持环境变量占位符;OAuth client_credentials 使用 SDK 发现元数据、获取并复用令牌,校验注册 issuer;通过本地 OAuth 服务测试 |
| 关闭和重连 | SDK 管理 stdio 子进程;测试确认重连后旧 PID 已退出;连接池去重并发请求并阻止重置后的连接复活 |

`auto` 的 stdio 探测使用 SDK 的临时兄弟进程,默认等待至多 2 秒;daemon 复用连接,不会为每次工具调用重复探测。对已知旧服务可配置 `protocolVersion: "legacy"` 跳过探测。配置 `"2026-07-28"` 则强制新版,连接旧服务会明确失败。旧 SSE 只用于兼容旧协议,不能强制新版。

## CLI 配置和错误处理

配置格式为 `{ "mcpServers": { "<name>": { ... } } }`。README 中原先的旧 `servers` 数组示例已修正。

- `mcps config path` / `mcps config validate`:查看有效路径并检查完整配置。
- 根级 daemonTimeout 的单位为毫秒;MCPS_DAEMON_TIMEOUT 环境变量的单位为秒,优先级更高。
- add / update 支持 type、cwd、env、headers、protocolVersion 和 disabled;update 支持 `--enabled` 恢复。
- env/header 按第一个等号拆分,保留空值和后续等号。参数错误返回非零退出码。
- 根级与服务扩展字段在读写过程中保留。损坏 JSON、旧格式或无效现有条目会阻止写入,原始文件不变。
- 写入通过临时文件原子替换,并用独占锁阻止并发覆盖。进程被强制终止时可能留下 `mcp.json.lock`;先确认没有写入进程,再移除遗留锁。
- 修改已连接服务后执行 `mcps restart <server>`。

多轮示例:

```bash
mcps call server approval_tool --output-json
# 退出码 2,返回 inputRequests 和 requestState;根据用户决定填写响应。
mcps call server approval_tool --output-json \
--request-state '<exact returned state>' \
--input-responses '{"approval":{"action":"accept","content":{"approved":true}}}'
```

退出码:0 表示完成,1 表示参数、连接、协议或工具级错误,2 表示需要输入后续接。工具返回 isError 时不会提示成功。资源和提示词命令也支持 `--input-responses` / `--request-state`。

OAuth 客户端凭据示例,只保存密钥变量名:

```bash
mcps add remote --type http --url https://mcp.example.com/mcp \
--oauth-client-id my-client \
--oauth-client-secret-env MCP_CLIENT_SECRET \
--oauth-issuer https://auth.example.com \
--oauth-scope 'mcp:read'
```

## 可选能力与后续范围

支持最新协议版本不等于实现所有可选 host 能力或官方扩展:

- 浏览器 OAuth authorization_code 登录、客户端 ID 元数据文档注册、DPoP 和企业 JWT grant 尚无 CLI 流程;目前提供 headers 和 client_credentials。
- 最新任务机制属于独立的 `io.modelcontextprotocol/tasks` 扩展,本 CLI 未声明或实现该扩展;不会沿用已经移出核心的旧实验任务 API。
- roots、sampling、logging 在最新规范中已弃用;本 CLI 不声明 roots 或 sampling,不包含 LLM 调用。stdio 日志走 stderr/daemon 日志。
- 旧协议 unsolicited elicitation 在后台 daemon 中显式取消;需要人工输入的流程应使用新版多轮交互。
- 自动列表变更订阅已经启用;独立的长期资源内容 watch 命令仍未提供。

这些能力需要各自的产品流程和互操作测试,不能靠增加 capability 标志宣称支持。

## 验证

`npm run check` 执行 TypeScript 编译及全部单元/集成测试;`npm run test:coverage` 输出覆盖率。CLI 子进程使用新编译输出,独立配置目录及随机端口,并清理自己启动的进程。实际协议测试使用官方新旧 SDK,覆盖成功、失败、分页、认证、输入续接和子进程生命周期。

本次在 Node 20.20.2 和 24.19.0 上运行全部 149 项测试,均通过。行覆盖率从升级前的 15.13% 提升到 77.16%;配置模块为 98.68%,MCP 客户端为 93.33%。CI 增加 Node 20/22/24 矩阵及覆盖率门槛:整体行/语句 70%、分支 60%、函数 75%,配置行/分支 90%,客户端行 90% / 分支 75%。

覆盖率统计来自 Vitest 当前进程;独立 CLI 子进程执行的代码不会自动合并进该数字。因此同时审阅覆盖率、进程退出码和真实请求断言,不能仅凭用例数量或总百分比判断完整性。
24 changes: 24 additions & 0 deletions examples/weather-server.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
import { McpServer } from '@modelcontextprotocol/server';
import { serveStdio } from '@modelcontextprotocol/server/stdio';
import * as z from 'zod/v4';

// A local development example. It returns simulated data and needs no network or credentials.
serveStdio(() => {
const server = new McpServer({ name: 'mcps-local-weather-example', version: '1.0.0' });
server.registerTool('get_weather', {
inputSchema: z.object({ city: z.string(), country: z.string() }),
outputSchema: z.object({
temperature: z.object({ celsius: z.number(), fahrenheit: z.number() }),
conditions: z.enum(['sunny', 'cloudy', 'rainy', 'stormy', 'snowy']),
humidity: z.number().min(0).max(100),
wind: z.object({ speed_kmh: z.number(), direction: z.string() }),
}),
}, async () => ({
content: [],
structuredContent: {
temperature: { celsius: 24, fahrenheit: 75.2 },
conditions: 'sunny', humidity: 50, wind: { speed_kmh: 10, direction: 'N' },
},
}));
return server;
});
Loading
Loading