使用说明

联盟文档MCP服务器

一种模型上下文协议（MCP）服务器，提供对加拿大数字研究联盟技术文档的编程访问。此服务器镜像MediaWiki网站上的文档，并通过MCP资源和工具将其公开，以供MCP兼容客户端使用。

特征

文档镜像：从联盟MediaWiki网站同步文档
MCP资源：通过资源模板延迟提供页面内容 (alliance-docs://page/{slug})，加上a alliance-docs://pages 发现索引
全文检索：Whoosh支持的内容和标题搜索，带有亮点和评分
相关页面：嗖的内容相似性（“更像这样”）相关的页面发现与启发式回退
搜索和查询工具：提供搜索、分类和查询功能
启动刷新：容器入口点在启动时触发增量同步；根据需要安排额外的跑步
Markdown存储：将文档存储为带有元数据的markdown文件

MCP接口说明

结构化输出：工具返回键入的结果(SearchHit, PageSummary, PageInfo, RelatedPage)使用JSON输出模式。
错误：工具升高 ToolError 真正的失败（例如请求页面由不存在的slug或搜索后端错误引起）。成功搜索如果没有匹配项，则返回空列表，而不是错误。
资源：单个页面不再预先注册。阅读页面 alliance-docs://page/{slug}；通过以下方式枚举可用页面 alliance-docs://pages 索引资源或 list_all_pages 工具。
配置：set DOCS_DIR （可选 MEDIAWIKI_API_URL, USER_AGENT)通过环境变量。服务器运行时使用 fastmcp run fastmcp.json.

快速开始

先决条件

Python 3.11+
紫外线用于包管理

安装

克隆并设置存储库：

git clone <repository-url>
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_documentation

MCP工具

服务器提供了几个查询文档的工具：

`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)`

通过Whoosh内容相似性（“更像这样”）查找相关页面，并自动回退到轻量级标题/类别启发式。

参数：

slug：源页面段塞
limit：要返回的最大相关页面数

退货： 具有相关性得分（或回退时的启发式得分）的相关页面列表

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

这 weekly-sync GitHub Action按计划运行增量同步，并提交更新的 docs/ 到 main；关于更改自动部署的Fly.io部署（请参阅 docs/deploy-fly.md)，因此托管服务器会镜像最新内容。您还可以在本地运行上面的sync命令并提交 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 强制仅保留标题）

服务器配置

通过stdio（默认MCP传输）在本地运行服务器：

uv run python -m alliance_docs_mcp.server [--verbose]

--verbose 是唯一被接受的旗帜。所有运行时配置都是通过环境变量完成的——请参阅环境变量以上部分为完整列表。最常用的是 DOCS_DIR, MEDIAWIKI_API_URL，以及 USER_AGENT.

Docker部署

提供的Docker镜像附带了预同步的文档缓存 /app/docs_seed当容器启动时，入口点为配置的 DOCS_DIR 然后在后台启动MediaWiki同步，以便MCP服务器立即开始接受连接。您可以通过以下方式配置启动行为：

RUN_SYNC_ON_START=0 跳过后台同步（在只读环境中运行时很有用）
SYNC_MODE=full 强制进行完全重新同步，而不是默认的增量同步
容器通过以下方式启动服务器 fastmcp run fastmcp.json --port 8080；从中读取传输、主机和路径 fastmcp.json 而不是作为CLI标志传递。通过覆盖可以注入其他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/

部署选项

Fly.io（推荐）

作为一台始终在线、无状态的机器运行。配置已完成 fly.toml；完整的runbook（一次性设置、切换、操作）位于 docs/deploy-fly.md.
.github/workflows/deploy.yml 船舶 main 在推送和每周文档同步完成后飞行，因此实时语料库每周刷新一次。需要a FLY_API_TOKEN 回购秘密。

自我管理容器/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许可证获得许可-有关详细信息，请参阅许可证文件。

致谢

加拿大数字研究联盟用于提供文件
FastMCP 用于MCP服务器框架
紫外线用于Python包管理

使用说明

联盟文档MCP服务器

特征

MCP接口说明

快速开始

先决条件

安装

用法

MCP资源

MCP工具

search_docs(query: str, category: Optional[str] = None, limit: int = 20, search_content: bool = True, fuzzy: bool = False)

list_categories()

get_page_by_title(title: str)

list_recent_updates(limit: int = 10)

get_page_info(slug: str)

list_all_pages()

find_related_pages(slug: str, limit: int = 5)

MCP提示

documentation_search_guide(query: str, category: Optional[str] = None)

technical_question_template(question: str, context: Optional[str] = None)

category_exploration_guide(category: str, purpose: Optional[str] = None)

related_content_discovery(topic: str, goal: Optional[str] = None)

getting_started_helper(use_case: str)

同步

手动同步

LLM优化文档文件

自动同步

配置

环境变量

服务器配置

Docker部署

项目结构

发展

运行测试

代码格式化

部署选项

添加新功能

故障排除

常见问题

日志

调试模式

贡献

许可证

致谢

相关 MCP

Meilisearch MCP 搜索服务器

Gemini API文档搜索服务

文档处理服务器

犹太文献搜索服务器

代码库教学平台生成器

Calibre图书馆MCP服务器

`search_docs(query: str, category: Optional[str] = None, limit: int = 20, search_content: bool = True, fuzzy: bool = False)`

`list_categories()`

`get_page_by_title(title: str)`

`list_recent_updates(limit: int = 10)`

`get_page_info(slug: str)`

`list_all_pages()`

`find_related_pages(slug: str, limit: int = 5)`

`documentation_search_guide(query: str, category: Optional[str] = None)`

`technical_question_template(question: str, context: Optional[str] = None)`

`category_exploration_guide(category: str, purpose: Optional[str] = None)`

`related_content_discovery(topic: str, goal: Optional[str] = None)`

`getting_started_helper(use_case: str)`