papermoon-mkdocs-mcp

MkDocsドキュメントサイト向けの軽量MCPサーバー。マークダウンファイルをディスクから直接読み取り、全文検索とオプションのセマンティック検索を提供し、Model Context Protocolを通じてプロジェクト構造を公開します。

特徴

• 5つのMCPツール -- search、read_document、list_documents、get_project_info、get_document_outline

• SQLite FTS5キーワード検索（BM25ランキング、外部依存ゼロ）

• オプションのセマンティックベクトル検索（sentence-transformersによる）

• ハイブリッド検索 -- キーワードとベクトルの結果をReciprocal Rank Fusionで統合

• インクリメンタルインデックス -- ファイル変更時の高速更新

• 永続的なSQLiteインデックス -- サーバー再起動後も保持

• ナビゲーション対応 -- mkdocs.ymlと.nav.ymlを解析

• 除外可能なドキュメント -- 下書きや内部ページをMCPサーフェスから除外

• セキュリティ最優先 -- パストラバーサル防止、読み取り専用検索接続

• 最小限の依存関係 -- 必須3つ、オプション2つ

Related MCP server: mdbook-mcp-server

インストール

pip install papermoon-mkdocs-mcp

ベクトル検索を有効にするには:

pip install papermoon-mkdocs-mcp[vector]

クイックスタート

任意のMkDocsプロジェクトのルート（mkdocs.ymlがある場所）から実行:

cd /path/to/your/mkdocs-project
papermoon-mkdocs-mcp

または、特定の設定ファイルを指定:

papermoon-mkdocs-mcp --config /path/to/mkdocs.yml

--configを省略すると、サーバーは現在のディレクトリのmkdocs.ymlを自動検出します。

トランスポートオプション

デフォルトでは、サーバーはstdioトランスポートを使用します。リモートまたはマルチクライアント設定用にネットワークトランスポートに切り替えることができます:

# Streamable HTTP (recommended for network access)
papermoon-mkdocs-mcp --transport streamable-http --host 0.0.0.0 --port 9000

# SSE (legacy client compatibility)
papermoon-mkdocs-mcp --transport sse --port 8080

セキュリティ注記: ループバック以外のアドレスにバインドする場合は、サーバーをTLSを終端するリバースプロキシ（例: nginx、Caddy）の背後に配置してください。

MCPクライアント設定

Claude Desktop

Claude Desktop設定ファイルに追加:

{
  "mcpServers": {
    "mkdocs": {
      "command": "papermoon-mkdocs-mcp",
      "args": ["--config", "/path/to/mkdocs.yml"]
    }
  }
}

注記: Claude Desktopがコマンドを見つけられない場合（Failed to spawn process: No such file or directory）、mkdocs-mcpの代わりに実行ファイルのフルパスを使用してください:

{
  "mcpServers": {
    "mkdocs": {
      "command": "/path/to/.venv/bin/mkdocs-mcp",
      "args": ["--config", "/path/to/mkdocs.yml"]
    }
  }
}

これは、パッケージが仮想環境にインストールされ、そのbin/ディレクトリがClaude DesktopのPATHにない場合によく発生します。

Claude Code / VS Code

プロジェクトルートの.mcp.jsonに追加:

{
  "mcpServers": {
    "mkdocs": {
      "command": "papermoon-mkdocs-mcp",
      "args": ["--config", "/path/to/mkdocs.yml"]
    }
  }
}

利用可能なツール

search

キーワード、セマンティック、またはハイブリッド検索でドキュメントを検索します。

パス、タイトル、関連性スコア（正規化0.0--1.0）、テキストスニペットを含むランク付けされた結果を返します。

read_document

相対パスでドキュメントファイルを読み取ります。

マークダウンボディ（フロントマターは除去）、解析されたフロントマターを別フィールドとして、見出し構造、ファイルメタデータを返します。

list_documents

すべてのドキュメントファイルを一覧表示します。オプションでセクションでフィルタリングできます。

ドキュメントメタデータ（パス、タイトル、説明、カテゴリ、サイズ、mtime）を返します。

get_project_info

MkDocsプロジェクトのメタデータを取得します。パラメータはありません。

サイト名、サイトURL、docsディレクトリ、テーマ、ナビゲーションツリー、ドキュメント数、インデックス状態を返します。

get_document_outline

ドキュメントの見出し構造（目次）を取得します。

ドキュメントのタイトルと、レベル、テキスト、アンカーを含む見出しのリストを返します。

ドキュメントの除外

一部のマークダウンファイルはMCPで公開する価値がありません -- 下書き、内部のランブック、生成されたスクラッチファイルなど。mkdocs.ymlにmcp_excludeリストを追加します:

site_name: My Docs

mcp_exclude:
  - drafts/             # any directory named 'drafts', at any depth
  - internal/**         # anchored: only 'internal/' at the docs root
  - "*-scratch.md"      # by filename suffix, at any depth
  - "!internal/public.md"  # re-include one file from a broader rule

除外はすべての場所に同時に適用されます。除外されたドキュメントはナビゲーションツリーに存在せず、検索インデックスに入らず、list_documentsに表示されず、read_documentとget_document_outlineによって拒否されます -- 拒否は存在しないファイルへの応答と同一であるため、ドキュメントが存在することを明かしません。

mcp_excludeはこのMCPサーバーにのみ影響します。mkdocs buildが公開する内容は変更しません。

パターン構文

パターンはgitignoreスタイルで、docs_dirからの相対パスでドキュメントにマッチします。

• /を含むパターンはdocs_dirにアンカーされます。含まないものは任意の深さでマッチします。

• 末尾の/はパターンをディレクトリに限定するため、drafts/はdrafts.mdという名前のファイルを隠しません。

• ルールは順に評価され、最後にマッチしたものが決定するため、!再包含は、それらが切り出すルールの後に置いてください。

• 空行と#コメントは無視されます。

新しく除外されたファイルは次回の実行時にインデックスから削除され、パターンを削除すると再び含まれます -- .mkdocs-mcp.dbを削除する必要はありません。

アーキテクチャ

src/mkdocs_mcp/
  config.py      -- MkDocs config detection and nav parsing
  exclusions.py  -- mcp_exclude pattern matching
  repository.py  -- SQLite schema and CRUD operations
  indexer.py     -- Index orchestration with incremental updates
  searcher.py    -- Keyword, vector, and hybrid search
  server.py      -- FastMCP server with 5 tool definitions
  utils.py       -- Path validation, frontmatter parsing, text extraction
  models.py      -- Pydantic response models

起動時にサーバーはmkdocs.ymlを読み取り、docsディレクトリをスキャンし、SQLite FTS5インデックスを構築（またはインクリメンタルに更新）します。検索クエリはインデックスに直接ヒットします。ベクトル検索はall-MiniLM-L6-v2でクエリを埋め込み、保存されたドキュメント埋め込みと比較します。ハイブリッドモードはReciprocal Rank Fusionを使用して両方の結果リストを統合します。

開発

git clone https://github.com/aspect-build/mkdocs-mcp.git
cd mkdocs-mcp
pip install -e ".[dev]"
pytest

リンターと型チェック:

ruff check .
mypy src/

要件

• Python >= 3.10

• 必須: fastmcp (>=3.0, <4)、pydantic (>=2.0, <3)、pyyaml (>=6.0)、markdown (>=3.4)

• オプション（ベクトル検索）: sentence-transformers (>=3.0)、numpy (>=1.24)

ライセンス

詳細はLICENSEを参照してください。