内容
# mcp-wheelcheck
> 在您的AI代理自豪地发明第412个“使用SQLite和嵌入式跟踪的使用跟踪器”之前，请先检查是否已经有人构建了它。
`mcp-wheelcheck`是一个MCP服务器，在您编写代码之前，它会在开源生态系统中进行搜索。
它并行检查 **npm**、**crates.io** 和 **GitHub**，并返回带有描述、星级/下载量和链接的排名候选结果。单个软件包检查也适用于 **PyPI**。
其理念很简单：
1. 描述您要构建的内容。
2. 搜索生态系统。
3. 发现已经存在三个成熟的项目。
4. 节省您2000行生成的代码和维护负担。
不要问：
> “你能构建一个将markdown转换为幻灯片的CLI吗？”
而是要问：
> “整个互联网是否已经解决了这个问题？”
然后让 `mcp-wheelcheck` 先回答。
旨在解决：
* 不再发明综合征（Not-Invented-Here Syndrome）
* 周末框架综合征（Weekend Framework Syndrome）
* “我只会自己快速构建一个版本”
* AI-Agent-Reimplemented-Postgres 综合征
* 神秘的冲动，花三个小时编写已经有 40k GitHub 星标的代码
连接的LLM可以决定：
* `USE_EXISTING`
* `BUILD_NEW`
* `MIXED`
因为有时最好的代码是代理永远不会编写的代码。
---
## 为什么？
现代编码代理非常擅长生成软件。
不幸的是，它们也非常擅长生成已经存在的软件。
典型的工作流程：
* “我需要一个使用跟踪器。”
* 代理编写1500行代码。
* 您发现五个成熟的替代方案。
* 代理添加配置文件。
* 您发现替代方案已经解决了配置问题。
* 代理添加插件。
* 您发现一个替代方案有300个插件。
* 代理开始实施分析。
* 恭喜，您不小心启动了一个竞争对手。
`mcp-wheelcheck` 插入了一个缺失的步骤：
**先查找，再构建**。
开源生态系统非常庞大。您的LLM知道很多，但它不会在每次编码任务前自动执行生态系统研究。
该工具帮助它在开始生成代码之前询问生态系统。
---
## 工具
| 工具 | 用途 |
| --- | --- |
| `search_ecosystem` | 在npm、crates.io和GitHub上进行自由文本搜索。返回排名靠前的候选结果。 |
| `find_similar` | 用普通语言描述一个功能，并找到已经具有该功能的项目。**在编写代码之前使用此工具**。 |
| `get_package_details` | 在决定采用或重新发明软件包之前，详细检查特定的软件包或存储库。 |
---
## 示例会话
### 示例1：Markdown幻灯片
> **您：** 我想构建一个CLI工具，将markdown文件转换为带有实时代码执行的演示文稿幻灯片。
**代理** (`find_similar`)：
发现12个候选结果：
* `slidev` [npm] ★ 36k — 面向开发者的演示文稿幻灯片
* `reveal-md` [npm] ★ 3.1k — 用于markdown的reveal.js
* `presenterm` [crates] ★ 4.2k — 终端markdown演示文稿
**裁决：** `USE_EXISTING`
**理由：** 您大约晚了四年，GitHub上已有36,000颗星标。
---
### 示例2：AI使用跟踪器
> **您：** 我想构建一个仪表板，用于跟踪LLM令牌使用情况和成本。
**代理** (`find_similar`)：
发现18个候选结果：
* Langfuse
* Helicone
* OpenLIT
* LangSmith
* Phoenix
**裁决：** `USE_EXISTING`
**理由：** 生态系统已经经历了这次存在危机。
---
### 示例3：实际构建某些内容
> **您：** 我想要一个CLI工具，根据Git提交和公司特定的Jira约定自动生成发布说明。
**代理** (`find_similar`)：
发现部分匹配结果。
**裁决：** `MIXED`
**理由：** 现有工具涵盖了提交解析，但您的工作流特定逻辑似乎是独一无二的。
这就是构建有意义的地方。
---
## 工作原理
`mcp-wheelcheck` 跨多个来源执行生态系统发现：
* **npm**
* **crates.io**
* **GitHub**
结果作为结构化数据返回，包含：
* 软件包/存储库名称
* 描述
* 人气指标（星级/下载量）
* 存储库/软件包链接
* 注册表来源
MCP客户端的LLM然后评估：
* 这是否已经解决了用户的问题？
* 它是否是一个接近的匹配？
* 用户是否应该扩展现有的工具？
* 这是否实际上是新颖的？
服务器故意保持简单：
* 只读
* 无代码生成
* 无意见
* 无框架战争
* 没有“您是否考虑过用Rust重写它？”的建议
只是生态发现。
---
## 安装
### Claude Desktop
添加到：
`~/Library/Application Support/Claude/claude_desktop_config.json`
（macOS）
或您所在平台的等效位置。
```json
{
"mcpServers": {
"wheelcheck": {
"command": "npx",
"args": ["-y", "mcp-wheelcheck"]
}
}
}
```
---
### Cursor
创建 `.cursor/mcp.json`：
```json
{
"mcpServers": {
"wheelcheck": {
"command": "npx",
"args": ["-y", "mcp-wheelcheck"]
}
}
}
```
---
### opencode
创建 `opencode.json`：
```json
{
"mcp": {
"wheelcheck": {
"type": "local",
"command": ["npx", "-y", "mcp-wheelcheck"]
}
}
}
```
或通过：
```bash
opencode mcp add wheelcheck
```
---
### Claude Code
```bash
claude mcp add wheelcheck -- npx -y mcp-wheelcheck
```
---
### Windsurf / Codex / 其他
任何支持stdio服务器的MCP兼容客户端都可以运行：
```bash
npx -y mcp-wheelcheck
```
---
## 重要：告诉您的代理使用它
安装服务器是不够的。大多数编码代理如果不告诉它们不会主动调用 `find_similar`。工具描述说“在编写代码之前使用此工具”，但代理需要明确的指示。
在您的代理的说明文件（`AGENTS.md`、`CLAUDE.md`、`cursorrules`、`AGENTS.md` 或您的客户端读取项目/全局说明的位置）中添加一条规则：
```markdown
## 在编写任何新功能、工具或软件包之前 - 先检查生态系统
在实施新功能、工具、库或软件包之前，您必须调用
`find_similar` 工具，并附上您即将构建的内容的描述。
1. 用自然语言描述该功能。
2. 调用 `find_similar`。
3. 阅读裁决（USE_EXISTING / BUILD_NEW / MIXED）。
4. 如果是USE_EXISTING：推荐现有的软件包。不要编写代码。
5. 如果是MIXED：使用现有的软件包作为依赖项，只构建空白部分。
6. 如果是BUILD_NEW：继续 - 您现在知道它实际上是新颖的。
```
如果没有这个，代理将乐意开始编码，只有在您明确要求时才会检查轮子检查。如果有了它，代理将首先检查并避免重复发明轮子。
---
## 可选：GitHub令牌
没有令牌，GitHub搜索的速率限制在每分钟大约：
* 10次请求/分钟/ IP
有了令牌：
* 30次请求/分钟/您的帐户
设置：
```bash
export GITHUB_TOKEN=ghp_xxxxxxxxxxxx
```
或在您的MCP客户端中配置：
```json
{
"mcpServers": {
"wheelcheck": {
"command": "npx",
"args": ["-y", "mcp-wheelcheck"],
"env": {
"GITHUB_TOKEN": "ghp_xxxxxxxxxxxx"
}
}
}
}
```
---
## 开发
```bash
git clone https://github.com/tobiaspape/mcp-wheelcheck
cd mcp-wheelcheck
npm install
npm run build
npm test
npm run typecheck
npm run mcp:inspect
```
最后一个命令启动MCP检查器UI用于本地测试。
---
## 限制
### PyPI搜索
PyPI搜索目前不可用。
为什么？
因为PyPI搜索受到客户端挑战的保护，并且遗留的XML-RPC搜索API已被删除。
因此：
* `search_ecosystem` 搜索：
* npm
* crates.io
* GitHub
* `find_similar` 搜索：
* npm
* crates.io
* GitHub
然而：
`get_package_details` **支持PyPI**，通过JSON API。
如果您已经知道软件包名称，您可以直接检查它。
---
### 语义匹配
语义匹配使用MCP客户端的LLM通过MCP采样。
这允许：
* 更好的查询生成
* 更好的结果排名
* 语义相关性评分
* 匹配分类
结果可以分类为：
* `EXACT_MATCH`
* `PARTIAL_MATCH`
* `UNRELATED`
当MCP采样不可用时，服务器会fallback到算法排名。
没有嵌入式数据库。没有矢量数据库。没有额外的基础设施。
LLM已经知道什么是markdown演示工具。
尽量让它帮忙。
---
### 注册表限制
每个注册表仍然适用速率限制。
结果在进程中缓存5分钟（200条记录，LRU），以减少冗余的API调用。
请将任何剩余的挫折感直接指向相应的API提供商。
---
## 哲学
许多编码代理的默认本能是：
> “我可以构建它。”
`mcp-wheelcheck` 首先提出的问题是：
> “你应该吗？”
有时答案是：
> 构建它。
有时答案是：
> 使用已有40k星标、800名贡献者和六年修复bug的项目。
两者都是有效的结果。
重要的事情是知道你正在处理哪一个。
---
## 许可证
MIT © Tobias Pape
构建以减少不必要的软件创建，数量微不足道。
