docs: define MCP compatibility contract

[mohanagy]

Summary

• publish the protocol-era, transport, deprecation, extension, and client-evidence compatibility contract
• test installed-package modern and legacy STDIO and Streamable HTTP paths with the locked MCP 2.0.0 client
• add a pinned MCP Inspector 2.1.0 installed-tarball gate for STDIO and modern Streamable HTTP on Linux Node 22
• distinguish stateless protocol requests from stateful Miftah application data, including the current in-process MRTR continuation boundary
• defer any legacy retirement to separate post-v1.1 gate [Compatibility] Gate any retirement of legacy MCP eras and deprecated features #388

Named Claude Desktop, Claude Code, Cursor, and VS Code claims remain configuration-shape evidence only until an exact packaged-host transcript exists.

Validation

• npm test — 158 files passed; 1,947 tests passed; 34 skipped
• npm run test:coverage — 96.04% statements; 92.17% branches
• npm run test:core -- --no-file-parallelism — 29 files; 478 passed; 26 skipped
• npm run test:package — 31 passed
• npm run test:inspector — packaged Inspector 2.1.0 STDIO and HTTP interoperability passed
• npm run lint
• npm run typecheck
• npm run build
• npm run check:test-fixture
• npm run check:pack — 57 files
• npm audit --omit=dev --audit-level=high — 0 vulnerabilities
• git diff --check

Fixes #368

Summary by CodeRabbit

• Documentation

  • Added a comprehensive MCP compatibility guide covering supported protocol eras, transports, clients, negotiation, statefulness, security boundaries, and deprecation policy.
  • Linked compatibility evidence from configuration, API, README, and client documentation.
  • Added an Unreleased changelog entry.

• Tests

  • Added packaged interoperability checks for MCP Inspector over STDIO and Streamable HTTP.
  • Added coverage for modern and legacy protocol negotiation, tool discovery, errors, timeouts, and cleanup.
  • Added documentation and compatibility contract tests.

• Chores

  • Expanded CI and test scripts to run compatibility validation automatically.

[coderabbitai]

📝 Walkthrough

Walkthrough

The pull request defines an MCP compatibility source of truth, links it from project documentation, adds contract tests for compatibility claims, tests packaged protocol negotiation, and adds MCP Inspector interoperability checks over STDIO and Streamable HTTP in CI.

Changes

MCP compatibility

Layer / File(s)	Summary
Compatibility contracts and documentation docs/mcp-compatibility.md, docs/library-api.md, README.md, docs/config.md, docs/presets-and-clients.md, CHANGELOG.md, tests/mcp-compatibility-docs-contract.test.ts	Documents supported MCP eras, transports, client evidence, state boundaries, deprecated behavior, and retirement requirements. Contract tests verify the documented claims and CI wiring.
Packaged protocol negotiation tests/package-contract.test.ts	Tests modern and legacy protocol negotiation over STDIO and Streamable HTTP, including session establishment and whoami discovery.
Packaged Inspector interoperability scripts/check-inspector-interop.mjs, package.json, .github/workflows/ci.yml	Packages the project, installs it into a temporary consumer, runs Inspector checks over STDIO and Streamable HTTP, validates audit output, cleans resources, and runs in Linux/Node.js 22 CI.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant CI
  participant InteropScript
  participant PackagedConsumer
  participant MCPInspector
  participant MCPServer
  CI->>InteropScript: run test:inspector
  InteropScript->>PackagedConsumer: install packaged project
  InteropScript->>MCPServer: start STDIO or Streamable HTTP server
  InteropScript->>MCPInspector: request tools/list
  MCPInspector->>MCPServer: inspect packaged server
  MCPServer-->>MCPInspector: return tool list
  InteropScript-->>CI: validate audit output and cleanup

Loading

Possibly related issues

• mohanagy/miftah#365 — The issue covers MCP 2026-07-28 compatibility and Streamable HTTP interoperability. This pull request adds related validation and documentation.

Possibly related PRs

• mohanagy/miftah#381 — This pull request adds tests and documentation for the MCP protocol-era paths introduced there.
• mohanagy/miftah#385 — Both pull requests validate MCP HTTP and protocol compatibility behavior.
• mohanagy/miftah#194 — Both pull requests use packaged MCP interoperability and test-harness infrastructure.

Suggested labels: documentation, area:mcp

Poem

A rabbit checks each protocol lane,
With Inspector hops through HTTP and STDIO rain.
Modern and legacy paths agree,
The audit log says, “All clear to me!”
Packages cleanly, then bounds away.

---

Caution

Pre-merge checks failed

Please resolve all errors before merging. Addressing warnings is optional.

• Ignore

❌ Failed checks (2 errors, 1 warning)

Check name	Status	Explanation	Resolution
Linked Issues check	❌ Error	For [#368], the PR covers the compatibility matrix, packaged dual-era tests, and Inspector, but lacks packaged interoperability evidence for documented primary clients.	Add packaged-host interoperability tests and exact transcripts for at least the documented primary clients named in [#368].
Docstring Coverage	❌ Error	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Description check	⚠️ Warning	The description includes the summary and validation commands, but it omits the required Security impact section and lacks results for all required checks.	Add a Security impact section covering subprocesses, dependencies, audit data, and failure behavior, and record results for each required validation item.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely identifies the PR's main change: defining the MCP compatibility contract.
Out of Scope Changes check	✅ Passed	The documentation, tests, packaging checks, Inspector script, and CI updates all support the compatibility objectives in [#368].

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/368-compatibility-audit

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@scripts/check-inspector-interop.mjs`:
- Around line 53-73: The startup timeout in the endpoint promise must fully
terminate the child before rejecting. Update the timeout handling around child
and startHttpServer so it sends SIGTERM, waits for the child exit, and uses a
bounded SIGKILL fallback if needed; only reject after termination completes,
while preserving the existing timeout error details and cleanup behavior.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 363e0293-c908-4345-b912-0e904c8eb048

📥 Commits

Reviewing files that changed from the base of the PR and between 6156927 and 85da0d5.

📒 Files selected for processing (11)

• .github/workflows/ci.yml
• CHANGELOG.md
• README.md
• docs/config.md
• docs/library-api.md
• docs/mcp-compatibility.md
• docs/presets-and-clients.md
• package.json
• scripts/check-inspector-interop.mjs
• tests/mcp-compatibility-docs-contract.test.ts
• tests/package-contract.test.ts

Superseded by 586c77c. CodeRabbit re-reviewed that exact head, confirmed the only finding was addressed, and posted no new findings. Exact-head CI run 31532095834 passed all jobs.