version-compat-mcp

"Your agent reads the wrong docs. version-compat makes it read the right version."

Version-Aware Setup, Dependency Compatibility & Migration MCP Server for JavaScript/TypeScript & Python Ecosystems.

version-compat-mcp is not a generic documentation search engine. It is a local Model Context Protocol (MCP) server that analyzes your project's actual Node.js & Python runtimes, package managers (npm/pnpm/yarn/bun/uv/poetry/pip), lockfile versions, and configuration files to supply deterministic compatibility checks and tag-pinned migration facts to AI coding agents (Google Antigravity, OpenAI Codex, Cursor, Claude Code).

Table of Contents

1. Why version-compat-mcp? (And How It Differs from Generic Doc MCPs)

2. Core Architecture

3. Supported Libraries & Versions

4. Quick Start & Host Agent Configuration

   • Google Antigravity (AGY)

   • OpenAI Codex (CLI & Desktop App)

   • Cursor

   • Claude Code & Claude Desktop

   • Smithery CLI

5. MCP Tools Reference (5 Tools)

6. Real-World Prompt Examples

7. Safety & Epistemic Guardrails

8. Data Collection, Upstream Licenses & Attribution Policy

9. Privacy & Security Policy

10. Known Limitations & Roadmap

11. Testing with MCP Inspector & Evaluation Suite

12. License

Related MCP server: installed-version-mcp

1. Why version-compat-mcp? (And How It Differs from Generic Doc MCPs)

Because LLM pre-training weights are frozen at a cutoff date, coding agents routinely make costly setup and migration errors:

• Tailwind CSS v4 vs. v3: Proposing npx tailwindcss init -p, tailwind.config.js, and @tailwind base; in a Tailwind CSS v4 project (which uses @import "tailwindcss"; and @tailwindcss/vite or @tailwindcss/postcss).

• ESLint v9 vs. v8: Generating legacy .eslintrc.json or .eslintignore files in an ESLint v9 project that requires eslint.config.mjs (Flat Config).

• Next.js 15 & React 19: Using synchronous cookies(), headers(), or params in Next.js 15 (where Dynamic Request APIs are asynchronous Promises), or proposing incompatible React 18 / Node.js combinations.

• FastAPI & Pydantic v2: Suggesting deprecated @app.on_event("startup") instead of lifespan context manager, or Pydantic v1 class Config: / @validator instead of ConfigDict and @field_validator/@model_validator.

• Package Manager Mismatch: Suggesting npm install in a repository locked with pnpm-lock.yaml, bun.lock, yarn.lock, or proposing pip install in an active uv or poetry workspace.

How version-compat-mcp Differs from General Documentation MCPs (e.g., Context7)

2. Core Architecture

flowchart LR
    Agent["Host Agent<br/>(Antigravity / Codex / Cursor / Claude)"] <-->|"JSON-RPC 2.0 (stdio)"| Server["version-compat-mcp"]

    subgraph Deterministic["1. Deterministic Engine (Zero RAG / Zero Hallucination)"]
        Local["Local File & Lockfile Parser<br/>package.json, pnpm-lock.yaml,<br/>bun.lock, yarn.lock, .nvmrc"]
        Registry["npm Registry Abbreviated API<br/>engines.node, peerDependencies,<br/>deprecated (+ ETag Disk Cache)"]
    end

    subgraph Retrieval["2. Tag-Pinned Retrieval Engine (SQLite FTS5 BM25)"]
        SeedDB["Precomputed SQLite FTS5 Index<br/>(seed/index-js-ts.db + SHA-256 Verify)"]
        Corpus["Git-Tag Snapshots Only:<br/>Migration Guides, Breaking Changes,<br/>Deprecations & Setup Templates"]
    end

    Server --> Local
    Server --> Registry
    Server --> SeedDB
    Corpus --> SeedDB

1. Strict Separation of Structured vs. Unstructured Data: Structured data (package.json, lockfiles, npm registry metadata) is evaluated deterministically without RAG. Unstructured docs (migration guides, breaking changes) are indexed by immutable Git tags in SQLite FTS5.

2. Zero-Config & Precomputed Index: Built on Node.js native node:sqlite (DatabaseSync with FTS5 and unicode61 tokenchars '@/_-.')—requiring zero API keys and zero C++ node-gyp compilation during npx execution.

3. Strict stdio Protocol Hygiene: stdout is strictly reserved for JSON-RPC 2.0 frames. Accidental console.log calls are intercepted, and internal diagnostics write exclusively to process.stderr only when DEBUG="true" is set.

3. Supported Libraries & Versions

JavaScript / TypeScript Ecosystem

Supported JS/TS Package Managers: npm, pnpm (v6–v9 + pnpm-workspace.yaml catalogs), yarn (Classic v1 & Berry v2+), bun (bun.lock & bun.lockb).

Python Ecosystem

Supported Python Package Managers: uv (uv.lock, pyproject.toml), poetry (poetry.lock, pyproject.toml), pip (requirements.txt, Pipfile).

4. Quick Start & Host Agent Configuration

Prerequisites

• Node.js: >= 22.5.0

A. Google Antigravity (AGY)

Global MCP Config (~/.gemini/config/mcp_config.json):

{
  "mcpServers": {
    "version-compat": {
      "command": "npx",
      "args": ["-y", "version-compat-mcp"]
    }
  }
}

Workspace Rules: This repository also includes workspace rules in GEMINI.md and AGENTS.md.

