stackhint

stackhint

你的代码仓库实际需要哪些 MCP 服务、插件和技能？stackhint 会检查项目以及 Claude Code 和 Codex 已配置的内容，然后告诉你答案，并指出让它得出结论的文件。它还可以为你添加服务，并在操作前展示确切的更改。

它在本地运行，无需依赖，也不会向任何地方发送数据。

在任意项目中试用（Node.js 20+，无需安装）：

npx -y github:Protemir/stackhint recommend

也可以将其添加到 Claude Code，然后询问“这里有哪些 MCP 服务会有帮助？”：

/plugin marketplace add Protemir/stackhint
/plugin install stackhint@stackhint

这是在 examples/dotnet-shop 上的实际输出。它是一个小型 ASP.NET Core API（运行 npm run demo 即可重现）。「为何推荐」中的每一行都会指向一个文件；如果 README 只写着“我们也许有一天会尝试 Kubernetes”，就不会推荐 Kubernetes。

它会读取：清单文件（*.csproj、package.json、pyproject.toml、go.mod、Cargo.toml、Gradle、Composer、Gemfile）、compose 文件、Kubernetes 和 Terraform 文件、CI、.env.example 中的键名、README 链接和 git 历史，以及你的 Claude Code 和 Codex 配置。它收录了 143 个工具（MCP 服务、插件、技能、CLI），并逐一对照供应商文档进行人工核查，也包括已停用的工具，因此 stackhint check 可以告诉你该替换什么。

我为何构建它

MCP 服务有数千个，而许多“十大”榜单仍在推荐 2025 年已归档的服务。例如，官方 Postgres 服务存在已知的只读限制绕过问题，且没有修复。我想要一个工具，能检查我的代码仓库，了解我已在 Claude Code 和 Codex 中配置了什么，并告诉我哪些值得添加、哪些应该替换；它不会向任何地方发送我的代码，也不会擅自修改我的配置。

与现有工具相比：

• Anthropic 的 claude-code-setup 插件会让 Claude 检查代码库并推荐自动化方案。它很不错，但只能在 Claude Code 中使用，每次运行都会消耗令牌，不会检查你已有的配置，也不会安装任何内容。
• MCP Advisor 和 MCP Compass 会根据自然语言查询搜索 MCP 目录，但不会检查你的项目。
• stackhint 的结果是确定性的，且在本地运行。它支持 Claude Code 和 Codex，了解你已有的配置，维护经过人工核查的注册表，其中包含准确的安装命令和默认只读设置；安装时还会提供差异对比、备份和回滚。

安装

stackhint 需要 Node.js 20 或更高版本，没有运行时依赖。

无需安装即可运行（从 GitHub 下载）：

npx -y github:Protemir/stackhint recommend

也可以全局安装命令：

npm install -g github:Protemir/stackhint

Claude Code

该插件会添加一个 stackhint 技能，让 Claude 可以回答“这里有哪些 MCP 服务会有帮助？”，并提供安静的会话启动提示（参见主动提示）。

/plugin marketplace add Protemir/stackhint
/plugin install stackhint@stackhint

也可以在 Shell 中运行：claude plugin marketplace add Protemir/stackhint，然后运行 claude plugin install stackhint@stackhint。

Codex

Codex 会将同一仓库作为插件市场读取：

codex plugin marketplace add Protemir/stackhint

然后从 /plugins 安装 stackhint。Codex 会要求你在 /hooks 中批准插件钩子，然后才会运行它们。

Claude Desktop

从最新版本下载 stackhint-<version>.mcpb 并打开：Claude Desktop 会将其安装为扩展。请求建议时，将项目文件夹作为 path 传入。同一服务也已收录于官方 MCP Registry，名称为 io.github.Protemir/stackhint。

不使用插件：MCP 服务

stackhint 也可以作为只读 MCP 服务运行，提供五个工具（recommend_tools、explain_tool、search_tools、tooling_status、plan_install）。它绝不会安装任何内容；plan_install 只会显示计划和供你运行的命令。

stackhint setup claude   # or: stackhint setup codex

setup 会显示将添加的内容（MCP 服务条目和技能文件），并先征求同意。手动操作方法如下：

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

命令

