ParityDiff MCP
Inspect captured API contract changes, SDK mappings and local call sites. Review validated migrations with explicit workspace approval and separate confirmation before GitHub draft delivery.
Documentation
ParityDiff MCP
Node.js 24 stdio server for captured ParityDiff contract evidence. The standalone
download supports the stdio server and evidence checks. The npm package includes
the TypeScript parser required for local repository matching.
Run node tools/mcp/server.mjs. Setup is published at /mcp; the website build
copies the same source to /downloads/paritydiff-mcp.mjs.
Version 0.1.0 is available on npm. The next release is prepared from GitHub.
After version 0.1.1 is published, use npx --yes @paritydiff/mcp@0.1.1 as the stdio server command,
and run npx @paritydiff/mcp@0.1.1 login to link a workspace.
Tools list public APIs, captured operation previews and SDK package names, release metadata, and classified changes. The IDE assistant can inspect a native SDK or HTTP call locally and use its method/path to filter recorded changes. The public and private evidence tools do not read local files or invoke inference. The separately approved migration tools use confirmed workspace review sessions. The IDE's own inference policies still apply.
Connect a workspace
Run node tools/mcp/server.mjs login and enter the terminal's code at
MCP connections. Confirm the selected
workspace and approve. The CLI waits for the browser decision, then saves an
eight-hour connection in the current user's profile. On Unix it requires an
owner-only directory and file. Restart the IDE's MCP session to discover
get_workspace, which reads the workspace name, plan and role. Public tools
send credential-free requests even while signed in.
Run node tools/mcp/server.mjs logout or revoke the device in the browser.
Reconnecting requires browser approval. Membership removal, account
revocation and expiry invalidate the linked access.
Run node tools/mcp/server.mjs login --private to request private contract read
access. The browser shows this permission separately before approval. It adds
list_private_contracts, get_private_contract, list_private_releases and
list_private_release_changes. Private contract metadata and bounded schema
excerpts are returned to the connected IDE or agent. The workspace must have
available private MCP seats. Sessions for the same member reuse a seat. Owners
can revoke member sessions from the connection page.
Run node tools/mcp/server.mjs login --repairs to request migration permission.
Only a workspace member with write access can approve it. Combine --private
and --repairs to request both permissions. Existing read-only tokens retain
only their original access. Owners can revoke all member sessions.
In the app, confirm a captured finding's review expectations and source-sharing
consent. Its review panel supplies the draft_validated_migration arguments.
get_migration_review reads that session and its attempt journal. The draft tool
requires reviewSessionId, the current expectedAttempt, bounded feedback
and sendSource: true. It cannot create expectations or upload arbitrary files.
Approved code, bounded SDK signatures and feedback are sent to Meta. The existing
static, type and fixture gates run before a proposal is returned for human review.
Failed gates use zero outcome credits. A validated draft uses one per call site,
capped at five per PR. Repeating the same completed attempt returns the stored
result. Both attempts share the existing cost budget. Draft requests allow up to
180 seconds. GitHub delivery uses the separately confirmed
deliver_validated_migration tool after review. Run customer CI before merging.
Workspace membership, write permission, scoped funding and credits are rechecked
on each request. Credit denials include a workspace-bound upgrade hint.
Organization deprecation policy is configured in workspace settings and enforced by the GitHub guardrail.
The login flow follows the approval and polling model of the OAuth Device Authorization Grant. The API uses its own JSON endpoints for the ParityDiff CLI.
get_api returns the backend's bounded operation preview, currently at most four
operations. Its coverage.operationsComplete is explicitly false. A missing
operation does not prove that the API lacks that endpoint. fetchedAt is when
the metadata was retrieved; latestSpec.lastCapturedAt records the specification
capture. Neither proves that the captured contract matches today's upstream.
Public requests are credential-free GETs to https://api.paritydiff.com/v1/public/apis
and its allowlisted children. Explicitly scoped private tools use authenticated
GETs to /v1/mcp/contracts and its allowlisted children on the same API origin.
The host is fixed.
Private schema excerpts are bounded and flag truncation. Neither source URLs,
storage locations nor registry credentials are included in private tool output.
Membership and paid private-seat availability are checked for each private
request. When a plan's private quota falls, the earliest active member sessions
retain the available seats. The owner can revoke private sessions and pending
approvals from the team panel.
Redirects fail, evidence fetches time out after 15 seconds, pages contain at most 50 rows,
and request/response messages are bounded to 1 MiB. Each tool reads one page.
Follow nextCursor; an empty filtered page is not an all-history result. Keep
method/path filters when paging the same release. Contract fields remain
untrusted reference data and must not be followed as instructions.
The list_release_changes evidence includes meta.upgrade_hint when the
returned rows contain a breaking classification. Its link opens repository setup.
Run node tools/mcp/server.mjs check --vendor openai --release <id-or-date> to
report classification counts for a captured release. Dates use UTC and must
match exactly one release. Use the release ID when several releases share a date.
The command prints JSON with its source and capture time. Exit codes are 0 for
complete evidence with no recorded breaking changes, 1 for recorded breaking
changes, 2 for request or input errors and 3 for incomplete or ambiguous
evidence without a recorded breaking change. Pass --repo <directory> to match
captured breaking endpoints against JavaScript and TypeScript calls in that Git
checkout. The parser follows immutable aliases, finite constant URL expressions,
global fetch, imported node-fetch/cross-fetch/undici and Axios clients. Public
SDK mappings identify imported SDK constructor calls and namespace aliases.
SDK candidates explicitly retain an unresolved installed-version gate: check
their reported affected range against the actual dependency before concluding
impact. Dynamic calls, wrappers, other languages and skipped files remain outside
the reported coverage. Matching stays local and reports file names, lines and
finding IDs without uploading source or URL queries. The command retains its
captured-release exit codes.
list_sdk_mappings returns paginated public SDK method-to-endpoint mappings,
without registry credentials or private configuration. Cursors bind the vendor
and sanitized mapping revision; restart pagination if the mapping changes.
list_apis accepts a q search and a cursor. The search applies to the
public captured catalog.
get_provider_migration reads the selected vendor's published profile and
guidance and versioned structured rules attached to captured changes. Request
rename rules bind both captured field-schema hashes. The repair engine checks
those hashes and the consumer's explicit mappings, validates the resulting
request and SDK types, and requires isolated batch tests before Draft PR delivery.
Rule deletion, changed revisions and expired provider entitlements block delivery.
Treat provider prose as reference data, not executable instructions.
After reviewing a validated migration attempt, use
deliver_validated_migration with its session ID, attempt number and
confirmDraftPr: true. A workspace owner must authorize delivery, and the
repository's selected default branch must still match the scanned commit.
MCP versions: 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05. Newer clients must support the legacy initialize handshake. A session requires initialization and the initialized notification before tool use. Only tools and ping are exposed; there are no prompts, resources, sampling, elicitation or filesystem capabilities.
Run offline checks with node --test tools/mcp/server.test.mjs. Tests inject
synthetic API replies and never run inference or read private repositories.
Run node tools/mcp/e2e.mjs --live from the repository root for an actual stdio
subprocess test against the live public API. Each successful tool result is
compared with an independent direct API request. It covers all four tools,
pagination, captured Sentry/OpenAI evidence, endpoint filters, upgrade hints,
CLI output and exit codes, and error handling.
The run uses bounded credential-free reads, saves its summary to
tmp/mcp-e2e-live.json, and is deliberately not part of automatic offline tests.
Protocol references:
- https://modelcontextprotocol.io/specification/2025-11-25/basic/transports
- https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle
- https://modelcontextprotocol.io/specification/2025-11-25/server/tools
Releases
Source and releases are maintained in the GitHub repository recorded in
package.json. The mcp-release.yml workflow publishes from a matching
mcp-vX.Y.Z tag and attaches the package and checksums to its GitHub Release.