McpVanguard MCP 安全代理服务器

使用说明（简明、易操作的指南，包含核心要点）

• 项目简介 McpVanguard 是一个 MCP 服务器实现的安全代理，在代理端对进入与离开的 MCP 请求进行拦截、评估和控制，确保对 MCP 客户端的上下文信息和功能的访问符合安全策略。核心能力包括资源/工具/ prompts 的标准化上下文管理、JSON-RPC 通信、以及多层防护（静态规则、语义分析、行为分析）与审计。

• 主要功能点

  • 拦截与控制：在代理端对 MCP 请求和响应进行实时检查，必要时阻断并返回标准的 JSON-RPC 错误。
  • 层次化安全：Layer 1 静态规则（基于 YAML 的模式匹配）、Layer 2 语义分析（可选，调用 Ollama/OpenAI 进行意图评分）、Layer 3 行为分析（基于会话的统计与模式检测）。
  • VEX 集成：被阻断的请求可异步上报到 VEX 审计系统，形成可溯源的证据卷。
  • SSE/Stdio 传输：支持通过标准 IO 以及 SSE 桥接的传输方式，与 MCP 客户端和服务端灵活适配。
  • 审计与日志：详尽的行为日志，帮助追踪代理对话和策略转变。

• 安装步骤

  • 运行前提：需要 Python 3.11+，并可选地搭建 Ollama/OpenAI 做语义分析。
  • 安装：pip install mcp-vanguard
  • 启动示例（SSE 流）： vanguard sse --server "npx @modelcontextprotocol/server-filesystem ." 或传统模式（_stdio 包裹）： vanguard start --server "npx @modelcontextprotocol/server-filesystem ."
  • 可选设置：VANGUARD_VEX_URL/VANGUARD_VEX_KEY 用于 VEX Flight Recorder，VANGUARD_API_KEY 保护 SSE 端点等。

• 服务器配置（示例 JSON） 服务器配置用于 MCP 客户端以了解如何连接并启动被代理的 MCP 服务器。配置格式为 JSON，包含服务器名称、要执行的服务器命令及附加参数等。请将以下示例作为参考，并据实际服务器替换对应字段。 { "server_name": "Filesystem MCP Server", "command": ["npx", "@modelcontextprotocol/server-filesystem", "."], "args": [] } 注释说明：

  • server_name: 对应 MCP 服务器的描述，便于在监控与日志中识别。
  • command: 启动真实 MCP 服务器的完整命令（不含代理本身的启动指令）。
  • args: 该 MCP 服务器启动所需的附加参数列表（若无则为空）。 MCP 客户端在建立连接时需要知道服务器的启动命令及参数，以便通过代理实现点对点通信。

• 基本使用方法

  • 启动代理并包装目标 MCP 服务器：按照上述示例命令启动，代理会在后台拦截并处理消息。
  • 观察输出与日志：代理会在 audit 日志中记录每次请求的结果、阻断信息及规则匹配情况。
  • 调整策略：通过 rules 目录下的 YAML 文件修改 Layer 1 的判定规则，结合行为与语义分析的开启/关闭来实现不同的安全策略。

• 运行与调试要点

  • 若要开启语义分析，请确保 Ollama 服务就绪，并在启动时开启相应参数（如 --semantic）。
  • VEX 审计部分为可选，需正确配置 VEX 的 API 地址和鉴权凭证。
  • SSE 桥接适合云端代理与远程代理场景，需在网络环境中保持稳定的流通信。