Repository avatar
Developer Tools
v0.1.0
active

stackcheck-mcp

io.github.titouannnn/stackcheck-mcp

Latest stable npm/PyPI/Maven versions plus the incompatibilities between them.

Documentation

stackcheck-mcp

An MCP server that gives coding agents the latest stable version of every npm, PyPI and Maven package in a stack, and every incompatibility between them, in one call and a few hundred tokens of JSON.

Why

Agents pin dependencies from stale training data, and "always use latest" is not enough either. On 2026-10-27:

  • typescript dist-tags.latest is 7.0.2;
  • typescript-eslint@8.72.1 (latest) declares peerDependencies.typescript: ">=4.8.4 <6.1.0";
  • so "latest everything" breaks linting. The compatible pin is typescript 6.0.3.

Version-lookup servers answer 7.0.2. stackcheck-mcp answers 7.0.2 too (it never downgrades), and also tells you, with the suggested fix:

{"kind":"peer","ecosystem":"npm","package":"typescript@7.0.2",
 "required_by":"typescript-eslint@8.72.1","range":">=4.8.4 <6.1.0",
 "suggestion":{"typescript":"6.0.3"}}

Install

Claude Code:

claude mcp add stackcheck -- uvx stackcheck-mcp

Any client with a JSON config (Claude Desktop, Cursor, VS Code, …):

{
  "mcpServers": {
    "stackcheck": {"command": "uvx", "args": ["stackcheck-mcp"]}
  }
}

Streamable HTTP instead of stdio:

uvx stackcheck-mcp --http --host 127.0.0.1 --port 8000   # endpoint: http://127.0.0.1:8000/mcp

The HTTP server has no authentication. On a loopback address the MCP SDK also rejects requests whose Host/Origin is not local (DNS rebinding protection). Any other --host is refused unless you pass --allow-remote, which you should only do behind a proxy that authenticates clients; that also disables the rebinding protection, and with --resolver-validation every caller can make the server run uv and npm.

Only uv is needed. Public registries only, no credentials.

Options

FlagDefault
--httpoff (stdio)serve streamable HTTP
--host, --port127.0.0.1, 8000HTTP bind address (loopback only, unless --allow-remote)
--allow-remoteoffaccept a non-loopback --host (no authentication: put an authenticating proxy in front)
--resolver-validationoffalso check the picks with real resolvers (see below)
--resolver-timeout120seconds per resolver run
--call-timeout45seconds of registry work per tool call; past it, the answer is partial and the slow parts are in errors (fetches keep warming the cache)
--log-levelWARNINGlogs go to stderr (stdout is the stdio transport)
EnvironmentDefault
STACKCHECK_CACHE_DIRplatform cache dir (platformdirs)on-disk cache of reduced registry data
STACKCHECK_CACHE_TTL21600 (6 h)seconds; 0 disables the cache
STACKCHECK_CACHE_MAX_AGE60days; entries unused for longer (and those of older cache layouts) are deleted at startup, at most once a day; 0 never prunes
HTTPS_PROXY, SSL_CERT_FILE, SSL_CERT_DIRhonoured (the OS trust store is used on Windows/macOS)

Tools

check_stack

{
  "npm": ["react", "react-dom", "@types/react", "typescript", "typescript-eslint", "vite@^8"],
  "pypi": ["fastapi", "pydantic>=2", "uvicorn[standard]", "sqlalchemy"],
  "maven": ["org.springframework.boot:spring-boot-starter-web", "com.fasterxml.jackson.core:jackson-databind"],
  "maven_bom": "org.springframework.boot:spring-boot-dependencies",
  "runtimes": ["nodejs", "python", "sqlite"],
  "targets": {"node": "24", "python": "3.14", "java": "21"}
}

All fields are optional, but at least one list is required. Each list takes at most 100 entries.

  • npm: name or name@range (@types/react@^19: the range follows the last @). name@latest means the latest stable; other dist-tags (next, canary, …) are rejected.
  • PyPI: PEP 508 with extras (uvicorn[standard]>=0.30); URLs and markers are rejected.
  • Maven: groupId:artifactId[:version|range], e.g. [3.5,4.0). A plain version is exact.
  • maven_bom: a BOM to align against (groupId:artifactId[:version|range], latest by default).
  • runtimes: any endoflife.date slug (aliases like node work; java means eclipse-temurin, like the Java target).
  • targets: a cycle ("24", "3.14"), a prefix ("3") or an exact version. Defaults: Node = active maintained LTS, Python = newest released maintained cycle, Java = latest LTS of eclipse-temurin. A target is resolved (and shown) only when an ecosystem needs it.

Answer for the reference stack (the spec §9 stack, live on 2026-10-27, 963 bytes):

