Skip to main content

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

Flag Default
--http off (stdio) serve streamable HTTP
--host, --port 127.0.0.1, 8000 HTTP bind address (loopback only, unless --allow-remote)
--allow-remote off accept a non-loopback --host (no authentication: put an authenticating proxy in front)
--resolver-validation off also check the picks with real resolvers (see below)
--resolver-timeout 120 seconds per resolver run
--call-timeout 45 seconds 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-level WARNING logs go to stderr (stdout is the stdio transport)
Environment Default
STACKCHECK_CACHE_DIR platform cache dir (platformdirs) on-disk cache of reduced registry data
STACKCHECK_CACHE_TTL 21600 (6 h) seconds; 0 disables the cache
STACKCHECK_CACHE_MAX_AGE 60 days; 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_DIR honoured (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
issues list 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"}
stale true when some data came from an expired cache entry because a registry was unreachable

Issue:

Field
kind see below
ecosystem npm, pypi, maven
package the offending package at its picked version (name@v, name==v, g:a:v)
required_by the package (or BOM) that declares the constraint
range the declared constraint
target the runtime target checked (node 24.22.1, python 3.15.2, java 21.0.13+9)
suggestion another 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
alternative only 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
message resolver 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.

Kind Meaning
peer npm peerDependencies between requested packages (optional peers count when requested)
requires PyPI requires_dist between requested packages (markers evaluated for the target, extras honoured)
shared two 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
engines npm engines.node vs the Node target
python requires_python vs the Python target
wheels no wheel for the target CPython on Linux x86_64 (any / manylinux*_x86_64 tags; warn when an sdist exists)
bom Maven version differs from the one managed by maven_bom (warn)
java Spring Boot's Java baseline (java.version of spring-boot-starter-parent) vs the Java target
deprecated npm deprecated version, PyPI project archived/deprecated/quarantined (warn)
yanked the latest PyPI version is yanked (warn; the pick prefers a non-yanked one)
unsatisfiable your own constraint matches no stable version
resolver a 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

Metadata

Release files for stackcheck-mcp 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for stackcheck-mcp 0.1.0
File Size Uploaded Provenance Actions
stackcheck_mcp-0.1.0.tar.gz 151.7 kB Without provenance Details for stackcheck_mcp-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for stackcheck-mcp 0.1.0
File Interpreter ABI Platform Actions
stackcheck_mcp-0.1.0-py3-none-any.whl Python 3 none any Details for stackcheck_mcp-0.1.0-py3-none-any.whl

Total release size: 209.0 kB

Release files / stackcheck_mcp-0.1.0.tar.gz

Download URL stackcheck_mcp-0.1.0.tar.gz
Size 151.7 kB
Tags Source
SHA-256 checksum
How to use checksums
70c23d6836e353da409684ceb7f0401f64535e6e40fa95c52e854d13a0723fd7
BLAKE2b-256 checksum
How to use checksums
a746f83b0171b4e16a3aed9343f80710a9194bbcf65598bff1a640990fb464e3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / stackcheck_mcp-0.1.0-py3-none-any.whl

Download URL stackcheck_mcp-0.1.0-py3-none-any.whl
Size 57.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
425c8cc96087841c248b9748588aedd28b8e9ae5633078ba016badc4f00cc861
BLAKE2b-256 checksum
How to use checksums
c7f0ef228867b30af22e5593c91d4c3b8fbb669ecc33e938b4038e9a28eaaeb4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for stackcheck-mcp 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page