金大哥 - codedox MCP 详情

article

README

🚀 CodeDox - 文档代码提取与搜索

CodeDox 是一个强大的系统，可用于爬取文档网站、提取代码片段，并通过 MCP（模型上下文协议）集成提供快速搜索功能。

✨ 主要特性

可控的网页爬取：支持手动爬取，爬取深度可配置（0 - 3 层）。
智能代码提取：在提取代码块的同时保留上下文信息。
语言检测：使用大语言模型（LLM）进行上下文感知的语言检测。
快速搜索：利用 PostgreSQL 进行全文搜索，响应时间小于 100 毫秒。
MCP 集成：通过模型上下文协议将工具暴露给 AI 助手。
来源管理：跟踪多个文档来源并提供统计信息。
内容净化：集成 Crawl4AI，去除导航栏、广告和杂乱内容。
现代 Web 界面：基于 React 的仪表盘，用于管理爬取任务、搜索代码和监控系统活动。
自动站点内容去重：仅更新或添加有变化的内容。

🔧 技术细节

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│    Web UI       │────▶│   FastAPI       │────▶│   PostgreSQL    │
│ (React + Vite)  │     │   Server        │     │  (Full-Text)    │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                              │
┌─────────────────┐           │
│   MCP Client    │────▶│ MCP Tools │
│  (AI Assistant) │     │           │
└─────────────────┘     └───────────┘
                              │
                              ▼
                       ┌─────────────────┐
                       │   Crawl4AI      │
                       │  (Web Crawler)  │
                       └─────────────────┘

🚀 快速开始

前提条件

Python 3.10 及以上版本
PostgreSQL 12 及以上版本
Playwright（使用 crawl4ai 时会自动安装）

📦 安装指南

克隆仓库：

git clone https://github.com/yourusername/codedox.git
cd codedox

创建虚拟环境：

uv venv
source .venv/bin/activate  # 在 Windows 上：.venv\Scripts\activate

安装依赖：

uv pip install -r requirements.txt

# 安装 Playwright 浏览器（网页爬取所需）
crawl4ai-setup

设置 PostgreSQL：

# 创建数据库
createdb codedox

# 初始化数据库架构（仅首次需要）
python cli.py init

# 重置并重新创建所有表（警告：会删除所有数据）
python cli.py init --drop

配置环境：

cp .env.example .env
# 使用你的设置编辑 .env 文件

运行应用程序

快速启动

# 创建并激活虚拟环境（如果尚未完成）
uv venv
source .venv/bin/activate  # 在 Windows 上：.venv\Scripts\activate

# 初始化数据库（仅首次需要）
python cli.py init

# 启动所有服务（API + Web UI）
python cli.py all

这将：

✅ 在 http://localhost:8000 启动 API 服务器
✅ 在 http://localhost:5173 启动 Web UI
✅ 在 http://localhost:8000/mcp 启用 MCP 工具
✅ 为两个服务启用热重载

⚠️ 重要提示

Web UI 为所有操作提供了用户友好的界面，无需记忆 CLI 命令！

分别运行服务

# 仅启动 API 服务器
python cli.py run

# 仅启动 Web UI（在另一个终端中）
python cli.py ui

# 仅启动 API 服务器（另一种方式）
python cli.py api

MCP（模型上下文协议）集成

CodeDox 支持两种 MCP 模式：

HTTP 模式（推荐） - 通过主 API 服务器上的 HTTP 端点暴露 MCP 工具
Stdio 模式 - 传统的 MCP 服务器，用于直接与 AI 助手集成

HTTP 模式（集成在 API 服务器中）

当运行 API 服务器（python cli.py api 或 python cli.py all）时，MCP 工具可通过 HTTP 端点自动使用，无需单独的 MCP 服务器。

MCP 协议端点（推荐给 AI 助手）：

POST /mcp - 可流式传输的 HTTP 传输（MCP 2025 - 03 - 26 规范） - 最新且推荐
POST /mcp/v1/sse - 服务器发送事件传输（旧版支持）

旧版 REST 端点：

GET /mcp/health - 健康检查
GET /mcp/tools - 列出可用工具及其架构
POST /mcp/execute/{tool_name} - 执行特定工具
POST /mcp/stream - 用于简单集成的流式端点

使用示例：

对于使用 MCP 协议（可流式传输的 HTTP - 推荐）的 AI 助手：

# 配置你的 AI 助手使用最新的可流式传输的传输方式：
# URL: http://localhost:8000/mcp
# 传输方式: 可流式传输的 HTTP
# 请求头: Accept: application/json, text/event-stream

对于使用 MCP 协议（SSE - 旧版）的 AI 助手：

# 配置你的 AI 助手使用 SSE 传输方式：
# URL: http://localhost:8000/mcp/v1/sse
# 传输方式: 服务器发送事件（SSE）

对于直接使用 API：

# 列出可用工具
curl http://localhost:8000/mcp/tools

# 从库中获取代码片段（使用库名）
curl -X POST http://localhost:8000/mcp/execute/get_content \
  -H "Content-Type: application/json" \
  -d '{"library_id": "nextjs", "query": "authentication"}'

# 或者使用 UUID
curl -X POST http://localhost:8000/mcp/execute/get_content \
  -H "Content-Type: application/json" \
  -d '{"library_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "query": "authentication"}'

Stdio 模式（独立的 MCP 服务器）

对于需要传统基于 stdio 的 MCP 通信的 AI 助手：

# 运行独立的 MCP 服务器
python cli.py mcp

此模式仅适用于不支持 HTTP 端点的特定 AI 集成。

可用的 MCP 工具