命令	功能
stackhint scan [path]	显示检测结果，以及每项信号的依据
stackhint recommend [path]	按排名显示建议。使用 --task "..." 获取针对特定任务的建议，使用 --host claude|codex 指定主机，使用 --all 显示全部
stackhint explain <id>	说明原因、可访问内容、设置方法、将添加的确切 JSON/TOML，以及供应商提供的命令
stackhint install <id> --host <h>	显示计划和差异，征求同意后应用。可使用 --dry-run、--scope user|project|local、--access read|write、--param k=v
stackhint try <id> --host <h>	为单次会话启动服务，不更改任何配置
stackhint status	显示 Claude Code 和 Codex 的配置情况
stackhint check	检查配置：已归档的服务、写入配置的密钥、存在只读权限时仍使用写入权限的情况，以及重复项。遇到问题时，--strict 会以状态码 1 退出（适用于 CI）
stackhint registry search <words>	搜索本地注册表。使用 --remote 还会查询官方 MCP Registry（需主动启用）
stackhint dismiss <id>	永不再建议。使用 --for 14d 暂停建议 14 天，使用 --project 仅对当前仓库生效
stackhint rollback [id]	列出 stackhint 执行的安装，或撤销其中一项
stackhint config ...	show、get <key>、set <key> <value>
stackhint doctor	检查 Node、配置文件、主机 CLI 和常见问题
stackhint mcp	通过 stdio 运行只读 MCP 服务

每个命令都支持 --format text|md|json。退出码：0 表示成功，1 表示错误，2 表示用法错误，3 表示未获批准，4 表示已阻止。

它会检查什么

• 软件包清单：*.csproj、Directory.Packages.props、package.json、requirements*.txt（也包括 requirements/ 文件夹和 UTF-16 文件）、pyproject.toml（Poetry、uv、PDM）、Pipfile、go.mod（仅直接依赖）、Cargo.toml、pom.xml、build.gradle(.kts)、Gradle 版本目录、composer.json、Gemfile、pubspec.yaml、Prisma 架构。
• 基础设施：Dockerfile、compose 文件（如 postgres:17 这样的服务镜像）、Kubernetes 清单、Helm chart、Argo CD 和 Flux 对象、Terraform providers、Pulumi、Bicep、CDK，以及 Wrangler、Vercel、Netlify、Fly.io、Render、Railway、Heroku、DigitalOcean、Firebase 和 Supabase 的配置。
• 框架和引擎：Angular、Svelte、Nuxt、Astro、Next.js、Expo、Flutter、Shopify 应用和主题、Laravel、Storybook、Nx、shadcn/ui、Xcode、Unity、Unreal、浏览器扩展、浏览器游戏（three.js、Phaser、Pixi），以及带脚本的普通页面。
• CI：GitHub Actions、GitLab CI、Azure Pipelines、CircleCI、Jenkins、Buildkite、Bitbucket。
• API 和测试：OpenAPI 文件、.http 文件、Postman 集合、protobuf、GraphQL、Playwright/Cypress/Jest/Vitest/pytest 配置。
• 设置文件：appsettings*.json 中的连接字符串和 .env.example 中的键名，仅用于判断使用了哪种数据库或服务。绝不会存储或打印值。
• README/CONTRIBUTING 中的链接：Jira、Confluence、Linear、Asana、monday.com、ClickUp、Figma、Notion。
• Git：远程主机、分支名称、近期提交主题（本地 git log）。类似 SHOP-123 的 issue 键表示可能使用 Jira；8 条或更多格式相同的提交（如“add migration ...”）表示可能需要某项技能。
• 团队已为 VS Code 或 Cursor 配置的 MCP 服务（.vscode/mcp.json、.cursor/mcp.json）。
• 你的任务（如果提供）。英语和俄语关键词均可。

项目仅在说明文字中提及某项技术，不会因此获得该技术的推荐。每项信号都有强度，大多数条目需要具体证据（requiresAny）。

排名机制

注册表中的每个条目都会列出相关信号及其权重。评分如下：

fit   = relevance × (0.55 + 0.25 × value + 0.2 × immediacy) × compatibility × overlap
score = 100 × (fit − setup cost − risk), clamped to 0..100

• 相关性综合匹配信号计算得出（权重 × 强度的 noisy-OR）；
• 价值取决于注册表对节省时间和使用频率的估算；
• 证据来自你的任务时，即时性更高；
• 如果已设置等效工具，重叠度会降低（像 gh 这样的 CLI 也会部分计入）；
• 设置成本涵盖所需工作、身份验证和缺失的前置条件；风险涵盖写入/管理员权限、社区或预览状态，以及元数据不完整。

这些数字是编辑估算值，并非测量结果；stackhint 会在输出中说明这一点。置信度（高/中/低）反映证据强度，以及兼容性和元数据是否经过验证。stackhint explain <id> 会打印完整的评分明细。

它对你的设置了解什么

