Local Docs MCP

🚀 Local Docs MCP Server

Local Docs MCP Serverは、Model Context Protocol (MCP) サーバーを実装し、Claudeに複数のソースからのマークダウンドキュメントへのシームレスなアクセスを提供します。

🚀 クイックスタート

Local Docs MCP Serverを使用することで、Claudeが複数のソースからマークダウンドキュメントにアクセスできるようになります。以下の手順でサーバーをセットアップしてください。

✨ 主な機能

• 複数ソースのドキュメント: コマンド、プロジェクトドキュメント、プロジェクトルートからドキュメントにアクセスできます。
• スマート検索: 完全一致や部分一致を優先したファジーマッチングが可能です。
• YAMLフロントマターサポート: 検索を強化するためのオプションのメタデータ（説明、タグ）をサポートします。
• 常時キャッシュ: ファイルリストのキャッシュを行い、変更時に自動的に無効化されます（約3000倍高速）。
• ファイル監視: ドキュメントファイルが変更されたときに自動的にキャッシュを無効化します。
• 安全なパス処理: ディレクトリトラバーサルを防止し、パスを検証します。
• ソースプレフィックス: ドキュメントのソースを明示的に指定できます（例: commands:file.md）。
• サイズ制限: 5MBを超えるファイルの読み取りを防止します。

📦 インストール

バイナリのダウンロード

リリースページから最新のリリースをダウンロードしてください。

Goを使用する場合

go install github.com/umputun/local-docs-mcp/app@latest

Homebrewを使用する場合（macOS）

brew tap umputun/apps
brew install umputun/apps/local-docs-mcp

ソースからビルドする場合

git clone https://github.com/umputun/local-docs-mcp.git
cd local-docs-mcp
make build
make install

Claudeの設定

~/.claude.jsonに以下を追加します。

{
  "mcpServers": {
    "local-docs": {
      "command": "local-docs-mcp"
    }
  }
}

または、絶対パスを使用する場合は以下のようにします。

{
  "mcpServers": {
    "local-docs": {
      "command": "/path/to/local-docs-mcp"
    }
  }
}

Claude Codeを再起動してサーバーを読み込みます。

📚 ドキュメント

ドキュメントソース

1. 共有ドキュメント (~/.claude/commands/**/*.md): ユーザーコマンドと知識ベース（設定可能）
2. プロジェクトドキュメント ($CWD/docs/**/*.md): 設定可能な除外条件を持つプロジェクト固有のドキュメント
3. プロジェクトルート ($CWD/*.md): README.mdなどのルートレベルのドキュメント（オプトイン）

YAMLフロントマターサポート

ドキュメントファイルには、検索性を向上させるためにオプションでYAMLフロントマターを含めることができます。

---
description: Enforce Test-Driven Development approach for Go code with test-first workflow
tags: [testing, development, go]
---

# Your Documentation Content

サポートされるフィールド:

• description: 検索の関連性を高めるために使用されるテキスト説明
• tags: 分類のためのタグの配列またはカンマ区切りのリスト

検索動作:

• 説明が一致すると検索スコアに+0.5が追加されます。
• タグが完全一致すると検索スコアに+0.3が追加されます。
• タグが部分一致すると検索スコアに+0.15が追加されます。
• フロントマターはread_docの出力から自動的に削除されます。
• list_all_docsには、ファイルのメタデータに説明とタグが含まれます。

注意: フロントマターは完全にオプションです。プレーンなマークダウンファイルでも問題なく動作します。

コマンドラインオプション

# ドキュメントディレクトリをカスタマイズする
local-docs-mcp --shared-docs-dir=~/.my-docs --docs-dir=documentation

# ルートレベルのマークダウンスキャンを有効にする
local-docs-mcp --enable-root-docs

# プロジェクトドキュメントスキャンからディレクトリを除外する
local-docs-mcp --exclude-dir=plans --exclude-dir=drafts

# 環境変数を介した複数の除外
EXCLUDE_DIRS=plans,drafts,archive local-docs-mcp

利用可能なオプション:

• --shared-docs-dir - 共有ドキュメントディレクトリ（デフォルト: ~/.claude/commands）
• --docs-dir - プロジェクトドキュメントディレクトリ（デフォルト: docs）
• --enable-root-docs - ルートレベルの*.mdファイルをスキャンする（デフォルト: 無効）
• --exclude-dir - プロジェクトドキュメントスキャンから除外するディレクトリ（デフォルト: plans）
• --cache-ttl - キャッシュの有効期限（デフォルト: 1h）
• --max-file-size - インデックスする最大ファイルサイズ（デフォルト: 5242880 - 5MB）
• --dbg - デバッグログを有効にする

キャッシュ

ファイルリストのキャッシュは常に有効になっており、繰り返しのクエリを大幅に高速化します。キャッシュのTTLは設定可能です。

# デフォルトの1時間のTTLを使用する
local-docs-mcp

# カスタムTTL
local-docs-mcp --cache-ttl=30m

# 環境変数を介して設定
CACHE_TTL=2h local-docs-mcp

パフォーマンス: キャッシュヒットはファイルシステムスキャンよりも約3000倍高速です（66ナノ秒対201マイクロ秒）。ドキュメントファイルが変更されるとキャッシュは自動的に無効化され、最新のデータが保証されます。

動作原理:

• 最初のクエリではファイルシステムをスキャンし、キャッシュを作成します。
• それ以降のクエリはメモリから即座に返されます。
• ファイルウォッチャーが変更を検出し、500ms以内にキャッシュを無効化します。
• TTLは安全策として機能します（デフォルト: 1時間）。

💻 使用例

設定が完了すると、Claudeは自然な言語でドキュメントをクエリできます。

• "Show me docs for routegroup"
• "Find documentation about testing"
• "List all available commands"
• "What's in the go-architect command?"

利用可能なツール

search_docs

ファジーマッチングを使用してドキュメントファイルを名前で検索します。 入力: {"query": "search-term"} 出力: スコア付きの上位10件の一致するファイル

read_doc

特定のドキュメントファイルを読み取ります。 入力: {"path": "file.md"} または {"path": "commands:action/commit.md"} 出力: メタデータ付きのファイル内容

list_all_docs

すべてのソースから利用可能なすべてのドキュメントファイルをリストします。 出力: サイズとソース情報付きの完全なファイルリスト

🔧 技術詳細

セキュリティ

• パストラバーサルの防止
• ファイルサイズ制限（5MB）
• UTF-8の検証
• ベースディレクトリ外のシンボリックリンクの追跡禁止
• 絶対パスの拒否

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。詳細についてはLICENSEファイルを参照してください。