又开发了一个 MCP Server，用于参考文献和引用的格式化
原
GrissomFI约 7 分钟
GrissomFI约 7 分钟Markdown Reference MCP Server
1. 项目概述
Markdown Reference MCP Server 是一个基于 Model Context Protocol (MCP) 的参考文献处理工具，专为 Markdown 文档设计，提供自动化的参考文献提取、引用重编号映射、参考文献列表生成以及相关文献推荐功能。该工具采用 FastAPI 架构实现，并通过 fastmcp 集成到 Trae IDE 中，为学术写作和文档处理提供专业的技术支持。
• 目标：为 Markdown 文档提供参考文献与引用的自动化处理，包括参考文献提取、引用重编号映射、参考文献列表生成以及相关文献推荐功能。 • 协议：基于 Model Context Protocol（MCP）暴露工具接口，便于在 Trae IDE 中集成使用。 • 架构：采用 FastAPI 应用作为核心实现，通过 fastmcp 库将 HTTP 路由映射为 MCP 工具接口。
2. 安装与运行
2.1 运行 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 服务器，默认端口为 80002.2 在 Trae 中配置
• 配置文件： 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可执行。
3. 使用提示词调用 MCP 工具
在 Trae IDE 中，可以通过自然语言提示词直接调用 MCP 工具接口：
3.1 提取参考文献
请使用 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
}
}3.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": {}
}
]
}3.3 获取引用信息
请使用 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
}3.4 文献推荐
注意：这部分功能还在完善中。
请使用 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
}3.5 典型工作流程
1. 提取阶段：使用 extract_references和extract_citations解析文档2. 处理阶段：使用 index_generate对引用进行重新编号3. 优化阶段：使用 recommendations获取相关文献建议4. 输出阶段：获取重编号后的参考文献列表和引用映射
提示：在 Trae IDE 中，可以直接使用自然语言指令如"请使用 MCP 工具获取文章的所有引用"来调用相应工具接口，系统会自动选择合适的工具并返回处理结果。
4. 接口说明（MCP / HTTP 路由）
以下路由在 MCP 中以工具接口形式暴露，工具接口名称基于
operation_id。具体实现见app/main.py。
4.1 健康检查
• 方法路径： GET /health• operation_id： health• tags： 系统• summary：健康检查 • description：检查服务是否正常运行
# 调用示例（HTTP）
curl -s http://localhost:8000/health
# 注释：返回 {"status":"ok"}4.2 停止服务
• 方法路径： 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"}4.3 提取参考文献
• 方法路径： 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 去重4.4 提取引用
• 方法路径： 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\"."
}
// 注释：同时支持数值型与作者-年份引用4.5 引用重编号映射
• 方法路径： 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 }4.6 生成参考文献推荐
• 方法路径： POST /api/v1/recommendations• operation_id： recommendations• tags： 推荐• summary：生成参考文献推荐 • description：基于 Markdown 内容与已解析参考文献，给出 Top-K 相关文献推荐。
{
"markdown": "GPU 虚拟化相关综述",
"top_k": 3
}
// 注释：返回 { recommendations, count }，包含匹配术语与权重信息5. 返回模型要点
• ExtractReferencesResponse：references、count、style_stats。• ExtractCitationsResponse：citations、count（包含类型与位置）。• IndexGenerateResponse：• mappings：引用位置上下文与新编号序列；• renumber_map：original_id → new_id映射；• new_references：按新编号重排后的参考文献列表（仅包含正文中出现过的引用所对应条目）；• count：映射条目数量。• RecommendResponse：recommendations（带匹配术语与权重）、count。
6. 运行测试
# 运行全部测试
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 参数显示每个测试用例的详细信息7. 主要目录结构
/app
main.py # FastAPI 路由与 MCP 工具元数据
mcp_server.py # 通过 fastmcp 导出 MCP 服务器
models.py # Pydantic 模型定义（响应/请求）
services/ # 引用、参考文献、索引、推荐等服务实现
/tests # 端到端与服务层测试用例
trae_mcp_server.json # Trae IDE 的 MCP 启动配置
requirements.txt # 项目依赖版本