内容
# mcpkit
MCP 开发工具包 — 脚手架、代理和检查 MCP 服务器。
MCP（模型上下文协议）是 AI 代理与工具之间的标准接口。mcpkit 为您提供了缺失的开发工具：从配置文件生成 MCP 服务器、实时调试工具调用以及代理流量进行检查。
**可观察性：** MCP 流量是 JSON-RPC via stdio — 没有浏览器网络选项卡。mcpkit 填补了这一空白：查看哪些方法运行、参数和响应、延迟以及调用是否失败 — 包括工具级失败，而 JSON-RPC 层仍将其视为正常。当您运行多个 MCP 服务器（Cursor、Claude Desktop 等）时，跟踪信息会按服务器标记，因此您不会从平坦的日志流中猜测。
## 安装
在 npm 上发布为 **`@abdlrahmansaber/mcpkit`** （[软件包页面](https://www.npmjs.com/package/@abdlrahmansaber/mcpkit)）。CLI 命令在您的 PATH 上保持为 **`mcpkit`**：
```bash
npm install -g @abdlrahmansaber/mcpkit # 全局 CLI → 运行 `mcpkit`
npx @abdlrahmansaber/mcpkit --help # 运行无需全局安装
```
需要 Node.js 20+。
要从克隆中黑客 CLI，请使用 `npm link` （参见 [CONTRIBUTING.md](CONTRIBUTING.md)）。
## 命令
### `mcpkit init` — 脚手架 MCP 服务器
从 YAML 配置文件或 OpenAPI 规范生成完整的 MCP 服务器项目。
```bash
# 从 YAML 配置文件
mcpkit init --from config.yaml
# 从 OpenAPI 规范
mcpkit init --from openapi.yaml --format openapi
# 预览无需写入
mcpkit init --from config.yaml --dry-run
# HTTP 传输代替 stdio
mcpkit init --from config.yaml --transport http
```
**YAML 配置文件格式：**
```yaml
name: my-api-server
transport: stdio
tools:
- name: get_user
description: 按 ID 获取用户
params:
id:
type: string
required: true
- name: list_orders
description: 列出用户的订单
params:
user_id:
type: string
required: true
limit:
type: integer
default: 10
```
这会生成一个可运行的 TypeScript MCP 服务器，并带有类型化的处理程序存根。编辑 `src/tools/` 中的处理程序，运行 `npm install && npm run dev`。
### `mcpkit proxy` — 透明 MCP 代理
位于 MCP 客户端和服务器之间，记录所有 JSON-RPC 流量。
```bash
# 包装服务器命令
mcpkit proxy -- node my-server.js
# 输出 NDJSON 跟踪信息
mcpkit proxy --json -- node my-server.js
# 将跟踪信息转发到检查器
mcpkit proxy --inspector ws://localhost:3200/ws/ingest -- node my-server.js
```
输出（stderr）：
```
[mcpkit] 代理已启动：node my-server.js
[10:15:30] → tools/call search_repos (333ms) ✓
[10:15:31] → tools/call query_db (120ms) ✓
[10:15:32] → tools/call deploy (—) ✗
```
### `mcpkit inspect` — 实时调试仪表盘
MCP 流量的代理 + 基于浏览器的检查器。实时可见每个工具调用、延迟和请求/响应有效载荷。
```bash
# 检查服务器（打开浏览器仪表盘）
mcpkit inspect -- node my-server.js
# 自定义端口
mcpkit inspect --port 3201 -- node my-server.js
# 仅终端（无浏览器）
mcpkit inspect --log-only -- node my-server.js
# 退出时将跟踪信息导出到文件
mcpkit inspect --export traces.json -- node my-server.js
```
仪表盘显示：
- 所有工具调用的实时流，包含方法、工具名称、延迟和状态
- 点击任意行查看完整的请求/响应 JSON
- 按方法、状态或方向过滤
- 在工具名称和参数中搜索（搜索原始有效载荷，因此即使在屏蔽关闭时，您仍然可以找到值）
- **屏蔽敏感信息**（默认开启）：隐藏常见的类似机密的密钥，并在详细信息面板中截断非常长的字符串；切换在浏览器中持久存在；内存中的跟踪数据仍然完整 — 下载使用未屏蔽的 JSON
- 大型 JSON 响应（序列化大小 **> ~56 KiB**）：高亮横幅 + **响应** 下的工具栏，截断预览，**展开完整** （确认如果 >1 MiB），**下载 JSON** （完整未屏蔽正文）；当适用时，跟踪详细信息中显示黄色提示行
- 虚拟化跟踪表，以便长时间会话保持响应（环形缓冲区最多 1000 条目）
- 配色编码：绿色 = 成功，红色 = 错误，黄色 = 慢，灰色 = 通知
使用 **仅工具** 过滤器隐藏协议噪音，专注于真正的工具调用：
### `mcpkit serve` — 共享检查仪表盘
启动一个独立的仪表盘，接受来自多个 MCP 服务器的跟踪信息。无需包装服务器 — 所有 MCP 服务器都将跟踪信息代理到此处。
```bash
# 启动共享仪表盘（保持此终端打开）
mcpkit serve
# 自定义端口
mcpkit serve --port 3201
```
输出：
```
[mcpkit] 检查仪表盘：http://localhost:3200
[mcpkit] 监听来自 ws://localhost:3200/ws/ingest 的代理连接
```
然后配置每个 MCP 服务器使用 `--inspector` 将跟踪信息流式传输到此处：
```json
{
"mcpServers": {
"my-server": {
"command": "mcpkit",
"args": ["proxy", "--server-name", "my-server", "--inspector", "ws://localhost:3200/ws/ingest", "--", "node", "my-server.js"]
},
"other-server": {
"command": "mcpkit",
"args": ["proxy", "--server-name", "other-server", "--inspector", "ws://localhost:3200/ws/ingest", "--", "node", "other-server.js"]
}
}
}
```
仪表盘显示一个 **服务器** 列，以便您可以分辨每个调用来自哪个 MCP，以及一个 **服务器过滤器** 以专注于某一个。
## 与 Cursor / Claude Desktop 一起使用
在 MCP 配置中添加 mcpkit 作为代理包装器：
```json
{
"mcpServers": {
"my-server": {
"command": "mcpkit",
"args": ["proxy", "--", "node", "my-server.js"]
}
}
}
```
或用于检查：
```json
{
"mcpServers": {
"my-server": {
"command": "mcpkit",
"args": ["inspect", "--log-only", "--export", "traces.json", "--", "node", "my-server.js"]
}
}
}
```
## 开发
```bash
git clone https://github.com/AbdlrahmanSaberAbdo/mcpkit.git
cd mcpkit
npm install
npm run dev # 监视模式（tsup）
npm test # Vitest
npm run lint # ESLint
npm run typecheck # tsc --noEmit
npm run build # 生产构建
```
参见 [CONTRIBUTING.md](CONTRIBUTING.md) 了解 PR 指南、发布和如何使用 `--output` 安全运行 `mcpkit init`。
## 许可证
[MIT](LICENSE)
