stackhint

stackhint

Which MCP servers, plugins and skills does your repo actually need? stackhint looks at the project and at what Claude Code and Codex already have set up, then tells you, pointing at the file that made it think so. It can also add a server for you, after showing the exact change.

It runs locally, has no dependencies and sends nothing anywhere.

Try it in any project (Node.js 20+, nothing to install):

npx -y github:Protemir/stackhint recommend

Or add it to Claude Code and ask "which MCP servers would help here?":

/plugin marketplace add Protemir/stackhint

/plugin install stackhint@stackhint

That is the real output on examples/dotnet-shop, a small ASP.NET Core API (npm run demo reproduces it). Every line in "Why now" points at a file; a README that only says "we might try Kubernetes one day" gets no Kubernetes suggestion.

What it reads: manifests (*.csproj, package.json, pyproject.toml, go.mod, Cargo.toml, Gradle, Composer, Gemfile), compose files, Kubernetes and Terraform files, CI, .env.example key names, README links and git history, plus your Claude Code and Codex configs. It knows 143 tools (MCP servers, plugins, skills, CLIs), checked by hand against the vendors' docs, including the retired ones, so stackhint check can tell you what to replace.

Why I built it

There are thousands of MCP servers, and a good share of the "top 10" lists still point at servers that were archived in 2025. The reference Postgres server, for example, has a known read-only bypass and no fixes. I wanted something that looks at my repo, knows what I already have configured in Claude Code and Codex, and tells me what is worth adding and what to replace, without sending my code anywhere and without touching my config behind my back.

How it compares to what exists:

• Anthropic's claude-code-setup plugin has Claude itself look at the codebase and suggest automations. It is good, but it works only in Claude Code, costs tokens on every run, doesn't check what you already have, and doesn't install anything.
• MCP Advisor and MCP Compass search MCP directories from a natural-language query. They don't look at your project.
• stackhint is deterministic and local. It covers Claude Code and Codex, knows your existing setup, keeps a hand-checked registry with exact install commands and read-only defaults, and handles installs with a diff, a backup and a rollback.

Install

stackhint needs Node.js 20 or newer. It has no runtime dependencies.

Run it without installing (downloads from GitHub):

npx -y github:Protemir/stackhint recommend

Or install the command globally:

npm install -g github:Protemir/stackhint

Claude Code

The plugin adds a stackhint skill, so Claude can answer "which MCP servers would help here?", and a quiet session-start hint (see Proactive mode).

/plugin marketplace add Protemir/stackhint

/plugin install stackhint@stackhint

From a shell: claude plugin marketplace add Protemir/stackhint and then claude plugin install stackhint@stackhint.

Codex

Codex reads the same repository as a plugin marketplace:

codex plugin marketplace add Protemir/stackhint

Then install stackhint from /plugins. Codex asks you to approve plugin hooks in /hooks before they run.

Claude Desktop

Download stackhint- .mcpb from the latest release and open it: Claude Desktop installs it as an extension. Pass the project folder as path when you ask for recommendations. The same server is in the official MCP Registry as io.github.Protemir/stackhint.

Without plugins: MCP server

stackhint can also run as a read-only MCP server with five tools (recommend_tools, explain_tool, search_tools, tooling_status, plan_install). It can never install anything; plan_install only shows the plan and the command for you to run.

stackhint setup claude   # or: stackhint setup codex

setup shows what it will add (an MCP server entry and the skill file) and asks first. To do it by hand:

claude mcp add --scope user stackhint -- npx -y github:Protemir/stackhint mcp

codex mcp add stackhint -- npx -y github:Protemir/stackhint mcp

Commands

Every command takes --format text|md|json. Exit codes: 0 ok, 1 error, 2 usage error, 3 not approved, 4 blocked.

What it looks at

