Guardrail MCP 服务器端实现

关键词

GuardrailsModel Context ProtocolSSEJSON-RPCTools

使用说明

  • 项目简介

    • 该仓库实现了一个完整的 MCP 服务器，遵循 MCP 标准，提供对资源（Resources）、工具（Tools）及提示模板（Prompts/Prompts 渲染）的托管、注册与执行能力，并通过 JSON-RPC 与客户端通信。服务器端包含会话管理、能力声明、日志与鉴权、以及基于 SSE 的实时消息推送。还提供 Web UI 用于管理和监控。

  • 主要功能点

    • MCP 核心端点与协议支持：实现 SSE 流式端点、JSON-RPC 消息处理，以及会话管理。
    • 17 个 MCP Tools、8 个 MCP Resources（如快速参考、活跃规则、文档等）供 LLM/代理调用和查询。
    • 数据存储与缓存：PostgreSQL 16、Redis 7 集成，提供持久化与高速缓存能力。
    • 会话与权限：对会话、Agent 类型、项目上下文进行管理，提供基于密钥的鉴权路径。
    • 安全与监控：内置的中间件、健康检查、指标采集与日志记录，配套网页 UI。
    • Web UI 与 API：提供 Web UI 进行规则、项目、失败记录等的可视化管理，以及 REST 风格的扩展端点。

  • 安装步骤

    • 打包与部署（常见做法）：
      • 使用 Docker 构建镜像并部署：
        • 构建镜像 guardrail-mcp: docker build -t guardrail-mcp:latest -f deploy/Dockerfile .
        • 启动部署（Podman/Docker Compose 皆可）：参见 deploy 目录的 podman-compose.yaml 或 docker-compose.yaml。
      • 使用 Podman/Docker Compose 启动后可以验证 health：
        • 通过 health/ready 端点检查 MCP 服务是否就绪
        • 访问 /web 获取 Web UI 管理界面
    • 运行时要求包含 PostgreSQL 16、Redis 7 等外部依赖，按部署指南配置环境变量（数据库、缓存、密钥等）。
    • 更多部署方式与排错信息请参阅仓库中的 DEPLOYMENT_GUIDE.md 与 README 中的部署章节。

  • 服务器配置（客户端使用的连接信息描述）

    • MCP 客户端连接配置并非必需在客户端端执行代码层面的配置。客户端通常只需知道 MCP 服务器的地址和认证信息即可建立连接。以下为配置要点的描述性说明（非代码片段）：
      • 服务器名称（serverName）：guardrail-mcp（标识 MCP 服务）
      • 启动命令（command）：用于运行 MCP 服务器的可执行文件，例如容器内入口命令或二进制启动命令
      • 参数（args）：启动参数，例如端口号、数据库、缓存地址、JWT 秘钥等环境相关参数（具体取值请参考部署文档中的环境变量说明）
    • 重要提示：MCP 客户端本身不需要在此处包含自定义的应用逻辑启动参数；客户端通过服务器地址与认证信息与 MCP 服务器进行通信，无须嵌入服务器端启动命令的具体实现。

  • 基本使用方法

    1. 部署后启动 MCP 服务器，确保数据库与缓存服务可用。
    2. 使用 SSE 端点获取 endpoint，或通过 /mcp/v1/message?session_id=<session_id> 进行 JSON-RPC 2.0 请求。
    3. 调用 tool（如 guardrail_init_session、guardrail_validate_bash 等）进行上下文创建、命令/编辑/提交等动作的校验与执行。
    4. 使用 Web UI 管理规则、资源和项目等，查看会话、失败登记和执行历史。
    5. 结合客户端离线/IDE 集成对接，完成对代码、命令、提交等动作的实时 guardrail 验证。

  • 备注

    • MCP 服务在实现中提供了大量工具、资源与端点，且具备示例、文档与 Web UI 支持，适合在 AI 代理、IDE 集成、以及生产级工作流中作为上下文与能力服务的后端。具体部署参数、环境变量与端口映射请结合仓库文档逐步配置。

服务器信息

访问项目