Skip to main content
Glama
wfengq

artifactdiff-mcp

by wfengq

ArtifactDiff

面向人类与 AI 代理的合同变更验证门禁。

在文档交付之前,证明 AI 代理仅修改了你授权的 Office/PDF 合同条款——无论是语义、视觉还是密码学层面。

ArtifactDiff 以本地优先、离线运行为设计原则。它将诸如“将付款窗口从 30 天改为 45 天”的请求编辑转化为冻结的策略,验证候选文档,并生成不可变的 Review Bundle,供人类和代理共同检查。

项目状态:0.1.0 alpha。合同安全核心与签名 Golden Path 已实现,并覆盖超过 900 项自动化测试。打包与公开发布自动化仍在进行中。

它能捕获什么

候选情况

判定

交付门禁

仅修改了被授权的确切条款出现位置

通过

可继续

编辑在语义上被允许,但存在无法解释的布局变化

审查

阻塞,直到人类批准该发现

一方、金额、日期、签名、印章、附件或其他受保护内容发生变更

失败

阻塞且不可批准

ArtifactDiff 刻意采用失败即关闭的策略。审查默认保持阻塞,且 FAIL 发现无法被批准绕过。

Related MCP server: Decapod Intent Kernel

三分钟 Golden Path

前提条件:Python 3.11+ 以及本仓库的本地检出。演示仅使用合成合同,依赖安装后不发起任何网络请求。

python -m venv .venv
# Activate .venv using your shell, then:
python -m pip install -e ".[dev]"
python scripts/run_contract_golden_path.py --output build/contract-golden-path
python -m json.tool build/contract-golden-path/summary.json

运行将生成三个独立验证、Ed25519 签名的 Review Bundle:

authorized    raw=pass    effective=pass
review        raw=review  effective=review
unauthorized  raw=fail    effective=fail

review 案例保持阻塞。要演示带显式模拟合成人类审查者的签名事件链转换,请使用不同的输出目录:

python scripts/run_contract_golden_path.py --output build/contract-golden-path-approved --approve-review

--approve-review 仅用于演示。真实批准仍是通过 artifactdiff review 或 artifactdiff approve 进行的交互式人类操作;代理无法批准自己的发现。有关生成的文件和隐私边界,请参阅 Golden Path 演练。

工作流程

Human instruction
      │
      ▼
contract-safe policy ── freeze + optional Ed25519 authorization
      │
      ▼
controlled agent edit session
      │
      ▼
semantic rules + protected entities + visual envelope
      │
      ├── PASS ───────────────────────────────► deliver
      ├── REVIEW ─► signed per-finding review ─► deliver or reject
      └── FAIL ───────────────────────────────► reject
                          │
                          ▼
                 immutable Review Bundle

Review Bundle 是系统记录。本地审查台只是该 bundle 之上的经过身份验证的回环接口。

人类与自动化接口

相同的应用边界驱动所有接口:

  • CLI: 创建/验证/密封策略、打开受控会话、验证变更、检查发现、批准发现,以及验证或打包 bundle。

  • 本地审查台: 检查 bundle 并一次签署一个发现,而无需将合同或私钥发送到浏览器 JavaScript。

  • MCP: 为 AI 代理提供受限的检查/草拟/验证/本地验证工具,具有独立的输入和输出根,且不具备批准或验证签名能力。

  • 离线 HTML: 与已验证事实关联的可移植人类审查报告。

artifactdiff --help
artifactdiff policy --help
artifactdiff verify --help
artifactdiff review path/to/review-bundle

对于 MCP 主机,在启动 stdio 服务器之前,请配置以路径分隔符分隔的绝对根目录:

ARTIFACTDIFF_MCP_INPUT_ROOTS=/absolute/contracts
ARTIFACTDIFF_MCP_OUTPUT_ROOTS=/absolute/artifactdiff-output
artifactdiff-mcp

MCP 有意无法批准发现或执行验证签名。

为什么这不是另一个 PDF 差异工具

普通文档差异

ArtifactDiff

显示所有变更内容

证明变更是否匹配预先授权的指令

文本或像素是最终结果

语义、受保护实体、出现位置、元数据和视觉规则合并为一个门禁

截图/报告是证据

内容寻址的 Review Bundle,包含策略、事实、判定、证据、签名和仅追加的决策

仅设计给查看两个文件的人

CLI、Python、MCP、离线报告和人工审查台共享同一真相模型

“看起来没问题”可能通过

REVIEW 和不可用证据默认阻塞

安全与隐私模型

  • 本地优先且离线;无需账户或云服务。

  • contract-safe 默认启用,且无隐式授权。

  • 精确的预期编辑绑定到其条款和出现位置。

  • 各方、金额、货币、日期、持续时间、百分比、页眉、页脚、签名、印章和附件默认受保护。

  • 离线 Ed25519 是核心信任机制;企业身份可通过适配器后续添加。

  • 证据默认 minimal;full 为显式,sealed 为对指定接收者加密。

  • MCP 响应受限,不返回完整合同、页面图像或密钥材料。

