osdev-wiki-mcp

osdev-wiki-mcp

OSDev Wikiをオフラインで検索可能にし、AI エージェントから利用できます。

wiki.osdev.orgは、趣味でオペレーティングシステムを開発する際のリファレンスです。ディスクリプターテーブル、ページング、割り込みコントローラー、タイマー、ACPI、ディスクコントローラー、ブートローダー、ツールチェーンなどを扱っています。カーネルコードを書くエージェントは、こうした詳細を記憶から再構成しようとして、ビット配置を間違えがちです。また、Wikiはボット対策チャレンジの背後にあるため、エージェント自身で閲覧することもできません。

osdev-wiki-mcpは、Wikiの公開アーカイブを一度ダウンロードしてSQLiteの全文検索でローカルにインデックス化し、エージェントが検索したり、ページ全体やその一部のセクションを読んだり、リンクをたどったりするためのツールを提供します。

出力例

これは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.]

この出力がエージェントにとって役立つ点は次のとおりです。

• 略語も機能します。 「PIT」と「IDT」はWiki内のリダイレクトです。リダイレクトは転送先の別名としてインデックス化されるため、略語から目的のページを最初に見つけられます。
• ビット配置テーブルも読みやすく表示されます。 Wikiでは、ディスクリプターやページテーブルの配置をHTMLテーブルで示しています。これらは1行ずつ表示され、ビット範囲は63..48のように示されます。
• 曖昧さが報告されます。 ページ内に同じ見出しが2回登場する場合、もう一方の場所もエージェントに通知されます。
• 切り詰められた理由がわかります。 結果が途中で切れている場合、次に呼び出すべきものが正確に示されます。

インストール

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は省略できます。インデックスがまだない場合は、ほかのすべてのツールがwiki_updateを呼び出すようエージェントに伝えます。エージェント自身が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を設定してください。SQLite FTS5を備えたPython 3.10以降が必要です。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 のチュートリアル」「ページフォールトのエラーコード」「ロングモードに入る方法」など）を確認し、該当するページが上位 3 位以内にランクインする必要があります。CI でも実際のインデックスをビルドし、このテストを実行します。

ライセンス

コードには MIT ライセンスが適用されます。Wiki のコンテンツは含まれていません。上記をご覧ください。