LoopGrid MCP

LoopGrid MCP 服务 — v0.1 设计预览

通过 MCP 访问 LoopGrid 证据平面，为重大 AI 和 Agent 决策提供支持。

loopgrid-mcp 是连接 LoopGrid 的轻量级模型上下文协议（MCP）桥接层。

它允许兼容 MCP 的 AI 主机通过六个 MCP 工具记录和检索经过签名、防篡改的决策证据，同时使 MCP 层与 LoopGrid 核心运行时保持分离。

该桥接层仅通过 REST API 与 LoopGrid 通信。它不会导入 LoopGrid 内部组件、直接访问 LoopGrid 数据库、更改签名逻辑、修改证据架构，也不会更改现有 LoopGrid SDK 合约。

正式发布

当前版本：

0.1.0

可通过以下渠道获取：

• PyPI： loopgrid-mcp
• GitHub： github.com/loopgridio/loopgrid-mcp
• MCP Registry： io.github.loopgridio/loopgrid-mcp

官方 MCP Registry 条目已启用，目前指向使用本地 stdio 传输的 PyPI 0.1.0 软件包。

架构

MCP-compatible AI host/client
          |
          | stdio MCP
          v
     loopgrid-mcp
          |
          | LoopGrid REST API
          v
        LoopGrid
          |
          v
 signed, tamper-evident
 decision evidence

v0.1 版本使用本地 stdio 传输。

无需单独托管 MCP 服务、部署到 Railway 或 Render、使用 AWS 服务，或使用专为 MCP 配置的数据库。

MCP 工具

该服务提供六个工具：

• loopgrid.record_decision
• loopgrid.record_review
• loopgrid.record_action
• loopgrid.record_outcome
• loopgrid.get_evidence
• loopgrid.verify_evidence

重要安全边界

LoopGrid MCP 是证据桥接层，而不是业务操作执行器。

loopgrid.record_action 不会发起 Stripe 退款、修改 Salesforce、更改 ServiceNow，或调用其他外部业务系统。它会记录调用集成提供的证据，表明某项外部操作已经发生。

同样，loopgrid.record_outcome 会记录调用集成报告的结果。

LoopGrid 可以通过加密方式验证所捕获记录的完整性。但这种验证无法独立证明记录中有关外部世界的所有说法都属实，也无法判定其是否符合法律或监管要求。

人工审核会受到额外保护。loopgrid.record_review 已注册为 MCP 工具，但默认处于禁用状态。若要启用，操作员必须明确配置审核标志和审核者身份。模型无法选择已配置的审核者身份。

默认情况下，MCP 证据导出也不包含原始 FULL 模式披露载荷。

要求

• Python 3.10+
• 可访问的 LoopGrid v0.8.x 服务
• 本地评估时，公开的 LoopGrid GHCR 镜像即可满足需求

正常使用 Python stdio 服务不需要 Node.js。

只有在使用可选的基于浏览器的 MCP Inspector 工具时才需要 Node.js。

本项目使用官方 MCP Python SDK v2 系列：

mcp>=2,<3

快速开始

1. 启动 LoopGrid

使用 Docker 进行本地评估：

docker run --rm `
  --platform linux/amd64 `
  -p 8000:8000 `
  -v loopgrid_demo_data:/app/data `
  ghcr.io/cybertechsoft/loopgrid:edge

保持 LoopGrid 容器运行。

默认情况下，LoopGrid MCP 预期服务位于：

http://127.0.0.1:8000

2. 从 PyPI 安装 LoopGrid MCP

创建 Python 虚拟环境：

py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip

安装已发布的软件包：

pip install loopgrid-mcp

3. 检查连接

运行：

loopgrid-mcp-doctor

预期格式：

[OK] LoopGrid reachable: http://127.0.0.1:8000
[OK] version: 0.8.1-design-partner
[OK] evidence profile: 3.0-draft
[OK] database: ok
[OK] signer: local_ed25519
[OK] MCP workspace: default

禁用 LoopGrid 身份验证后，本地评估配置无需服务密钥。

4. 启动 MCP 服务

运行：

loopgrid-mcp

由于这是一个 stdio MCP 服务，直接运行时通常会等待从标准输入接收 MCP 消息。

