Skip to main content
Glama
stackcheck-mcp

stackcheck-mcp

by titouannnn

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"}}

Related MCP server: Dependency Health MCP

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

Available Tools

3 tools
check_stackB
Read-onlyIdempotent

Latest stable versions plus incompatibilities between the packages and their shared deps (peer deps, requires_dist, engines, requires_python, wheels, BOM). Example: {"npm": ["react", "typescript", "typescript-eslint", "vite@^8"], "pypi": ["fastapi"]}

Inputs: npm, pypi, maven, targets, +2 more. Returns: npm, pypi, maven, stale, +6 more

explain_issueB
Read-onlyIdempotent

Declared peer deps/engines (npm), requires_dist/requires_python (PyPI) or parent and dependencies (Maven) of one version, to dig into an issue. Example: {"ecosystem": "npm", "package": "typescript-eslint", "version": "8.72.1"}

Inputs: package (required), ecosystem (required), version. Returns: error, stale, extras, parent, +11 more

get_runtime_infoB
Read-onlyIdempotent

Latest, LTS (lts_eol: true if that LTS is end-of-life), next LTS, maintained cycles and EOL date of the recommended cycle, from endoflife.date. Example: {"products": ["nodejs", "python", "eclipse-temurin"]}

Inputs: products (required). Returns: stale, errors, runtimes

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 3 tools

    Disambiguation4/5

    Each tool targets a distinct job: bulk stack compatibility checking, runtime/language lifecycle and EOL data, and single-package dependency drill-down. The only mild overlap is that explain_issue is essentially a detail view of what check_stack surfaces, but the descriptions make the boundary clear enough to avoid misselection.

    Naming Consistency4/5

    All three names follow a snake_case verb_noun pattern (check_stack, get_runtime_info, explain_issue). The verbs differ (check/get/explain) but the variation is semantically meaningful rather than inconsistent.

    Tool Count4/5

    Three tools is on the lean side but each maps to a clearly different diagnostic step, with no redundancy. It sits at the low end of the comfortable 3-15 range rather than being under-scoped.

    Completeness3/5

    The surface covers diagnosis well (compatibility, lifecycle/EOL, per-version dependency inspection) but stops at reporting: there is no remediation tool to suggest compatible version combinations, no way to look up a single package's latest version outside a stack, and no lockfile/manifest ingestion. These are notable gaps an agent would hit when asked to actually fix a conflict.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables users to look up package versions, scan for vulnerabilities, and analyze dependencies across multiple registries (npm, Maven, PyPI, etc.) using exact version recommendations for security.
      5
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables checking whether software packages are deprecated, archived, stale, active, or unknown with supporting evidence, auditing dependency manifests, and looking up runtime support and end-of-life dates.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Verified, dated facts for AI coding agents: what breaks between npm package versions (diffed from TypeScript types), per-version vulnerabilities, the newest version compatible with a given Node/Python/Rust/PHP, end-of-life dates of ~480 runtimes and frameworks, and AI model prices. Covers npm, PyPI, crates.io and Packagist.
      12
      1
      AGPL 3.0
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI coding agents to ground dependency setup, compatibility checks, and major-version migration advice in a project's real runtime, lockfiles, and config files. It parses local project state and npm registry metadata deterministically, then returns tag-pinned install commands, breaking changes, and upgrade steps rather than generic documentation.
      5
      53 npm
      MIT