Mcp Documentation Server

MCP Documentation Server

AI コーディングエージェント向けの、ローカルファーストなドキュメント管理とセマンティック検索です。 外部データベースもクラウド API もなく、ベンダーロックインもありません。

CLI 専用の他の MCP サーバーとは異なり、このサーバーには完全なウェブダッシュボードが付属しています。ブラウザーからナレッジベースの閲覧、検索、アップロード、管理ができます。すべての MCP ツールは REST API としても公開されているため、AI エージェントにスキーマ不要の軽量なインターフェースを提供します。

• 🏠 完全オフラインで動作 — Orama ベクトル DB とローカル AI 埋め込み（Transformers.js）
• 🌐 組み込みウェブ UI — MCP サーバーとともにポート 3080 で自動起動します
• 🔍 ハイブリッド検索 — 全文検索とベクトル類似度検索を親子チャンク化と組み合わせています
• 🤖 オプションの AI 検索 — 高度なドキュメント分析に Google Gemini を使用します（API キーはご自身で用意してください）
• 📁 ドラッグ＆ドロップでアップロード — .txt、.md、.pdf に対応
• 📦 MCP Registry で公開済み — npx からインストールでき、リポジトリのクローンは不要です

クイックスタート

{
  "mcpServers": {
    "documentation": {
      "command": "npx",
      "args": ["-y", "@andrea9293/mcp-documentation-server"]
    }
  }
}

ブラウザーで http://localhost:3080 を開きます。ウェブ UI は自動的に起動します。

🤖 エージェントスキル（REST API）— AI エージェントに推奨

すべての MCP ツールは http://127.0.0.1:3080/api/ の REST API からも利用できます。AI エージェント（Claude Code、OpenCode、Gemini CLI、Cursor）とのやり取りには、この方法を推奨します。MCP ツールのスキーマを会話コンテキストに読み込まずに済み、レスポンス JSON だけが追加されるためです。

curl -s http://127.0.0.1:3080/api/config
curl -s http://127.0.0.1:3080/api/documents
curl -s -X POST http://127.0.0.1:3080/api/search-all \
  -H "Content-Type: application/json" \
  -d '{"query": "your search", "limit": 5}'

すぐに使えるスキルが skills/documentation-server/SKILL.md に含まれています。エージェントが各エンドポイントを例とともに使えるようにするものです。インストール方法は次のとおりです。

npx skills add https://github.com/andrea9293/mcp-documentation-server --skill documentation-server

基本的なワークフロー

1. add_document を使ってドキュメントを追加するか、.txt／.md／.pdf ファイルをアップロードフォルダーに置いて process_uploads を呼び出します。
2. search_all_documents ですべてのドキュメントを横断検索するか、search_documents で単一のドキュメント内を検索します。
3. get_context_window を使って前後のチャンクを取得し、LLM により広いコンテキストを提供します。

ウェブ UI

MCP サーバーの起動時に、ウェブインターフェースがポート 3080 で自動的に起動します。ウェブ UI では次の操作ができます。

• 📊 ダッシュボード — すべてのドキュメントと統計情報の概要
• 📄 ドキュメント — ドキュメントの閲覧、表示、削除
• ➕ ドキュメントを追加 — タイトル、コンテンツ、メタデータを指定してドキュメントを作成
• 🔍 すべてを検索 — すべてのドキュメントを横断したセマンティック検索
• 🎯 ドキュメント内を検索 — 特定のドキュメント内を検索
• 🤖 AI 検索 — Gemini を活用した分析（GEMINI_API_KEY が設定されている場合）
• 📁 ファイルをアップロード — ファイルをドラッグ＆ドロップし、ナレッジベースに取り込む
• 🪟 コンテキストウィンドウ — 指定したインデックスの周辺にあるチャンクを確認

MCP クライアントを設定する

最小構成

{
  "mcpServers": {
    "documentation": {
      "command": "npx",
      "args": ["-y", "@andrea9293/mcp-documentation-server"]
    }
  }
}

環境変数を使用（すべて任意）

{
  "mcpServers": {
    "documentation": {
      "command": "npx",
      "args": ["-y", "@andrea9293/mcp-documentation-server"],
      "env": {
        "MCP_BASE_DIR": "/path/to/workspace",
        "GEMINI_API_KEY": "your-api-key-here",
        "MCP_EMBEDDING_MODEL": "Xenova/all-MiniLM-L6-v2",
        "START_WEB_UI": "true",
        "WEB_HOST": "127.0.0.1",
        "WEB_PORT": "3080"
      }
    }
  }
}

すべての環境変数は任意です。GEMINI_API_KEY を設定しない場合、ローカル埋め込みベースの検索ツールのみ利用できます。

MCP ツール

サーバーは次のツールを登録します（すべて Zod スキーマで検証済み）。

📄 ドキュメント管理

ツール	説明
add_document	ドキュメントを追加します（タイトル、内容、任意のメタデータ）
list_documents	メタデータと内容のプレビューを含むすべてのドキュメントを一覧表示します
get_document	ID を指定してドキュメントの全内容を取得します
delete_document	ドキュメント、そのチャンク、データベースエントリー、および関連ファイルを削除します

📁 ファイル処理

