fix: preserve v1 library host compatibility

[mohanagy]

Summary

• retain the documented SDK v1 createMiftahRuntime STDIO host path through the 1.x line
• keep SDK v2 runtime packages and createMiftahServerFactory as the preferred implementation path
• pin patched Hono and Node adapter runtime dependencies so the retained SDK cannot select the unsafe 1.x adapter range
• compile the exact legacy consumer from a freshly installed package tarball
• defer removal to the future major-version evidence gate [Compatibility] Gate any retirement of legacy MCP eras and deprecated features #388

Reproduced SemVer blocker

A clean consumer declaring only published Miftah 1.0.0 compiled the documented @modelcontextprotocol/sdk/server/stdio.js integration. The same consumer failed with TS2307 against the prior development tarball because the SDK dependency disappeared. This PR restores that documented 1.x contract without changing runtime internals.

Security impact

The retained SDK accepts the patched @hono/node-server 2.x range. The package now carries exact @hono/node-server 2.0.10 and Hono 4.12.34 runtime dependencies, and the installed-package test verifies those exact resolved versions. Both production-only and full npm audits report zero vulnerabilities.

Validation

• npm run test:package: 31 passed
• npm test: 1,947 passed, 34 skipped
• npm run lint
• npm run typecheck
• npm run build
• npm audit --omit=dev --audit-level=high: zero vulnerabilities
• npm audit --audit-level=high: zero vulnerabilities

Fixes #391

Summary by CodeRabbit

• Compatibility

  • Continued support for MCP SDK v1 STDIO integrations alongside the v2 runtime throughout the 1.x release line.
  • Added documentation and examples for connecting legacy STDIO servers.

• Package Updates

  • Ensured required runtime components and compatible dependency versions are included in consumer installations.

• Quality Assurance

  • Added verification for packed releases, runtime dependency placement, legacy integration type compatibility, and release-tarball support for v1 hosting.

[coderabbitai]

Important

Review skipped

No new commits to review since the last review.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 69809af6-cd49-42a3-81b4-a3a33ee3990c

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

The package retains MCP SDK v1 and Hono dependencies at runtime. Documentation preserves the v1 STDIO integration path and identifies the v2 factory path. Contract tests verify dependency placement, packed installations, and legacy consumer type checking.

Changes

MCP v1 compatibility

Layer / File(s)	Summary
Runtime dependency contract package.json, tests/mcp-v2-migration-contract.test.ts, tests/release-config.test.ts	Runtime dependencies now include the MCP SDK and Hono packages. Contract tests verify dependency placement and retained v2 development packages.
Compatibility documentation CHANGELOG.md, docs/library-api.md	The changelog and library guide document v1 StdioServerTransport support through 1.x and the preferred v2 factory path.
Consumer and package validation tests/package-contract.test.ts	Packed-install tests verify Hono package versions. The generated TypeScript consumer verifies the legacy STDIO connection path.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• mohanagy/miftah#283: Both changes update MCP SDK, Hono dependencies, and package-contract tests.
• mohanagy/miftah#381: This change extends the MCP v2 migration while retaining the monolithic v1 SDK.
• mohanagy/miftah#389: Both changes update MCP compatibility documentation and package-contract tests.

Suggested labels: documentation, area:mcp

Poem

A rabbit checks the STDIO gate,
V1 stays in the runtime state.
Hono joins the package train,
V2 leads the path again.
Packed types pass every test,
Through 1.x, compatibility rests.

---

Caution

Pre-merge checks failed

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

• Ignore

❌ Failed checks (1 error)

Check name	Status	Explanation	Resolution
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.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes satisfy the coding objectives in [#391], including v1 consumer compatibility, package regression coverage, v2 support, documentation, and deferred removal.
Out of Scope Changes check	✅ Passed	The dependency, documentation, changelog, and test changes directly support the linked compatibility objectives and show no unrelated scope.
Title check	✅ Passed	The title clearly states the main change: preserving SDK v1 library host compatibility.
Description check	✅ Passed	The description includes the required sections and reports the main validation results, although it omits some template checklist items.

✨ 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 fix/391-v1-host-compatibility

---

_{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 `@tests/mcp-v2-migration-contract.test.ts`:
- Around line 12-26: The package contract tests must enforce that
`@modelcontextprotocol/node` is dev-only. In
tests/mcp-v2-migration-contract.test.ts lines 12-26, add a negative assertion
that dependencies excludes `@modelcontextprotocol/node`; apply the same assertion
in tests/package-contract.test.ts lines 800-809 while preserving the existing
devDependencies checks.

🪄 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: effaccaf-ddbf-4e3f-9af9-ddb6cec90f9d

📥 Commits

Reviewing files that changed from the base of the PR and between 16504c6 and 8b85218.

⛔ Files ignored due to path filters (1)

• package-lock.json is excluded by !**/package-lock.json

📒 Files selected for processing (6)

• CHANGELOG.md
• docs/library-api.md
• package.json
• tests/mcp-v2-migration-contract.test.ts
• tests/package-contract.test.ts
• tests/release-config.test.ts

[mohanagy]

@coderabbitai review

[coderabbitai]

⚠️ Action not completed

Already reviewed.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

Addressed in exact-head commit 1d22a42: both package contracts now enforce that @modelcontextprotocol/node remains dev-only; the review thread is resolved and focused validation passes.