AgentGuard

关键词

安全网关本地AI工具拦截上下文服务自动化配置

使用说明（Markdown 格式）

  • 项目简介

    • AgentGuard 是一个面向本地自治 AI 代理的后端服务框架，实现了 Model Context Protocol (MCP) 的核心能力，包括对 MCP 客户端的代理、对工具调用的拦截与评估、对提示/上下文的管理，以及一个与 LLM 直接交互的网关组件。系统提供多种传输方式（stdio、HTTP、SSE 等），并附带日志审计、策略引擎和 MCP 客户端的自动化配置能力，为本地 AI 代理提供安全、可扩展的上下文服务。

  • 主要功能点

    • MCP 代理实现（stdio 代理）：在本地将 MCP 客户端与 MCP 服务器之间的调用进行拦截、策略化处理后转发。
    • MCP HTTP 网关：对 MCP Tool 调用进行策略检查、阶段性评估（Stage 2）、并对结果进行日志审计和统计。
    • LLM 网关：拦截并对外部 LLM 的请求进行 PII 去识别、工具调用分析、以及多 PROVIDER 支持（OpenAI/Anthropic 自动识别）。
    • 资源与工具管理：支持对 MCP 客户端的工具列表进行过滤/隐藏，记录工具调用历史与敏感路径标签。
    • Prompts 管理与渲染：通过诊断、评估流程输出可观测的提示和回答，包含警报与决策结果的日志。
    • 自动化 MCP 客户端配置（mcp-setup、mcp-proxy、wrap/unwrap 功能）：为 Claude/Kiro/Cursor/VS Code 等客户端自动封装与解封装 MCP 服务端代理配置。
    • 安全特性与审计：网页版 UI、JSON Lines 审计日志、Webhook 回调等，支持在本地直接评估和回放。

  • 安装步骤

    • 获取源码并编译：将代码克隆到本地，使用 Go 1.20+ 构建并运行 main 程序（go build 或 go run）。
    • 启动 AgentGuard：直接执行程序，默认监听端口为 10180，LLM 网关默认开启，目标后端 MCP 服务器为本地 18789 端口的 OpenClaw 实例。
    • 配置环境变量（选配）：
      • AGENTGUARD_PORT 指定代理端口（默认 :10180）
      • AGENTGUARD_LLM_ENABLED 指定是否开启 LLM 网关
      • AGENTGUARD_LLM_PORT 指定 LLM 网关端口
      • AGENTGUARD_GATE_ENABLED 指定是否开启 Stage 2 审核
      • 其他如 CI、审计、PII 去识别等开关可按需启用

  • MCP 服务器配置（说明） 说明 MCP 客户端需要向 AgentGuard 的 MCP 服务器启动命令和参数，以便通过 MCP 网关进行统一的策略控制与工具拦截。以下为描述性配置信息示例（不以代码块呈现，便于理解）：

    • 服务器名称：filesystem
    • 启动命令（command）：AgentGuard 可执行文件的完整路径，例如 /path/to/agentguard
    • 启动参数（args）：应包含 mcp-proxy 的包装参数，例如 ["mcp-proxy","--target","npx -y @modelcontextprotocol/server-filesystem /tmp","--policy","/path/to/mcp-policy.json"]
    • 说明：wrap 过程在 MCP 客户端端配置时会将原始命令封装为通过 AgentGuard 的 mcp-proxy 启动，目标是对 MCP 调用进行策略化过滤与审计。若客户端已被 AgentGuard 封装过，将跳过封装。
    • 同类服务器配置（示例）：
      • 服务器名称：database
      • 启动命令（command）：AgentGuard 可执行文件的完整路径，例如 /path/to/agentguard
      • 启动参数（args）：["mcp-proxy","--target","npx server-postgres postgresql://localhost/mydb","--policy","/path/to/mcp-policy.json"]

  • 基本使用方法

    • 启动并对接 MCP 客户端：
      • 在本地启动 AgentGuard，使其监听 :10180 端口，OpenClaw/MCP 服务器在 18789 端口。
      • 使用 MCP 客户端与 AgentGuard 构成的代理进行通信，客户端通过 agentguard 封装的代理启动命令来实现对 MCP 调用的拦截与策略执行。
    • 使用 MCP HTTP 网关的方式：
      • 通过 AgentGuard 的 MCP HTTP 网关对 Tool 调用进行拦截、策略评估和审计，返回阻断或通过的响应，确保 LLM 调用在合规范围内执行。
    • 观察与诊断：
      • 通过 /agentguard/stats 端点查看请求量、阻塞率、LLM 网关统计等。
      • 通过 /api/audit 查看统一审计日志，必要时结合 webhook 进行告警。

服务器信息

访问项目