B. OpenAI Codex (CLI & Desktop App)

codex mcp add version-compat -- npx -y version-compat-mcp

Or in ~/.codex/config.toml:

[mcp_servers.version-compat]
command = "npx"
args = ["-y", "version-compat-mcp"]
startup_timeout_sec = 15
tool_timeout_sec = 30
enabled = true

C. Cursor

Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "version-compat": {
      "command": "npx",
      "args": ["-y", "version-compat-mcp"]
    }
  }
}

(For local development from a cloned repository, use "command": "node" and "args": ["/absolute/path/to/version-compat-mcp/dist/index.js"].)

D. Claude Code & Claude Desktop

claude mcp add version-compat -- npx -y version-compat-mcp

E. Smithery CLI

npx -y smithery@latest mcp add eunryong/version-compat-mcp --client cursor
# or for Claude Desktop / Claude Code:
npx -y smithery@latest mcp add eunryong/version-compat-mcp --client claude

5. MCP Tools Reference (5 Tools)

6. Real-World Prompt Examples

Once version-compat-mcp is connected to Cursor, Claude Code, Codex, or Antigravity, try asking:

1. Environment & Compatibility Audit

   "Check the current project's Next.js, React, and Node.js versions using version-compat and let me know if there are any peerDependency or engine compatibility issues."

2. Tailwind CSS v3 → v4 Upgrade

   "We want to upgrade Tailwind CSS from v3.4 to v4.0 in this repository. Inspect our project environment first, then give me the exact migration steps, config changes, and commands for our package manager with official source URLs."

3. ESLint v8 → v9 Flat Config Migration

   "Migrate our .eslintrc.json and .eslintignore setup to ESLint v9 Flat Config. Cite the official ESLint v9 migration docs."

4. Next.js 14 → 15 Breaking Changes

   "What breaking changes affect cookies(), headers(), and params when upgrading from Next.js 14.2 to 15.0, and what is the official codemod command?"

7. Safety & Epistemic Guardrails

• No Silent "latest" Substitution (status: "ambiguous_version"): When a version is omitted without a project_path, or spans multiple majors (>=13.0.0 <16.0.0), the server refuses to guess "latest" and returns candidate versions.

• Zero Search Results ≠ Feature Removed (status: "no_results_found"): Returns epistemic_notice: "NO_EVIDENCE_DO_NOT_ASSUME_REMOVED" so the host agent never falsely claims an API was removed simply because no breaking-change chunk matched.

• Explicit Unsupported Scope (status: "unsupported_library"): Immediately identifies libraries outside the 7 supported targets.

• Read-Only Execution: Commands and codemods are returned as strings; the server never executes shell commands.

8. Documentation Sources and Data Policy

• version-compat-mcp does not claim ownership of third-party documentation.

• Every search result and migration guide step includes original source_url links and version metadata (git_tag, version, collected_at, upstream_license).

• Indexed documents are strictly limited to migration guides, release notes, deprecation notices, and compatibility-related content. Full documentation websites and general tutorials are excluded.

• Documentation sources are collected from official repositories or official documentation sites pinned to immutable Git tags (recorded in seed/metadata.json).

• Third-party documentation remains subject to its original license, terms of service, and copyright policy. See NOTICE.md and THIRD_PARTY_NOTICES.md for complete attribution details.

• Upstream maintainers can request modification or removal of any indexed snapshot by opening an issue at https://github.com/Eunryong/version-compat-mcp/issues.

9. Privacy & Security Policy

• 100% Local Execution: Runs locally on your machine over stdio. No source code or .env files are ever read or uploaded.

• No Telemetry: Zero analytics or tracking. Outbound network calls are limited to npm registry metadata lookups (registry.npmjs.org) and can be disabled completely via VERSION_COMPAT_OFFLINE=1.

• SHA-256 Integrity: Precomputed index databases are verified against seed/index-js-ts.db.sha256 and seed/manifest.json before loading.

• See SECURITY.md for full details.

10. Known Limitations & Roadmap

• Current Scope (Phase 1): Focused on the 7 core JS/TS libraries (node, typescript, react, nextjs, vite, tailwindcss, eslint) using SQLite FTS5 BM25 keyword/symbol retrieval.

• Phase 2 Roadmap: Hybrid retrieval combining BM25 with local ONNX query embeddings (transformers.js + sqlite-vec using Xenova/bge-small-en-v1.5) and automated GitHub Actions release asset index updates.

• Phase 3 Roadmap: Modular ecosystem collections (@version-compat/mcp-core + on-demand ecosystem indexes) so large ecosystems can be downloaded selectively into ~/.cache/version-compat-mcp/.

11. Testing with MCP Inspector & Evaluation Suite

# Build TypeScript + SQLite FTS5 seed index (manifest.json, index-js-ts.db.sha256, metadata.json)
npm run build

# Run unit tests, 8 fixture project tests, safety guardrail tests, and stdio integration test
npm test

# Run golden dataset retrieval & guardrail benchmark (Recall@1, Recall@5, MRR@10, Leakage)
npm run eval

# Verify MCP protocol via official MCP Inspector CLI
npm run inspect:cli

# Launch interactive MCP Inspector Web UI
npm run inspect

# Verify npm package tarball before publishing
npm pack --dry-run

12. License

MIT License. See LICENSE for details. For third-party documentation and software/model attribution, see NOTICE.md and THIRD_PARTY_NOTICES.md.