Invariant Gateway 使用说明

Invariant Gateway 是一个轻量级的零配置服务，充当 AI 代理和 LLM 提供者（如 OpenAI、Anthropic、Gemini）之间的中间层。它能自动追踪代理与 LLM 的交互并记录，同时提供安全防护（通过 Guardrails）。该项目也特别支持 Model Context Protocol (MCP)，可以作为 MCP 客户端和 MCP 服务器之间的网关层。

主要功能点

LLM 请求代理与转发: 无缝代理转发对 OpenAI, Anthropic, Gemini 等主流 LLM API 的调用。
行为追踪与记录: 自动捕获代理的 LLM 交互（包括工具调用），并可推送到 Invariant Explorer 进行可视化分析和调试。
工具调用支持: 能够捕获和处理代理在执行工具调用时的交互。
MCP 协议支持: 支持通过标准 I/O (Stdio) 和 Server-Sent Events (SSE) 方式与 MCP 客户端/服务器交互，并在此过程中应用网关的功能。
安全防护 (Guardrails): 支持基于策略的输入/输出内容检查，可以配置拦截或记录敏感/有害信息。

安装步骤

Invariant Gateway 推荐使用 Docker 安装和运行，以简化依赖管理。

方法 1: 使用发布的 Docker 镜像 (推荐)

直接拉取并运行最新的 Docker 镜像：

docker pull --platform linux/amd64 ghcr.io/invariantlabs-ai/invariant-gateway/gateway:latest
docker run -p 8005:8005 -e PORT=8005 --platform linux/amd64 ghcr.io/invariantlabs-ai/invariant-gateway/gateway:latest

这将启动 Gateway 并监听本地 8005 端口。默认情况下，Gateway 会将追踪数据推送到 'https://explorer.invariantlabs.ai'。

方法 2: 从源代码构建并运行 (需要 Docker 和 Git)

克隆仓库：

git clone https://github.com/invariantlabs-ai/invariant-gateway.git
cd invariant-gateway

构建并启动：

bash run.sh build && bash run.sh up

这会使用 Docker Compose 构建镜像并启动 Gateway，监听本地 8005 端口。

服务器配置 (从 MCP 客户端视角)

MCP 客户端需要配置连接到 MCP 服务器的参数。对于 Invariant Gateway，取决于 Gateway 是作为 Stdio 中间层运行，还是作为 SSE 端点运行，配置方式有所不同。

作为 Stdio 中间层 (使用 'gateway mcp --exec ...' 命令)

在这种模式下，MCP 客户端需要配置执行一个外部进程作为 MCP 服务器。这个外部进程实际上是 Gateway 的 'gateway mcp' 命令，它会再启动实际的 MCP 服务器进程并作为 Stdio 中间层。

MCP 客户端（如 'mcp.client.stdio.stdio_client'）需要配置一个 'StdioServerParameters' 对象。其中：

'command': 启动 Gateway 的命令，例如 'uvx' (如果使用 'uv' 管理环境) 或 Python 可执行文件路径。

'args': 启动 Gateway 及其代理的 MCP 服务器的参数列表。格式大致如下：

[
  "--from", "<path_to_invariant_gateway_whl_file>",
  "invariant-gateway", "mcp",
  "--project-name", "<your_invariant_dataset_name>", // 可选，用于推送到 Explorer
  "--push-explorer", // 可选，启用推送到 Explorer
  "--exec", // 分隔符
  "<actual_mcp_server_command>", // 实际 MCP 服务器的启动命令
  "<arg1_for_server>", "<arg2_for_server>", ... // 实际 MCP 服务器的参数
]

'project_name': 指定用于接收追踪数据和配置 Guardrails 的 Invariant Explorer 数据集名称。
'push_explorer': 如果存在，表示将 MCP 交互追踪推送到 Invariant Explorer。
'--exec': 分隔 Gateway 自身的参数和实际 MCP 服务器的参数。
'actual_mcp_server_command', 'argN_for_server': 这是启动您实际 MCP 服务器进程的命令和参数。

'env': 环境变量，必须包含 'INVARIANT_API_KEY' 以允许 Gateway 与 Invariant Explorer 交互（获取 Guardrails, 推送追踪）。

例如，如果您的实际 MCP Stdio 服务器命令是 'python your_mcp_server.py --port 1234'，并且 Gateway 的 whl 文件路径是 '/opt/gateway.whl'，一个可能的客户端配置参数会指导其运行类似以下的命令：

uvx --from /opt/gateway.whl invariant-gateway mcp --project-name my-mcp-app --push-explorer --exec python your_mcp_server.py --port 1234

作为 SSE 端点 (使用 'gateway server up' 命令启动 FastAPI 服务器)

在这种模式下，Gateway 作为一个 HTTP 服务器运行，提供 '/api/v1/gateway/mcp/sse' 端点供 MCP SSE 客户端连接。MCP 客户端（如 'mcp.client.sse.sse_client'）需要配置连接到 Gateway 的 SSE 端点，并在请求头中告知 Gateway 实际的 MCP 服务器地址。

MCP 客户端需要配置连接参数：

'server_url': Gateway 的 MCP SSE 端点 URL，例如 'http://localhost:8005/api/v1/gateway/mcp/sse'。

'headers': HTTP 请求头，必须包含以下关键信息供 Gateway 使用：

{
  "MCP-SERVER-BASE-URL": "<The base URL to your MCP server>", // 实际 MCP 服务器的基准URL
  "INVARIANT-PROJECT-NAME": "<The Invariant dataset name>", // 可选，用于推送到 Explorer
  "PUSH-INVARIANT-EXPLORER": "true", // 可选，启用推送到 Explorer (字符串形式 "true" 或 "false")
  "Invariant-Authorization": "Bearer <your-invariant-api-key>" // 用于推送到 Explorer 和获取 Guardrails
}

'MCP-SERVER-BASE-URL': 必须提供，指定 Gateway 应代理请求转发到哪个实际的 MCP SSE 服务器。
'INVARIANT-PROJECT-NAME': 指定用于接收追踪数据和配置 Guardrails 的 Invariant Explorer 数据集名称。
'PUSH-INVARIANT-EXPLORER': 如果为 '"true"'，表示将 MCP 交互追踪推送到 Invariant Explorer。
'Invariant-Authorization': 包含 Invariant API Key，用于认证推送到 Explorer 和获取配置在 Explorer 中的 Guardrails。

基本使用方法

对于标准 LLM API（如 OpenAI Chat Completions），只需修改您 LLM 客户端 SDK 的 'base_url' 指向 Invariant Gateway 的地址（例如 'http://localhost:8005/api/v1/gateway/<可选数据集名称>/openai'），并确保请求头中包含 Invariant API Key ('Invariant-Authorization: Bearer <key>')。对于 MCP，请参考上述“服务器配置”部分，根据您使用的 MCP 传输方式配置 MCP 客户端。

更多详细的集成示例，请参考项目的 README 文档。

关键词