Markdown Reference MCP Server 是一个基于 Model Context Protocol (MCP) 的参考文献处理工具，专为 Markdown 文档设计，提供自动化的参考文献提取、引用重编号映射、参考文献列表生成以及相关文献推荐功能。该工具采用 FastAPI 架构实现，并通过 fastmcp 集成到 Trae IDE 中，为学术写作和文档处理提供专业的技术支持。
- 目标：为 Markdown 文档提供参考文献与引用的自动化处理，包括参考文献提取、引用重编号映射、参考文献列表生成以及相关文献推荐功能。
- 协议：基于 Model Context Protocol（MCP）暴露工具接口，便于在 Trae IDE 中集成使用。
- 架构：采用 FastAPI 应用作为核心实现，通过 fastmcp 库将 HTTP 路由映射为 MCP 工具接口。
# 使用 uv 运行 fastmcp，将 FastAPI 应用导出为 MCP Server
uv run --python 3.12 \
--with fastmcp==2.0.0 \
--with fastapi==0.115.12 --with uvicorn==0.32.0 --with pydantic==2.9.0 \
--with markdown-it-py==3.0.0 --with mdit-py-plugins==0.4.0 \
fastmcp run app/mcp_server.py
# 注释：以上命令将创建临时 Python 环境并启动 MCP 服务器，默认端口为 8000- 配置文件：
trae_mcp_server.json - 作用：定义本地 MCP 服务器的启动配置，包括执行命令、参数、环境变量和工作目录
- 停止方式：可通过 MCP 工具接口
stop主动停止服务，或在 Trae IDE 中手动关闭服务器进程
{
"mcpServers": {
"markdown-reference-mcp": {
"command": "bash",
"args": [
"-lc",
"cd mcp-reference && PYTHONPATH=. LOG_LEVEL=INFO uv run --python 3.12 --with fastmcp==2.0.0 --with fastapi==0.115.12 --with uvicorn==0.32.0 --with pydantic==2.9.0 --with markdown-it-py==3.0.0 --with mdit-py-plugins==0.4.0 fastmcp run app/mcp_server.py"
],
"env": {
"PYTHONPATH": ".",
"LOG_LEVEL": "INFO"
}
}
}
}注意：注意
cd到项目根目录，确保app/mcp_server.py可执行。
在 Trae IDE 中，可以通过自然语言提示词直接调用 MCP 工具接口：
请使用 MCP 工具提取这篇文章的所有参考文献
示例输出：
{
"references": [
{
"id": 1,
"type": "Docs",
"authors": ["Smith", "J"],
"title": "GPU Scheduling",
"year": 2023,
"doi": null,
"url": "https://example.org",
"org": null,
"meta": {}
},
{
"id": 2,
"type": "Docs",
"authors": ["Wang", "L"],
"title": "Distributed GPU Scheduling",
"year": 2022,
"doi": null,
"url": null,
"org": null,
"meta": {}
}
],
"count": 2,
"style_stats": {
"APA": 2
}
}请使用 MCP 工具对本文的引用进行重新编号，并生成新的参考文献列表
示例输出：
{
"mappings": [
{
"original": 1,
"renumbered": 1,
"positions": {
"start_line": 3,
"end_line": 3,
"start_col": 4,
"end_col": 4
},
"context": "正文 [1] 与 [Smith2023]"
}
],
"count": 1,
"renumber_map": {
"1": 1
},
"new_references": [
{
"id": 1,
"type": "Docs",
"authors": ["Smith", "J"],
"title": "GPU Scheduling",
"year": 2023,
"doi": null,
"url": "https://example.org",
"org": null,
"meta": {}
}
]
}请使用 MCP 工具获取文章的所有引用，并分析引用分布情况
示例输出：
{
"citations": [
{
"raw": "[1]",
"type": "numeric",
"range": "1",
"positions": [
{
"start_line": 3,
"end_line": 3,
"start_col": 4,
"end_col": 6
}
],
"reference_ids": [1]
},
{
"raw": "[Smith2023]",
"type": "author_year",
"range": null,
"positions": [
{
"start_line": 3,
"end_line": 3,
"start_col": 10,
"end_col": 20
}
],
"reference_ids": [1]
}
],
"count": 2
}注意：这部分功能还在完善中。
请使用 MCP 工具基于当前内容推荐相关文献
示例输出：
{
"recommendations": [
{
"reference": {
"id": 1,
"type": "Docs",
"authors": ["Smith", "J"],
"title": "GPU Scheduling",
"year": 2023,
"doi": null,
"url": "https://example.org",
"org": null,
"meta": {}
},
"reason": {
"score": 1.0,
"matched_terms": ["gpu"],
"authority": 0.5
}
},
{
"reference": {
"id": 2,
"type": "Docs",
"authors": ["Wang", "L"],
"title": "Distributed GPU Scheduling",
"year": 2022,
"doi": null,
"url": null,
"org": null,
"meta": {}
},
"reason": {
"score": 1.0,
"matched_terms": ["gpu"],
"authority": 0.5
}
}
],
"count": 2
}- 提取阶段：使用
extract_references和extract_citations解析文档 - 处理阶段：使用
index_generate对引用进行重新编号 - 优化阶段：使用
recommendations获取相关文献建议 - 输出阶段：获取重编号后的参考文献列表和引用映射
提示：在 Trae IDE 中，可以直接使用自然语言指令如"请使用 MCP 工具获取文章的所有引用"来调用相应工具接口，系统会自动选择合适的工具并返回处理结果。
以下路由在 MCP 中以工具接口形式暴露，工具接口名称基于
operation_id。具体实现见app/main.py。
- 方法路径：
GET /health - operation_id：
health - tags：
系统 - summary：健康检查
- description：检查服务是否正常运行
# 调用示例（HTTP）
curl -s http://localhost:8000/health
# 注释：返回 {"status":"ok"}- 方法路径：
POST /api/v1/system/stop - operation_id：
stop - tags：
系统 - summary：停止 MCP 服务器
- description：触发服务停止并退出进程
# 调用示例（HTTP）
curl -s -X POST http://localhost:8000/api/v1/system/stop
# 注释：异步退出进程，返回 {"status":"stopping"}- 方法路径：
POST /api/v1/extract/references - operation_id：
extract_references - tags：
参考文献 - summary：提取参考文献
- description：从 Markdown 内容或文件路径中提取参考文献项，可选择按 DOI、标题或作者-年份进行合并去重，并返回解析结果与样式统计。
{
"file_path": "mcp-reference/tests/GPU 管理相关技术深度解析 - 虚拟化、切分及远程调用.md",
"deduplicate": true,
"merge_by": "doi"
}
// 注释：按文件路径读取并按 DOI 去重- 方法路径：
POST /api/v1/extract/citations - operation_id：
extract_citations - tags：
引用 - summary：提取引用
- description：从 Markdown 内容或文件路径中提取所有引用位置与类型，并生成与参考文献的映射上下文。
{
"markdown": "正文 [1, 3-4] 与 [Smith2023]\n\n## 参考文献\n1. Smith, J. (2023). \"GPU Scheduling\"."
}
// 注释：同时支持数值型与作者-年份引用- 方法路径：
POST /api/v1/index/generate - operation_id：
index_generate - tags：
索引 - summary：生成引用排序映射
- description：按首次引用顺序重新编号，并返回编号映射与新的参考文献列表（仅包含被引用条目）。
{
"file_path": "mcp-reference/tests/GPU 管理相关技术深度解析 - 虚拟化、切分及远程调用.md"
}
// 注释：返回 { mappings, renumber_map, new_references, count }- 方法路径：
POST /api/v1/recommendations - operation_id：
recommendations - tags：
推荐 - summary：生成参考文献推荐
- description：基于 Markdown 内容与已解析参考文献，给出 Top-K 相关文献推荐。
{
"markdown": "GPU 虚拟化相关综述",
"top_k": 3
}
// 注释：返回 { recommendations, count }，包含匹配术语与权重信息ExtractReferencesResponse：references、count、style_stats。ExtractCitationsResponse：citations、count（包含类型与位置）。IndexGenerateResponse：mappings：引用位置上下文与新编号序列；renumber_map：original_id → new_id映射；new_references：按新编号重排后的参考文献列表（仅包含正文中出现过的引用所对应条目）；count：映射条目数量。
RecommendResponse：recommendations（带匹配术语与权重）、count。
# 运行全部测试
uv run --python 3.12 \
--with fastapi==0.115.12 --with uvicorn==0.32.0 --with pydantic==2.9.0 \
--with markdown-it-py==3.0.0 --with mdit-py-plugins==0.4.0 \
--with fastmcp==2.0.0 --with pytest==8.3.3 --with pytest-cov==5.0.0 \
-m pytest -v
# 注释：执行测试并显示详细结果，-v 参数显示每个测试用例的详细信息/app
main.py # FastAPI 路由与 MCP 工具元数据
mcp_server.py # 通过 fastmcp 导出 MCP 服务器
models.py # Pydantic 模型定义（响应/请求）
services/ # 引用、参考文献、索引、推荐等服务实现
/tests # 端到端与服务层测试用例
trae_mcp_server.json # Trae IDE 的 MCP 启动配置
requirements.txt # 项目依赖版本