osdev-wiki-mcp

osdev-wiki-mcp

离线且可搜索的 OSDev wiki，供你的 AI Agent 使用。

wiki.osdev.org 是业余操作系统开发的参考资料。它涵盖描述符表、分页、中断控制器、计时器、ACPI、磁盘控制器、引导加载程序和工具链。编写内核代码的 Agent 往往会凭记忆重建这些细节，导致位布局出错。它们也无法自行浏览 wiki，因为网站设有机器人验证。

osdev-wiki-mcp 会下载 wiki 的公开存档，并使用 SQLite 全文搜索在本地建立索引，然后为 Agent 提供工具来搜索内容、阅读整个页面或其中一个章节，以及追踪链接。

效果展示

以下是 2025-12-30 数据转储中的实际输出：

> wiki_search("PIT", limit=3)
1. Programmable Interval Timer *
   The Programmable Interval Timer ([PIT]) chip (Intel 8253/8254) basically consists of an oscillator…
2. PC Speaker
   …When the [PIT] interrupts you, you need to program [PIT] timer 2 so that…
3. APIC Timer
   …Real Time Clock, TimeStamp Counter, [PIT] or even polling CMOS registers. In this tutorial…

> wiki_page("IDT", section="Gate Descriptor", max_chars=900)
# Interrupt Descriptor Table
https://wiki.osdev.org/Interrupt_Descriptor_Table · last edited 2025-06-05 · categories: X86 CPU, Interrupts
('IDT' redirects to 'Interrupt Descriptor Table'; 'Gate Descriptor' appears 2 times; showing
section 4 under 'Structure on IA-32'. Also: section 8 under 'Structure on x86-64')

### Gate Descriptor

Each entry in the table has a complex structure:

Gate Descriptor (32-bit):
63..48 | 47 | 46..45 | 44 | 43..40 | 39..32
Offset 31..16 | P | DPL 1..0 | 0 | Gate Type 3..0 | Reserved
31..16 | 15..0
Segment Selector 15..0 | Offset 15..0

- Offset: A 32-bit value, split in two parts. It represents the address of the entry point ...
[... section truncated]

[Cut at max_chars=900; the full text is 1567 chars. Call again with max_chars=1767 to read the rest.]

注意这些输出如何帮助 Agent：

• 缩写也能搜到。“PIT”和“IDT”是 wiki 重定向，重定向会作为目标页面的别名建立索引，因此搜索缩写时会优先找到正确的页面。
• 位布局表格清晰易读。 wiki 使用 HTML 表格绘制描述符和页表布局。这里会将它们渲染为每行一行，并以 63..48 的形式显示位范围。
• 会报告歧义。 如果同一页面上有多个同名标题，Agent 会获知其他副本的位置。
• 截断原因一目了然。 结果被截断时，会明确说明下一步该调用什么工具。

安装

pip install osdev-wiki-mcp
osdev-wiki-mcp --update          # one-time: download (~5 MB) and index (~15 s)
claude mcp add osdev-wiki -- osdev-wiki-mcp

可以跳过 --update。Agent 可以自行调用 wiki_update：如果尚无索引，其他每个工具都会提示它这样做。

索引约 18 MB，位于 Windows 的 %LOCALAPPDATA%\osdev-wiki-mcp、macOS 的 ~/Library/Application Support/osdev-wiki-mcp，以及其他系统的 $XDG_DATA_HOME/osdev-wiki-mcp（或 ~/.local/share/osdev-wiki-mcp）。设置 OSDEV_WIKI_DIR 可将其存放到其他位置。需要 Python 3.10+，并且 SQLite 必须支持 FTS5。python.org 构建版、由 uv 管理的构建版和大多数发行版的构建版都包含 FTS5；如果你的版本不支持，服务会告知你。

工具

工具	功能
wiki_search	按相关性排序的全文搜索，并提供匹配片段。标题和重定向名称的权重最高，精确匹配标题时会标记为 *。
wiki_sections	页面大纲：列出带编号的标题及其内容长度。
wiki_page	以纯文本形式返回页面，或返回指定章节（按编号或标题）的内容及其子章节。代码块保持原样，并会跟随重定向。
wiki_links	显示页面链接到的内容（并标记不存在的页面），以及链接到该页面的内容，包括通过重定向建立的链接。
wiki_update	获取最新的数据转储并重建索引。如果索引已经是最新版本，则不执行任何操作。
wiki_status	显示源数据转储、页面数量、索引的时间和存放位置。

内容来源及其许可证

wiki.osdev.org 无法通过爬虫抓取：其 API 受到 Cloudflare 机器人验证保护。 因此，wiki_update 会在 archive.org 上查找该 wiki 的最新 WikiTeam 数据转储（项目名称为 wiki-wiki.osdev.org-YYYYMMDD）。它会下载该转储的历史文件，根据 archive.org 的清单校验 MD5，并保留每篇文章的最新修订版本。数据转储并非实时生成，因此索引可能比在线 wiki 滞后几个月。wiki_status 会显示你所使用的数据转储。

本软件包不包含任何 wiki 内容。 它会将公开的数据转储下载到你的设备，并在本地建立索引。关于许可证，wiki 自己的 OSDev Wiki:Copyrights 页面说明，2011 年 6 月 6 日之后添加的内容以 CC0 许可发布。其 OSDev Wiki:License 页面则称 “本 wiki 的内容采用多种许可证”，因为较早的内容不受该政策约束。所有内容均归 OSDev wiki 及其贡献者所有。搜索结果会链接回 wiki.osdev.org 上的页面。

（请注意，GitHub 上的 osdev0/wiki 是另一个无关的 wiki 项目，并非 wiki.osdev.org 的镜像。）

测试

pip install -e ".[test]" "ruff==0.16.0" "mypy==2.3.0"
ruff check src tests && mypy --strict src
pytest tests

单元测试使用一个采用真实转储格式的小型样例文件，位于 tests/fixtures/mini-wiki.xml。其中有一个页面的历史记录分散在多个 <page> 元素中，这是 WikiTeam 转储存储较长历史记录的方式。当 OSDEV_WIKI_REAL_DIR 指向已构建的索引时，排名测试会针对真实 wiki 运行。它会检查 OS 开发者实际会提出的 14 个问题（“PIT”“GDT tutorial”“page fault error code”“how to enter long mode”等），正确页面必须排在前 3 名。CI 也会构建真实索引并运行该测试。

许可证

代码采用 MIT 许可证。未包含 wiki 内容。参见上文。