Geometry Knowledge MCP

面向几何分析研究 Agent 的证据优先文献知识库 MCP 服务

将专著、论文和综述中的章节、公开问题与原文证据组织成可追溯知识单元，
通过 MCP 向 Agent 提供专业检索和原文回查能力。

[!IMPORTANT] 研究人员与几何分析 Agent 对话，Agent 通过 MCP 工具检索知识库，再根据返回的原文证据组织回答。

[!NOTE] 当前公开试用链路仅支持 .md / .markdown 文件。请使用 test_docs/ 中的 MinerU Markdown 示例；PDF 和纯文本不在当前试用支持范围内。

架构 · 快速开始 · FastAPI 试用 · MCP Inspector · MCP 能力 · 项目文档

为什么做这个项目

几何分析文献具有中英文混排、重音专名、LaTeX 公式、复杂章节层级和严格前提条件等特点。普通“切片后聊天”的 RAG 容易丢失章节背景、原文出处和证据等级。

本项目围绕“证据优先”设计：

原始文件、文献版本和知识单元可追溯；
Markdown 标题层级转化为稳定的 section_path；
定理、引理、定义、公开问题等内容使用明确类型；
Milvus 原生 BM25 与 Dense 向量互补召回；
RRF 融合后调用在线 Reranker 精排；
Agent 得到的是 EvidencePackage，而不是无来源的自然语言结论；
文献明确陈述、系统推断、研究假设和专家确认严格区分。

核心能力

能力	当前实现
文献入库	Markdown 上传、SHA-256、MinIO 原文保存、版本与任务记录
结构提取	MinerU Markdown H1/H2 层级、章节路径、公开问题识别
事实主库	PostgreSQL 保存文献、版本、知识单元、证据状态和索引记录
专业词法检索	Milvus 原生 BM25、ICU 多语言 Analyzer
语义检索	OpenAI-compatible 在线 Embedding API
结果融合	BM25 + Dense + RRF
智能精排	Bearer 鉴权的在线 `/rerank` API
Agent 工具	MCP `search_knowledge`、`get_source_evidence`
证据输出	原文、文献、章节、页码、证据状态和各阶段分数
降级策略	Milvus 不可用时回退 PostgreSQL 简单词法检索

架构

系统分为后台建库和 Agent 使用两条链路：

