contextmine (Mayflower)

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存储库进行索引
• 自托管 -您的数据保留在您的基础设施上

深度研究代理

深度研究代理不仅限于简单的搜索，还可以回答有关代码库的复杂问题。它使用迭代方法和多种工具：

代理人从多个来源收集证据，验证调查结果，并将综合答案与引用相结合。

快速开始

选择部署方法：

• （建议用于当地开发）
• 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) 了解详情。