mcp-firewall

关键词

Model Context Protocolpolicy-engineredactionsandboxingsupply chain

使用说明（Markdown 格式）

  • 项目简介 mcp-firewall 是一个完整的 MCP 服务器实现，设计目标是为基于 MCP 的 LLM 客户端提供标准化的上下文信息和功能服务。它通过代理下游 MCP 服务器来注册和暴露 Tools/Resources，并实现策略（allow/deny/prompt）、数据脱敏、沙箱执行、供应链校验等功能，支持多种传输协议，提供可扩展的上下文服务框架。

  • 主要功能点

    • 资源与工具托管：从下游服务器读取并注册资源与工具，使上游客户端能够通过统一入口访问。
    • 策略与审计：内置策略引擎，支持允许、拒绝和提示三种行为，并记录审计信息。
    • 提示与合规性：提供 explain_effective_policy 等工具，用于展示当前策略及 provenance 信息。
    • 脱敏与 redaction：基于配置的模式对工具输入/输出以及资源内容进行脱敏处理。
    • 供应链校验：对下游的可执行文件进行哈希与路径校验，提升安全性。
    • 沙箱执行：支持在沙箱中运行下游进程（Linux/Landlock 等能力检测），提升对危险操作的隔离。
    • 影子代理/工作流：通过 in-memory 传输及多下游路由，支持多服务器并发场景。
    • 配置驱动：通过 YAML/JSON 的配置文件来定义下游服务器、策略、脱敏、沙箱和供应链等，支持本地覆盖与工作区(remotes)。

  • 安装步骤（简明）

    • 安装开发环境：需要 Go 1.x 及相关依赖。
    • 构建程序：在仓库根目录执行构建命令，将生成用于运行的二进制。
    • 启动 MCP 服务器：按下游配置启动代理服务器，它会启动一个 MCP 服务器对外暴露，使用 MCP 客户端与下游服务器通信。
    • 配置下游服务器：按需配置下游服务器的启动命令、参数、工作目录、沙箱等信息，确保下游可访问且符合安全策略。

  • 服务器配置（用于 MCP 客户端连接的配置示例说明） 说明：MCP 客户端需要知道启动的 MCP 服务器信息，以便建立连接。以下为配置信息要点（以 JSON 形式描述字段含义，实际向 MCP 客户端提供时可以由客户端自行生成或读取）：

    • server_name: "echoserver"
    • command: "./testdata/echoserver/echoserver" // 下游 MCP 服务器的启动命令路径
    • args: ["--verbose"] // 下游 MCP 服务器启动参数
    • timeout: "10s" // 下游工具/资源调用的默认超时
    • sandbox: "" // 沙箱配置名称，若为空表示不开启沙箱
    • hash: "" // 供应链哈希值（可选），用于校验下游可执行文件
    • downstream_profile: "" // 下游特定配置或描述，可选

    注：MCP 客户端通常需要向服务器提供下游的启动信息（command、args 等）以建立连接，具体客户端实现会使用这些信息来创建连接并与 MCP 服务器进行 JSON-RPC 风格的通信。

  • 基本使用方法

    • 启动代理：运行编译后的 binary，指定配置路径，代理会自动拉起并代理下游 MCP 服务器，向上游客户端暴露工具与资源。
    • 调用工具/读取资源：在上游客户端（如一个 LLM 框架）中，通过统一的清单获取工具和资源的名称，并通过类似 alpha__tool 的命名格式调用具体工具，或通过相应的资源 URI 读取资源内容。
    • 审计与审批：当策略需要时，系统会提示用户进行审批；如用户同意，工具调用将继续执行，否则返回拒绝信息。
    • 脱敏/红action：调用工具前后都会应用配置中的红action，确保敏感信息不会泄露。
    • 观察与调试：使用 explain_effective_policy 工具查看当前政策、 provenance、以及 sandbox、 redaction、timeout 等设置，便于调试与合规检查。

  • 运行与调试提示

    • 配置字段要保持合理性，确保 downstreams、timeout、approval_timeout、max_output_bytes 等字段符合格式。
    • 本仓库还包含大量测试用例，能帮助你在本地环境中验证代理行为、策略评估、脱敏等特性。

服务器信息

访问项目