MCP Kontext
状态： 工作正在进行中——接口和部署流程可能会发生变化。
MCP Kontext（简称“Kontext”）是为Android和Kotlin文档量身定制的检索增强生成堆栈。\ 它作为一个带有模块化服务的Gradle monorepo发布，因此您可以抓取文档源，将其嵌入并索引到PostgreSQL/pgvector中，并将其作为MCP服务器（stdio传输）或通过爬虫的Ktor web UI公开。
______________________________________________________________________
目录
| 模块 | 目的 |
|---|---|
modules/shared | 共享配置+模型定义(SearchRequest, Document等等）。 |
modules/indexer | 暴露/Flyway/Postgres层、存储库和向量搜索。 |
modules/embedder | ONNX Runtime BGE大型集成+令牌化器。 |
modules/parser | 解析器框架+安卓/Kotlin解析器+分块工具。 |
modules/crawler | Ktor管理UI、调度、HTTP获取、爬网编排。 |
modules/mcp-server | MCP stdio服务器 search_docs 由索引器驱动的工具。 |
支持资产在 docs/, docker/，以及 config/.
______________________________________________________________________
快速开始
先决条件
- Java 21+
- Docker和Docker Compose（用于postgres/pgvector和容器构建）
- Gradle包装（含）
本地构建和测试
./gradlew build # compiles everything + runs unit + integration tests
./gradlew test # faster test-only pass测试包括：
- 每个模块的单元套件
- 测试容器支持的集成测试（索引器存储库、MCP评估工具）
- 第5阶段评估数据集和指标
SearchEvaluationIntegrationTest
注： 集成测试下载/运行 pgvector/pgvector:pg16请确保Docker正在运行。运行MCP服务器（stdio）
./gradlew :modules:mcp-server:run服务器读取 config/application.conf 默认情况下。覆盖 APP_CONFIG_PATH 或 --config.
运行爬虫Web UI
./gradlew :modules:crawler:run然后打开 http://localhost:8080 （默认）。凭据已在 modules/crawler/src/main/resources/application.conf 并且可以用env-vars覆盖（见下文）。
______________________________________________________________________
码头工人
Kontext为两个主要服务提供了Dockerfiles：
docker/Dockerfile.mcp-serverdocker/Dockerfile.crawler
使用提供的 docker-compose.yml 要运行postgres+这两个服务：
docker compose up --build关键卷：
postgres_data–Postgres/pgvector存储model_cache–服务器和爬虫之间共享ONNX模型缓存
重要环境变量（默认值请参见compose文件）：
| 变量 | 描述 |
|---|---|
DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD | 两个应用程序共享的数据库连接 |
EMBEDDING_MODEL_PATH | ONNX型号标识符/路径 |
MODEL_CACHE_DIR | 包含已下载模型权重的目录(/app/models) |
APP_CONFIG_PATH | HOCON配置路径（容器默认值： /app/config/application.conf) |
CRAWLER_PORT | 爬虫的主机/UI端口 |
CRAWLER_AUTH_USERNAME, CRAWLER_AUTH_PASSWORD_BCRYPT | 仪表板凭据 |
CRAWLER_SESSION_SECRET | Ktor会话的签名秘密 |
CRAWLER_INDEXER_BASE_URL | 内部用于索引器调用的基本URL |
健康检查：
- MCP服务器使用
docker/healthcheck-mcp-server.sh - 履带暴露
GET /healthz和docker/healthcheck-crawler.sh
有关更多部署详细信息，请参阅 docs/deployment.md.
______________________________________________________________________
评估和监测（第5阶段）
- 数据集 –
modules/mcp-server/src/test/resources/evaluation/queries.json（24个具有代表性的Android/Kotlin/混合查询和关键字期望）。 - 指标 –
RetrievalMetrics.kt实现Precision@K, Recall@K以及MRR。 - 集成测试 –
SearchEvaluationIntegrationTest在Docker中启动Postgres，种子确定性嵌入，运行整个SearchService，并记录汇总指标。
- 上次运行（确定性嵌入）： Precision@5 ≈ 0.23, Recall@5 ≈ 0.33, MRR ≈ 0.33. - 阈值故意设置得较低，因为测试使用确定性嵌入器存根来提高速度；一旦使用真正的ONNX嵌入运行，就会提高这些性能。
要仅执行评估套件，请执行以下操作：
./gradlew :modules:mcp-server:test --tests SearchEvaluationIntegrationTest______________________________________________________________________
配置说明
config/application.conf保持基本设置${?ENV_VAR}超控；复制/修改以供本地使用。- 爬虫特定的配置（身份验证、会话、索引器基本URL）位于
modules/crawler/src/main/resources/application.conf. - MCP服务器和爬虫均获得荣誉
APP_CONFIG_PATH指向自定义配置。 - 爬虫受保护的HTTP API通过
POST /login当您发送JSON凭据时；在中重用该令牌Authorization: Bearer脚本客户端的标头。
______________________________________________________________________
阶段状态快照
| 阶段 | 状态 | 注释 |
|---|---|---|
| 第一阶段——基础 | ✅ | 已完成 |
| 第2阶段——核心基础设施 | ✅ | 索引器/分析器/嵌入器就绪 |
| 第3阶段——服务 | ✅ | 错误处理+重试逻辑，爬虫和MCP服务器上线 |
| 第4阶段——部署 | ⏳ | Dockerfiles、编写堆栈、部署文档 |
| 第5阶段——测试 | ⚙️ | 数据集+指标+E2E线束已完成；性能调优推迟到部署后进行 |
| 第6阶段——增强功能 | 🔜 | （未来） |
优化任务（相似性阈值、块大小调整等）被有意推迟，直到在阶段/生产中执行真正的嵌入模型。
______________________________________________________________________
贡献和问题跟踪
- 支持模块级单元测试(
./gradlew :modules::test)在迭代过程中。 - 使用
./gradlew build在提交PR之前；它运行包括测试容器在内的所有套件。 - 编辑SQL或Flyway迁移时，请保持
docker/init-db.sql与本地开发容器同步。 - 对于第5阶段的性能调优，在调整相似性阈值之前，将评估线束切换到真实嵌入。
______________________________________________________________________
许可证
麻省理工学院——见 LICENSE.