使用说明

🔐 MCP见证

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

pip install mcp-witness
mcp-witness quickstart

✨ 为什么是mcp证人？

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

功能	mcp见证	标准日志记录
篡改检测	✅ SHA-256哈希链+默克尔树❌ 文本文件，易于编辑
O（log n）验证	✅ 带有自动回填功能的Merkle检查点	❌ 仅线性扫描
不可否认性	⚠️ Ed25519记录签名（需要持久密钥）	❌ 没有
外部锚固	✅ TSA、比特币（OTS）、IPFS	❌ 没有
合规预设	✅ HIPAA、GDPR、SOX、PCI DSS、FedRAMP、SOC2	❌ 手动配置
PII/PHI编辑	✅ 加密哈希	❌ 纯文本或手册
GDPR删除权✅ `witness_delete` 带链条保护	❌ 破坏性删除
法律等级证明	⚠️ RFC 3161时间戳（严格模式默认值；降级模式下的本地证明）	❌ 没有
链条故障警报	✅ Webhook通知	❌ 无声的失败
多租户	✅ org_id隔离	❌ 没有
报告	✅ HTML+PDF合规报告	❌ 手册
仪表板	✅ 带有实时API的Web仪表板	❌ 没有
结构化日志记录	✅ JSON日志格式选项	❌ 非结构化

🔒 保证水平

级别	描述	当前
ASSURANCE-1	尽力记录，无加密保证	--
ASSURANCE-2	哈希链+默克尔树，篡改EVIDENT，可配置锚定	✓
保证-3	不可否认性（Ed25519）、严格锚定、静态加密、正式威胁模型	v1.0.0

截至 v1.0.0，mcp证人是 默认安全：它拒绝在没有持久签名密钥，如果链在启动时没有验证，则失败关闭。每默认情况下有一个退出选项——请参阅 docs/configuration.md.

⚠️ 已知限制

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

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

静态加密是可选的。 集 MCP_WITNESS_ENCRYPTION_KEY （32字节十六进制）到启用AES-256-GCM字段级信封加密。没有它，敏感领域以明文JSON格式存储。

⬆️ 从0.9.x升级

v1.0.0更改了几个默认值。要顺利升级：

设置签名密钥： export MCP_WITNESS_SIGNING_KEY=$(openssl rand -hex 32) （或 MCP_WITNESS_REQUIRE_PERSISTENT_KEY=false 保存临时密钥）。
请先验证您的链： mcp-witness verify （或设置 MCP_WITNESS_FAIL_ON_STARTUP_VERIFICATION_FAILURE=false).
如果webhook以内部收集器为目标，请设置 MCP_WITNESS_ALLOW_INTERNAL_WEBHOOKS=true.

请参阅完整配置参考和安全.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": "<32-byte hex key>",
        "MCP_WITNESS_SIGNING_KEY": "<32-byte hex seed for Ed25519>",
        "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个）

工具	说明
`witness_record`	将AI操作记录到不可变的审计跟踪中
`witness_verify`	验证哈希链完整性（检测篡改）
`witness_verify_fast`	使用Merkle检查点进行O（logn）验证
`witness_query`	按会话、演员、工具、时间搜索记录
`witness_chain`	获取会话的完整决策链
`witness_stats`	获取审计跟踪统计数据和运行状况
`witness_health`	检查数据库连接、签名状态、锚点、版本
`witness_attest`	来自外部权威机构的RFC 3161时间戳
`witness_export`	导出合规报告记录
`witness_delete`	GDPR删除权（数据编辑，链保留）
`witness_search`	跨推理/输入/输出数据的全文搜索
`witness_checkpoints`	列出Merkle检查点
`witness_anchor`	将检查点锚定到TSA/比特币/IPFS
`witness_verify_anchors`	验证外部锚收据
`witness_proof`	获得单个记录的Merkle证明
`witness_backfill`	为现有记录创建检查点
`witness_configure_compliance`	应用HIPAA/GDSGVO/SOX/FedRAMP/SOC2/PCI DSS预设
`witness_token`	创建Ed25519签名的JWT进行客户端身份验证

🏛️ 合规预设

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

# 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

预设	保留	自动重置	证明	不可变
HIPAA	6年	12个PHI字段	✅ 必填	--
GDPR	按目的	12个PII字段	✅ 必需	删除权
SOX	7年	7个金融领域	✅ 必填	✅ 是的
FedRAMP	3年	6个CUI领域	✅ 必填	--
SOC 2	1年	7个字段	✅ 必填	--
PCI DSS	1年	7个卡字段	✅ 必填	--

📊 运作原理

哈希链+默克尔树+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 为空数据字段，但保留哈希链——记录可以在不破坏完整性验证的情况下进行编辑。

验证性能

记录	全链	带检查点
1000	~100ms	~100ms
10000	~1s	~100ms
100000	~10s	~1s
1000000	~100秒	~10秒

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

🔒 安全

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

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

🐳 码头工人

# Build
docker build -t mcp-witness .

# Run MCP server (stdio)
docker run -v witness-data:/data mcp-witness serve

# Run web dashboard
docker run -v witness-data:/data -p 9090:9090 mcp-witness dashboard

# With PostgreSQL
docker run -v witness-data:/data \
  -e MCP_WITNESS_BACKEND=postgresql \
  -e MCP_WITNESS_PG_URL=postgresql://user:pass@host:5432/db \
  mcp-witness serve

🧪 发展

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

CI/CD管道

职位	描述
棉绒	ruff+黑色格式检查
测试	Python 3.10、3.11、3.12中的251个测试，覆盖率≥65%
测试postgres	Postgres 16上的12个PostgreSQL集成测试
安全	pip审计漏洞扫描
建造	包装构建+烟雾测试

🗺️ 路线图

[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）
[x] 对抗强化——TSA严格模式、规范签名、加密敏捷性、密钥生命周期（v0.9.0）
[x] 默克尔证明严格验证+信封加密+度量（v0.9.0）
[x] PostgreSQL完整后端奇偶校验+敏感数据日志清理（v0.9.0）
[x] 默认强化安全——所需签名密钥、故障关闭启动、SSRF保护、ASSURANCE-3（v1.0.0）
[]流媒体架构（Kafka/NATS）
[]AWS KMS/云HSM签名
[]Grafana/Prometheus指标端点
[]自定义锚点提供者的插件系统
[]后量子密码算法支持（跟踪NIST PQC）

📄 许可证

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

👤 作者

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