ContextMine
Self-hosted documentation and code indexing with MCP integration.
Give your AI assistant accurate, up-to-date context from your own sources.
什么是ContextMine？
ContextMine为您的文档和代码库建立索引，使其可以通过 模型上下文协议（MCP）。将其连接到Claude Desktop、Cursor或任何兼容MCP的AI助手，为代码理解、文档查找和代码库探索提供丰富的上下文。
主要特点：
- 混合搜索 -全文+向量相似度与RRF排名相结合，实现准确检索
- 深度研究代理 -具有LSP和Tree sitter的多步AI代理，用于解决复杂的代码库问题
- 代码智能 -通过Tree sitter进行符号提取、代码大纲和结构导航
- 建筑驾驶舱 -只读提取每个集合/场景的双视图(
Overview,Topology,Deep Dive,C4 Diff,Exports) - 严格的真实指标 -具有明确可用性状态的GitHub源代码的文件级LOC/复杂性/耦合/覆盖率
- 信息采集 -自动索引文档站点
- Git索引 -使用增量更新对GitHub存储库进行索引
- 自托管 -您的数据保留在您的基础设施上
深度研究代理
深度研究代理不仅限于简单的搜索，还可以回答有关代码库的复杂问题。它使用迭代方法和多种工具：
| 工具 | 说明 |
|---|---|
| 混合搜索 | BM25+基于RRF排序的向量相似性搜索 |
| LSP转到定义 | 跨文件跳转到符号定义 |
| LSP查找参考 | 查找符号的所有用法 |
| LSP悬停 | 获取类型信息和文档 |
| 树保姆轮廓 | 提取文件结构（类、函数、方法） |
| 树保姆查找符号 | 按名称模式定位符号 |
| 图的遍历 | 浏览调用图和依赖关系 |
代理人从多个来源收集证据，验证调查结果，并将综合答案与引用相结合。
快速开始
选择部署方法：
- （建议用于当地开发）
- Kubernetes（Helm） （推荐用于生产）
Docker Compose
# Clone the repository
git clone https://github.com/mayflower/contextmine.git
cd contextmine
# Copy environment template and configure
cp .env.example .env
# Edit .env with your API keys (see Configuration section)
# Start all services
docker compose up -d
# Run database migrations
docker compose exec api sh -c "cd /app/packages/core && alembic upgrade head"Kubernetes（Helm）
对于生产部署，请使用GHCR的Helm图表：
# Create a values file with your configuration
cat > my-values.yaml **备注**：管理UI和MCP客户端都使用相同的回调URL。服务器会自动将OAuth流路由到相应的处理程序。
### 生成安全密钥
Generate session secret
python -c "import secrets; print(secrets.token_urlsafe(32))"
Generate encryption key
python -c "import secrets; print(secrets.token_urlsafe(32))"
## 添加源
### Web文档
最适合：API文档、指南、参考文档
1. 在管理UI中创建集合
1. 添加类型为的源 **网络**
1. 输入基本URL（例如。， `https://docs.example.com/`)
1. 爬虫跟踪同一域内的链接
### GitHub存储库
最适合：源代码、README文件、内联文档
1. 添加类型为的源 **GitHub**
1. 以以下身份输入存储库 `owner/repo`
1. 可选择指定：
- **分支**：默认为默认分支
- **路径过滤器**：限于特定目录（例如。， `src/`, `docs/`)
1. 代码文件被解析为符号（函数、类、方法）
**符号提取支持的语言：**
Python、TypeScript、JavaScript、Go、Rust、Java、C、C++、Ruby、PHP
**支持严格真实指标的语言（双子城/城市）：**
Python、TypeScript、JavaScript、Java、PHP
GitHub源代码的严格度量门行为：
1. 同步计算结构度量(`loc`, `complexity`, `coupling`)而不会阻碍报道。
1. 覆盖率从CI异步获取，并绑定到精确的提交SHA。
1. 覆盖率摄取是严格的：无效的令牌/有效载荷/SHA不匹配/路径不匹配导致摄取作业失败。
1. 只有在成功获取覆盖率后，城市指标才能完全准备就绪。
## 建筑
┌───────────────────────────────┐ ┌─────────────┐ │ FastAPI + React SPA │────▶│ PostgreSQL │ │ /api/* /mcp/* /* (frontend) │ │ pg4ai │ └───────────────────────────────┘ └─────────────┘ │ ┌──────┴──────┐ ▼ ▼ ┌─────────┐ ┌─────────┐ │ Prefect │ │ spider │ │ Worker │ │ _md │ └─────────┘ └─────────┘
- **API** (`apps/api`)：FastAPI服务于的REST API `/api/*`MCP在 `/mcp/*`，以及React前端 `/*`
- **网络** (`apps/web`)：React管理控制台（由API构建并提供服务）
- **工人** (`apps/worker`)：使用Prefect进行后台同步作业
- **核心** (`packages/core`)：共享模型、数据库和实用程序
## 发展
### 先决条件
- Python 3.12+
- Node.js 20+
- [紫外线](https://github.com/astral-sh/uv) 用于Python依赖管理
- Docker（适用于pg4ai：PostgreSQL+pgvector+Apache AGE）
### 地方发展设置
Start database
docker compose up -d postgres
Optional: verify vector + graph capabilities in postgres
./scripts/docker/smoke-pg4ai.sh
Install Python dependencies
uv sync --all-packages
Run migrations
cd packages/core DATABASE_URL=postgresql+asyncpg://contextmine:contextmine@localhost:5432/contextmine \ uv run alembic upgrade head cd ../..
Build frontend (one-time, or after frontend changes)
cd apps/web && npm install && npm run build && cd ../..
Start API server (serves both API and frontend)
STATIC_DIR=apps/web/dist uv run uvicorn apps.api.app.main:app --reload --port 8000
对于热重载的前端开发，请单独运行Vite-dev服务器：
Terminal 1: API server
uv run uvicorn apps.api.app.main:app --reload --port 8000
Terminal 2: Frontend dev server (proxies API requests to :8000)
cd apps/web && npm run dev
### 运行测试
All tests
uv run pytest -v
Specific test file
uv run pytest packages/core/tests/test_treesitter.py -v
With coverage
uv run pytest --cov=contextmine_core --cov-report=term-missing
### 代码质量
Linting
uv run ruff check .
Type checking
uvx ty check
Auto-format
uv run ruff format .
Pre-commit hooks
uv run pre-commit install uv run pre-commit run --all-files
## 容器图像
预构建映像可从GitHub容器注册表获得：
docker pull ghcr.io/mayflower/contextmine-api:latest docker pull ghcr.io/mayflower/contextmine-worker:latest docker pull ghcr.io/mayflower/contextmine-web:latest
## 故障排除
### MCP客户端中“未找到集合”
1. 确保您在管理UI中至少创建了一个集合
1. 检查集合可见性是否设置为 **全球** （或者您已通过身份验证）
1. 在MCP客户端提示时，验证您是否已完成GitHub OAuth流程
### 同步找不到文档
1. 请在以下位置查看Prefect UIhttp://localhost:4200关于工作状态
1. 对于GitHub源代码，确保存储库可访问
1. 对于web源，验证URL是否可访问并返回HTML
### 未提取符号
符号提取仅适用于支持的语言。检查：
1. 该文件具有可识别的扩展名(`.py`, `.ts`, `.js`, `.go`等等）
1. 同步已完成（同步期间提取符号）
### 驾驶舱概览显示 `N/A` 指标
1. 检查 `GET /api/twin/collections/{collection_id}/views/city`.
1. 检查 `metrics_status.reason`:
- `awaiting_ci_coverage`：CI尚未推动报道。
- `coverage_ingest_failed`：查看摄取作业诊断。
- `no_real_metrics`：未生成结构度量快照。
1. 验证最新摄取作业：
- `GET /api/sources/{source_id}/metrics/coverage-ingest/{job_id}`
1. 重新运行CI上传并匹配 `commit_sha=${{ github.sha }}` 以及有效的报告。
## 许可证
MIT许可证-请参阅 [许可证](LICENSE) 了解详情。