阅读已批准的 验证门禁设计 和 Plan 4.5 验收记录 以了解完整的信任与判定模型。

当前格式支持

  • PDF → PDF

  • DOCX → DOCX

  • DOCX → PDF

  • 英文、中文及双语合同结构

  • 可选通过 LibreOffice 渲染 DOCX;PDF 渲染为本地进行

开发

python -m pip install -e ".[dev]"
python -m pytest -q

仓库目前包含单元、集成、篡改、CLI、MCP、审查台、跨格式以及签名 Golden Path 验收覆盖。

后续里程碑

  • 可复现的公开合成语料库和零误通过门禁

  • 用于二进制文档拉取请求审查的 GitHub Action

  • 演示媒体和可下载的示例 Review Bundle

  • 模式、威胁模型、SBOM、来源和签名 alpha 发布

  • 面向企业解析器、渲染器、签名、加密和存储的插件边界

ArtifactDiff 围绕一个狭窄的承诺构建:当代理编辑合同时,你可以精确证明它被允许更改的内容——以及它没有更改其他任何内容。

Available Tools

10 tools
compare_documentsD
ParametersJSON Schema
NameRequiredDescriptionDefault
forceNo
visualNo
after_pathYes
output_dirNo
before_pathYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

draft_contract_policyD
ParametersJSON Schema
NameRequiredDescriptionDefault
afterYes
anchorYes
beforeYes
headingYes
rule_idYes
clause_labelYes
ancestor_pathNo
baseline_pathYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_review_findingD
ParametersJSON Schema
NameRequiredDescriptionDefault
finding_idYes
bundle_pathYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

inspect_contractD
ParametersJSON Schema
NameRequiredDescriptionDefault
pathYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

inspect_documentD
ParametersJSON Schema
NameRequiredDescriptionDefault
pathYes
forceNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_review_findingsD
ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
cursorNo
bundle_pathYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

seal_local_policyD
ParametersJSON Schema
NameRequiredDescriptionDefault
output_pathYes
policy_pathYes
baseline_pathYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

validate_contract_policyD
ParametersJSON Schema
NameRequiredDescriptionDefault
policy_pathYes
baseline_pathYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

verify_contract_changeD
ParametersJSON Schema
NameRequiredDescriptionDefault
visualNo
output_pathYes
baseline_pathYes
candidate_pathYes
sealed_policy_pathYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

verify_review_bundleD
ParametersJSON Schema
NameRequiredDescriptionDefault
bundle_pathYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 10 tool updatesv0.1.0
    • First observedcompare_documents
    • First observeddraft_contract_policy
    • First observedget_review_finding
    • First observedinspect_contract
    • First observedinspect_document
    • First observedlist_review_findings
    • First observedseal_local_policy
    • First observedvalidate_contract_policy
    • First observedverify_contract_change
    • First observedverify_review_bundle

TDQS

D1.9/5.0

Scored across 10 tools

Disambiguation2/5

The tool set includes several pairs with ambiguous boundaries: inspect_document vs inspect_contract likely overlap, and compare_documents vs verify_contract_change seem to address similar tasks. Without descriptions, an agent would struggle to distinguish which tool to call for a given operation.

Naming Consistency5/5

All tools use a clear snake_case verb_noun pattern (compare, inspect, draft, validate, seal, verify, list, get). Consistency is high and follows a predictable convention.

Tool Count5/5

10 tools is within the ideal range for a domain covering document comparison and contract policy management. The count is well-scoped with no obvious bloat.

Completeness4/5

Core workflows for contract policy drafting/validation/sealing and review finding retrieval are covered. However, there is no tool for listing or managing documents/contracts, and the generic artifact diffing implied by the server name is thin, leaving minor but noticeable gaps.

Maintenance

ActivityActive
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    D
    maintenance
    Provides cryptographic governance receipts for AI agents, enabling pre-execution evaluation and signed verdicts (EXECUTE/BLOCK/REVIEW/SHADOW) with offline-verifiable audit trails.
    MIT
  • F
    license
    Not graded
    quality
    C
    maintenance
    Enables AI agents to propose wallet payments while a local, human-authored policy decides whether each transaction is approved, requires human confirmation, or is refused, and records every decision in a signed, append-only ledger.
    -
  • A
    license
    Not graded
    quality
    B
    maintenance
    Enables users' AI agents to join signed, hash-chained rooms with another person's agent to negotiate, coordinate, or hand off work, while a locally enforced mandate filters every outbound message. Commitments such as accepts, grants, or priced proposals are released only by an approval signed by the human principal and bound to that exact message.
    63 npm
    Apache 2.0