Piqrypt Mcp Server

PiQrypt MCP 服务

通过模型上下文协议为 AI Agent 提供加密审计追踪

🚀 什么是 PiQrypt MCP？

PiQrypt MCP 服务通过 模型上下文协议 提供对 PiQrypt 的访问——这是面向 AI Agent 的后量子密码学审计追踪工具。

使用场景：

• 🤖 AI Agent：为每项决策签名，提供加密证明
• 📊 n8n 工作流：为自动化工作流添加审计追踪
• 🏦 交易机器人：满足自动化交易的 SEC/FINRA 合规要求
• 👥 人力资源自动化：确保 AI 招聘决策符合 GDPR
• 🏥 医疗 AI：为医疗决策提供符合 HIPAA 的审计追踪

---

📦 安装

前置条件

1. 安装 piqrypt（必需——Python 3.8+）

pip install piqrypt

MCP 服务会将所有加密操作委托给 piqrypt Python 包。 如果未安装该包，每次调用工具时，服务都会返回清晰的错误信息。

2. 安装 MCP 服务（Node.js 18+）

npm install -g @piqrypt/mcp-server

通过 npx 安装（无需全局安装）

npx @piqrypt/mcp-server

从源代码构建

git clone https://github.com/piqrypt/piqrypt-mcp-server
cd piqrypt-mcp-server
npm install
npm run build

PIQRYPT_PYTHON — 自定义 Python 环境

默认情况下，服务使用 python3（Linux/Mac）或 python（Windows）。 如果 piqrypt 安装在虚拟环境中，请将此变量设置为指向正确的解释器：

Windows

set PIQRYPT_PYTHON=C:\path\to\venv\Scripts\python.exe

Linux / Mac

export PIQRYPT_PYTHON=/path/to/venv/bin/python

若要使设置持久生效，请将其添加到 MCP 客户端配置中：

{
  "mcpServers": {
    "piqrypt": {
      "command": "piqrypt-mcp-server",
      "args": [],
      "env": {
        "PIQRYPT_PYTHON": "/path/to/venv/bin/python"
      }
    }
  }
}

---

⚙️ 配置

Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "piqrypt": {
      "command": "piqrypt-mcp-server",
      "args": []
    }
  }
}

n8n（v1.88+）

1. 安装 n8n MCP 集成
2. 将 PiQrypt MCP 服务添加到配置中
3. 通过 MCP 节点在工作流中使用

---

兼容对象

MCP 客户端

客户端	版本	备注
任何兼容 MCP 的客户端	MCP 规范 2024-11+	stdio 传输
n8n	1.88+	通过 MCP 节点
Cursor	任意	添加到 mcp 设置
VS Code	任意	添加到 mcp 设置
Continue	任意	添加到 mcp 设置
Windsurf	任意	添加到 mcp 设置

自动化平台（通过 MCP 节点）

平台	集成方式	使用场景
n8n	MCP 节点（原生）	无代码审计追踪
Make.com	HTTP 模块	由 Webhook 触发的盖章
Zapier	Webhooks + HTTP	基本事件记录

使用 PiQrypt MCP 可以审计的内容

每次工具调用都会经过相同的 4 个操作 — 签章、验证、导出、搜索。以下是不同场景下的 实际含义：

自动化交易 / 金融 任何提交订单、重新平衡投资组合 或触发交易的 Agent，都可以在执行前 为每项决策签章。签名链可导出，用于 SEC/FINRA 审计，无需任何额外基础设施。

HR 和招聘自动化 任何评估候选人、为简历打分 或分流申请者的工作流，都可以为每项决策签章。为 AI 辅助招聘提供符合 GDPR Art.22 的审计轨迹 — 谁在何时作出了什么决定，以及使用了哪些数据 （仅存储哈希，绝不存储原始数据）。

内容和发布流水线 任何起草、审批或发布内容的 Agent，都可以为每个步骤签章。当多个 AI Agent 协作且需要证明归属时，这很有用 — 哪个 Agent 按什么顺序写了什么。

DevOps 和 CI/CD 任何触发部署、合并分支 或轮换密钥的 Agent，都可以为每项操作签章。为 自主 Agent 执行的基础设施变更提供防篡改记录。

医疗保健和医疗 AI 任何诊断或分诊 Agent，都可以为每项 建议签章。提供符合 HIPAA 的审计轨迹， 将每项 AI 输出关联到可验证的 Agent 身份。

所有场景的共同模式：

[Agent makes decision]
↓
piqrypt_stamp_event    ← sign + chain
↓
[Agent executes action]
↓
piqrypt_export_audit   ← portable proof, verifiable
                          without PiQrypt installed

---

🛠️ 可用工具

1. piqrypt_stamp_event

使用加密证明为 AI 决策签名。

参数：

• agent_id（字符串，必填）：Agent 标识符
• payload（对象，必填）：决策数据
• previous_hash（字符串，可选）：用于串联的上一事件哈希

示例：

const event = await mcp.call('piqrypt_stamp_event', {
  agent_id: 'trading_bot_v1',
  payload: {
    action: 'buy',
    symbol: 'AAPL',
    quantity: 100,
    price: 150.25
  }
});

返回：

{
  "version": "AISS-1.0",
  "agent_id": "trading_bot_v1",
  "timestamp": 1739382400,
  "nonce": "uuid-...",
  "payload": { ... },
  "previous_hash": "sha256:...",
  "signature": "base64:..."
}

---

2. piqrypt_verify_chain

验证事件链的完整性。