ツール	説明
process_uploads	uploads フォルダー内のすべてのファイルを処理します（チャンク分割＋埋め込み）
get_uploads_path	uploads フォルダーの絶対パスを返します
list_uploads_files	uploads フォルダー内のファイルを、サイズと形式の情報とともに一覧表示します
get_ui_url	Web UI の URL（例：http://localhost:3080）を返します。ダッシュボードを開いたり、ブラウザーから uploads フォルダーを確認したりするのに便利です

🔍 検索

ツール	説明
search_documents	特定のドキュメント内でセマンティックベクトル検索を行います
search_all_documents	ドキュメント横断検索をハイブリッド方式（全文検索＋ベクトル検索）で行います
get_context_window	指定したチャンクインデックスの前後にあるチャンクの範囲を返します
search_documents_with_ai	🤖 Gemini を使用した AI 検索です（GEMINI_API_KEY が必要です）

設定

環境変数、またはプロジェクトのルートにある .env ファイルで設定します。

変数	デフォルト	説明
MCP_BASE_DIR	~/.mcp-documentation-server	データ保存用のベースディレクトリ
MCP_EMBEDDING_MODEL	Xenova/all-MiniLM-L6-v2	埋め込みモデル名
GEMINI_API_KEY	—	Google Gemini API キー（search_documents_with_ai を有効にします）
MCP_CACHE_ENABLED	true	LRU 埋め込みキャッシュを有効または無効にします
START_WEB_UI	true	組み込み Web インターフェースを無効にするには false を設定します
WEB_HOST	127.0.0.1	Web UI のバインドアドレス（すべてのインターフェースで公開するには 0.0.0.0 を使用します）
WEB_PORT	3080	Web UI のポート
MCP_STREAMING_ENABLED	true	大きなファイルのストリーミング読み込みを有効にします
MCP_STREAM_CHUNK_SIZE	65536	ストリーミングバッファーのサイズ（バイト単位、64KB）
MCP_STREAM_FILE_SIZE_LIMIT	10485760	ストリーミングに切り替えるしきい値（10MB）

ストレージ構成

~/.mcp-documentation-server/     # Or custom path via MCP_BASE_DIR
├── data/
│   ├── orama-chunks.msp         # Orama vector DB (child chunks + embeddings)
│   ├── orama-docs.msp           # Orama document DB (full content + metadata)
│   ├── orama-parents.msp        # Orama parent chunks DB (context sections)
│   ├── migration-complete.flag   # Written after legacy JSON migration
│   └── *.md                     # Markdown copies of documents
└── uploads/                     # Drop .txt, .md, .pdf files here

埋め込みモデル

MCP_EMBEDDING_MODEL で設定します。

モデル	次元数	備考
Xenova/all-MiniLM-L6-v2	384	デフォルト — 高速で、品質も良好です
Xenova/paraphrase-multilingual-mpnet-base-v2	768	推奨 — 品質が最も高く、多言語に対応しています

モデルは初回使用時にダウンロードされます（約80～420 MB）。ベクトルの次元数はプロバイダーから自動的に判定されます。

⚠️ 重要：埋め込みモデルを変更した場合、すべてのドキュメントを再追加する必要があります。異なるモデルの埋め込みには互換性がありません。次元数が変わると、Orama データベースは自動的に再作成されます。

アーキテクチャ

Server (FastMCP, stdio)
  ├─ Web UI (Express, port 3080)
  │    └─ REST API → DocumentManager
  └─ MCP Tools
       └─ DocumentManager
            ├─ OramaStore          — Orama vector DB (chunks DB + docs DB + parents DB), persistence, migration
            ├─ IntelligentChunker  — Parent-child chunking (code, markdown, text, PDF)
            ├─ EmbeddingProvider   — Local embeddings via @xenova/transformers
            │    └─ EmbeddingCache — LRU in-memory cache
            └─ GeminiSearchService — Optional AI search via Google Gemini

• OramaStore は3つの Orama インスタンスを管理します。1つはドキュメントのメタデータと内容用、1つはベクトル埋め込みを含む子チャンク用、もう1つは親チャンク（コンテキストセクション）用です。すべてディスク上のバイナリファイルに永続化され、起動時に復元されます。
• IntelligentChunker は親子チャンク分割パターンを実装します。まず、ドキュメントをコンテキスト全体（セクション、段落）を保持する大きな親チャンクに分割し、次に各親チャンクを、精密なベクトル検索に適した小さな子チャンクにさらに分割します。クエリ時には、親ごとに結果を重複排除することで、LLM が一致した断片とより広いコンテキストの両方を受け取れるようにします。
• EmbeddingProvider は、ローカル推論用の Transformers.js モデルを必要に応じて読み込みます。API 呼び出しは不要です。

開発

git clone https://github.com/andrea9293/mcp-documentation-server.git
cd mcp-documentation-server
npm install

npm run dev       # FastMCP dev mode with hot reload
npm run build     # TypeScript compilation
npm run inspect   # FastMCP web UI for interactive tool testing
npm start         # Direct tsx execution (MCP server + web UI)
npm run web       # Run only the web UI (development)
npm run web:build # Run only the web UI (compiled)

貢献

1. リポジトリをフォークします
2. フィーチャーブランチを作成します：git checkout -b feature/name
3. コミットメッセージには Conventional Commits に従います
4. プルリクエストを作成します

ライセンス

MIT — LICENSE を参照してください

サポート

• 📖 ドキュメント
• 🐛 問題を報告
• 💬 MCP コミュニティ
• 🤖 Google AI Studio — Gemini API キーを取得

---

スターの履歴

FastMCP、Orama、TypeScript で構築