MCP Source Evidence

MCP Source Evidence turns a complete source snapshot supplied to WordPress into an immutable, content-addressed evidence package. A consuming workflow can rely on exact files, excerpts, statements, and a current-snapshot receipt without depending on an external hosting account or release channel.

• Stable tag: 0.1.4
• Tested up to: WordPress 7.0
• License: GPLv2 or later
• Tags: mcp, evidence, local snapshots, WordPress abilities, source verification

What It Does

The plugin accepts one bounded ZIP snapshot through an authenticated WordPress Ability. It verifies the complete archive, validates curated excerpts against the exact file bytes, optionally checks a declared inventory of direct WordPress Ability registrations, builds an immutable Evidence Package, and atomically makes that revision current for its source key.

Each package records:

• the local source key, archive root, and snapshot SHA-256;
• every file path, byte count, and SHA-256 in the archive;
• exact evidence statements, excerpts, locators, kinds, and authority labels;
• a deterministic package revision derived from canonical package content.

The Real Workflow

1. Prepare a complete ZIP snapshot from the locally authoritative source.
2. Declare the snapshot's source key, archive root, expected Ability inventory, and required evidence kinds.
3. Supply curated evidence items whose excerpts occur verbatim in the snapshot.
4. Call mcp-source-evidence/capture-package with explicit ingestion confirmation and the expected current revision.
5. Store the returned package revision in the consuming workflow.
6. Request a current-snapshot receipt immediately before the consumer changes public state.

The first capture for a source key expects an empty current revision. A later capture must name the exact current revision it replaces. Concurrent or stale activation attempts fail closed.

Why This Feels Different

Loose research notes can drift away from the code or documentation they describe. MCP Source Evidence binds every accepted statement to exact bytes inside one complete snapshot and gives consumers a small currentness Interface they can check before acting.

The snapshot is supplied directly to WordPress. Continued capture, package reads, currentness checks, and consumer operation do not require a remote repository, release provider, or third-party account.

Before vs After

Before

• Claims can point to mutable pages or manually copied notes.
• Capability inventories can describe different source bytes.
• A newer source snapshot may not invalidate an older review.
• Every consumer must invent its own archive and excerpt checks.

After

• One complete snapshot produces one immutable package revision.
• Every accepted excerpt is verified verbatim against an exact file.
• Activating a new snapshot immediately supersedes the prior current revision.
• Consumers share one package and current-snapshot Interface while keeping their own editorial rules.

Who It Is For

• WordPress workflows that require factual evidence before publication.
• MCP and Abilities integrations that need source-bound capability evidence.
• Review systems that require exact citations instead of unstructured notes.
• Automation that must stop when its source snapshot changes.

Requirements

• WordPress 6.9 or later.
• PHP 8.0 or later with ZipArchive.
• WordPress Abilities API and an MCP exposure layer when calling the Ability through MCP.
• An authenticated user with manage_options for snapshot capture.
• A complete ZIP snapshot no larger than 8 MiB when compressed.

Documentation

• MCP Source Evidence product page
• Stable plugin download

Start Here

1. Install and activate the plugin with the WordPress Abilities API and your MCP exposure layer.
2. Create a complete ZIP whose files share one archive root.
3. Derive each evidence excerpt and any expected Ability name from that exact snapshot.
4. Capture the package and retain its package_revision in the owning consumer.
5. Re-read the package and verify it is still current before mutation.

Public Interfaces

WordPress Ability

PHP Interfaces

Usage Example

The complete ZIP is sent as canonical base64. The abbreviated value below is only a placeholder for readability.

{
  "source_key": "example_plugin",
  "archive_base64": "<canonical base64 of the complete ZIP>",
  "archive_root": "example-plugin",
  "expected_current_revision": "",
  "ability_inventory_mode": "literal_wp_register_ability_calls",
  "expected_abilities": [
    "example/read"
  ],
  "required_evidence_kinds": [
    "identity",
    "claim_support",
    "scope_boundary"
  ],
  "evidence_items": [
    {
      "id": "write_boundary",
      "kind": "scope_boundary",
      "statement": "Writes stay within the configured root.",
      "source_path": "example-plugin/README.md",
      "excerpt": "Writes stay within the configured root.",
      "authority": "documentation"
    },
    {
      "id": "local_operation",
      "kind": "claim_support",
      "statement": "No external account is required.",
      "source_path": "example-plugin/README.md",
      "excerpt": "No external account is required.",
      "authority": "documentation"
    }
  ],
  "confirm": "INGEST_EVIDENCE_SNAPSHOT"
}

On success, the Ability returns the immutable package revision, current revision, snapshot SHA-256, and evidence-item count.

Use literal_wp_register_ability_calls only when the complete snapshot contains direct literal registrations that match expected_abilities. Use curated_only with an empty expected_abilities list for wrapper-based implementations; exact curated excerpts are still verified, but the package makes no extracted Ability-inventory claim.

Safety and Ownership

• Compressed snapshots are limited to 8 MiB.
• ZIP preflight allows at most 512 unique entries, 4 MiB per file, 16 MiB expanded total, and a 100:1 compression ratio.
• Absolute paths, traversal, duplicate paths, symbolic links, unexpected roots, size mismatches, and incomplete extraction fail closed.
• Evidence Packages allow at most 64 evidence items and 64 KiB of canonical package data.
• Curated excerpts must occur verbatim in the supplied snapshot.
• Literal Ability extraction rejects zero, dynamic, duplicate, wrapper-like, object, static, nullsafe, or mismatched registrations.
• Stored packages contain no site, page, post, product, editorial consumer, review taxonomy, or publication policy.
• The consumer owns subject mapping, required evidence kinds, claim coverage, Quality review, and publication authority.

Installation

1. Download mcp-source-evidence.zip from the stable download link.
2. In WordPress, open Plugins → Add Plugin → Upload Plugin.
3. Upload the ZIP, install it, and activate it.
4. Confirm that the WordPress Abilities API and your MCP exposure layer are active.
5. Discover mcp-source-evidence/capture-package before attempting capture.

Changelog

0.1.3

• Add explicit curated-only capture for wrapper-based implementations without claiming an extracted Ability inventory.

0.1.2

• Replace external release acquisition with complete local snapshot ingestion.
• Add atomic current-snapshot activation and currentness receipts.
• Prevent snapshot replacement from crossing a consumer write that relies on the current package.
• Keep archive verification, exact excerpts, and package content addressing inside WordPress.

0.1.1

• Accept a direct global function_exists( 'wp_register_ability' ) dependency check without weakening fail-closed handling for ambiguous registrations.

0.1.0

• Add immutable Evidence Packages, bounded ZIP verification, exact excerpt validation, and literal WordPress Ability extraction.

Contributing

Changes should preserve context-neutral package meaning, bounded complete-snapshot verification, exact source excerpts, atomic activation, and fail-closed behavior.

License

GPLv2 or later. See the GNU General Public License.

Author

basicus

Links

• Product page
• Stable download