stackcheck-mcp
# 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.
<!-- mcp-name: io.github.titouannnn/stackcheck-mcp -->
## 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:
```json
{"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:
```bash
claude mcp add stackcheck -- uvx stackcheck-mcp
```
Any client with a JSON config (Claude Desktop, Cursor, VS Code, …):
```json
{
"mcpServers": {
"stackcheck": {"command": "uvx", "args": ["stackcheck-mcp"]}
}
}
```
Streamable HTTP instead of stdio:
```bash
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`
```json
{
"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](https://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](https://github.com/titouannnn/stackcheck-mcp/blob/main/docs/SPEC.md) §9 stack, live on 2026-10-27, 963
bytes):
```json
{
"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.
```json
{"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
```bash
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](https://github.com/titouannnn/stackcheck-mcp/blob/main/AGENTS.md)
for the project's invariants and [docs/PLAN.md](https://github.com/titouannnn/stackcheck-mcp/blob/main/docs/PLAN.md) for verified facts and
deviations from the original spec.
## License
Apache-2.0
TDQS
Scored across 3 tools
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.
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.
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.
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.