PEAC Protocol: Signed interaction receipts

@peac/mcp-server

用于 PEAC 签名交互记录的本地 MCP 服务。它通过 stdio 或本地 Streamable HTTP 传输，提供验证、检查、解码、签发和打包 PEAC 记录的工具。

安装

pnpm add @peac/mcp-server

或者直接运行：

npx @peac/mcp-server

功能

@peac/mcp-server 将 PEAC 签名交互记录操作作为 Model Context Protocol（MCP）工具提供，供 AI Agent 和基于 LLM 的应用调用。它支持 stdio 和 Streamable HTTP 两种传输方式，并提供静态策略检查、并发限制、输入大小防护，以及包含恢复提示的结构化错误响应。

如何使用？

添加到 Claude Desktop

将以下内容添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "peac": {
      "command": "npx",
      "args": ["-y", "@peac/mcp-server"]
    }
  }
}

添加到 Cursor 或 Windsurf

将以下内容添加到项目根目录下的 .mcp.json：

{
  "mcpServers": {
    "peac": {
      "command": "npx",
      "args": ["-y", "@peac/mcp-server"]
    }
  }
}

Streamable HTTP 传输

npx @peac/mcp-server --transport http --port 3000

HTTP 传输提供按会话隔离、速率限制和 RFC 9728 PRM 发现功能。默认绑定到 127.0.0.1。端到端演示请参阅 examples/mcp-http-quickstart/。

启用回执签发

npx @peac/mcp-server \
  --issuer-key env:PEAC_ISSUER_KEY \
  --issuer-id https://example.com

使用 HTTP 传输启动

npx @peac/mcp-server --transport http --port 3000

CLI 选项

标志	说明	默认值
--transport <type>	传输方式：stdio 或 http	stdio
--port <number>	HTTP 端口	3000
--host <address>	HTTP 绑定地址	127.0.0.1
--issuer-key <ref>	签发方密钥引用（env:VAR 或 file:/path）	无
--issuer-id <uri>	签发方标识符 URI	无
--policy <path>	策略配置文件路径	内置默认值
--jwks-file <path>	用于解析验证密钥的 JWKS 文件	无
--bundle-dir <path>	证据包输出目录	无
--cors-origins <list>	允许的 CORS 来源（逗号分隔，仅限 HTTP）	无
--trust-proxy <value>	信任 X-Forwarded-For（off、loopback、private）	off

以编程方式使用

无需绑定 MCP 服务即可直接使用处理程序：

import { createPeacMcpServer, handleVerify } from '@peac/mcp-server';
import { getDefaultPolicy, computePolicyHash } from '@peac/mcp-server';

const policy = getDefaultPolicy();
const policyHash = await computePolicyHash(JSON.stringify(policy));

const result = await handleVerify({
  input: { jws: 'eyJ...', public_key_base64url: '...' },
  policy,
  context: {
    version: '0.16.5',
    policyHash,
    protocolVersion: '2025-11-25',
  },
});

可用工具

工具	说明	可用条件
peac_verify	验证 PEAC 签名交互记录。	始终可用
peac_inspect	检查 PEAC 签名交互记录，但不进行验证。	始终可用
peac_decode	解码 PEAC 回执 JWS 头部和载荷，以供诊断。	始终可用
peac_issue	根据提供的声明签发 PEAC 签名交互记录。	需要 --issuer-key 和 --issuer-id
peac_create_bundle	根据签名记录及相关材料创建 PEAC 包。	需要 --issuer-key、--issuer-id 和 --bundle-dir

所有结构化工具输出都包含一个由架构声明的 _meta 审计区块，其中包含 serverVersion、policyHash、protocolVersion 和 registeredTools。此区块与顶层 MCP _meta 载体相互独立，后者由 @peac/mappings-mcp 用于附加 PEAC 回执引用。

集成

• @peac/protocol（第 3 层）：签名记录的签发与验证
• @peac/crypto（第 2 层）：JWS 签名与解码
• @peac/schema（第 1 层）：回执架构验证
• @peac/kernel（第 0 层）：错误代码与常量
• @modelcontextprotocol/sdk：MCP 服务与传输绑定

面向 Agent 开发者

通过 stdio 或 HTTP 将你的 Agent 连接到此服务，即可使用签名记录验证、回执解码和签发功能。这些工具使用结构化输出，其中包含错误代码和 next_action 恢复提示，便于你的 Agent 以编程方式处理故障。每个响应都包含 _meta，用于审计和追踪。

只读工具（peac_verify、peac_inspect、peac_decode）无需配置即可使用。若要启用签发功能，请通过 --issuer-key 和 --issuer-id 提供 Ed25519 签名密钥。

面向运维人员

此服务会执行静态策略检查，并支持配置并发限制、输入大小上限、JWS 大小上限和工具超时。HTTP 传输默认绑定到 localhost，并拒绝所有 CORS 请求。stdout 防护机制可避免非 JSON-RPC 输出破坏 stdio 传输。

安全特性：不自动发现密钥（必须显式提供密钥）、工具处理程序不会隐式发起网络请求、可防止 bundle 输出路径遍历，以及 HTTP 传输中的会话隔离。

许可证

Apache-2.0

---

PEAC Protocol 是由 Originary 和社区贡献者共同维护的开源项目。

文档 | GitHub | Originary