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:
typescriptdist-tags.latestis 7.0.2;typescript-eslint@8.72.1(latest) declarespeerDependencies.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:
nameorname@range(@types/react@^19: the range follows the last@).name@latestmeans 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 likenodework;javameanseclipse-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 ofeclipse-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 abovedist-tags.latest(unlesslatestis 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'sComparableVersionrules. The<release>tag ofmaven-metadata.xmlis not trusted (it is often a release candidate). Early build-date versions (commons-collections20040616, which Maven orders above3.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, aresolverissue carries uv's explanation, and an unpinned run supplies uv's own choices assuggestion. - npm:
npm install --package-lock-only --ignore-scripts --no-audit --no-fundin a fresh temp directory.ERESOLVEbecomes aresolverissue.
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.