# MCP Firewall

**工具说“写入已拒绝”，文件真的没被动过吗？**

给 MCP 工具加权限，不能只看一句成功或失败。
MCP Firewall 提供一个能动手验证的本地审查台：关着写入权限试一次，打开再试一次，把规则、执行结果和文件前后哈希放在一起看。

![真实 MCP 请求记录与详情：规则、载荷及文件前后哈希](docs/images/request-overview.png)

### 把权限判断变成看得见的结果

这适合正在接入 MCP 的开发者，也适合团队一起讨论“权限检查应该放在哪里”。你会看到官方 MCP SDK 发出的真实调用，以及请求被拒绝或获准后，示例文件发生了什么。

| 一次操作 | 你能核对的结果 |
| --- | --- |
| 读取笔记 | 工具返回的实际文件内容 |
| 禁止写入后尝试修改 | 拒绝规则、未执行标记、相同的前后哈希 |
| 允许写入后再试 | 执行结果与已经变化的文件哈希 |

无需账号、模型或 API Key。所有操作都发生在本机的一份示例笔记上。

### 在本机打开

准备 **Node.js 24 LTS** 与 npm（也支持 22.12+ 的 22 系列及 26+；不支持 23/25），然后运行：

```sh
git clone https://github.com/shenyangs/mcp-firewall.git
cd mcp-firewall
npm run setup
npm run doctor
npm run dev
```

浏览器打开 [http://127.0.0.1:4205](http://127.0.0.1:4205)，终端保持运行；结束时按 Ctrl+C。首次 setup 会联网安装依赖与测试浏览器，下载时间取决于网络。安装问题见 [使用手册](docs/usage.md)。

### 先挡住一次，再放行一次

1. 点击 **读取笔记**，确认 SDK 调用成功。
2. 保持写入关闭，点击 **尝试写入**。选中请求，检查“未执行”和相同的 SHA-256。
3. 开启 **允许写入** 再试，查看“已改变”；最后点击 **恢复示例并关闭写入**，回到起点。

![关闭权限时的拒绝记录：请求未执行，文件前后 SHA-256 相同](docs/images/request-denied.png)

点击每条请求，看到的都是调用当时的证据。当前页面暂存完整载荷、响应和哈希，刷新后正文消失；历史日志保留时间、工具、规则和执行结果。喜欢终端的话，可运行 `npm run mcp:demo`，不要与界面或测试同时操作。

### 它保护的范围

当前只有 `read_project_note` 和 `write_project_note`，目标固定为 `fixtures/sandbox/note.txt`，写入最多 2,048 字符。权限检查位于工具内部、文件操作之前，**尚不是可接在任意 MCP 服务前的通用防火墙**。

这是单用户演示，没有身份认证、操作系统隔离或防篡改日志；不能防止其他程序直接修改文件。重启后写入权限自动关闭，最多保留 100 条历史日志。

### 想继续看代码或验证结果

本地构建、单元测试、浏览器流程和演示录屏已经在 macOS 通过；README 配图来自实际运行的应用。Windows / Linux 实机与全新机器完整安装尚未验证。所有服务仅监听本机，没有部署所需的账号与鉴权，请勿直接暴露到公网。

停止开发服务后，可自行运行：

```sh
npm run build
npm run test
npm run e2e
npm run demo
```

[安装、排错与实现细节](docs/usage.md) · [验证记录与当前状态](status.json) · [MIT 许可](LICENSE)