MCP Witness

🔐 MCP见证

每个AI决策的加密证明。 一个不可变、可验证的审计跟踪MCP服务器——因为“相信我兄弟”不符合SOC2。

pip install mcp-witness
mcp-witness quickstart

✨ 为什么是mcp证人？

AI代理做出决策。监管机构会提出问题。mcp证人提供 密码证明 关于发生了什么、何时发生以及为什么发生的事情，包括哈希链完整性、Merkle树验证、Ed25519签名、外部信任锚定（RFC 3161 TSA严格模式，可选本地证明，结构验证的开放时间戳，IPFS），以及HIPAA、GDPR、SOC2等的合规预设。

🔒 保证水平

⚠️ 电流限制（v0.6.0→ v1.0)

锚定是异步的。 首先创建记录，然后在以下情况下锚定 检查点触发器 AnchorService在记录创建和检查点锚定之间， 记录存在时没有外部信任证明。使用 witness_attest 锚定个人 立即记录。

单节点存储。 SQLite（默认）和PostgreSQL后端是单实例。 没有内置的复制、集群或HA。定期备份数据库。 看 docs/backup.md.

静态加密需要配置。 合规预设参考AES-256-GCM 但默认情况下加密不处于活动状态。集 MCP_WITNESS_DEK 启用 字段级信封加密。没有它，敏感字段将以明文形式存储 JSON。

不可否认性需要持久密钥。 Ed25519签名已实现，但默认为 转换为临时（每个进程）密钥。集 MCP_WITNESS_SIGNING_KEY 固定为32字节 用于跨会话验证不可否认性的十六进制密钥。

看 安全.md 对于完整的威胁模型。

🚀 30秒快速入门

# Install
pip install mcp-witness

# One command: init + serve
mcp-witness quickstart
# ✅ Database ready: ~/.mcp-witness/witness.db
# 📋 Next Steps:
#    1. Configure signing:  export MCP_WITNESS_SIGNING_KEY=$(openssl rand -hex 32)
#    2. Configure HMAC:     export MCP_WITNESS_HMAC_KEY=$(openssl rand -hex 32)
#    3. Start dashboard:    mcp-witness dashboard
#    4. Add to Claude:      claude mcp add witness -- mcp-witness serve

# Or go step-by-step:
mcp-witness init        # Initialize database
mcp-witness serve       # Start MCP server

# Check system health
mcp-witness stats       # Chain statistics
mcp-witness verify      # Chain integrity check
mcp-witness dashboard   # Web dashboard on :9090
mcp-witness report      # Generate compliance report

Claude桌面集成

{
  "mcpServers": {
    "witness": {
      "command": "mcp-witness",
      "args": ["serve"],
      "env": {
        "MCP_WITNESS_DB": "~/.mcp-witness/witness.db",
        "MCP_WITNESS_HMAC_KEY": "",
        "MCP_WITNESS_SIGNING_KEY": "",
        "MCP_WITNESS_CHECKPOINT_INTERVAL": "1000",
        "MCP_WITNESS_AUTO_ANCHOR": "false",
        "MCP_WITNESS_WEBHOOK_URL": "https://alerts.example.com/witness",
        "MCP_WITNESS_LOG_FORMAT": "json"
      }
    }
  }
}

🛠️ CLI参考

mcp-witness quickstart           One-command init + serve with next steps
mcp-witness serve                Start the MCP server
mcp-witness init                 Initialize database
mcp-witness verify [--fast]      Verify hash chain integrity
mcp-witness stats                Chain health dashboard
mcp-witness export [--output]    Export audit report
mcp-witness report [--format]    Generate HTML/PDF compliance report
mcp-witness proof SEQUENCE       Merkle proof for a record
mcp-witness search QUERY         Full-text search across audit records
mcp-witness checkpoints          List Merkle checkpoints
mcp-witness dashboard            Start web dashboard (default :9090)
mcp-witness anchors create ID    Anchor to TSA/Bitcoin/IPFS
mcp-witness anchors verify ID    Verify external anchor receipts

🛠️ MCP工具（共17个）

🏛️ 合规预设

一个命令。完全合规基线。

# Via MCP tool:
witness_configure_compliance(preset="hipaa")
# → 6-year retention, auto-redacts 12 PHI fields, requires attestation

