fabdendev/ferret-mcp
GitHub: fabdendev/ferret-mcp
一个 MCP 协议服务器，结合静态分析与 AI 驱动的深度解读，从任意代码库中提取架构、模式、依赖、API 接口等完整知识。
Stars: 0 | Forks: 0
# Ferret MCP
[](https://pypi.org/project/ferret-mcp/)
[](https://pepy.tech/project/ferret-mcp)
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](https://github.com/fabdendev/ferret-mcp/actions/workflows/tests.yml)
一个 [MCP](https://modelcontextprotocol.io/) 服务器，可从任何代码库中提取完整的知识——包括架构、模式、依赖项、API 接口。结合了静态分析与 AI 驱动的深度解读。
适用于任何 MCP 客户端：[Claude Code](https://docs.anthropic.com/en/docs/claude-code)、[Claude Desktop](https://claude.ai)、[Cursor](https://cursor.sh) 等。
**给它一个代码库，只需约 $0.09 即可在 30 秒内获得资深工程师级别的分析。**
## 快速开始
### 使用 uvx 安装并运行（无需克隆）
```
uvx ferret-mcp
```
### 或使用 pip 安装
```
pip install ferret-mcp
```
## MCP 客户端配置
### Claude Code
```
claude mcp add ferret -- uvx ferret-mcp
```
要启用 AI 驱动的工具（`deep`、`ask`），请设置您的 API key：
```
claude mcp add ferret -e FERRET_LLM_API_KEY=sk-ant-... -- uvx ferret-mcp
```
### Claude Desktop / Cursor / Windsurf / 任何 MCP 客户端
添加到您的 MCP 配置文件（`claude_desktop_config.json`、`.cursor/mcp.json` 等）中：
```
{
"mcpServers": {
"ferret": {
"command": "uvx",
"args": ["ferret-mcp"],
"env": {
"FERRET_LLM_API_KEY": "sk-ant-..."
}
}
}
}
```
### 本地开发
```
git clone https://github.com/fabdendev/ferret-mcp.git
cd ferret-mcp
cp .env.example .env # Add your API key
uv sync
uv run ferret-mcp
```
## 工具
### 静态分析（免费，无需 LLM）
| 工具 | 描述 |
|------|-------------|
| `scan` | 代码库概览 — 语言、结构、入口点、配置文件 |
| `dependencies` | 外部包 + 内部导入图及核心模块 |
| `architecture` | 分层、架构模式、模块分解 |
| `patterns` | 设计模式、命名规范、测试、错误处理 |
| `api_surface` | REST 端点、MCP 工具、CLI 命令、GraphQL、gRPC、导出项 |
| `full_extraction` | 以上所有内容的综合报告 |
### AI 驱动（使用 Haiku 约 $0.09/报告）
| 工具 | 描述 |
|------|-------------|
| `deep` | 综合知识提取报告 — 包含 10 个章节的专家分析，涵盖架构、数据流、优势、风险和学习要点 |
| `ask` | 针对代码库提出任何问题，结合完整代码库上下文进行解答 |
所有工具均接受一个 `path` 参数 — 即代码库根目录的绝对路径。
## 配置
AI 驱动的工具（`deep`、`ask`）需要一个 LLM。通过环境变量进行配置：
| 环境变量 | 默认值 | 描述 |
|---------|---------|-------------|
| `FERRET_LLM_PROVIDER` | `anthropic` | `anthropic` 或 `openai`（适用于 Ollama, vLLM, LM Studio） |
| `FERRET_LLM_MODEL` | `claude-haiku-4-5-20251001` | 模型名称 |
| `FERRET_LLM_API_KEY` | — | API key（Anthropic 必需；本地使用 `ollama`） |
| `FERRET_LLM_BASE_URL` | `http://localhost:11434/v1` | OpenAI 兼容提供商的 Base URL |
### 配合本地 LLM (Ollama) 使用
```
claude mcp add ferret \
-e FERRET_LLM_PROVIDER=openai \
-e FERRET_LLM_BASE_URL=http://localhost:11434/v1 \
-e FERRET_LLM_MODEL=qwen3:8b \
-- uvx ferret-mcp
```
## 示例输出
`deep` 工具会生成一份约 1000 行的知识提取报告，涵盖：
1. **执行摘要** — 是什么、处于什么阶段、客观评估
2. **架构深入剖析** — 模式、模块、依赖方向、上帝对象 (God Objects)
3. **技术栈及原理** — 每个选择背后的原因
4. **数据与控制流** — ASCII 图表、执行模型
5. **设计模式与规范** — 附带文件引用
6. **API 与接口契约** — REST、CLI、MCP、认证模型
7. **关键文件阅读指南** — 为新贡献者提供的有序阅读路径
8. **优势** — 真正设计得当的地方
9. **风险与技术债务** — 直言不讳、具体明确，并提供修复建议
10. **学习要点** — 值得借鉴之处与应当避免的地方
## 限制
- `.gitignore` 解析仅读取根目录文件（不支持嵌套的 `.gitignore` 文件）
- 每个代码库最多扫描 15,000 个文件
- 文件内容分析仅限于 512 KB 以下的文件
- AI 分析质量取决于所使用的 LLM 模型（Haiku 快速且便宜，Sonnet/Opus 用于更深入的分析）
## 许可证
MIT
标签：AI 编程, AI风险缓解, API 接口提取, Claude, Cursor, CVE检测, MCP Server, Petitpotam, Python, WebSocket, 云安全监控, 代码库分析, 代码模式识别, 代码理解, 依赖分析, 大模型工具, 威胁情报, 开发者工具, 技术债务, 数据管道, 无后门, 架构提取, 源码解析, 软件工程, 逆向工具, 静态分析