• Package manifests: *.csproj, Directory.Packages.props, package.json, requirements*.txt (also requirements/ folders and UTF-16 files), pyproject.toml (Poetry, uv, PDM), Pipfile, go.mod (direct requirements only), Cargo.toml, pom.xml, build.gradle(.kts), Gradle version catalogs, composer.json, Gemfile, pubspec.yaml, Prisma schemas.
• Infrastructure: Dockerfiles, compose files (service images like postgres:17), Kubernetes manifests, Helm charts, Argo CD and Flux objects, Terraform providers, Pulumi, Bicep, CDK, and the configs of Wrangler, Vercel, Netlify, Fly.io, Render, Railway, Heroku, DigitalOcean, Firebase and Supabase.
• Frameworks and engines: Angular, Svelte, Nuxt, Astro, Next.js, Expo, Flutter, Shopify apps and themes, Laravel, Storybook, Nx, shadcn/ui, Xcode, Unity, Unreal, browser extensions, browser games (three.js, Phaser, Pixi) and plain pages with scripts.
• CI: GitHub Actions, GitLab CI, Azure Pipelines, CircleCI, Jenkins, Buildkite, Bitbucket.
• APIs and tests: OpenAPI files, .http files, Postman collections, protobuf, GraphQL, Playwright/Cypress/Jest/Vitest/pytest configs.
• Settings files: appsettings*.json connection strings and .env.example key names, only to learn which database or service is used. Values are never stored or printed.
• Links in README/CONTRIBUTING: Jira, Confluence, Linear, Asana, monday.com, ClickUp, Figma, Notion.
• Git: remote hosts, branch names, recent commit subjects (local git log). Issue keys like SHOP-123 suggest Jira; 8+ commits with the same shape ("add migration ...") suggest a skill.
• MCP servers your team already configured for VS Code or Cursor (.vscode/mcp.json, .cursor/mcp.json).
• Your task, if you pass one. English and Russian keywords both work.

A project that merely mentions a technology in prose does not get a recommendation for it. Signals carry a strength, and most entries need concrete evidence (requiresAny).

How ranking works

Each registry entry lists the signals that make it relevant, with a weight. The score is:

fit   = relevance × (0.55 + 0.25 × value + 0.2 × immediacy) × compatibility × overlap

score = 100 × (fit − setup cost − risk), clamped to 0..100

• relevance combines matching signals (noisy-OR of weight × strength);
• value comes from the registry's estimate of time saved and how often you'd use it;
• immediacy is higher when the evidence comes from your task;
• overlap goes down when an equivalent tool is already set up (a CLI like gh counts partially);
• setup cost covers effort, auth and missing prerequisites; risk covers write/admin access, community or preview status and incomplete metadata.

These numbers are editorial estimates, not measurements, and stackhint says so in its output. Confidence (high/medium/low) reflects how strong the evidence is and whether compatibility and metadata are verified. stackhint explain prints the full breakdown.

What it knows about your setup

Claude Code: ~/.claude.json (user scope and per-project local scope), the project .mcp.json, approvals in .claude/settings*.json, enabled plugins and the MCP servers they bundle, skills and commands, and an admin-managed managed-mcp.json.

Codex: ~/.codex/config.toml (or $CODEX_HOME), a trusted project's .codex/config.toml, enabled plugins, and skills in ~/.agents/skills, .agents/skills and ~/.codex/skills.

It reports each tool as configured, disabled, not configured, incompatible or unknown (for example when a config file can't be parsed). "Configured" means it is in the config. stackhint does not claim a server is running unless you ask it to verify with the host's CLI (install --verify).

Installing safely

Installing changes your configuration, so stackhint follows the same steps every time:

1. It builds a plan: the official source, the scope, the exact diff or command, permissions, auth, network access, required environment variables (by name only) and side effects.
2. It asks. Without a terminal it refuses unless you pass --yes. --dry-run never asks and never writes.
3. Before writing, it checks the file hasn't changed since the plan was made, and saves a backup.
4. It writes atomically, then parses the result back and checks the new server is there. If anything is off, the original is restored.
5. For Codex it can confirm with codex mcp get. For Claude Code, --verify runs claude mcp get.
6. It prints the undo command. stackhint rollback restores the file byte-for-byte, or runs claude mcp remove. If you edited the file after the install, rollback refuses unless you pass --force.

Where it writes:

Rules it follows:

• Read-only variants are the default where the vendor offers one (X-MCP-Readonly for GitHub, --access-mode=restricted for Postgres MCP Pro, --read-only f