正常使用时，兼容 MCP 的主机会为你启动此命令。

通用 MCP 客户端配置

通用客户端配置如下所示：

{
  "mcpServers": {
    "loopgrid": {
      "command": "loopgrid-mcp",
      "env": {
        "LOOPGRID_BASE_URL": "http://127.0.0.1:8000",
        "LOOPGRID_WORKSPACE": "default"
      }
    }
  }
}

在 Windows 上，某些 MCP 主机可能需要可执行文件的完整路径，例如：

.venv\Scripts\loopgrid-mcp.exe

示例请参见：

examples/mcp-client-config.windows.json

从源代码安装

用于开发或验证代码库时：

git clone https://github.com/loopgridio/loopgrid-mcp.git
cd loopgrid-mcp

py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1

python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

然后检查连接：

loopgrid-mcp-doctor

开发与验证

单元测试和协议测试

运行：

python -m pytest -ra

代码库发布检查

运行：

python .\scripts\release_check.py

REST 冒烟测试

运行：

python .\scripts\smoke_test.py

冒烟测试会创建一个合成决策，记录合成的操作和结果证据，验证该决策，并下载一个证据 ZIP 文件。

它不会调用真实的外部业务系统。

真实 stdio MCP 客户端测试

运行：

python .\scripts\mcp_stdio_test.py

此命令会使用官方 MCP Python 客户端，将 loopgrid-mcp 作为子 stdio 服务启动，并验证：

connect
  -> discover all 6 tools
  -> record decision
  -> record action evidence
  -> record outcome evidence
  -> service-side verification
  -> evidence ZIP export
  -> review tool remains disabled by default

成功运行后会显示：

[PASS] Real stdio MCP client test completed successfully.

这是 MCP 协议路径推荐的自动化发布门禁测试。

可选的 MCP Inspector

基于浏览器的 MCP Inspector 可用于手动探索，但运行或验证 LoopGrid MCP 并不需要它。

本仓库中规范的自动化协议测试仍然是：

python .\scripts\mcp_stdio_test.py

如果已安装的 MCP 开发工具能够顺畅支持 Inspector，也可以尝试：

mcp dev .\src\loopgrid_mcp\server.py

工具行为

loopgrid.record_decision

通过 LoopGrid REST API 捕获决策。

可选输入还可以追加模型证据，并评估现有的 LoopGrid 策略。

它绝不会执行 proposed_action。

示例：

{
  "decision_type": "customer_refund",
  "agent_id": "support-agent",
  "agent_version": "1.0",
  "proposed_action": {
    "tool": "stripe.refunds.create",
    "amount": 720,
    "currency": "USD"
  },
  "model": {
    "provider": "openai",
    "name": "gpt-5"
  },
  "authority": {
    "acting_for": "Acme",
    "limit_usd": 1500,
    "scope": ["refund:create"]
  }
}

loopgrid.record_review

通过 LoopGrid review 端点记录批准／拒绝审核。

此工具默认处于禁用状态。

如需主动启用：

$env:LOOPGRID_MCP_ENABLE_REVIEW_TOOL="true"
$env:LOOPGRID_MCP_REVIEWER_ID="[email protected]"

启用 LoopGrid 身份验证时，配置的服务密钥还必须具备相应的审核作用域。

loopgrid.record_action

向决策记录追加 tool_executed 证据。

它不会执行外部工具。

不能通过自由格式的 details 覆盖工具名称等规范字段。

loopgrid.record_outcome

追加 outcome_observed 证据。

调用方集成负责获取真实的下游结果。

不能通过自由格式的 details 覆盖 status 和 verified_against 等规范字段。

loopgrid.get_evidence

将可移植的 LoopGrid 证据 ZIP 文件下载到：

LOOPGRID_EVIDENCE_DIR

默认目录为：

./loopgrid-evidence

除非明确启用，否则会阻止将原始披露载荷导出为 MCP 证据：

$env:LOOPGRID_MCP_ALLOW_PAYLOAD_EXPORT="true"

loopgrid.verify_evidence

请求连接的 LoopGrid 服务验证该决策的已签名工作区链。

这是服务端验证。

