AI导哈

MCP代理验证器

基于FastAPI的MCP代理服务，支持多上游MCP服务器注册、能力周期性验证及变更自动禁用功能，提供管理界面和SQLite存储。

  • by jacklatrobe
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 jacklatrobe/MCP-Guardian

使用说明

MCP守护者🛡️

A. 基于FastAPI的MCP代理 它允许您注册多个上游MCP服务器，在稳定的URL下公开每个服务器，定期重新验证它们的功能，以及 自动禁用 任何工具/提示/资源/规范发生变化的服务器，直到人工重新批准。

特性

  • ✅ 代理多个MCP服务器 在稳定路径下(/{SERVICE_NAME}/mcp)
  • ✅ 快照功能 关于入职培训（工具、资源、提示）
  • ✅ 定期验证 具有可配置的检查频率
  • ✅ 更改时自动禁用 -如果功能漂移，服务将自动禁用
  • ✅ 管理用户界面 用于服务管理和差异查看
  • ✅ RFC 8785 JCS 用于稳健变化检测的规范JSON哈希
  • ✅ SSE流媒体支持 用于实时MCP交互
  • ✅ SQLite存储 支持JSON1

建筑

MCP Guardian位于MCP客户端和上游MCP服务器之间：

MCP Clients → MCP Guardian → Upstream MCP Servers
               (proxy + validator)

关键组件

  • 代理层：将POST/GET/DELETE转发到上游服务器的通配符路由
  • 快照器：通过MCP协议捕获功能（工具/资源/提示）
  • 规范化器：RFC 8785用于确定性指纹的JCS+SHA256哈希
  • 调度器：路线轮询和定期检查的后台任务
  • 管理用户界面：用于服务管理的Web界面

快速开始

使用Docker

# Build the image
docker build -t mcp-guardian .

# Run with auto-generated password (check logs for password)
docker run -d \
  -p 8000:8000 \
  --name mcp-guardian \
  mcp-guardian

# View logs to get the generated admin password
docker logs mcp-guardian

# Or run with custom config.yml and persistent data
docker run -d \
  -p 8000:8000 \
  -v $(pwd)/config.yml:/app/config.yml:ro \
  -v mcp-guardian-data:/app/data \
  --name mcp-guardian \
  mcp-guardian

对Docker数据持久性很重要:

  • 使用 命名卷 （例如。， mcp-guardian-data:/app/data)持久化您的数据库
  • 在你的 config.yml，将数据库URL设置为： sqlite+aiosqlite:////app/data/mcp_guardian.db （注意绝对路径的4个斜线）
  • 命名卷方法在跨平台（Windows、macOS、Linux）上可靠地工作
  • 如果没有卷装载，当容器被删除时，您的数据库将丢失

使用Python

# Install dependencies
pip install -e .

# Run the server (will generate random admin password)
python -m uvicorn mcp_guardian.app.main:app --host 0.0.0.0 --port 8000

# Or with custom config
cp config.yml.example config.yml
# Edit config.yml with your settings
python -m uvicorn mcp_guardian.app.main:app --host 0.0.0.0 --port 8000

配置

MCP Guardian使用 config.yml 所有配置的文件。此文件是 可选的 -如果没有提供，将使用合理的默认值。

快速开始

  1. 复制示例配置 （可选）：

    cp config.yml.example config.yml

  2. 编辑config.yml 自定义：

    • 管理员密码（如果未设置，则生成随机密码）
    • 数据库位置
    • 轮询间隔
    • 预配置的MCP服务

配置文件(config.yml)

# Admin interface configuration
admin:
  password: "your-secure-password"  # Optional - random if not set
  disable_ui: false                  # Set true to disable admin UI/API

# Polling and scheduling
polling:
  interval_seconds: 60               # Scheduler wake-up frequency
  min_check_frequency: 5             # Minimum check frequency (minutes)

# Database
database:
  # For Docker with persistence (recommended):
  url: "sqlite+aiosqlite:////app/data/mcp_guardian.db"
  # For local development:
  # url: "sqlite+aiosqlite:///./mcp_guardian.db"

# Pre-configured services (optional)
services:
  - name: "my-service"
    upstream_url: "http://localhost:3000/mcp"
    enabled: true
    check_frequency_minutes: 15

安全说明

  • 管理员密码：如果中未设置密码 config.yml，在启动时生成随机密码并记录到控制台。 保存此密码！
  • HTTP基本身份验证：管理界面使用HTTP基本身份验证。用户名可以是任何东西；密码必须与配置/生成的密码匹配。
  • 禁用管理UI：用于完全通过以下方式管理的生产部署 config.yml，set admin.disable_ui: true 完全禁用管理界面。

部署场景

地方发展:

# No config file needed - defaults work fine
python -m uvicorn mcp_guardian.app.main:app --reload
# Watch logs for generated admin password

生产环境（已挂载配置的Docker）:

