内容
---
type: Readme
title: mcp-slim-guard
timestamp: "2026-07-23T18:00:00+08:00"
description: 轻量级 MCP 安全代理 — 压缩 (最高 86%) + SSRF 保护 + 允许/拒绝 + 审计 + 速率限制 + 注入检测
tags:
- mcp-slim-guard
- readme
- mcp
- security
- compression
---
<p align="center">
<a href="./README_CN.md">中文文档</a> · <strong>English</strong>
</p>
<h1 align="center">🛡️ mcp-slim-guard</h1>
<p align="center">
<b>一个代理。两种超级能力：压缩 + 安全。</b>
</p>
<p align="center">
<a href="https://www.npmjs.com/package/mcp-slim-guard"><img src="https://img.shields.io/npm/v/mcp-slim-guard" alt="npm version"></a>
<img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen" alt="Node >=18">
<img src="https://img.shields.io/badge/tests-402%20passed-green" alt="402 tests">
<img src="https://img.shields.io/badge/compression-up%20to%2086%25-blue" alt="86% compression">
<img src="https://img.shields.io/badge/dependencies-5%20prod-lightgrey" alt="5 deps">
<img src="https://img.shields.io/npm/l/mcp-slim-guard" alt="MIT">
</p>
<br>
mcp-slim-guard 位于您的 AI 代理和 MCP 服务器之间，透明地添加 **模式压缩** （5 个级别，最高可减少 86% 的令牌）和 **安全策略** （SSRF 保护、工具允许/拒绝、注入检测、速率限制、审计日志）。
```mermaid
graph LR
A[AI Agent] --> B[mcp-slim-guard]
B --> C[压缩管道]
B --> D[安全管道]
C --> E[MCP Server 1]
C --> F[MCP Server N]
D --> E
D --> F
style B fill:#4a90d9,color:#fff
style C fill:#e6f3ff
style D fill:#ffe6e6
```
---
## 为什么选择 mcp-slim-guard？
| 问题 | 影响 | mcp-slim-guard 如何解决 |
| --------------------- | ---------------------------------------------- | ------------------------------------------------- |
| **上下文浪费** | 工具模式占用 60-86% 的上下文窗口 | 5 种压缩级别，延迟加载，请求缓存 |
| **无访问控制** | 任何代理都可以调用任何工具，带有任何参数 | 基于 glob 的允许/拒绝，默认关闭 |
| **SSRF** | 工具参数注入内部网络请求 | IP 黑名单 + 域名白名单 |
| **提示注入** | 恶意参数执行 shell/SQL | 17 种启发式模式，3 种敏感度级别 |
| **滥用** | 无限制的工具调用导致上游服务器过载 | 令牌桶速率限制器（每个工具可配置） |
| **无审计轨迹** | 没有记录谁调用了什么 | 结构化 JSON 审计日志，带有轮换和 gzip |
**只有 mcp-slim-guard 在单个代理中结合了压缩和安全功能。**
其他工具压缩模式但不保护您。安全代理不会为您节省令牌。
---
## 快速开始
```bash
# 安装
npm install -g mcp-slim-guard
# 从 .mcp.json 自动发现 MCP 服务器
cd your-project/
mcp-slim-guard init
# 预运行策略检查误报
mcp-slim-guard validate
# 启动代理
mcp-slim-guard start
```
您的代理现在连接到 mcp-slim-guard 而不是原始服务器。就这样。
> MCP 服务器从 `.mcp.json`、`mcp.json` 或 `claude_desktop_config.json` 自动发现。
### 生成的 `mcp-slim-guard.yml`
```yaml
tools:
allow: ["search_*", "read_*"] # 只允许 search/read 工具
deny: ["*_delete_*", "*_admin_*"] # 阻止危险操作
ssrf:
mode: block
block_private_ips: true
allow_domains: ["*.github.com"]
rate_limit:
default: 60/min # 每个工具的速率限制
injection_detection:
enabled: true
mode: block
sensitivity: medium
compressor:
enabled: true
level: light # 5 个级别：off/light/normal/extreme/maximum
cache:
enabled: false # TTL+LRU 只读响应缓存
audit:
output: file # 结构化 JSON 审计日志
maxSize: 10MB
maxFiles: 5
```
---
## 功能
### 🗜️ 模式压缩 — 重获上下文窗口
| 级别 | 策略 | 令牌（14 个工具） | 节省 | 何时使用 |
| ----------- | ------------------------------------------ | ----------------- | -------- | ------------------------------------------- |
| `off` | 直通 | 1,736 | — | < 5 个工具，或测试 |
| **`light`** | **3 个包装工具（按需模式）** | **300** | **-83%** | **⭐ 默认。适用于大多数用户的最佳平衡** |
| `normal` | 2 个包装工具（无 list_tools） | 245 | -86% | 30+ 个工具，强大的 LLM |
| `extreme` | 就地：删除属性描述 | 1,361 | -22% | 少数工具，复杂模式（10+ 参数） |
| `maximum` | 就地：签名仅为空属性 | 1,294 | -25% | 非常大的单个模式 |
| `lazy` | 预算预加载 + 按需模式 | 1,644 | -5% | 30+ 个工具，偶尔只使用最常用的工具 |
> **为什么有这么大的差距？** `light`/`normal` 用 2-3 个包装工具替换所有工具（`mcp__invoke_tool`、`mcp__get_tool_schema`）。LLM 按需获取模式。`extreme`/`maximum` 保留所有工具，只在原地压缩每个模式 - 节省取决于模式复杂性。
#### 现实世界成本影响
| 设置 | 令牌/调用 | 每月成本（DeepSeek V4） |
| ------------------- | ----------- | -------------------------- |
| 无压缩 | 1,736 | ~$52（10K 调用） |
| **启用 `light` 压缩** | **300** | **~$9（-83%）** |
#### 精确性验证
在 12 个场景 × 5 个级别 × 3 次运行 = 180 个 API 调用中针对 DeepSeek V4 Flash 进行基准测试。
[自行运行 →](#benchmarks)
### 🛡️ 安全管道 — 深度防御
每个工具调用都通过串行管道运行。第一个拒绝停止执行：
```
代理请求
│
▼
┌─────────────────┐
│ 1. 允许/拒绝 │ ← Glob 模式匹配。默认关闭。
│ （白名单） │
└────────┬────────┘
▼
┌─────────────────┐
│ 2. SSRF 盾牌 │ ← IP 黑名单 + 域名白名单。
│ │ 阻止 10.*、192.168.*、169.254.*
└────────┬────────┘
▼
┌─────────────────┐
│ 3. 注入检测 │ ← 17 种启发式模式：
│ 检测 │ Shell/SQL/NoSQL/提示注入
└────────┬────────┘
▼
┌─────────────────┐
│ 4. 速率限制 │ ← 令牌桶。每个工具或全局。
│ │ 默认：60 请求/分钟/工具
└────────┬────────┘
▼
┌─────────────────┐
│ 5. 审计日志 │ ← 结构化 JSON。轮换 + 压缩。
│ │ 记录每个决定。
└────────┬────────┘
▼
上游 MCP 服务器
```
### 🔄 附加功能
| 功能 | 描述 |
| ------------------------ | ------------------------------------------------------------------------------------------------------------ |
| **多服务器路由** | 一个代理，多个上游 MCP 服务器。工具名称带有前缀（`{server}_{tool}`）以实现自动路由。 |
| **热重载** | `kill -HUP <pid>` — 零停机时间配置重载。所有字段都支持热交换。 |
| **请求缓存** | TTL+LRU 内存缓存，用于只读工具结果。每个工具的统计信息。 |
| **可流式 HTTP** | `mcp-slim-guard start --http --port 3000` — 作为远程 MCP 端点工作。 |
| **STDIO 模式** | 默认。本地代理的透明替换。 |
---
## 工作原理
```mermaid
sequenceDiagram
participant LLM as AI 代理
participant MM as mcp-slim-guard
participant US as 上游 MCP 服务器
LLM->>MM: 工具/列表
Note over MM: 压缩管道<br/>过滤器 + 转换工具
MM-->>LLM: 压缩的工具列表（light：3 个包装工具）
LLM->>MM: mcp__get_tool_schema("search")
MM-->>LLM: "search" 的完整模式
LLM->>MM: mcp__invoke_tool("search", {q: "..."})
Note over MM: 安全管道<br/>白名单 → ssrf → 注入 → 速率限制
MM->>US: 转发调用
US-->>MM: 结果
Note over MM: 审计日志条目
MM-->>LLM: 结果
```
### CLI 参考
| 命令 | 描述 |
| ----------------------------------------- | -------------------------------------------------------- |
| `mcp-slim-guard init` | 自动发现 `.mcp.json`，生成 `mcp-slim-guard.yml` |
| `mcp-slim-guard validate` | 预运行策略，显示每个工具的允许/拒绝 |
| `mcp-slim-guard start` | 启动代理（STDIO 模式） |
| `mcp-slim-guard start --http --port 3000` | 启动代理（HTTP 模式） |
| `mcp-slim-guard status` | 显示配置摘要 + 策略概览 |
| `mcp-slim-guard doctor` | 诊断上游服务器连接性 |
| `mcp-slim-guard audit` | 查看审计日志 |
| `mcp-slim-guard uninit` | 删除 `mcp-slim-guard.yml` 并回滚 |
---
## 基准测试
所有基准测试均使用真实的 MCP 服务器工具模式（`filesystem` 服务器，14 个工具）与 `tiktoken`（gpt-4o 编码）。
自行运行：`npm run bench`
### 令牌节省
| 级别 | 令牌 | 减少 |
| ---------- | ------- | --------- |
| off | 1,736 | 基线 |
| **light** | **300** | **-83%** |
| **normal** | **245** | **-86%** |
| extreme | 1,361 | -22% |
| maximum | 1,294 | -25% |
| lazy | 1,644 | -5% |
### 延迟开销
```
策略管道： ~2ms/调用 （白名单 → ssrf → 注入 → 速率限制）
压缩（轻）： <0.05ms
缓存命中： 0.01ms
```
### 精确度（DeepSeek V4 Flash）
12 个场景 × 5 个级别 × 3 次运行 = 180 个 API 调用。场景包括 4 个模糊名称测试（read vs search, list vs tree）。
| 级别 | 精确度 | 备注 |
| ------ | -------------- | ---------------------------------- |
| off | 100% | 基线 |
| light | ✅（按需） | 包装模式使用额外往返 |
| normal | ✅（按需） | 与轻量级相同 |
---
## 比较
| 功能 | mcp-slim-guard | slim-mcp | mcp-compressor | mcp-guardian |
| -------------------------- | -------------------- | ------------------- | ------------------- | ---------------- |
| 模式压缩 | ✅ 5 级别，-86% | ✅ 5 级别，-77% | ✅ | ❌ |
| 精确度验证 | ✅ 180 个 API 调用 | ✅ 120 个 API 调用 | ❌ | — |
| 请求缓存 | ✅ TTL+LRU | ❌ | ❌ | ❌ |
| 工具允许/拒绝 | ✅ 基于 glob | ❌ | ❌ | ✅ |
| SSRF 保护 | ✅ IP + 域名 | ❌ | ❌ | ✅ |
| 注入检测 | ✅ 17 种模式 | ❌ | ❌ | ✅ |
| 速率限制 | ✅ 令牌桶 | ❌ | ❌ | ✅ |
| 审计日志 | ✅ JSON，轮换 | ❌ | ❌ | ✅ |
| 热重载 | ✅ SIGHUP | ❌ | ❌ | ❌ |
| 多服务器路由 | ✅ 前缀自动路由 | ❌ | ❌ | ❌ |
| HTTP 传输 | ✅ 流式 HTTP | ❌ | ✅ | ❌ |
| **压缩 + 安全** | **✅ 一个代理** | ❌ 仅压缩 | ❌ 仅压缩 | ❌ 仅安全 |
---
## 要求
- **Node.js** >= 18
- **仅 5 个生产依赖项** （MCP SDK、commander、js-yaml、micromatch、pino）
---
## Docker
```bash
docker build -t mcp-slim-guard .
docker run -i --rm -v $(pwd)/mcp-slim-guard.yml:/app/mcp-slim-guard.yml mcp-slim-guard start
```
---
## 许可证
MIT
连接信息
猜你喜欢
暂无推荐服务器