witness_configure_compliance(preset="gdpr")
# → Right-to-erasure support, consent records, 12 PII fields redacted

witness_configure_compliance(preset="soc2")
# → 1-year retention, API key redaction, quarterly audit schedule

📊 运作原理

哈希链+默克尔树+Ed25519签名

Records:    [R0] → [R1] → [R2] → ... → [R999] → [R1000] → ...
           ✍️🔑    ✍️🔑    ✍️🔑              ✍️🔑       ✍️🔑
           Ed25519 Ed25519 Ed25519          Ed25519     Ed25519
                                                   ↓
                                           [Checkpoint #1]
                                           Merkle Root: abc123
                                           Covers: records 0-999
                                                   ↓
                                           [External Anchors]
                                           🕐 TSA (RFC 3161)
                                           ₿  OpenTimestamps
                                           🌐 IPFS

Merkle Tree:         root_hash
                    /         \
               hash_01        hash_23
               /    \         /    \
            h_0    h_1      h_2    h_3
             ↓      ↓        ↓      ↓
          R0:R0h  R1:R1h  R2:R2h  R3:R3h

每条记录 使用Ed25519进行不可否认性签名（如果未配置，则自动生成签名密钥）。

篡改检测： 更改任何记录→ 其哈希值发生了变化→ 签名无效→ 默克尔根变化→ 检查点无效→ 外部锚点证明了真正的根何时存在。

GDPR删除权： witness_delete 为空数据字段，但保留哈希链——记录可以在不破坏完整性验证的情况下进行编辑。

验证性能

单个记录： O（对数n） 具有Merkle证明（vs O（n）线性扫描）。

🔒 安全

• SHA-256哈希链 使用空字节分隔符以防止冲突攻击
• Ed25519记录签名 --自动生成的临时密钥，可通过env-var配置
• HMAC密钥保护 --可选的服务器端机密使哈希值不可重新计算
• RFC 3161 TSA锚定 --法定等级时间戳（严格模式；降级模式下的本地认证）
• 开放时间戳 --结构验证（完整的比特币确认需要外部OTS客户端）
• IPFS内容寻址 --带网关验证的CIDv0/CIDv1计算
• 域分离的Merkle树 --防止第二次预映像攻击
• 原子事务 — BEGIN IMMEDIATE 防止比赛条件和链叉
• 速率限制 --可配置令牌桶（数据库支持）
• 基于角色的访问控制 --基于角色的只读审计部署访问控制
• 错误清理 --堆栈跟踪永远不会泄露给客户端
• 路径遍历保护 --导出仅限于允许的目录
• 幂等性 --基于nonce的重放攻击防御，每行TTL清理
• Webhook警报 --POST到链上可配置URL的完整性失败
• 结构化日志记录 --用于生产监控的可选JSON日志格式

看 贡献.md 安全披露政策。

环境变量

🧪 发展

git clone https://github.com/edwiniac/mcp-witness.git
cd mcp-witness
pip install -e ".[dev]"
pytest -v                    # 251 unit tests
pytest --ignore=tests/test_storage_pg.py  # Skip PG (needs PostgreSQL)

CI/CD管道

🗺️ 路线图

• \[x\] 核心哈希链（v0.1.0）
• \[x\] Merkle检查点+外部锚定（v0.2.0）
• \[x\] CLI+合规预设+安全强化（v0.3.0）
• \[x\] PostgreSQL后端（v0.5.0）
• \[x\] Ed25519记录签名+不可否认性（v0.6.0）
• \[x\] GDPR删除权+模式迁移（v0.6.0）
• \[x\] 带有实时API（v0.6.0）的Web仪表板
• \[x\] HTML+PDF合规报告（v0.6.0）
• \[x\] 结构化JSON日志记录（v0.6.0）
• \[x\] 多租户（v0.6.0）
• \[x\] 链故障时的Webhook警报（v0.6.0）
• \[x\] 全文搜索（v0.6.0）
• \[\]流媒体架构（Kafka/NATS）
• \[\]AWS KMS/云HSM签名
• \[\]Grafana/Prometheus指标端点
• \[\]自定义锚点提供者的插件系统

📄 许可证

麻省理工学院——见 许可证

👤 作者

埃德温·伊萨克 --AI工程师\ · 电子邮件