内容
# wg21-wiki-mcp
一个本地的 [模型上下文协议](https://modelcontextprotocol.io)（stdio）服务器，提供对 **WG21（ISO C++）委员会wiki** 的只读访问，地址为 `wiki.isocpp.org`，作为 **可验证的真实来源**。
委员会wiki需要登录才能阅读，其议程、投票、文件和子组页面否则很难从代理访问。该服务器使用您的凭证进行身份验证，实时通过MediaWiki API获取页面并缓存它们 - 返回 **确切** 的wiki文本，带有可点击的URL和修订ID，以便每个答案都可以验证。
> 访问需要WG21成员资格。该工具在其源代码中存储没有任何机密信息，并且从不记录页面内容。参见 [SECURITY.md](SECURITY.md)。
## 功能
- **可验证的内容**。工具返回带有出处（规范URL、永久`oldid` URL、`revid`、最后编辑时间）的维基文本。没有任何内容被服务器汇总或重新格式化。
- **身份验证，无需浏览器**。优先使用MediaWiki **机器人密码**；如果未设置机器人密码，则回落到通过**无头SSO**（SimpleSAMLphp）进行的 **正常帐户**。工作路径被固定和重用；会话中断时，会透明地重新建立。
- **共享、会议感知的缓存**。`~/.isocpp.wiki/`中的跨进程SQLite缓存由您的所有本地代理共享。页面通常缓存一周，在一年三次的会议期间（从公共会议日历中检测）每小时重新检查。
- **令牌精简的工具**，具有不透明的光标分页和UTF-8安全的长页面分块。
## 安装
从 [PyPI](https://pypi.org/project/wg21-wiki-mcp/)（推荐）安装：
```bash
pipx install wg21-wiki-mcp
# 或，安装到虚拟环境中：
pip install wg21-wiki-mcp
```
固定版本以实现可重复性，例如 `pip install wg21-wiki-mcp==0.2.0`。
或通过 [`uv`](https://docs.astral.sh/uv/) 运行，无需手动安装：
```bash
uvx wg21-wiki-mcp
# 固定版本：
uvx --from wg21-wiki-mcp==0.2.0 wg21-wiki-mcp
```
从GitHub安装，当您需要特定提交或分支时：
```bash
pipx install "git+https://github.com/cppalliance/wg21-wiki-mcp.git@v0.2.0"
# 或跟踪最新发布分支：
uvx --refresh --from git+https://github.com/cppalliance/wg21-wiki-mcp.git@master wg21-wiki-mcp
```
或从本地克隆（用于开发）：
```bash
git clone https://github.com/cppalliance/wg21-wiki-mcp
cd wg21-wiki-mcp
pip install -e ".[dev]"
```
需要Python 3.10+。适用于Windows、macOS和Linux。
## 配置
wiki基本URL是固定的（`https://wiki.isocpp.org`），因此只需要凭证。与MCP主机一起，通过服务器的启动`env`块传递它们。最简单的设置使用PyPI包通过`uvx`：
```json
{
"mcpServers": {
"wg21-wiki": {
"command": "uvx",
"args": [
"--from",
"wg21-wiki-mcp==0.2.0",
"wg21-wiki-mcp"
],
"env": {
"WIKI_BOT_USERNAME": "YourAccount@yourbot",
"WIKI_BOT_PASSWORD": "the-bot-password"
}
}
}
}
```
要始终运行最新的PyPI版本而不是固定版本，请使用 `"wg21-wiki-mcp"`（无版本固定）作为 `--from` 值。固定版本是推荐的，以便源代码工具的行为是可重复的。要从Git安装，请使用 `"git+https://github.com/cppalliance/wg21-wiki-mcp.git@v0.2.0"`。
如果您安装了控制台脚本（通过pipx/pip），请使用 `"command": "wg21-wiki-mcp"` 而无需 `args`。要使用您的正常帐户而不是机器人密码，请提供 `WIKI_USER_USERNAME` / `WIKI_USER_PASSWORD`（要求MFA未启用）。如果两者都存在，则默认使用机器人密码。参见 [`.env.example`](.env.example) 以进行可选调整（缓存目录、TTL、会议覆盖）。机器人在 `Special:BotPasswords` 处创建，授予读取权限，是推荐的可撤销选项。
## 工具
| 工具 | 用途 |
| --- | --- |
| `search_wiki` | 全文搜索；返回标题和URL（可选API片段 via `include_snippet`）。 |
| `get_page` | 页面的逐字维基文本，带有出处；如果较大，则分块。 |
| `list_pages` | 枚举命名空间中的页面标题。 |
| `list_namespaces` | 列出内容命名空间及其数字ID。 |
| `list_meetings` | 列出发现的会议（最新的优先）；标记活跃的会议。 |
| `get_meeting_overview` | 会议的登陆页面及其子页面索引。 |
| `get_meeting_sessions` | 原始材料（议程时间段 + 相关页面）以组成日程。 |
| `get_recent_changes` | 最近的编辑/新页面，可选按命名空间或时间。 |
| `wiki_status` | 身份验证路径、会议感知的TTL状态、缓存统计（无wiki内容）。 |
## 快速开始（编程）
```python
from wg21_wiki_mcp.config import Config
from wg21_wiki_mcp.context import ServerContext
from wg21_wiki_mcp import tools
ctx = ServerContext.create(Config.from_env())
# 搜索，然后读取一个页面的逐字文本，带有可验证的URL。
hits = tools.search_wiki(ctx, "some topic", limit=5)
page = tools.get_page(ctx, hits.hits[0].title)
print(page.provenance.url, page.provenance.revid)
print(page.content) # 准确的维基文本
```
## 依赖
- [`mcp`](https://github.com/modelcontextprotocol/python-sdk) - MCP/FastMCP服务器框架。
- [`requests`](https://requests.readthedocs.io/) + [`mwclient`](https://mwclient.readthedocs.io/) - MediaWiki API访问（重新登录，批量获取）。
- [`beautifulsoup4`](https://www.crummy.com/software/BeautifulSoup/) + [`lxml`](https://lxml.de/) - 解析SSO登录表单以进行无头用户身份验证。
- [`pydantic`](https://docs.pydantic.dev/) - 结构化工具输出。
- [`python-dotenv`](https://pypi.org/project/python-dotenv/) - 用于本地开发的可选 `.env` 加载。
- [`filelock`](https://py-filelock.readthedocs.io/) - 跨进程单次飞行页面锁定。
## 错误合约
每个工具错误都表现为一个结构化的 `McpError`，具有不同的、文档化的代码。消息是可操作的，不包含凭证或wiki页面内容。
| 代码 | 名称 | 含义 |
| --- | --- | --- |
| `1` | `PAGE_NOT_FOUND` | 请求的页面在wiki上不存在。 |
| `2` | `AUTH_ERROR` | 身份验证失败；请检查服务器配置中的凭证。 |
| `3` | `FETCH_ERROR` | 重试后网络或API错误；请检查连接性。 |
| `4` | `CONFIG_ERROR` | 凭证环境变量未设置（`WIKI_BOT_USERNAME` / `WIKI_BOT_PASSWORD`）。 |
| `-32602` | `INVALID_PARAMS` | 格式错误的或过期的分页光标。 |
参见 [ARCHITECTURE.md](ARCHITECTURE.md#error-contract) 以获取完整的不变性。
## 版本和稳定性
该软件包是 **0.x Alpha**（`Development Status :: 3 - Alpha`）。直到 **1.0.0**：
- **固定版本** 在您的MCP配置中（`@v0.2.0` 或PyPI版本），以便升级是故意的。
- **稳定：** MCP工具名称、工具参数名称/类型、应用程序错误代码（`1`–`4`，`-32602`）以及所有 `Provenance` 字段和 `PageContent.content` / `section`（任何其他必需的出处字段也是稳定的 - 参见 [STABILITY.md](STABILITY.md)）。对这些的破坏性更改需要至少一个小版本进行废弃。
- **不稳定：** 响应模型的可选字段、分页光标格式、磁盘缓存布局、内部Python模块和日志消息词序可能会在任何0.x版本中更改，无需事先废弃。
- **0.x 小版本更新**（`0.2.0` → `0.3.0`）可能会添加工具或废弃稳定API；不稳定层级的破坏性更改可以无需废弃期直接进行。
- **0.x 补丁更新** 是错误修复和非合约更改。
阅读 [STABILITY.md](STABILITY.md) 以获取完整层级列表、废弃流程和1.0后计划。在升级固定版本之前，请查看 [CHANGELOG.md](CHANGELOG.md)（包括 `### Deprecated`）。
## 文档
- [docs/API.md](docs/API.md) - MCP工具参考（从源代码生成；运行 `python scripts/build_api_docs.py` 以更新）。
- [STABILITY.md](STABILITY.md) - API稳定性层级和废弃策略（预-1.0）。
- [docs/RUNBOOK.md](docs/RUNBOOK.md) - MCP主机设置、故障排除和代理工具选择指南。
- [docs/FIRST_PYPI_PUBLISH.md](docs/FIRST_PYPI_PUBLISH.md) - 首次PyPI版本的一次性受信任发布者设置。
- [ARCHITECTURE.md](ARCHITECTURE.md) - 设计、数据流、解析与卸载策略、可能发生故障的内容、未来工作。
- [CONTRIBUTING.md](CONTRIBUTING.md) - 开发设置、测试、机密规则、治理和阅读起点。
- [SECURITY.md](SECURITY.md) - 凭证处理和机密性。
## 许可证
Boost Software License 1.0 - 参见 [LICENSE](LICENSE)。