init_crawl - 开始文档爬取
- name：库/框架名称（可选 - 如果未提供则自动检测）
- start_urls：要爬取的 URL 列表
- max_depth：爬取深度（0 - 3）
- domain_filter：可选的域名限制
- url_patterns：可选的要包含的 URL 模式列表（例如，["docs", "guide"]）
- max_concurrent_crawls：最大并发页面爬取数（默认：20）
- metadata：额外的元数据（可选）
search_libraries - 按名称搜索可用的库
- query：库名称的搜索查询（例如，'react', 'nextjs', 'django'）
- max_results：返回的最大结果数（1 - 50，默认：10）
get_content - 从库中获取代码片段
- library_id：库 ID（UUID）或库名称（例如，'nextjs', 'react'）
- query：可选的搜索词，用于过滤结果
- max_results：限制结果数（1 - 50，默认：10）
get_snippet_details - 获取特定代码片段的详细信息
- snippet_id：代码片段的 ID（来自 get_content 的结果）

📚 详细文档

API 端点

爬取

POST /crawl/init - 启动新的爬取任务，可选择进行 URL 模式过滤
GET /crawl/status/{job_id} - 检查爬取状态
POST /crawl/cancel/{job_id} - 取消正在运行的任务

搜索

POST /search - 搜索代码片段
GET /search/languages - 列出可用的语言
GET /search/recent - 获取最近的代码片段

来源

GET /sources - 列出文档来源
GET /snippets/{id} - 获取特定的代码片段
GET /export/{job_id} - 导出爬取结果

上传

POST /upload/markdown - 上传 Markdown 内容
POST /upload/file - 上传 Markdown 文件

Web UI

CodeDox 包含一个基于 React 和 TypeScript 构建的现代响应式 Web 界面。在运行开发服务器时，可通过 http://localhost:5173 访问。

特性

仪表盘：实时统计信息、系统概述和最近活动监控
高级搜索：强大的代码片段搜索功能，支持语言过滤和语法高亮
来源管理：浏览和管理文档来源，并提供详细的统计信息
爬取监控：通过 WebSocket 实时跟踪爬取任务的进度更新
设置：通过直观的界面配置应用程序设置

技术栈

前端框架：使用 TypeScript 的 React 18
构建工具：Vite，实现闪电般快速的开发
样式：支持暗模式的 Tailwind CSS
状态管理：使用 React Query 进行高效的数据获取
实时更新：集成 WebSocket 实现实时爬取进度更新

Web UI 为所有主要操作提供了一个用户友好的替代 CLI 的方式，无需记忆命令即可轻松管理文档管道。

LLM 并行请求配置

为了在本地 LLM 服务器上获得最佳性能，请在 .env 文件中配置并行请求设置：

# LLM 配置
LLM_ENDPOINT=http://localhost:8080
LLM_MODEL=gpt-4
LLM_API_KEY=your-api-key-here
LLM_MAX_TOKENS=1000
LLM_TEMPERATURE=0.1

# 并行请求设置（根据你的 LLM 服务器能力进行调整）
LLM_MAX_CONCURRENT_REQUESTS=20    # 向 LLM 发送的最大并行请求数
LLM_REQUEST_TIMEOUT=30.0          # 请求超时时间（秒）
LLM_RETRY_ATTEMPTS=3              # 失败时的重试次数

寻找最佳值： 使用包含的配置测试来确定适合你 LLM 设置的最佳配置：

# 快速测试以找到最佳设置（推荐）
python scripts/test_llm_config.py

# 或者运行全面的性能分析
python tests/performance/test_llm_concurrency_performance.py
python tests/performance/visualize_concurrency_results.py

配置指南：

本地 LLM（如 Ollama 等）：从 LLM_MAX_CONCURRENT_REQUESTS = 5 - 10 开始
GPU 服务器：根据 VRAM 情况，可处理 LLM_MAX_CONCURRENT_REQUESTS = 15 - 30
云 API（如 OpenAI、Claude）：根据速率限制，使用 LLM_MAX_CONCURRENT_REQUESTS = 20 - 50
仅使用 CPU：将 LLM_MAX_CONCURRENT_REQUESTS 保持在 2 - 5 以避免系统过载

监控你的 LLM 服务器的资源使用情况并相应调整。更高的并发度可以提高爬取速度，但可能会增加延迟或导致超时。

语言支持

支持自动检测以下语言：

Python、JavaScript、TypeScript
Java、Go、Rust、C/C++、C#
Ruby、PHP、SQL、Bash
HTML、CSS、YAML、JSON、XML

开发

项目结构

codedox/
├── src/
│   ├── api/          # FastAPI 端点
│   ├── crawler/      # 网页爬取逻辑
│   ├── database/     # 模型和搜索
│   ├── language/     # 语言检测
│   ├── mcp_server/   # MCP 服务器实现
│   └── parser/       # 代码提取
├── tests/            # 测试套件
├── config.yaml       # 配置文件
└── requirements.txt  # 依赖项

运行测试

pytest tests/

性能

搜索速度：全文搜索响应时间小于 100 毫秒
存储：每个带有上下文的代码片段约 50KB

故障排除

常见问题

数据库连接失败

检查 PostgreSQL 是否正在运行
验证 .env 文件中的凭据

贡献

分叉仓库
创建功能分支 (git checkout -b feature/amazing)
提交更改 (git commit -m 'Add amazing feature')
推送分支 (git push origin feature/amazing)
打开拉取请求

作者

Chris Scott - 初始工作和开发

📄 许可证

本项目采用 MIT 许可证 - 有关详细信息，请参阅 LICENSE 文件。

codedox