参数：

• events（数组，必填）：要验证的事件

示例：

const result = await mcp.call('piqrypt_verify_chain', {
  events: [event1, event2, event3]
});

返回：

{
  "valid": true,
  "events_count": 3,
  "chain_hash": "sha256:...",
  "errors": []
}

---

3. piqrypt_export_audit

导出用于合规审查的审计轨迹。

参数：

• agent_id（字符串，必填）：要导出的 Agent
• certified（布尔值）：请求 PiQrypt 认证
• output_format（字符串）：json 或 pqz

示例：

const audit = await mcp.call('piqrypt_export_audit', {
  agent_id: 'trading_bot_v1',
  certified: true,
  output_format: 'json'
});

---

4. piqrypt_search_events

通过 SQLite 索引快速搜索。

参数：

• event_type（字符串，可选）：按类型筛选
• from_timestamp（数字，可选）：开始时间
• to_timestamp（数字，可选）：结束时间
• limit（数字）：最大结果数（默认值：100）

示例：

const trades = await mcp.call('piqrypt_search_events', {
  event_type: 'trade_executed',
  from_timestamp: 1739300000,
  limit: 50
});

---

📊 Vigil 仪表板（可选，免费）

每个已签章事件都会显示在 Vigil — PiQrypt 的本地监控仪表板中。

**注意：**Vigil 不会由 MCP 服务自动启动。 打开仪表板前，必须单独启动它。

piqrypt vigil
# → http://localhost:8421

免费套餐包括：链健康状态、VRS 风险评分、 7 天历史记录、CRITICAL 警报。 升级到 Pro 可获得 90 天 历史记录、TrustGate 治理和后量子 签名。

---

🗑️ 管理 Agent

Agent 会在首次签章时自动创建。查看和删除 Agent 的步骤：

1. 启动 Vigil：piqrypt vigil
2. 打开 http://localhost:8421
3. 进入 所有 Agent 视图
4. 勾选要删除的 Agent → 点击 ✕ 删除所选项
5. 确认 — 所有 Agent 删除后，Vigil 会返回欢迎界面

Agent 存储在你计算机上的 ~/.piqrypt/agents/ 中。 删除 Agent 会永久移除其密钥和事件历史记录。

---

🔒 安全模型

进程隔离

┌─────────────────────────────────────┐
│  MCP Client (any MCP-compatible client)     │
│  ↓ JSON-RPC over stdio              │
├─────────────────────────────────────┤
│  MCP Server (TypeScript/Node.js)    │  ← No crypto here
│  ↓ subprocess call                  │
├─────────────────────────────────────┤
│  Python Bridge (bridge.py)          │
│  ↓ invokes CLI                      │
├─────────────────────────────────────┤
│  PiQrypt CLI (Python)               │
│  ↓ uses                             │
├─────────────────────────────────────┤
│  Core Crypto (aiss package)         │  ← All crypto here
│  • Ed25519 / Dilithium3             │
│  • RFC 8785 canonical JSON          │
│  • Hash chains                      │
└─────────────────────────────────────┘

保障

✅ 私钥绝不会暴露给 MCP 层
✅ 所有加密操作都在 Python 中执行（Ed25519、Dilithium3）
✅ 安全性与 CLI 相同（进程隔离）
✅ 符合 RFC AISS-1.1（输出完全一致）
✅ 在调用子进程前进行输入验证

---

📚 示例

交易机器人（n8n）

[Webhook: price alert] 
    ↓
[AI Decision: buy/sell?]
    ↓
[PiQrypt MCP: stamp decision]  ← Audit trail
    ↓
[Execute trade API]
    ↓
[Database: store proof]

HR 自动化

[Upload CV]
    ↓
[AI Agent: evaluate candidate]
    ↓
[PiQrypt MCP: stamp evaluation]  ← GDPR compliance
    ↓
[Email HR team]

---

🧪 测试

# Build
npm run build

# Test bridge
python3 src/python/bridge.py stamp '{"agent_id":"test","payload":{"action":"test"}}'

# Test MCP server (manual)
node dist/index.js
# Then send MCP request via stdin

---

🔧 故障排除

Error: piqrypt is not installed in this Python environment

MCP 服务使用的 Python 解释器无法找到 piqrypt 包。

修复方法：

pip install piqrypt

如果 piqrypt 安装在虚拟环境中，而不是系统 Python 中，请将 PIQRYPT_PYTHON 设置为指向正确的解释器：

# Linux / Mac
export PIQRYPT_PYTHON=/path/to/venv/bin/python

# Windows
set PIQRYPT_PYTHON=C:\path\to\venv\Scripts\python.exe

验证服务将使用哪个 Python：

# Linux / Mac
$PIQRYPT_PYTHON -c "import aiss; print('ok')"

# Windows
%PIQRYPT_PYTHON% -c "import aiss; print('ok')"

---

📖 文档

• MCP 配置指南
• 工具参考
• n8n 集成
• 安全模型
• RFC 合规性

---

🤝 贡献

欢迎贡献！请参阅 CONTRIBUTING.md。

---

📄 许可证

MCP 服务 → MIT 许可证 - 请参阅 LICENSE PiQrypt Core → 免费层级 + 商业层级

---

🔗 链接

• PiQrypt Core：https://github.com/piqrypt/piqrypt
• MCP 协议：https://modelcontextprotocol.io
• n8n：https://n8n.io
• 文档：https://docs.piqrypt.com

---

由 PiQrypt Inc. 倾情打造 ❤️