Wezylnia/toolgate
GitHub: Wezylnia/toolgate
为 MCP 服务器工具提供策略、审批、脱敏、超时和审计能力的 TypeScript 中间件库。
Stars: 2 | Forks: 0
# ToolGateKit
为您的 MCP 工具设置防护机制。
ToolGateKit 是一个 TypeScript 中间件库，专为构建 Model Context Protocol 服务器的开发者设计。它封装了您现有的 MCP 工具处理器，并在处理器运行前检查声明的策略。
当工具需要读取文件、写入数据、调用 API、删除记录、发送消息，或向 AI 智能体公开敏感输出时，都可以使用它。
```
npm install toolgate-mcp
```
## 它解决的问题
MCP 工具本质上只是函数，但一旦智能体可以调用它们，就需要明确的边界限制：
- 该工具可以读取任意路径，还是只能读取 `src/**`？
- `.env`、`secrets/**` 或 `node_modules/**` 是否应该始终被拦截？
- 破坏性工具在运行前是否需要审批？
- 返回输出前是否应隐藏敏感信息？
- 每次工具调用是否都应写入审计日志？
- 如果处理器挂起会发生什么？
ToolGateKit 将这些检查直接置于处理器旁，使得策略清晰可见、易于测试，并与您的服务器代码一起进行版本控制。
## 工作原理
```
policy + handler -> protected handler
```
对于每次调用，ToolGateKit 都会：
1. 评估声明的策略。
2. 拦截需要审批或违反策略的调用。
3. 在支持超时的情况下运行处理器。
4. 如果已启用，则对敏感输出进行脱敏。
5. 如果已配置，则写入审计条目。
6. 返回结构化的成功或错误结果。
## 示例
```
import { createAuditLogger, gate } from "toolgate-mcp";
const audit = createAuditLogger({
file: ".toolgate/audit.jsonl"
});
const readFileTool = gate(
{
name: "read_file",
risk: "read",
allowedPaths: ["src/**", "docs/**"],
deniedPaths: [".env", "secrets/**"],
timeoutMs: 5000,
redact: true,
audit
},
async ({ path }, ctx) => ({
content: await fs.readFile(path, { encoding: "utf8", signal: ctx.signal })
})
);
```
如果智能体请求 `.env`，则不会执行处理器：
```
{
"ok": false,
"error": {
"type": "policy_violation",
"code": "PATH_DENIED",
"message": "Tool 'read_file' is not allowed to access '.env'."
}
}
```
## 核心功能
- 用于 MCP 工具处理器的 `gate(policy, handler)` 包装器
- 适配 MCP 兼容 `content` 和 `isError` 结果的 `gateMcp(policy, handler)` 适配器
- 风险级别：`read`、`write`、`external`、`destructive`
- 对危险工具实施需要审批的拦截机制
- 宿主驱动的异步审批提供程序，提供结构化的拒绝和失败结果
- 具备拒绝优先行为的路径允许列表和拒绝列表
- 网络域名允许列表和拒绝列表
- 命令允许列表和拒绝列表
- 每个受保护处理器的内存速率限制
- 用于路径、URL 和命令的自定义输入提取器
- 针对常见文件系统和外部 API 工具的策略预设
- 基于 `AbortSignal` 的超时处理
- 对常见机密和 token 的默认脱敏
- 只追加的 JSONL 审计日志，通过 `audit: true` 写入 `.toolgate/audit.jsonl`
- 通过 API 或 CLI 进行流式审计日志过滤和摘要
- 导出策略清单以增强可见性
- 快速失败（fail-fast）的运行时策略验证和重复名称配置检查
- 清单 JSON schema 和验证辅助工具
- 用于生成和验证清单的 `toolgate` CLI
- 可预测的结构化错误
## 它不包含的范围
ToolGateKit 不是 MCP 服务器、MCP 客户端、网关、代理、沙盒、审批 UI、智能体框架或身份验证系统。它降低了工具处理器周边的风险，但本身并不能使不安全的处理器代码变得安全。
## 状态
适用于 TypeScript MCP 服务器的 v0.5 版本。优先使用 ESM，要求 Node.js 18+。
## CLI
从 JSON 策略配置生成清单：
```
toolgate manifest --config toolgate.config.json --out policy-manifest.json
```
验证清单：
```
toolgate validate-manifest --file policy-manifest.json
```
在生成清单前验证策略配置：
```
toolgate validate-config --file toolgate.config.json
```
检查审计日志中被拦截的调用：
```
toolgate audit --file .toolgate/audit.jsonl --decision blocked --limit 100
```
## 开发
```
npm install
npm run typecheck
npm test
npm run build
npm audit
```
## 发布
npm 发布仅通过 GitHub Releases 自动进行。普通的提交和推送不会触发发布。
创建一个与包版本匹配的发布标签（例如 `v0.5.1`），发布工作流将在向 npm 发布 `toolgate-mcp` 之前运行测试。请参阅[发布流程](docs/release.md)。
## 文档
- [包 README](packages/mcp/README.md)
- [策略](docs/policies.md)
- [审批](docs/approvals.md)
- [审计日志](docs/audit-logs.md)
- [脱敏](docs/redaction.md)
- [清单](docs/manifest.md)
- [CLI](docs/cli.md)
- [限制](docs/limitations.md)
- [示例](docs/examples.md)
- [MCP 集成](docs/mcp-integration.md)
- [发布流程](docs/release.md)
- [更新日志](CHANGELOG.md)
标签：AI代理, MCP, MITM代理, TypeScript, 中间件, 代码注入, 安全插件, 数据脱敏, 暗色界面, 权限控制, 自动化攻击