mcp slim guard

MCP Slim Guard

MCP Slim Guard 为宿主提供了一种明确的方式来访问获授权的上游工具。它会保持输入架构不变，在调用上游之前验证调用，并且可以在不重复该调用的情况下，完整恢复过大的结果。

选择模式

模式	宿主可见内容	适用场景
Native	获授权的原始工具名称和完整架构，以及 read_result	适用于可良好支持常规 MCP 目录的宿主，包括 Codex
Compact	find_tool、call_tool 和 read_result；发现结果会返回每个匹配项的完整原始架构	需要精简、可预测宿主界面的场景
Extreme	Compact 工具界面和架构；只有足够大的结果才会以更短且可恢复的形式首次交付	对上下文敏感、适合缩短首次结果的宿主

start 的默认模式为 Compact。Codex 的默认安装方案为 Native。Claude Code 的默认模式为 Compact；Claude Code 支持 Compact 和 Extreme 安装方案，不支持 Native。

所有模式均应用相同的允许/拒绝授权规则。Compact 和 Extreme 最多返回 3 个发现结果，每个结果都包含原始的必填字段、枚举和嵌套架构。联系上游服务之前，会先根据原始架构验证调用。

find_tool 会在本地拒绝未知字段，以及超过 256 个 Unicode 码点的查询。它只搜索当前获授权的目录，绝不会回退到未获授权的条目。

快速开始

0.1.1-alpha.2 是一个源代码候选版本，目前尚未发布到 npm。请从经过审核的该候选版本检出中执行：

npm ci
npm run build
npm link
cd /path/to/project-with-mcp-config
mcp-slim-guard init
mcp-slim-guard validate

# Run the default Compact mode.
mcp-slim-guard start

init 会写入包含版本 2 的 mcp-slim-guard.yml。该文件仅包含上游和安全设置。请在宿主命令中选择模式，而非在 YAML 中选择。

# Inspect a host-specific plan without changing host files.
mcp-slim-guard plan --host codex
mcp-slim-guard plan --host claude-code --mode extreme

# Verify the configured runtime without changing Host configuration or calling a business Tool.
mcp-slim-guard verify --host codex

# Apply a reviewed plan.
mcp-slim-guard install --host codex --mode native

宿主配置项

对于 Codex，若要使用常规的获授权 MCP 目录，请选择 Native：

[mcp_servers.slim_guard]
command = "mcp-slim-guard"
args = ["start", "--mode", "native"]
cwd = "/absolute/path/to/project"

对于 Claude Code，默认使用 Compact：

{
  "mcpServers": {
    "slim-guard": {
      "command": "mcp-slim-guard",
      "args": ["start", "--mode", "compact"],
      "cwd": "/absolute/path/to/project"
    }
  }
}

完整配置和验证步骤请参见宿主设置。

配置

version: 2
tools:
  allow:
    - "upstream_*"
  deny:
    - "*_delete_*"
ssrf:
  mode: block
  block_private_ips: true
  allow_domains: []
  block_domains: []
rate_limit:
  default: "60/min"
injection_detection:
  enabled: true
  sensitivity: medium
  mode: block
audit:
  output: file
  filePath: mcp-slim-guard-audit.log
servers:
  upstream:
    command: npx
    args: ["-y", "@your/mcp-server"]

不支持版本 1 配置。已移除的 compressor 部分会被拒绝，不会自动迁移。

修复无效调用

如果参数与获授权工具的原始架构不匹配，Slim Guard 会返回常规 MCP 工具错误，其中的 structuredContent 会说明架构校验失败，并确认未调用上游工具。请更正参数后重试；错误中不会回显提交的参数值。

结果恢复

如果响应需要可恢复交付，首次响应会包含 result_ref。使用 query 调用 read_result，可定位最多 3 个有界本地片段；或者省略 query 并跟随 next_cursor，以恢复精确快照。这两种方式使用相同的不可变捕获内容，且都不会再次调用上游工具。请勿同时使用 query 和 cursor。Native 和 Compact 使用标准交付边界。Extreme 仅在首次交付的响应至少达到精确响应大小的一半时，才使用更小的边界；否则会原样传递精确响应。

证据与检查

仓库包含一项 24 个任务的模式对比、结果恢复测试样例，以及一个包含 100 个工具和 8,000 行的压力测试样例。运行当前构建产物：

npm run build
npm run bench:task
npm run bench:compression
npm run bench:stress
npm run bench:compression:verify

报告按模式分别生成，并在本地生成；请勿将较早的 alpha 基准数据视为该产品线的性能声明。

开发

npm run build
npm run typecheck
npm run lint
npm test
npm run verify:package-boundary
npm run smoke:package

本项目处于 alpha 阶段。使用特权工具前，请检查授权模式和上游设置。