AI导哈

JSON-RPC防火墙

MCP防火墙是一个代理JSON-RPC并执行允许/拒绝策略的工具，适用于工具、资源、提示和方法的管理，可作为stdio包装器或流式HTTP反向代理运行，并提供本地GUI进行策略编辑、历史记录、模板和实时日志查看。

  • by dx-corp
  • Go
  • 本地部署
  • 更新于
在 GitHub 查看 haasonsaas/mcp-firewall

使用说明

MCP防火墙

一种小型MCP（模型上下文协议）防火墙，代理JSON-RPC并强制执行工具、资源、提示和方法的允许/拒绝策略。它可以作为stdio包装器或可流式传输的HTTP反向代理运行，并包括一个干净的本地GUI，用于策略编辑、历史记录、模板和实时日志。

重要：政策控制意图，遏制控制能力。如果允许CLI工具，则该工具仍然可以访问外部数据，除非启用遏制(--no-network + --allow-bin).

易于设置（几分钟内即可完成主机范围内的设置）

  1. 构建：
go build ./cmd/mcp-firewall
  1. 扫描+安装（包装stdio服务器、代理HTTP服务器）：
./mcp-firewall --host-scan --host-root .
./mcp-firewall --host-install --policy policy.example.yaml --host-root . --no-network --allow-bin git
  1. 运行HTTP代理+GUI（用于HTTP上游和仪表板）：
./mcp-firewall --listen 127.0.0.1:17880 --routes ~/.mcp-firewall/routes.json --path /mcp --ui 127.0.0.1:8081

打开 http://127.0.0.1:8081/ui.

提示：使用 --host-dry-run 预览更改，以及 --host-uninstall --host-restore 回滚。

快速启动（stdio）

构建：

go build ./cmd/mcp-firewall

在真正的MCP服务器上作为包装器运行：

./mcp-firewall --policy policy.example.yaml -- <server-command> <args>

GUI（本地仪表板）

运行stdio时提供GUI：

./mcp-firewall --ui 127.0.0.1:8081 --policy policy.example.yaml -- <server-command> <args>

打开 http://127.0.0.1:8081/ui. 策略编辑器在高级抽屉中显示差异计数、本地警告、具有差异视图的库模式和历史记录。仪表板包括“Top blocked by”图表、日志表过滤器、CSV导出、过滤器预设和被阻止事件的回放/模拟控件。

模式（心智模型）

  • 观察模式：仅日志+标记（无阻塞）。
  • 强制模式：阻止违反策略的行为。
  • 包含模式：强制+网络沙盒+分配的二进制文件。
./mcp-firewall --mode observe --policy policy.example.yaml -- <server-command>
./mcp-firewall --mode enforce --policy policy.example.yaml -- <server-command>
./mcp-firewall --mode contain --policy policy.example.yaml --no-network --allow-bin git -- <server-command>

笔记：

  • --mode observe 是缩写 --dry-run.
  • --mode contain 使能够 --no-network 自动，但您仍应设置 --allow-bin 以约束子流程。

从GUI启用策略编辑：

./mcp-firewall --ui 127.0.0.1:8081 --policy policy.example.yaml --policy-write -- <server-command>

使用令牌锁定GUI/neneneba API：

./mcp-firewall --ui 127.0.0.1:8081 --api-token YOUR_TOKEN --policy policy.example.yaml -- <server-command>

调整要保留的版本数：

./mcp-firewall --ui 127.0.0.1:8081 --policy-history 50 --policy policy.example.yaml -- <server-command>

主机范围内的发现+安装

扫描常见的MCP主机配置位置（Claude Desktop、Cursor、VS Code）和工作区根：

./mcp-firewall --host-scan --host-root . --host-root ~/Projects

用防火墙包裹发现的stdio服务器（和代理HTTP服务器）：

./mcp-firewall --host-install \\
  --policy policy.example.yaml \\
  --no-network \\
  --allow-bin git \\
  --host-root . \\
  --host-http-listen 127.0.0.1:17880 \\
  --host-http-path /mcp

安装程序在每个配置文件旁边写入带时间戳的备份，以及一个路由文件（默认 ~/.mcp-firewall/routes.json)对于HTTP上游，并打开全局切换文件（默认 ~/.mcp-firewall/enabled).

仅预览有差异的更改：

./mcp-firewall --host-install --host-dry-run --policy policy.example.yaml --host-root .

卸载（就地解包），或从最新备份还原：

./mcp-firewall --host-uninstall --host-root .
./mcp-firewall --host-uninstall --host-restore --host-root .

为这些路由运行HTTP代理：

./mcp-firewall --listen 127.0.0.1:17880 --routes ~/.mcp-firewall/routes.json --path /mcp --ui 127.0.0.1:8081

全局切换

使用启用的文件打开/关闭强制：

./mcp-firewall --enabled-file ~/.mcp-firewall/enabled --enable
./mcp-firewall --enabled-file ~/.mcp-firewall/enabled --disable
./mcp-firewall --enabled-file ~/.mcp-firewall/enabled --status

当 --enabled-file 在包装器上设置，缺少文件=绕过，存在文件=强制。配置后，GUI状态面板包括一个切换按钮。

HTTP模式（流式HTTP）

在MCP HTTP服务器前作为反向代理运行防火墙：

./mcp-firewall --listen 127.0.0.1:8080 \
  --upstream http://127.0.0.1:9000/mcp \
  --path /mcp \
  --ui-path /ui \
  --allow-origins http://localhost:1234 \
  --policy policy.example.yaml