{
  "targets": {"node": "24.22.1", "python": "3.15.2"},
  "npm": {"react": "19.3.1", "react-dom": "19.3.1", "@types/react": "19.3.0",
          "@types/react-dom": "19.3.0", "typescript": "7.0.2", "typescript-eslint": "8.72.1",
          "eslint": "10.13.0", "vite": "8.3.5", "@vitejs/plugin-react": "6.1.2", "vitest": "5.0.5"},
  "pypi": {"fastapi": "0.162.0", "pydantic": "2.14.1", "uvicorn": "0.54.0", "sqlalchemy": "2.1.6",
           "pytest": "9.1.1", "playwright": "1.64.1", "ruff": "0.17.3", "mypy": "2.4.0"},
  "runtimes": {
    "nodejs": {"latest": "26.12.1", "lts": "24.22.1", "next_lts": {"version": "26", "from": "2026-10-28"},
               "maintained": ["26", "24", "22"], "eol": "2028-04-30"},
    "python": {"latest": "3.15.2", "maintained": ["3.15", "3.14", "3.13", "3.12", "3.11"], "eol": "2031-10-31"},
    "sqlite": {"latest": "3.54.1", "maintained": ["3"]}
  },
  "issues": [
    {"kind": "peer", "ecosystem": "npm", "package": "typescript@7.0.2",
     "required_by": "typescript-eslint@8.72.1", "range": ">=4.8.4 <6.1.0",
     "suggestion": {"typescript": "6.0.3"}}
  ],
  "validation": {"npm": "skipped", "pypi": "skipped"}
}

get_runtime_info

{"products": ["nodejs", "python", "eclipse-temurin"]} → per product: latest, lts (products with LTS), lts_eol: true when that LTS is past its end of life (Laravel 6), next_lts ({"version", "from"} when a cycle becomes LTS later), maintained (newest first, max 5, past-EOL extended-support cycles excluded) and eol of the recommended cycle (the LTS if still maintained, else the newest maintained). Unknown slugs get up to 3 suggestions.

{"runtimes": {"nodejs": {"latest": "26.12.1", "lts": "24.22.1", "next_lts": {"version": "26", "from": "2026-10-28"},
              "maintained": ["26", "24", "22"], "eol": "2028-04-30"}},
 "errors": {"pythn": "unknown product; did you mean: python, ..."}}

explain_issue

{"ecosystem": "npm", "package": "typescript-eslint", "version": "8.72.1"} → the declarations of one version, so an agent can dig into an issue without downloading registry documents: npm peerDependencies/optionalPeers/engines/deprecated, PyPI requires_dist (unconditional lines plus those of the extras named in package, e.g. fastapi[standard]), extras, requires_python, yanked; Maven parent and direct dependencies. The version defaults to the latest stable one.

Output schema

Every empty field is omitted: no null, [] or {}. The tools also publish an outputSchema, and the result arrives both as structuredContent and as compact JSON text.

check_stack:

Field
targets{"node"|"python"|"java": full version} used for the checks
npm, pypi, maven{name: latest stable version}. PyPI names are PEP 503-normalized; Maven keys are group:artifact (the BOM is included)
runtimes{slug: runtime info} as in get_runtime_info
issueslist of issues (below)
errors{"npm"|"pypi"|"maven"|"runtimes"|"targets": {item: message}}. One failure never fails the call
warnings{"targets": {"node"|"python"|"java": message}} when a target you asked for is end-of-life ("3.9 is end-of-life since 2025-10-31")
validation{"npm"|"pypi": "skipped"|"ok"|"failed"|"unavailable"|"timeout"}
staletrue when some data came from an expired cache entry because a registry was unreachable

Issue:

Field
kindsee below
ecosystemnpm, pypi, maven
packagethe offending package at its picked version (name@v, name==v, g:a:v)
required_bythe package (or BOM) that declares the constraint
rangethe declared constraint
targetthe runtime target checked (node 24.22.1, python 3.15.2, java 21.0.13+9)
suggestionanother version of the flagged package: the highest stable one that fixes the issue (satisfies every constraint the other requested packages, the target or the BOM put on it, and your own range). resolver issues: uv's own choices
alternativeonly when there is no suggestion (peer, requires, shared): highest stable version of a required_by package that accepts the picked one (or, for shared, lets the dependency resolve)
severity"warn"; absent means error
messageresolver output, deprecation or yank reason, …

suggestion and alternative are indicative only. The primary answer never moves.

Scope. Issues cover the constraints between the packages you request, and those that two of them put on a dependency they share (one level deep). A conflict further down the dependency tree is only caught by --resolver-validation: no issue does not guarantee that the set installs.