flowchart TB
    subgraph Build["① 后台文献建库"]
        Maintainer["知识库维护人员"]
        Upload["Markdown 上传与版本管理"]
        Parse["文档解析与章节识别"]
        Units["数学知识单元提取"]
        Maintainer --> Upload --> Parse --> Units
    end

    subgraph Knowledge["② 专业证据知识库"]
        Source[("MinIO
原始文献")]
        Facts[("PostgreSQL
事实与证据")]
        Index[("Milvus
Dense + BM25")]
    end

    subgraph Service["③ MCP 证据服务"]
        MCP["MCP Server
search_knowledge
get_source_evidence"]
        Retrieval["混合检索
BM25 + Dense + RRF + Reranker"]
        Evidence["EvidencePackage
原文 · 来源 · 章节 · 证据状态"]
        MCP --> Retrieval --> Evidence
    end

    subgraph AgentSide["④ Agent 使用"]
        Researcher["数学研究人员"]
        Agent["几何分析研究 Agent"]
        Researcher -->|"提出研究问题"| Agent
        Agent -->|"基于证据回答"| Researcher
    end

    Upload --> Source
    Units --> Facts
    Units --> Index
    Retrieval --> Facts
    Retrieval --> Index
    Agent -->|"MCP 工具调用"| MCP
    Evidence -->|"结构化证据返回"| Agent

FastAPI 用于后台建库、内部集成和交互式调试；MCP 是面向 Agent 的正式使用入口。

快速开始

1. 环境要求

依赖	建议版本	用途
Python	`3.12`	API、worker、MCP 服务
uv	当前稳定版	Python workspace 与依赖管理
Docker Compose	当前稳定版	PostgreSQL、MinIO、etcd、Milvus
Node.js	`>=22.7.5`	仅 MCP Inspector 需要

进入项目根目录后，先创建本地配置：

cp .env.example .env

2. 先配置 Embedding 和 Reranker

在启动 worker、执行测试或导入示例文档前，必须编辑 .env，填入真实的在线 API 配置：

VECTOR_INDEX_ENABLED=true

EMBEDDING_PROVIDER=openai-api
EMBEDDING_BASE_URL=https://your-provider.example/v1
EMBEDDING_API_KEY=your-embedding-api-key
EMBEDDING_MODEL=your-embedding-model
EMBEDDING_DIMENSION=1024
EMBEDDING_API_DIMENSIONS_ENABLED=true

RERANKER_ENABLED=true
RERANKER_PROVIDER=openai-api
RERANKER_BASE_URL=https://your-provider.example/v1
RERANKER_API_KEY=your-reranker-api-key
RERANKER_MODEL=your-reranker-model

[!WARNING] 不要把真实 API key 提交到 Git。.env 只用于本地环境，.env.example 只保存空 key 和配置模板。

配置约定：

Embedding 服务必须提供 OpenAI-compatible POST /embeddings；
Reranker 服务必须提供 POST /rerank；
Reranker 请求和响应使用 model、query、documents、top_n 与 results[index, relevance_score]；
EMBEDDING_DIMENSION 必须与远程模型实际返回维度一致；
如果服务不支持 dimensions 请求参数，设置 EMBEDDING_API_DIMENSIONS_ENABLED=false；
Embedding 和 Reranker 可以使用不同服务商和不同 API key。

3. 安装依赖并启动数据服务

make sync
make db-up
uv run python scripts/bootstrap_buckets.py
make migrate
uv run python scripts/bootstrap_milvus.py

确认数据服务状态：

docker compose ps

4. 启动 FastAPI

make api

浏览器打开：

http://127.0.0.1:8000/docs

FastAPI 的 Swagger 交互文档可以直接创建项目、上传 Markdown、查询任务和测试检索，无需手写请求代码。

在 FastAPI 交互文档中完成一次试用

第一步：创建项目

在 Swagger 中展开：

POST /api/v1/projects

点击 Try it out，输入：

{
  "name": "Geometry Analysis Demo",
  "description": "Geometry Knowledge MCP quick start"
}

执行后记录响应中的 id，后续将它作为 project_id。

第二步：上传示例 Markdown

当前请只使用 Markdown。项目已经提供一份 MinerU 示例文档：

test_docs/
└── MinerU_markdown_丘成桐综述文章选集_第1卷_附评论_...md

在 Swagger 中展开：

POST /api/v1/projects/{project_id}/documents

填写：

字段	示例
`project_id`	第一步返回的项目 UUID
`file`	从 `test_docs/` 选择 `.md` 示例
`title`	`Selected Expository Works of Shing-Tung Yau`
`document_type`	`BOOK`
`language`	`en`
`publication_year`	可暂时留空

执行后记录：

document_id；
document_version_id；
ingestion_job_id。

第三步：运行 worker

上传只会创建入库任务。另开终端启动 worker：

make worker

worker 会依次完成：

下载原文
-> 解析 Markdown
-> 提取章节和知识单元
-> 写入 PostgreSQL
-> 调用 Embedding API
-> 写入 Milvus
-> 发布文献版本

第四步：查看任务状态

在 Swagger 中调用：

GET /api/v1/jobs/{job_id}

将 job_id 替换为上传响应中的 ingestion_job_id。成功状态应为：

{
  "status": "SUCCEEDED",
  "current_stage": "PUBLISHING"
}

若任务失败，可以查看 error_message，修复配置后调用：

POST /api/v1/jobs/{job_id}/retry

然后重新运行 worker。

第五步：测试检索

在 Swagger 中调用：

POST /api/v1/retrieval/search

请求示例：

{
  "project_id": "替换为项目 UUID",
  "query": "sectional curvature and topology open problems",
  "unit_types": ["OPEN_PROBLEM"],
  "verified_only": true,
  "top_k": 5
}

响应是结构化 EvidencePackage，包含原文、文献来源、章节路径、证据状态，以及 BM25、Dense、RRF 和 Reranker 的分数与排名。

[!TIP] Swagger 检索接口是内部联调入口。实际 Agent 使用时应通过 MCP 调用相同的检索服务。

使用 MCP Inspector 可视化查看服务

MCP Inspector 可以可视化查看并测试 MCP 的 Tools、Resources 和 Prompts，无需安装到项目依赖中。

连接 Streamable HTTP

确认 .env 包含：

MCP_TRANSPORT=streamable-http
MCP_HOST=0.0.0.0
MCP_PORT=8080
MCP_PATH=/mcp

终端一启动 MCP 服务：

make mcp

终端二启动 Inspector：

make mcp-inspector

Inspector 会在终端打印一个包含会话 token 的本地地址，通常基于：

http://localhost:6274

在 Inspector 页面中：

Transport 选择 Streamable HTTP；
URL 输入 http://127.0.0.1:8080/mcp；
点击 Connect；
打开 Tools，点击 List Tools；
选择 search_knowledge 或 get_source_evidence；
填入参数后点击 Run Tool 查看结构化结果。

还可以在：

Resources 查看 geometry://projects/{project_id}/units/{unit_id}；
Prompts 查看 evidence_verification；
Notifications 查看 MCP 调试日志。

[!CAUTION] MCP Inspector 的 Web UI 和 Proxy 只应在本机开发环境使用，不要暴露到不可信网络。

MCP 能力

类型	名称	说明
Tool	`search_knowledge`	检索定理、引理、公开问题、方法和证明证据
Tool	`get_source_evidence`	回查指定知识单元的原文和来源
Resource	`geometry://projects/{project_id}/units/{unit_id}`	以资源形式读取证据包
Prompt	`evidence_verification`	要求 Agent 只依据给定证据判断结论

search_knowledge 支持：

unit_types：限定知识单元类型；
year_from / year_to：限定发表年份；
verified_only：只使用文献明确证据或专家确认内容；
top_k：控制返回证据数量。

示例文档与提取效果

示例目录：

test_docs/

其中包含一份丘成桐综述文章选集的 MinerU Markdown。使用当前解析与切块代码实测：

指标	结果
原始文本	6,811 行
H1 / H2 标题	26 / 82
知识单元	108 个
不同章节路径	93 条
章节路径覆盖率	100%
独立公开问题	10 个
含公式或 LaTeX 标记的单元	35 个
含重音拉丁字符的单元	54 个

Problem 1 至 Problem 10 会被识别为独立 OPEN_PROBLEM，并继承所属章节：

Problem Section
> Curvature and the Topology of Manifolds
> Sectional curvature

MinerU Markdown 不按普通空行切块。当前规则优先处理：

# ...：文章或大章；
## I. ...、## 1 ...：章节；
## A. ...：子章节；
## Problem 1：公开问题证据单元。

当前 Markdown 尚未恢复原 PDF 页码，较长章节也需要后续增加安全的二次切块。

混合检索

flowchart LR
    Agent["Agent 调用 search_knowledge"] --> BM25["Milvus BM25"]
    Agent --> Embed["Query Embedding"]
    Embed --> Dense["Milvus Dense Search"]
    BM25 --> RRF["RRF 融合"]
    Dense --> RRF
    RRF --> PG["PostgreSQL 回取事实"]
    PG --> Rank["在线 Reranker"]
    Rank --> Evidence["EvidencePackage"]
    Evidence --> AgentResult["MCP 返回 Agent"]

Milvus search_text 使用 ICU Analyzer：

{
    "tokenizer": "icu",
    "filter": ["lowercase", "asciifolding", "removepunct"],
}

它能够处理中文、英文、欧洲语言和重音数学专名。例如 Kahler 可以匹配 Kähler，Metriques 可以匹配 Métriques。

[!NOTE] ICU Analyzer 面向自然语言 BM25，不是 LaTeX 解析器。公式语义目前主要由 Dense 召回补充。

Milvus Collection 与版本说明

当前默认 Collection：

knowledge_units_v3

knowledge_units_v1：旧 Dense-only schema；
knowledge_units_v2：Jieba BM25 schema；
knowledge_units_v3：当前 ICU BM25 schema；
dense_idx：Dense 向量索引；
bm25_idx：Milvus 原生 BM25 索引。

Analyzer 和向量维度是 Collection schema 的一部分，不能原地修改。更换 Analyzer、Embedding 维度或字段后应创建新 Collection，并重新索引已有文档。

关键配置

环境变量	说明
`VECTOR_INDEX_ENABLED`	是否启用 Milvus 混合索引
`MILVUS_COLLECTION`	当前 Milvus Collection
`EMBEDDING_BASE_URL`	Embedding API base URL
`EMBEDDING_API_KEY`	Embedding API key
`EMBEDDING_MODEL`	Embedding 模型名
`EMBEDDING_DIMENSION`	Dense 向量维度
`RERANKER_ENABLED`	是否启用在线精排
`RERANKER_BASE_URL`	Reranker API base URL
`RERANKER_API_KEY`	Reranker API key
`RERANKER_MODEL`	Reranker 模型名
`MCP_TRANSPORT`	`stdio` 或 `streamable-http`
`MCP_PORT` / `MCP_PATH`	HTTP 模式监听端口与路径

完整模板见 .env.example。

测试与质量检查

make test
make lint
make format
uv lock --check

[!WARNING] make test 会读取 .env 并真实调用 Embedding 和 Reranker API，不使用 HTTP Mock，也不会因缺少 key 或网络异常而跳过。完整测试可能产生 API 费用。

当前测试覆盖：

Markdown 标题层级与公开问题切分；
本地 Hash Embedding 的确定性；
真实远程 Embedding 调用与向量维度；
真实远程 Reranker 调用与排序；
Milvus BM25 schema；
RRF 融合和本地词法精排。

常用开发命令

make sync             # 安装全部依赖
make db-up            # 启动 PostgreSQL / MinIO / etcd / Milvus
make db-down          # 停止本地数据服务
make migrate          # 执行 PostgreSQL 迁移
make api              # 启动 FastAPI
make worker           # 持续运行 worker
make worker-debug     # 等待 VS Code 接入后调试 worker
make mcp              # 启动 MCP Server
make mcp-debug        # 等待 VS Code 接入后调试 MCP Server
make mcp-inspector    # 启动 MCP Inspector UI
make test             # 运行测试
make test-debug       # 等待 VS Code 接入后调试测试
make lint             # Ruff 静态检查
make format           # Ruff 代码格式化

使用 VS Code 调试

项目使用 debugpy 和 VS Code Attach 模式调试。make worker-debug、make mcp-debug 和 make test-debug 都会在本机 5678 端口启动调试服务，并通过 --wait-for-client 暂停执行，直到 VS Code 接入。

准备调试环境

在 VS Code 中安装官方 Python 和 Python Debugger 扩展；
从 VS Code 打开项目根目录，而不是只打开某个子目录；
执行 make sync，确保开发依赖中的 debugpy 已安装；
在代码中设置断点；
打开 VS Code 的 Run and Debug 面板，选择 Attach: Geometry service (5678)。

仓库已经提供 .vscode/launch.json，通常不需要手动创建调试配置。

调试 worker

先通过 FastAPI 上传文档并产生入库任务，然后在终端执行：

make worker-debug

终端开始等待后，在 VS Code 中按 F5 接入。worker 随后开始取任务，可以在 Markdown 解析、知识单元切分、Embedding 调用和 Milvus 写入位置命中断点。

调试 MCP Server

终端一执行：

make mcp-debug

在 VS Code 中按 F5 接入并等待 MCP Server 启动，然后在终端二执行：

make mcp-inspector

连接 http://127.0.0.1:8080/mcp，调用 search_knowledge 或 get_source_evidence 即可进入 MCP 工具和检索服务断点。

调试测试

调试全部测试：

make test-debug

使用 FILE 只调试指定测试文件或测试用例：

make test-debug FILE=tests/unit/test_openai_embedding.py
make test-debug FILE=tests/unit/test_openai_embedding.py::test_openai_embedding_provider_calls_configured_remote_model

启动命令后再在 VS Code 中按 F5。VS Code 接入之前 pytest 不会开始执行。

[!WARNING] 三个 debug target 共用 5678 端口，同一时间只能运行一个。调试远程 Embedding 或 Reranker 测试时仍会发起真实 API 请求，并可能产生费用。

结束调试时，先在 VS Code 中停止调试，再在启动 debug target 的终端按 Ctrl+C 结束进程。launch.json 默认使用 justMyCode: true；需要进入第三方库源码时可临时改为 false。

项目结构

apps/
├── api/              FastAPI 建库与内部接口
├── worker/           PostgreSQL 任务 worker
└── mcp_server/       面向 Agent 的 MCP Server

packages/
├── common/           配置、日志和公共工具
├── domain/           领域枚举与 Pydantic schema
├── ingestion/        Markdown 解析与知识单元切分
├── retrieval/        Embedding、BM25/Dense、RRF、Reranker、证据包
└── storage/          PostgreSQL、MinIO、Milvus 适配器

docs/                 开发文档、工作小结和对外介绍
scripts/              Bucket 与 Milvus 初始化脚本
test_docs/            当前可试用的 Markdown 示例文档
tests/                单元测试与真实远程 API 测试

项目文档

[系统开发文档](/hjj1079290856/geometry-knowledge-mcp/tree/master/<docs/几何分析 MCP 知识库系统开发文档.md>)
几何分析领域知识库构建工作小结
面向数学系客户的 MCP 工具介绍

当前边界与路线图

当前 MVP 已完成 Markdown 建库、混合检索、结构化证据包和 MCP 接入。下一阶段重点：

接入 MinerU 页级映射和页面图片资产；
增加定理、证明、定义和注记的细粒度二次切块；
增加 LaTeX 公式规范化与独立公式检索；
实现文档 reindex API/脚本；
建立关系抽取、证据绑定和专家审核工作流；
建设几何分析专家问题与 MCP 检索评测集。

Geometry Knowledge MCP 的目标是让研究 Agent 在回答之前先找到可靠证据，并且能够说明证据来自哪里。