# Using a named volume for data persistence (recommended)
docker run -d \
  -p 8000:8000 \
  -v /path/to/config.yml:/app/config.yml:ro \
  -v mcp-guardian-data:/app/data \
  --name mcp-guardian \
  mcp-guardian:latest

# Or using a bind mount for data (Linux/macOS)
docker run -d \
  -p 8000:8000 \
  -v /path/to/config.yml:/app/config.yml:ro \
  -v /path/to/data:/app/data \
  --name mcp-guardian \
  mcp-guardian:latest

重要:

  • 如果你 config.yml 指定数据库路径，如下所示 sqlite+aiosqlite:////app/data/mcp_guardian.db，你 必须 将卷装载到 /app/data 为了坚持
  • 使用 命名卷 （例如。， mcp-guardian-data:/app/data)实现最佳跨平台兼容性
  • 绑定支架(./data:/app/data)在Windows上使用Docker Desktop可能会出现权限问题

使用Docker Compose

创建一个 docker-compose.yml 文件：

services:
  mcp-guardian:
    build: .
    ports:
      - "8000:8000"
    volumes:
      - ./config.yml:/app/config.yml:ro
      - mcp-data:/app/data
    restart: unless-stopped

volumes:
  mcp-data:

要点:

  • 这 mcp-data 命名卷在容器重新启动时保留数据库
  • 确保您的 config.yml 有： database.url: "sqlite+aiosqlite:////app/data/mcp_guardian.db"
  • 即使运行，数据也会持续存在 docker compose down 和 docker compose up --build

然后运行：

docker compose up -d

GitOps友好:

  • 商店 config.yml 在版本控制中
  • 启动时，配置中定义的服务会自动上传到数据库
  • 现有服务（按名称）永远不会被覆盖
  • 非常适合作为代码的CI/CD管道和基础设施

用法

管理用户界面

导航至 http://localhost:8000/ADMIN/ 访问管理界面。

认证：系统将提示您输入HTTP基本身份验证凭据。用户名可以是任何东西；密码必须与中的值匹配 config.yml （或从日志中生成的密码）。

概述

管理界面提供了一个仪表板来管理您的所有MCP服务：

服务列表显示已启用的服务及其上游URL、检查频率和快照批准状态

添加服务

  1. 点击 “添加服务”
  2. 填写：
    • 服务名称：字母数字标识符（例如。， my-mcp-service)
    • 上游MCP URL：上游MCP端点的完整URL（例如。， http://localhost:3000/mcp)
    • 检查频率：检查间隔分钟数（0=从不，至少5分钟）
    • 启用：是否立即启用服务
  3. 点击 “保存”

该系统将：

  • 初始化上游服务器
  • 列出所有工具、资源和提示
  • 创建规范JSON快照
  • 标记为 user_approved
  • 在以下位置公开服务 /{SERVICE_NAME}/mcp

查看服务详细信息

点击 “查看” 在任何服务上查看：

  • 服务配置
  • 最近的快照
  • 已批准快照与最新快照之间的差异
  • 操作：批准、启用/禁用、删除

显示配置、快照历史和批准状态的服务详细信息视图

处理变更

当定期检查器检测到能力变化时：

  1. 服务是 自动禁用
  2. 新快照标记为 unapproved
  3. 管理员查看UI中的差异
  4. 管理员点击 “批准最新快照” 重新启用

运作原理

初始化流程

  1. 管理员通过UI/API创建服务
  2. 监护人发送 initialize 向上游
  3. 监护人电话 tools/list, resources/list, prompts/list
  4. 功能被排序、规范化（RFC 8785）和散列（SHA-256）
  5. 快照存储在 user_approved 状态
  6. 已启用服务并将其添加到路由注册表中

定期检查流程

每分钟（可配置）：

  1. 调度程序确定需要检查的服务（基于 check_frequency_minutes)
  2. 对于每项到期服务：
    • 拍摄新快照
    • 将哈希值与上次批准的哈希值进行比较
    • 如果 相同：使用创建快照 system_approved 状态
    • 如果 不同的：使用创建快照 unapproved 状态和 禁用服务
  3. 重新加载路由注册表以反映更改

代理流

  1. 客户端向发送请求 /{service_name}/mcp
  2. Guardian检查路由注册表的启用状态
  3. 如果禁用：返回 HTTP 403 Forbidden。如果未配置，则返回 HTTP 404.
  4. 如果启用：将请求转发到上游，保留：
    • 标题： MCP-Protocol-Version, Mcp-Session-Id, Last-Event-ID
    • 正文：原始JSON-RPC
    • SSE：事件流 id: 传播
  5. 将响应流式传输回客户端

安全注意事项（POC）

这是一个 概念验证 基本安全：

  • ✅ 单个共享管理令牌（env-var）
  • ✅ 基于令牌的API身份验证
  • ❌ 无HTTPS（使用反向代理）
  • ❌ 无速率限制
  • ❌ 无审计跟踪导出
  • ❌ 无多租户RBAC

许可证

看 许可证.md

相关 MCP