KindMeaning
peernpm peerDependencies between requested packages (optional peers count when requested)
requiresPyPI requires_dist between requested packages (markers evaluated for the target, extras honoured)
sharedtwo or more requested packages need incompatible versions of a package you did not request (npm required peers, PyPI requires_dist); package is that dependency, required_by lists them
enginesnpm engines.node vs the Node target
pythonrequires_python vs the Python target
wheelsno wheel for the target CPython on Linux x86_64 (any / manylinux*_x86_64 tags; warn when an sdist exists)
bomMaven version differs from the one managed by maven_bom (warn)
javaSpring Boot's Java baseline (java.version of spring-boot-starter-parent) vs the Java target
deprecatednpm deprecated version, PyPI project archived/deprecated/quarantined (warn)
yankedthe latest PyPI version is yanked (warn; the pick prefers a non-yanked one)
unsatisfiableyour own constraint matches no stable version
resolvera real resolver rejected the set (only with --resolver-validation)

How versions are chosen

  • npm: versions matching ^\d+\.\d+\.\d+$ only, never above dist-tags.latest (unless latest is itself a pre-release). Canary/next/experimental tags are ignored.
  • PyPI: PEP 440 final releases (no pre/dev). A version whose files are all yanked is used only if nothing else matches, and is always flagged. A release without any installable file (all deleted, or eggs only) is ignored.
  • Maven: no alpha/beta/rc/cr/milestone/snapshot/preview/ea qualifiers (-M1, .RC2, -SNAPSHOT, a1, b2, …), ordered with Maven's ComparableVersion rules. The <release> tag of maven-metadata.xml is not trusted (it is often a release candidate). Early build-date versions (commons-collections 20040616, which Maven orders above 3.2.2) are skipped unless the artifact has nothing else or your range names one.
  • Version comparisons are numeric, never lexicographic (6.0.10 > 6.0.9).
  • Ranges that cannot be evaluated (workspace:*, npm: aliases, file:, git URLs, dist-tag names) never create issues.

Resolver validation (--resolver-validation)

Off by default. When enabled, and if the binaries are on PATH:

  • PyPI: uv pip compile - on the pinned set (--python-version <target> --python-platform linux). If uv rejects it, a resolver issue carries uv's explanation, and an unpinned run supplies uv's own choices as suggestion.
  • npm: npm install --package-lock-only --ignore-scripts --no-audit --no-fund in a fresh temp directory. ERESOLVE becomes a resolver issue.

No shell, no install scripts, a timeout on every run. Package names reach the resolvers through stdin or a generated package.json, never through the command line. This adds about 2 s per call on a warm machine.

Data sources and caching

npm abbreviated metadata, the PyPI JSON Simple API (PEP 691) plus per-version JSON, Maven Central maven-metadata.xml and POMs, and endoflife.date API v1. Only reduced data is cached (a few KB per package; typescript's 8.7 MB document becomes 2 KB). Per-version data (PyPI metadata, POMs) never expires. Writes are atomic and safe across processes. When a registry is unreachable, expired entries are served and the answer says "stale": true. A "not found" answer is reused for 15 minutes (at most the TTL), so a misspelled package is not looked up again on every call while a new publish still shows up quickly.

Measured for the reference stack: cold (empty cache) 1.6 s, warm 60–80 ms.

Roadmap (not in v1)

  • Vulnerability data (OSV).
  • Cooldown / minimum release age.
  • Private registries and authentication.
  • Manifest parsing (package.json, pyproject.toml, pom.xml).
  • Per-library Java minimums for Maven artifacts (v1 checks Spring Boot only).
  • Gradle-style ranges, transitive peer analysis.

Development

uv sync
uv run pytest                  # offline, deterministic (recorded fixtures, frozen dates)
uv run pytest -m live          # live registries, asserts properties
uv run pytest -m resolvers     # differential tests vs real uv/npm (needs node + uv)
uv run ruff check . && uv run ruff format --check .
uv run mypy --strict src/
uv run python scripts/record_fixtures.py   # refresh tests/fixtures/cache from the registries
uv run python scripts/reference_run.py     # reference stack, live, with timings
uv run python scripts/sweep.py --npm 1000 --pypi 1000   # picks vs registry truth, top packages

The differential tests are the main correctness guarantee. For each stack they cover, a set check_stack calls issue-free must resolve with uv pip compile / npm install --package-lock-only, and every peer/requires/shared conflict it reports must be rejected by them. See AGENTS.md for the project's invariants and docs/PLAN.md for verified facts and deviations from the original spec.

License

Apache-2.0

PYPI
stackcheck-mcp
Install Command
pip install stackcheck-mcp
Runtime: uvx