联盟文档MCP服务器
一种模型上下文协议（MCP）服务器，提供对加拿大数字研究联盟技术文档的编程访问。此服务器镜像MediaWiki网站上的文档，并通过MCP资源和工具将其公开，以供MCP兼容客户端使用。
特性
- 文档镜像：从联盟MediaWiki网站同步文档
- MCP资源：将单个文档页面作为MCP资源公开
- 全文检索：Whoosh支持的内容和标题搜索，带有亮点和评分
- 相关页面：嵌入支持启发式回退的相关页面发现
- 搜索和查询工具：提供搜索、分类和查询功能
- 启动刷新：容器入口点在启动时触发增量同步；根据需要安排额外的跑步
- Markdown存储：将文档存储为带有元数据的markdown文件
快速开始
先决条件
- Python 3.11+
- 紫外线 用于包管理
安装
- 克隆并设置存储库：
git clone
cd alliance-docs-mcp- 安装依赖项：
uv sync- 配置环境（可选）：
创建一个 .env 如果要覆盖默认值，请使用文件（或直接导出变量）。例如：
MEDIAWIKI_API_URL=https://docs.alliancecan.ca/mediawiki/api.php
DOCS_DIR=./docs
USER_AGENT=AllianceDocsMCP/1.0- 初始文档同步：
uv run python scripts/sync_docs.py_注意：从该存储库构建的Docker镜像在镜像构建过程中会自动运行此完全同步，因此容器从热缓存开始。_
- 启动MCP服务器：
uv run python -m alliance_docs_mcp.server用法
MCP资源
服务器将文档页面作为MCP资源公开：
- 资源uri:
alliance-docs://page/{slug} - 内容：文档页面的Markdown内容
例子：
alliance-docs://page/technical_documentationMCP工具
服务器提供了几个查询文档的工具：
search_docs(query: str, category: Optional[str] = None, limit: int = 20, search_content: bool = True, fuzzy: bool = False)
按标题（回退）或全文索引（如果可用）搜索文档页面。全文结果包括相关性得分和突出显示的片段。
参数：
query：搜索查询字符串category：可选类别筛选器limit：最大结果数search_content：使用全文索引（默认值：True）fuzzy：启用模糊匹配以允许拼写错误（仅限全文）
退货： 具有元数据、突出显示和分数（索引时）的匹配页面列表
list_categories()
列出所有可用的文档类别。
退货： 类别名称列表
get_page_by_title(title: str)
按标题查找特定页面。
参数：
title：要搜索的页面标题
退货： 如果找不到页面元数据，则选择“无”
list_recent_updates(limit: int = 10)
列出最近更新的页面。
参数：
limit：要返回的最大页数
退货： 最近包含元数据的页面列表
get_page_info(slug: str)
获取特定页面的详细信息。
参数：
slug：页面段塞
退货： 包括元数据在内的详细页面信息
list_all_pages()
列出所有可用的文档页面。
退货： 包含基本元数据的所有页面列表
find_related_pages(slug: str, limit: int = 5)
嵌入支持相关页面助手（Chroma+句子转换器），并自动回退到轻量级启发式。
参数：
slug：源页面段塞limit：要返回的最大相关页面数min_score：嵌入可用时的可选相似性阈值
退货： 具有相似性得分（或回退时的启发式得分）的相关页面列表
MCP提示
服务器提供可重用的提示模板，指导LLM如何有效地查询和使用文档系统。MCP客户端可以使用这些提示来构建查询并提高一致性。
documentation_search_guide(query: str, category: Optional[str] = None)
有效搜索联盟文档的指南。提供使用说明 search_docs 工具，解释搜索结果，并按类别过滤。
参数：
query：用户的搜索查询category：可选类别筛选器
用例：当法学硕士需要帮助用户搜索特定主题的文档时。
technical_question_template(question: str, context: Optional[str] = None)
使用文档回答技术问题的模板。通过搜索、阅读相关页面、查找相关内容和综合信息来指导法学硕士。
参数：
question：要回答的技术问题context：关于用户试图完成的内容的附加上下文
用例：当法学硕士需要根据文件回答技术问题时。
category_exploration_guide(category: str, purpose: Optional[str] = None)
按类别浏览文档的指南。帮助发现特定类别中的页面并了解文档结构。
参数：
category：要探索的类别purpose：用户试图完成什么
用例：当法学硕士需要帮助用户探索特定类别的文档时（例如“入门”、“技术参考”）。
related_content_discovery(topic: str, goal: Optional[str] = None)
查找相关文档页面的指南。提供使用说明 find_related_pages 工具和解释相似性得分。
参数：
topic：用于查找相关内容的主题或页面段符goal：用户的目标（学习、故障排除等）
用例：当LLM需要帮助用户在找到相关页面后发现相关文档时。
getting_started_helper(use_case: str)
帮助新用户入门的模板。指导LLM为用户提供入门文档和常见的第一步。
参数：
use_case：用户想要做什么（例如，“设置帐户”、“运行第一个作业”、“安装软件”）
用例：当LLM需要帮助新用户完成入职和初始设置任务时。
同步
手动同步
运行完全同步（带有丰富的进度条和视觉反馈）：
uv run python scripts/sync_docs.py运行增量同步（仅更改页面）：
uv run python scripts/sync_docs.py --incremental索引控件：
uv run python scripts/sync_docs.py --rebuild-index # Rebuild Whoosh index
uv run python scripts/sync_docs.py --no-index # Skip indexing
uv run python scripts/sync_docs.py --index-dir /tmp/idx # Custom index location
uv run python scripts/sync_docs.py --rebuild-related-index # Rebuild related-page embeddings
uv run python scripts/sync_docs.py --no-related-index # Skip related-page embeddings
uv run python scripts/sync_docs.py --related-index-dir /tmp/rel# Custom related index location
uv run python scripts/sync_docs.py --related-model-name all-MiniLM-L6-v2相关页面索引下载配置的句子转换模型（默认： all-MiniLM-L6-v2，约90 MB）首次运行时。
对于FastMCP Cloud部署，请在本地运行上述同步命令之一，并提交更新的 docs/ 在推送之前使用目录，以便托管服务器始终镜像最新内容。
同步脚本提供：
- 彩色输出 格式丰富
- 进度条 用于下载和处理阶段
- 实时统计 包括页数/秒
- 汇总表 有详细的指标
- 错误追踪 带有失败页面的警告
注： 大于10的Markdown页面 MB存储为 .md.gz 文件夹。服务器在运行时自动解压缩它们，因此不需要额外的配置。LLM优化文档文件
同步过程会自动生成两个文件供LLM使用：
docs/llms.txt：一个列出所有页面名称、类别和URL的简单目录（约35 KB）docs/llms_full.txt.gz：单个压缩文件中包含完整的文档内容（压缩约2.6 MB，未压缩约393 MB）
这些文件在每次同步（完整和增量）时都会重新生成，并提交到存储库，使LLM能够轻松访问整个文档语料库。
自动同步
为每周更新设置cron作业：
# Add to crontab (runs every Sunday at 2 AM)
0 2 * * 0 cd /path/to/alliance-docs-mcp && uv run python scripts/sync_docs.py --incremental此存储库还附带 .github/workflows/weekly-sync.yml，它在周日使用GitHub Actions执行相同的增量同步，并将任何更改推回到 main.
配置
环境变量
设置以下环境变量（通过 .env、shell导出或托管平台的秘密管理器）来自定义行为：
MEDIAWIKI_API_URL（默认值https://docs.alliancecan.ca/mediawiki/api.php)DOCS_DIR（默认值./docs，或/data/docs在容器中）USER_AGENT（默认值AllianceDocsMCP/1.0)SEARCH_INDEX_DIR（可选；覆盖默认值DOCS_DIR/search_index)DISABLE_SEARCH_INDEX（设置为1/true/yes强制仅保留标题）RELATED_INDEX_DIR（可选；覆盖默认值DOCS_DIR/related_index)RELATED_MODEL_NAME（句子转换模型，默认all-MiniLM-L6-v2)RELATED_BACKEND（默认值chroma)DISABLE_RELATED_INDEX（设置为1/true/yes跳过相关页面嵌入）
服务器配置
MCP服务器可以配置命令行参数：
uv run python -m alliance_docs_mcp.server --help选项：
--host：要绑定的主机（默认值：localhost）--port：要绑定的端口（默认值：8000）--docs-dir：文档目录（默认：./docs）
Docker部署
提供的Docker镜像附带了预同步的文档缓存 /app/docs_seed当容器启动时，入口点为配置的 DOCS_DIR 然后在后台启动MediaWiki同步，以便MCP服务器立即开始接受连接。您可以通过以下方式配置启动行为：
RUN_SYNC_ON_START=0跳过后台同步（在只读环境中运行时很有用）SYNC_MODE=full强制进行完全重新同步，而不是默认的增量同步- 容器通过以下方式启动服务器
fastmcp run server_entrypoint.py:mcp --transport http --path /mcp/ --port 8080，因此可以通过覆盖来注入任何其他FastMCP CLI标志CMD如果需要，可以按照自己的形象。 - 轻量级
/health端点暴露在平台探针中；点负载均衡器检查那里，而不是MCP协议路径。
项目结构
alliance-docs-mcp/
├── src/
│ └── alliance_docs_mcp/
│ ├── __init__.py
│ ├── server.py # FastMCP server implementation
│ ├── mirror.py # MediaWiki API client
│ ├── converter.py # WikiText to Markdown converter
│ └── storage.py # File storage and retrieval
├── docs/ # Mirrored markdown files
│ ├── pages/ # Organized by category
│ └── index.json # Page metadata index
├── scripts/
│ └── sync_docs.py # Synchronization script
├── tests/ # Test files
├── pyproject.toml # Project configuration
└── README.md发展
运行测试
uv run pytest代码格式化
uv run black src/
uv run ruff check src/部署选项
FastMCP云（托管）
- 登录地址： fastmcp.cloud 使用您的GitHub帐户，创建一个指向此存储库的项目。
- 使用
server_entrypoint.py:mcp作为入口点，平台运行导出的FastMCP服务器实例。 - 配置环境变量（例如。，
MEDIAWIKI_API_URL,DOCS_DIR,USER_AGENT)通过项目设置；该服务直接从以下位置安装依赖项pyproject.toml. - 推至
main触发部署；每个pull请求都会自动获得自己的预览环境，用于测试更改。
自我管理容器/VM
- 在此仓库中构建Docker镜像，并在任何可以在端口上公开HTTP的地方运行它
8080. - 通过调度程序或容器运行时提供相同的环境变量。
- 点负载平衡器运行状况检查
/health并将MCP客户端连接到/mcp/所服务的路径fastmcp run.
添加新功能
- 新MCP工具：添加新的工具功能
server.py - 存储增强功能：扩展
storage.py对于新功能 - API改进：修改
mirror.py针对不同的API交互
故障排除
常见问题
- 同步失败：检查API访问和网络连接
- 缺页：验证MediaWiki API响应
- 转换错误：确保
beautifulsoup4/wikitextparser已安装并且正在删除有效的HTML（使用--no-strip-html禁用）
日志
检查 sync.log 同步问题文件：
tail -f sync.log调试模式
运行详细日志记录：
uv run python scripts/sync_docs.py --verbose贡献
- 分叉存储库
- 创建要素分支
- 进行更改
- 如果适用，添加测试
- 提交拉取请求
许可证
此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。