Skip to content

CatalogLock v0.2.0 — Live MCP Tool-Surface Locking

Choose a tag to compare

View all tags
@github-actions github-actions released this 27 Aug 14:21
v0.2.0
88cfaac

🔒 CatalogLock v0.2.0

Live MCP Tool-Surface Locking

Version Tests Node Runtime deps ARD MCP Tool drift License

Stable identity is not stable capability. CatalogLock now locks both.

CatalogLock v0.2.0 directly addresses a dangerous agentic-supply-chain failure mode: an MCP server can keep the same publisher, identity, Server Card and endpoint while its runtime executable tool surface changes underneath the client.

A newly appearing delete_*, transfer_*, admin_* or any other tool is no longer invisible just because the discovery metadata stayed stable.

✨ What changed

  • Resolves current application/mcp-server-card+json ARD resources.
  • Follows public Streamable HTTP MCP remotes through the same SSRF/DNS-pinning boundary used by catalog resolution.
  • Calls live MCP tools/list using protocol revision 2026-07-28.
  • Canonicalizes and SHA-256 hashes every complete tool definition.
  • Separately hashes inputSchema and outputSchema when present.
  • Produces deterministic lockfile v2 with MCP Server Card, endpoint and tool-surface state.
  • Flags new MCP tools as CRITICAL drift.
  • Flags changed MCP tool definitions/schemas as CRITICAL drift.
  • Flags MCP endpoint changes as CRITICAL drift.
  • Flags Server Card semantic changes independently.
  • Handles paginated tools/list safely with page/tool ceilings and cursor-loop protection.
  • Parses both direct JSON and SSE-delivered JSON-RPC list results.
  • Detects required-auth Server Cards without persisting credentials.
  • Adds requireMcpInspection for environments that must fail closed when a surface cannot be inspected.
  • Updates the self-contained HTML report with live MCP surface/tool visibility.
  • Updates GitHub Action outputs with mcp-surfaces and mcp-tools.
  • Tracks the current ARD v0.91 proposal published 26 August 2026.

🎯 The exact drift case

Reviewed state:

get_invoice
search_invoices

Later, with the same server identity and endpoint:

get_invoice
search_invoices
delete_invoice

CatalogLock now reports:

[CRITICAL] mcp-tool-added:
New executable MCP tool appeared: delete_invoice on urn:air:example.com:mcp:billing

That is the core v0.2.0 change.

🛡️ Security properties

Live MCP inspection does not weaken CatalogLock's network boundary. Server Card URLs and MCP endpoints are subject to the same HTTPS policy, port allowlist, DNS resolution, public-IP rejection and pinned socket lookup as catalog retrieval.

POST redirects are only followed for HTTP 307/308 so an MCP request cannot silently mutate into a GET during redirect handling.

CatalogLock still does not execute tools, infer that a tool implementation matches its schema, or treat a clean scan as authorization to invoke a resource.

🧪 Verification

The release candidate passed 54/54 tests plus production TypeScript build and CLI smoke tests before publication.

Coverage includes:

  • exact same-identity/new-tool drift regression
  • tool-schema mutation
  • Server Card semantic drift
  • deterministic tool ordering and hashing
  • pagination and cursor-loop handling
  • duplicate tool rejection
  • JSON and SSE tools/list responses
  • authenticated Server Card handling
  • catalog → Server Card → tools/list → lockfile end-to-end flow
  • IPv4/IPv6 private-address rejection
  • nested catalog bounds
  • publisher/source and trust-identity checks
  • deterministic lockfiles
  • policy, catalog, resource and authority drift

🚀 Usage

cataloglock scan example.com
cataloglock lock example.com --output cataloglock.lock.json
cataloglock verify example.com --lock cataloglock.lock.json

Live MCP inspection is enabled by default for public, unauthenticated Streamable HTTP Server Cards.

To require complete MCP inspection:

{
  "requireMcpInspection": true
}

To explicitly disable live MCP inspection:

cataloglock lock example.com --no-mcp-tools

📦 Release artifacts

This release includes:

  • CatalogLock-v0.2.0.zip
  • cataloglock-0.2.0.tgz
  • CatalogLock-v0.2.0.sha256

The open agentic web needs more than identity pinning. It needs capability pinning.

⭐ Star the repository if you want agent discovery and runtime capability drift to become reviewable infrastructure.

Assets 5
Loading