打开 http://127.0.0.1:8080/ui.

笔记：

  • --allow-origins 强烈建议浏览器客户端使用。
  • 防火墙需要可流式传输的HTTP，并支持SSE响应。
  • 使用 --routes ~/.mcp-firewall/routes.json 以多上游模式运行（路径如 /mcp/<id>).

发现同种异体政策

从服务器的确切工具/提示符/资源名称生成一个满列表：

./mcp-firewall --discover --server-framing line -- <server-command> <args> > policy.discovered.yaml

示例：“仅限消息+CLI”

使用下面的策略只允许使用类似CLI的工具和本地资源。其他一切都被封锁了。

methods:
  # Only restrict these if needed; leaving allow empty keeps defaults permissive.
  deny: []

tools:
  # Allow only CLI tools. Adjust tool names to match your server.
  allow:
    - "cli.*"
    - "shell.*"
  deny: []

resources:
  # Allow only local/file-ish resources.
  allow_schemes:
    - "file"
    - "local"
  deny_schemes:
    - "http"
    - "https"
    - "smtp"
    - "imap"
    - "s3"

prompts:
  # Allow prompts by name if you expose any.
  allow: []
  deny: []

强化（阻止MCP服务器进程的出站网络）：

./mcp-firewall --no-network --policy policy.example.yaml -- <server-command> <args>

笔记：

  • --no-network 仅适用于stdio/发现模式，因为HTTP上游在其他地方运行。
  • 在macOS上，这使用 sandbox-exec；在Linux上，它尝试 firejail 或 unshare.使用 --no-network-best-effort 如果没有可用的沙盒，则继续。
  • 使用 --allow-bin git,ls （可重复）以限制服务器可以生成哪些可执行文件；这是通过以下方式执行的 sandbox-exec 或 firejail.

检查（快速注射启发式）

启用检查以标记工具/资源/提示中的可疑输出：

./mcp-firewall --inspect --inspect-threshold 5 --inspect-excerpt --policy policy.example.yaml -- <server-command>

每源阈值（在工具输出有噪声时有用）：

./mcp-firewall --inspect \
  --inspect-threshold-tools 7 \
  --inspect-threshold-resources 5 \
  --inspect-threshold-prompts 3 \
  --policy policy.example.yaml -- <server-command>

可选硬化：

  • --inspect-redact 将可疑文本替换为 [redacted by mcp-firewall].
  • --inspect-block 阻止超过阈值的响应。

默认情况下，检查是一个棉绒层：它记录 decision=flagged 事件，除非您启用它，否则不会阻止。

分类器支持的检查可以将提取的文本发送到治理服务 或正常块/编校之前的PurpleLlama兼容分类器端点 决定：

./mcp-firewall --inspect \
  --inspect-classifier-url http://127.0.0.1:8088/classify \
  --inspect-classifier-provider purplellama \
  --inspect-classifier-header "Authorization: Bearer $TOKEN" \
  --inspect-classifier-threshold 0.7 \
  --policy policy.example.yaml -- <server-command>

分类器接收JSON provider, kind，以及 text.答复可能 返回 score, label, flags，以及 categories；匹配的响应被折叠 进入相同 suspicionScore, suspicionFlags, classifier，以及 classifierScore 仪表板和执行模式使用的日志字段。

策略模型

  • methodsJSON-RPC方法名称（例如。， tools/call, resources/read).
  • tools：中的工具名称 tools/list 或 tools/call.
  • resources：资源URI模式和方案允许/拒绝列表。
  • prompts：提示名称 prompts/list 或 prompts/get.

规则按以下顺序应用：

  1. 拒绝列表
  2. 允许列表（如果非空）
  3. 否则允许

如果允许列表为空，并且 strict=false，该部分默认为允许。模式使用全局匹配(*, ?)默认情况下区分大小写，除非 case_insensitive=true.Set methods.strict=true 默认拒绝未知/未指定的方法。对于资源， normalize=true 规范方案/主机，解码 %XX，并在匹配之前清理路径。

框架（标准）

MCP stdio在当前规范中使用以行分隔的JSON。此代理默认为 --server-framing line，但您可以通过以下方式切换到LSP风格的框架 --server-framing lsp 如果需要的话。

日志记录

默认情况下，阻塞的流量以JSON行记录到stderr。使用 --log 写入文件和 --log-allowed 也记录允许的事件。产生可疑输出 decision=flagged 记录条目 suspicionScore 和 suspicionFlags 领域。每个事件都包括稳定 requestId/traceId, direction、标准化目标和匹配 policyRule/policyPattern 使下游分析更容易。GUI通过SSE从以下位置读取日志 /api/logs/stream 并用过滤器呈现表格。

局限性

  • 允许CLI工具仍然允许模型通过该工具获取外部数据。
  • 只有通过包装器或HTTP代理路由的MCP流量才会被拦截（直接绕过stdio/HTTP连接）。
  • HTTP模式是可流式传输HTTP服务器的反向代理（没有传统的SSE传输适配器）。
  • 快速注射检测是启发式的，可能会产生假阳性或阴性。

文件

  • cmd/mcp-firewall/main.go -CLI入口点
  • internal/firewall/* -代理、策略、发现、HTTP逻辑和GUI资产
  • policy.example.yaml -启动策略

相关 MCP