如需对导出的证据包进行独立／离线验证，应使用相应的 LoopGrid 证据验证工作流，而不是在 MCP 桥接程序中重复实现该验证器。

已启用身份验证的 LoopGrid 部署

在禁用 LoopGrid 身份验证的情况下进行本地评估，无需服务密钥。

启用身份验证时：

$env:LOOPGRID_SERVICE_KEY="<scoped-service-key>"

请使用 MCP 工具所需的最小作用域。

除非确实需要管理权限，否则不要使用管理员密钥。

配置

参见：

.env.example

了解受支持的完整环境变量配置。

常见设置包括：

LOOPGRID_BASE_URL
LOOPGRID_WORKSPACE
LOOPGRID_SERVICE_KEY
LOOPGRID_EVIDENCE_DIR
LOOPGRID_MCP_TIMEOUT_SECONDS
LOOPGRID_MCP_ENABLE_REVIEW_TOOL
LOOPGRID_MCP_REVIEWER_ID
LOOPGRID_MCP_ALLOW_PAYLOAD_EXPORT

此桥接程序不会自动加载 .env。

MCP 主机应注入环境变量，或者操作员应在启动服务的环境中配置这些变量。

LoopGrid 服务 URL 属于操作员配置，而不是 MCP 工具参数。这样可以防止模型通过工具调用将桥接程序重定向到任意 LoopGrid 主机。

隐私与披露默认设置

LoopGrid 支持不同披露级别的证据工作流。

MCP 桥接程序采用保守的默认设置：

• 默认禁用人工审核记录，除非明确启用；
• 审核者身份由操作员配置；
• 默认禁用原始 FULL 模式载荷导出；
• 已启用身份验证的部署应使用限定作用域的服务密钥；
• MCP 桥接程序本身绝不会执行外部业务操作。

仓库边界

LoopGrid 核心与 LoopGrid MCP 有意保持分离：

github.com/cybertechsoft/loopgrid
    core LoopGrid evidence infrastructure

github.com/loopgridio/loopgrid-mcp
    MCP protocol bridge

MCP 桥接程序仅通过 HTTP 与 LoopGrid 核心运行时通信。

验证状态

LoopGrid MCP 0.1.0 已在 Windows 上针对公开的 LoopGrid 0.8.1-design-partner 容器完成验证。

验证包括：

• 干净的仓库安装；
• Python 单元测试／协议测试；
• REST 连通性；
• 合成决策创建；
• 操作证据记录；
• 结果证据记录；
• 服务端加密验证；
• 可移植证据 ZIP 导出；
• 官方 MCP Python 客户端 stdio 协商；
• 发现全部六个 MCP 工具；
• 确认审查工具默认保持禁用。

官方 MCP Python 客户端已成功协商 MCP 协议：

2026-07-28

详细的发布门禁记录请参阅 VALIDATION.md。

MCP Registry

LoopGrid MCP 已发布到官方 MCP Registry：

io.github.loopgridio/loopgrid-mcp

当前 Registry 版本：

0.1.0

Registry 元数据：

Status: active
Latest: true
Package registry: PyPI
Package: loopgrid-mcp
Transport: stdio

Registry 条目可公开发现，并指向：

https://github.com/loopgridio/loopgrid-mcp

对应的 Python 包已发布为：

loopgrid-mcp==0.1.0

本 README 顶部附近的隐藏所有权标记：

会有意保留，因为它用于 MCP Registry 包所有权验证。

后续发布时：

1. 更新包版本；
2. 将 server.json 更新为相同版本；
3. 运行仓库验证套件；
4. 将新版本发布到 PyPI；
5. 确认该包可公开安装；
6. 使用 mcp-publisher 验证 server.json；
7. 将对应版本发布到 MCP Registry。

发布定位

0.1.0 是设计预览版，并非生产正式版。

此版本旨在验证适用于 LoopGrid v0.8.x 的干净 MCP 集成路径，而不更改 LoopGrid 的签名、哈希链、证据包、验证或 SDK 契约。

LoopGrid 提供已签名且具备防篡改能力的证据，以及仅追加的决策历史。验证可确认已捕获记录的完整性，但不会判定其是否符合法律规定。

许可证

Apache-2.0。

请参阅 LICENSE。