Claude Code：~/.claude.json（用户范围和各项目的本地范围）、项目的 .mcp.json、.claude/settings*.json 中的批准设置、已启用的插件及其捆绑的 MCP 服务、技能和命令，以及由管理员管理的 managed-mcp.json。

Codex：~/.codex/config.toml（或 $CODEX_HOME）、受信任项目的 .codex/config.toml、已启用的插件，以及 ~/.agents/skills、.agents/skills 和 ~/.codex/skills 中的技能。

它会将每项工具报告为已配置、已禁用、未配置、不兼容或未知（例如，无法解析配置文件时）。“已配置”表示该工具存在于配置文件中。除非你要求它使用主机的 CLI 进行验证（install --verify），否则 stackhint 不会声称某项服务正在运行。

安全安装

安装会更改配置，因此 stackhint 每次都会遵循相同的步骤：

1. 它会制定计划：官方来源、作用范围、精确差异或命令、权限、身份验证、网络访问、所需环境变量（仅列出名称）以及副作用。
2. 它会征求确认。没有终端时，除非传入 --yes，否则它会拒绝安装。--dry-run 不会征求确认，也不会写入任何内容。
3. 写入前，它会检查文件自制定计划后是否发生过更改，并保存备份。
4. 它会以原子方式写入，然后重新解析结果并检查新服务是否存在。如果有任何异常，就会还原原文件。
5. 对于 Codex，它可以通过 codex mcp get 确认。对于 Claude Code，--verify 会运行 claude mcp get。
6. 它会打印撤销命令。stackhint rollback <id> 会逐字节还原文件，或运行 claude mcp remove。如果你在安装后编辑了文件，除非传入 --force，否则回滚会被拒绝。

写入位置：

宿主	作用范围	方式
Claude Code	project	合并到 .mcp.json（通常会提交；Claude 会要求每个人批准）
Claude Code	local（默认）、user	运行 claude mcp add，因为 Claude Code 会持续重写 ~/.claude.json
Codex	user（默认）	在 ~/.codex/config.toml 中追加一个 [mcp_servers.<name>] 表，其余内容逐字节保持不变
Codex	project	追加到 .codex/config.toml（Codex 只会在受信任的项目中读取该文件）

遵循的规则：

• 如果供应商提供只读版本，则默认使用只读版本（GitHub 使用 X-MCP-Readonly，Postgres MCP Pro 使用 --access-mode=restricted，Kubernetes 使用 --read-only，Supabase 使用 read_only=true，等等）。使用 --access write 可选择不使用只读模式。
• 机密仅通过环境变量名称引用：Claude Code 配置中使用 ${VAR}，Codex 中使用 bearer_token_env_var 和 env_vars。stackhint 从不索要令牌，也从不写入令牌。
• 对于可以检查的包版本，都会固定版本（例如 [email protected]）。
• 它从不运行远程脚本，从不安装包，也从不更改其他内容。插件、技能和 CLI 会作为步骤显示（确认后，可通过 claude plugin install 安装 Claude Code 插件）。
• 在原生 Windows 上，npx 服务会通过 cmd /c 包装，因为两个客户端都要求这样做。
• 它不会安装已归档或已弃用的条目，不会覆盖同名服务，也不会在启用管理员管理的 MCP 配置时改动 Claude Code。

主动提示

该插件会安装两个钩子。它们的行为取决于 mode：

模式	会话开始时	每次提示词
manual	无	无
balanced（默认）	最多提供 2 条高置信度建议；每个项目每天最多一次	无
proactive	最多提供 3 条建议，并显示一行提示	如果提示词开启了一种新类型的任务（PR 审查、慢查询），且有适用的缺失工具，则提供一条建议

建议会进入 Agent 的上下文，并附带指示：仅在相关时提及，绝不要自行安装任何内容。同一条目 14 天内不会重复出现；被忽略的条目不会再次出现；项目中的新依赖可以突破每日限制。提示词钩子只会将提示词保留在内存中，绝不会写入任何位置。

stackhint config set mode manual       # turn hints off
stackhint config set mode proactive    # more hints

坦诚说明限制：

• 两个客户端都没有后台通知 API，因此“主动”指的是会话开始和提示词钩子。没有文件监视器。
• 钩子建议会发送给模型，而不是直接发送给你（主动模式中的一行提示除外）。它是否会提及建议取决于对话内容。
• Codex 要求你先在 /hooks 中批准钩子，它们才会运行。

隐私

