SpecDelta

Signed compatibility and safety receipts for MCP, OpenAI tool, and OpenAPI JSON specifications.

SpecDelta helps an AI agent or CI pipeline answer two questions before it adopts a tool:

• Is this tool description/schema safe enough to review?
• Did the candidate specification break compatibility or expand permissions?

The core engine is deterministic. It accepts JSON bodies only, never downloads URLs, never opens local files, and stores hashes and signed receipts instead of raw specifications.

Paid operations

Operation	REST	MCP	Apify event	Price
lint_spec	POST /v1/spec/lint	lint_spec	spec-lint	$0.01
compare_specs	POST /v1/spec/compare	compare_specs	spec-compare	$0.03

Free endpoints: GET /capabilities, GET /health, and GET /v1/keys/{key_id}.

Example

curl -sS http://127.0.0.1:8000/v1/spec/compare \
  -H 'content-type: application/json' \
  --data @samples/compare_breaking.json

Receipts include canonical input hashes, policy hash, status, issues, metrics, validator version, timestamp, receipt hash, Ed25519 signature, and key id.

Detection

• Removed operations and newly exposed operations
• Newly required fields, removed properties, type changes, enum narrowing
• Tightened numeric, string, and array bounds
• High-impact operation names and permission expansion
• Prompt-injection-like instructions in tool descriptions
• Invalid or unbounded JSON Schemas
• Excessive specification/context growth
• External $ref, $dynamicRef, and $recursiveRef values

Only local JSON Pointer references are resolved. The service supports a maximum request size of 2 MiB and does not accept external URLs.

Local run

python3.12 -m venv .venv
.venv/bin/pip install -e '.[test]'
.venv/bin/python -m specdelta

Open http://127.0.0.1:8000/docs. MCP is available at /mcp/ in local and Apify modes.

Development uses an ephemeral signing key. Production startup refuses to run without SPECDELTA_ED25519_PRIVATE_KEY_B64.

Signing key

$.venv/bin/python scripts/generate_signing_key.py

The command writes a new mode-0600 secret file under .secrets/ and prints only the file path, key id, and public key. It refuses to overwrite an existing file. Copy the private value into the deployment platform's Secret manager, then keep or securely delete the local file.

Apify

The project supports paid standard runs and Standby REST/OpenAPI with /mcp/. Choose lint-spec or compare-specs in the Input tab to receive the signed receipt in the run dataset and OUTPUT record. Automated Store tests remain free. Configure Pay-per-event prices exactly as follows:

• spec-lint: USD 0.01
• spec-compare: USD 0.03

Required Secret: SPECDELTA_ED25519_PRIVATE_KEY_B64. Optional ownership classification Secret: SPECDELTA_OWNER_APIFY_USER_ID.

The service persists only receipt/accounting data in its SQLite state and sends the same non-raw accounting record to the Actor dataset. See sales/APIFY_RELEASE.md.

x402

Run a separate deployment with SPECDELTA_BILLING_MODE=x402. MCP is disabled there because the payment middleware protects REST routes. Production requires the exact CDP facilitator origin, an HTTPS public origin, a receiving address, CDP credentials, and measured costs below each price.

Payment Identifier is required and must equal idempotency_key. Base Sepolia settlements are tests. The first Base mainnet settlement is classified as bazaar_indexing; owner payer hashes are classified as owner_test; only later unrelated mainnet payer hashes count as external_sale.

See sales/X402_RELEASE.md.

Verification

.venv/bin/ruff check src tests scripts
.venv/bin/ruff format --check src tests scripts
.venv/bin/pytest
.venv/bin/pip check
.venv/bin/pip-audit
.venv/bin/python scripts/generate_release_assets.py
.venv/bin/python scripts/release_check.py

Security boundaries and retained/outbound fields are documented in SECURITY.md.

한국어

SpecDelta는 AI가 사용할 MCP/OpenAI/OpenAPI 도구 명세를 검사하고, 호환성 파괴·권한 확대·위험 설명을 탐지해 Ed25519 서명 영수증을 반환합니다. URL 다운로드나 로컬 파일 읽기 기능이 없으며, 원본 명세는 저장하지 않습니다. lint_spec은 $0.01, compare_specs는 $0.03입니다.