Context Firewall 是一个本地 MCP 代理，用于降低 AI 代理使用 MCP 工具时的上下文 token 消耗。它位于 AI 代理（如 Claude Code、Claude Desktop、Cursor、Cline 等）与所有已配置的下游 MCP 服务器之间，负责压缩大型工具输出并折叠工具定义。
用途
- 解决 MCP 工具定义膨胀：将 50+ 个工具定义折叠为 4 个元工具，客户端只加载这 4 个工具，大幅减少启动时的 token 占用。
- 压缩工具输出：在原始 HTML、base64 数据块、超大 JSON 等大型输出进入模型上下文窗口前进行压缩，实测压缩率 60–95%。
主要能力
- 渐进式工具披露：客户端只看到 4 个元工具——list_tool_categories、search_tools、invoke_tool、read_more。只有在实际搜索某个工具时，才支付该工具完整 schema 的 token 成本。
- 输出压缩流水线：按固定顺序执行——剥离 base64 → 主内容提取与 HTML 转 Markdown（若页面有可识别的内容区域，则剥离导航、页眉页脚等页面外框）→ JSON 结构感知摘要 → 按字符预算截断。
- 完整输出可检索：所有压缩输出以完整形式存储在内存中（不透明句柄），可通过 read_more(handle, offset, length) 分页取回，不会静默丢弃。
- 会话节省报告：关闭时打印可分享的终端卡片（可选 Markdown 文件），展示工具定义和输出 token 的节省情况，以及哪些工具节省最多。
- 按工具的允许/拒绝策略：可在下游条目中添加 allowTools / denyTools（精确名称或 * 通配符）限制可调用的工具；deny 优先于 allow。
- 可选 LLM 摘要（默认关闭）：将超预算的文本发送到兼容 OpenAI /chat/completions 的端点进行事实性摘要，保留 ID、路径、URL、数字和错误信息，并附 read_more 指针。需要两层显式启用：顶层 llm 块和压缩策略中的 llmSummary: true。端点不可用时静默回退到确定性截断。
使用方式
- 将 Context Firewall 设为唯一的 MCP 服务器：把当前直接配置的所有下游服务器（filesystem、github、everything 等）移入 context-firewall.json 的 downstreams 块。如果客户端同时指向 Context Firewall 和现有服务器，则无法获得工具折叠或压缩收益。
- 配置格式：downstreams 块镜像 mcpServers 格式。每个条目为 stdio 服务器（与 mcpServers 形状相同）或 Streamable HTTP 服务器。字符串值中的 ${VAR_NAME} 会从环境变量展开，缺失变量会导致配置加载失败并给出可读错误。
- 客户端接入：在项目根目录的 .mcp.json、claude_desktop_config.json、.cursor/mcp.json 或 cline_mcp_settings.json 中使用相同的 mcpServers 块。
- 策略解析顺序为 default < perServer < perTool。callToolTimeoutMs 为顶层配置（不嵌套在 compression 下），是传给下游 MCP SDK 客户端的每次 invoke_tool 超时（毫秒），默认使用 SDK 默认值 60000ms。
适用场景
- 使用任何 MCP 客户端和任何模型，需要控制上下文 token 成本的环境。
- 配置了大量下游 MCP 服务器（如 50+ 工具）的场景。
- 工具输出包含大量 HTML、base64 或超大 JSON，需要压缩后再进入上下文的场景。
限制与注意事项
- 渐进式披露存在权衡：工具描述在会话中途按需到达，模型请求时也是其最不可能审阅嵌入指令的时机。v0.3.0 的缓解措施包括：search_tools 结果使用带随机 nonce 的 <untrusted-tool-descriptions> 分隔符包裹，仅匹配 nonce 的闭合标签能结束块；CLI 启动时向 stderr 打印可读摘要。但这是文本级约定而非沙箱，依赖调用模型阅读并遵守 nonce 匹配，且不清理描述内容本身。该分隔框架每次 search_tools 调用约消耗 80–85 token。
- list_tool_categories 显示的类别也来自下游提供的数据（通过 registry.ts 中粗略的动词前缀启发式），未使用上述分隔符包裹，视为风险较低但非无风险。
- 下游工具描述被当作不可信输入，仅展示、从不执行，但会原样传递、未做净化，search_tools 不会剥离或过滤恶意下游可能插入的提示注入文本。信任边界在于选择配置哪些下游服务器。
- token 计数始终以 chars / 3.5 估算，非精确的模型特定计数，会话报告始终标注“(estimated)”。
- 默认无任何代码路径将工具输出内容发送到外部 API。启用可选 LLM 摘要后，超预算的非安全敏感输出会发送到配置的端点。安全相关输出（错误、权限拒绝、警告、确认）在压缩流水线此阶段之前就被绕过，永不发送。
- 安全相关输出永不静默压缩，直接通过，仅硬性上限 50000 字符。
- 工具参数和输出内容永不写入日志或会话报告，仅记录服务器/工具名称和字符/token 计数。
- 官方文档中未提供具体收费或价格信息。