• 只读取检测器所需的文件，并限制文件大小和耗时。.env、.env.local、私钥、secrets.json 和 appsettings.*secret* 永远不会被打开。
• 连接字符串、令牌和包含凭据的 URL 永远不会被存储或打印；证据会注明文件和发现类型，而不会包含具体值。所有输出、审计日志和错误都会经过脱敏处理。
• 默认不访问网络。只有在执行 stackhint config set network true 后，registry search --remote 才会查询官方 MCP Registry，并将结果缓存 24 小时。
• git log 会在本地运行以读取提交主题。使用 stackhint config set gitHistory false 可将其关闭。
• 状态数据存放在 ~/.stackhint（或 $STACKHINT_HOME）中：config.json、state.json（忽略记录和冷却时间，以项目路径的哈希为键）、audit.log、backups/。

注册表

registry/registry.json 有 143 个条目：120 个可推荐工具（89 个 MCP 服务、28 个插件、2 个 CLI、1 个技能），以及 23 个已弃用或已归档的条目。stackhint 会检测配置中的这些条目，以便建议替代项。每个 URL、包名、标志和插件 ID 都已在 verifiedAt 日期（2026 年 10 月）对照供应商的代码库或文档进行核验。工作量、节省的时间和使用频率均为我的估算。

覆盖范围包括：源代码管理（GitHub、GitLab、Azure DevOps）、问题跟踪工具（Jira/Confluence、Linear）、数据库（Postgres、MySQL、SQL Server、ClickHouse、MongoDB、Redis、Supabase、Neon、Firebase）、容器和基础设施（Kubernetes、Docker、Terraform、Argo CD、Flux）、云平台（AWS、Azure、Google Cloud、Cloudflare、Vercel）、文档（Context7、Microsoft Learn、DeepWiki）、CI（CircleCI、Buildkite、Jenkins）、质量（SonarQube、Semgrep、Snyk）、可观测性（Sentry、Grafana）、设计（Figma）、支付（Stripe）、浏览器测试（Playwright、Chrome DevTools）、Claude Code LSP 和代码审查插件，以及用于重复工作流的项目技能。

添加自定义工具

将 JSON 文件放入 ~/.stackhint/registry.d/（或将 STACKHINT_REGISTRY 指向该文件）。自定义条目的验证方式与内置条目相同，始终视为由社区维护，并且可以覆盖具有相同 ID 的内置条目。

{
  "entries": [
    {
      "id": "team-db",
      "name": "Our analytics DB server",
      "kind": "mcp",
      "category": "database",
      "description": "Read-only access to the analytics warehouse.",
      "docs": "https://wiki.example.com/mcp/analytics",
      "status": "active",
      "triggers": [{ "signal": "db:clickhouse", "weight": 0.8 }, { "signal": "task:db", "weight": 0.6 }],
      "requiresAny": ["db:clickhouse"],
      "problem": "Analysts paste query results into the chat by hand.",
      "workflow": "Ask the agent to check yesterday's event counts.",
      "benefits": ["Schema and SELECT queries"],
      "access": { "level": "read", "summary": "SELECT only", "readOnlyAvailable": true },
      "auth": { "type": "oauth", "detail": "Company SSO" },
      "hosts": { "claude": { "support": "yes" }, "codex": { "support": "yes" } },
      "install": { "serverName": "analytics", "readOnly": { "transport": "http", "url": "https://mcp.example.com/analytics" } },
      "match": { "urls": ["mcp.example.com/analytics"] }
    }
  ]
}

验证会拒绝可能被滥用的条目：参数中含有 shell 元字符或引号、将解释器和下载器用作命令（bash、curl、powershell、node……）、Docker 特权标志和主机挂载、普通 HTTP URL（localhost 除外）、标头、环境变量或参数中的明文机密，以及试图指示 Agent 的文本（“ignore previous instructions”、伪造的 </system> 标签）。缺失的元数据会采用谨慎的默认值填充（未知访问权限按写入权限处理），并降低置信度。

stackhint scan 会显示在项目中发现的信号 ID；分析器可能生成的全部信号都位于 src/context/（packages.ts、analyzer.ts、task.ts）。如需添加内置工具，请提交拉取请求，并附上条目及已核验的来源；npm test 会验证每个触发条件都是分析器会生成的信号、安装规范能为两种宿主生成有效的 JSON 和 TOML，以及插件 ID 确实存在于官方市场中。

配置

stackhint config show 会打印当前值。键：

键	默认值	含义
mode	balanced	manual、balanced 或 proactive（见上文）
minScore	30	recommend 显示的最低分数
hookMinScore.balanced / .proactive	50 / 40	Hook 建议的最低分数
hookMaxItems.balanced / .proactive	2 / 3	每次 Hook 运行的建议数量
itemCooldownDays	14	同一建议在此期限内不重复出现
projectCooldownHours	24	此时间窗口内，每个项目最多生成一个会话启动批次
network	false	允许使用 registry search --remote
gitHistory	true	使用 git log 读取近期提交主题

环境变量：STACKHINT_HOME（状态目录）、STACKHINT_REGISTRY（额外的注册表文件，使用操作系统的路径分隔符分隔）、CLAUDE_CONFIG_DIR 和 CODEX_HOME（遵循与客户端相同的处理方式）、NO_COLOR。

架构

src/
  context/    project analyzer: file walk with budgets, manifest parsers, git, task keywords -> signals
  registry/   registry loading and validation, search, opt-in official MCP Registry client
  hosts/      read-only adapters: Claude Code and Codex configs, plugins, skills, PATH -> inventory
  engine/     ranking (recommend.ts) and configuration review (check.ts); pure functions
  install/    spec resolution, planning, applying with backup/validation, rollback
  hooks/      SessionStart and UserPromptSubmit hooks
  mcp/        minimal stdio MCP server (read-only tools)
  render/     text, Markdown and JSON output
  state/      config, dismissals, cooldowns, audit log
  cli.ts, commands.ts

引擎不处理主机配置格式；适配器会将配置转换为通用清单，安装模块则会将注册表规范转换为 Claude JSON 或 Codex TOML。TypeScript 通过 Node 内置的剥离器编译，移除类型（scripts/build.mjs），因此没有运行时或构建依赖；CI 会检查已提交的 dist/ 是否与源文件一致。

开发

npm install          # TypeScript and @types/node, for type checking only
npm run typecheck
npm run lint
npm test             # 300+ tests: node --test on the TypeScript sources (Node 22.18+)
npm run build        # writes dist/
npm run test:dist    # smoke tests on the built JavaScript (works on Node 20)

测试在临时沙盒中运行（虚拟主目录、Claude 和 Codex 配置目录），覆盖检测、排序、重复检测、配置合并、审批强制执行、试运行、回滚、脱敏、恶意注册表条目、网络故障、Hooks 和 MCP 协议。CI 还会使用 stackhint 写入的配置，通过真实的 claude 和 codex CLI 运行测试（tests/host-real.test.ts）。

故障排除

• “No terminal to confirm in”：你从脚本或 Agent 中运行了 install。请在终端中运行，或者阅读计划后传入 --yes。
• “Claude Code CLI not found on PATH”：用户和本地作用域需要 claude。请使用 --scope project，或自行运行打印出的命令。
• 某个服务显示“Failed to connect”：检查计划中列出的环境变量是否已在启动客户端的 Shell 中设置，并确认 npx/uvx/docker 可以下载软件包。
• Codex 忽略 .codex/config.toml：Codex 只会读取受信任项目中的项目配置。
• Codex 首次启动服务时超时：对于由软件包运行器启动的服务，stackhint 会设置 startup_timeout_sec = 60；如果下载速度较慢，请调高此值。
• 发现异常：运行 stackhint doctor，然后使用 stackhint scan --format json 的输出提交 Issue（其中不含机密信息，但分享前请先检查）。

卸载

• 撤销安装：stackhint rollback 会列出安装记录；stackhint rollback <id> 会撤销其中一条。
• Claude Code 插件：/plugin uninstall stackhint@stackhint 和 /plugin marketplace remove stackhint。
• Codex 插件：在 /plugins 中将其移除，然后运行 codex plugin marketplace remove stackhint。
• 由 setup 注册的 MCP 服务：运行 claude mcp remove stackhint --scope user，或从 ~/.codex/config.toml 中删除 [mcp_servers.stackhint]；技能文件位于 ~/.claude/skills/stackhint 或 ~/.agents/skills/stackhint。
• 全局命令：npm uninstall -g stackhint。
• 状态：删除 ~/.stackhint。

限制

• 注册表由人工整理，并于 2026 年 10 月核查。供应商可能会更改端点和标志；verifiedAt 会告知你信息的时效，check 会标记已知的弃用项。
• 检测基于启发式规则。它会读取通常能揭示技术栈的文件；不常见的目录结构可能无法识别（stackhint scan 会显示检测结果）。
• 分数是估算值，适合用于排序，不代表节省的时间。
• stackhint 本身不会安装软件包、插件或 CLI（Claude Code 插件会在你确认后通过 claude plugin install 安装）。
• Codex 支持已根据文档和 CI 中的 Codex CLI 进行验证；我每天都在 Windows 上使用 Claude Code，因此这一路径经过了更多实际使用。

许可证

MIT。如果 stackhint 为你节省了时间，在 GitHub 上点个星标可以帮助其他人找到它。