Librarian MCP Server

Librarian MCP サーバー

概要

Librarian は、構造化して保存された Markdown ファイルの一覧表示、検索、取得を行うための API を提供する Model Context Protocol（MCP）サーバーです。LLM のナレッジベースとして機能し、必要に応じて情報を提供します。

Librarian は書き込み操作を提供しません。MCP フレームワークを通じて LLM にドキュメントの内容を効率的に提供する、読み取り専用のサービスです。

機能

• 構造化されたドキュメント管理：ドキュメントはセクションごとに整理されています（例：daisyui/components/button.md）
• タグによるフィルタリング：フロントマターで定義されたタグを使ってドキュメントを絞り込めます
• 階層的なタグの継承：タグは親ディレクトリから継承されます
• 柔軟な検索機能：
  • 単純な文字列検索（大文字と小文字を区別しません）
  • フラグをカスタマイズできる正規表現検索
• 効率的なドキュメント取得：パスを指定して特定のドキュメントにすばやくアクセスできます
• タグの検出：使用回数や任意のファイルパスとともに、利用可能なすべてのタグを一覧表示できます
• MCP 連携：Model Context Protocol とシームレスに連携します

プロジェクト構成

Librarian MCP サーバーは、モジュール式のコンポーネントで構成されています。

• src/lib/config.ts：設定の型定義とローダー
• src/lib/load.ts：ドキュメントの読み込みと処理機能
• src/lib/librarian.ts：スキーマを含む Librarian の中核実装
• src/lib/util.ts：プレーンテキスト応答の整形ユーティリティ
• src/lib/server.ts：MCP サーバーの実装
• src/bin.ts：CLI のエントリーポイント
• src/index.ts：ライブラリのエントリーポイント

このモジュール設計により、関心事を明確に分離しながら、拡張や保守を容易にしています。

インストール

前提条件

• Node.js（v14 以降）
• npm または pnpm

インストール手順

# Clone the repository
git clone https://github.com/yourusername/mcp-server-librarian.git
cd mcp-server-librarian

# Install dependencies
pnpm install

# Build the project
pnpm build

設定

ドキュメントフォルダーのパスは、以下の方法で設定できます（優先順位の高い順）。

コマンドライン引数

node dist/bin.js --docs-root /path/to/your/docs

環境変数

LIBRARIAN_DOCS_ROOT=/path/to/your/docs node dist/bin.js

ドキュメント構成

整理方法

ドキュメントは階層構造に従って、セクションごとに整理されています。

<docs_root>/
├── daisyui/
│   ├── index.md              # DaisyUI section info with tags
│   └── components/
│       ├── index.md          # Components section info with tags
│       ├── button.md         # Document with specific tags
│       └── card.md           # Another document with specific tags
└── tailwind4/
    ├── index.md              # Tailwind section info with tags
    └── getting-started.md    # Document with specific tags

フロントマター

各 Markdown ドキュメントには、tags フィールドを含むフロントマターを記述できます。

---
tags: ["frontend", "ui", "button"]
---

# Button Component

This document describes the button component...

タグの継承

タグはフォルダー階層を通じて継承されます。

1. ドキュメントは、親ディレクトリにあるすべての index.md ファイルからタグを継承します
2. タグは最も一般的なもの（ルート）から最も具体的なもの（ドキュメント）へと統合されます

たとえば、次のような場合を考えてみましょう。

• /daisyui/index.md のタグ：["ui"]
• /daisyui/components/index.md のタグ：["components"]
• /daisyui/components/button.md のタグ：["interactive", "form"]

この場合、/daisyui/components/button.md は実質的にすべてのタグを持ちます：["documentation", "ui", "components", "interactive", "form"]

フォルダーの説明

フォルダー内に index.md ファイルを作成すると、そのフォルダー自体について説明できます。このファイルには、フロントマター（タグを含む）と、そのセクションの目的を説明する本文の両方を記述できます。

API リファレンス

Librarian MCP サーバーは、次のツールを提供します。

getDocuments

パスを指定して複数のドキュメントを取得します。

パラメーター：

• filepaths：取得するファイルパスの配列

応答：

**/path/to/document1.md**
- tags: tag1, tag2, tag3
======
Document 1 content
======

**/path/to/document2.md**
- tags: tag1, tag4, tag5
======
Document 2 content
======

getDocument

パスを指定して特定のドキュメントを取得します。

パラメーター：

• filepath：ドキュメントへのパス

応答：

**/path/to/document.md**
- tags: tag1, tag2, tag3
======
Document content
======

listDocuments

ディレクトリとタグで絞り込んで、すべてのドキュメントを一覧表示します。

パラメーター：

• directory（任意）：ドキュメントを一覧表示するディレクトリのパス（デフォルト：「/」）
• tags（任意）：絞り込みに使用するタグの配列（デフォルト：[]）
• includeContents（任意）：結果にドキュメントの内容を含めるかどうか（デフォルト：false）
• depth（任意）：走査するディレクトリの最大深度（無制限の場合は-1、デフォルト：-1）

レスポンス：（includeContents が false の場合）

- /path/to/document1.md
  - tags: tag1, tag2, tag3
- /path/to/document2.md
  - tags: tag1, tag4, tag5
...

レスポンス：（includeContents が true の場合）

**/path/to/document1.md**
- tags: tag1, tag2, tag3
======
Document 1 content
======

**/path/to/document2.md**
- tags: tag1, tag4, tag5
======
Document 2 content
======

searchDocuments

文字列または正規表現パターンを使用して、ドキュメントの内容を検索します。

パラメーター：

• query：検索クエリ（文字列または正規表現パターン）
• mode（任意）：検索モード（「string」または「regex」、デフォルト：「string」）
• caseSensitive（任意）：大文字と小文字を区別して検索するかどうか（デフォルト：false）
• directory（任意）：検索するディレクトリのパス（デフォルト：「/」）
• tags（任意）：絞り込みに使用するタグの配列（デフォルト：[]）
• includeContents（任意）：結果にドキュメントの内容を含めるかどうか（デフォルト：false）
• depth（任意）：走査するディレクトリの最大深度（無制限の場合は-1、デフォルト：-1）

レスポンス：（includeContents が false の場合）

- /path/to/document1.md
  - tags: tag1, tag2, tag3
- /path/to/document2.md
  - tags: tag1, tag4, tag5
...

レスポンス：（includeContents が true の場合）

**/path/to/document1.md**
- tags: tag1, tag2, tag3
======
Document 1 content
======

**/path/to/document2.md**
- tags: tag1, tag4, tag5
======
Document 2 content
======

listTags

すべてのタグを件数とともに一覧表示し、必要に応じてファイルパスも表示します。

パラメーター：

• directory（任意）：タグを一覧表示するディレクトリのパス（デフォルト：「/」）
• includeFilepaths（任意）：結果にファイルパスを含めるかどうか（デフォルト：false）
• depth（任意）：走査するディレクトリの最大深度（無制限の場合は-1、デフォルト：-1）

レスポンス：（includeFilepaths が false の場合）

- tag1 (5)
- tag2 (3)
- tag3 (2)
...

レスポンス：（includeFilepaths が true の場合）

- tag1 (5)
  - /path/to/document1.md
  - /path/to/document2.md
  - ...
- tag2 (3)
  - /path/to/document3.md
  - ...

使用例

サーバーの起動

# Start with default configuration
node dist/bin.js

# Start with custom docs directory
node dist/bin.js --docs-root ./my-documentation

# Start with environment variable
LIBRARIAN_DOCS_ROOT=./my-documentation node dist/bin.js

クエリの例

ドキュメントの一覧表示

// List all documents
const allDocs = await mcp.useTool("librarian", "listDocuments", {});

// List documents in a specific directory
const uiDocs = await mcp.useTool("librarian", "listDocuments", {
  directory: "/daisyui/components",
});

// List documents with specific tags
const buttonDocs = await mcp.useTool("librarian", "listDocuments", {
  tags: ["button", "interactive"],
});

// List documents with depth limit
const topLevelDocs = await mcp.useTool("librarian", "listDocuments", {
  directory: "/daisyui",
  depth: 1, // Only include direct children, not nested subdirectories
});

ドキュメントの検索

// Simple string search
const results = await mcp.useTool("librarian", "searchDocuments", {
  query: "button styling",
});

// Regex search
const regexResults = await mcp.useTool("librarian", "searchDocuments", {
  query: "\\bbutton\\b.*\\bstyle\\b",
  mode: "regex",
  caseSensitive: true,
  includeContents: true,
});

// Search with tag filtering
const filteredResults = await mcp.useTool("librarian", "searchDocuments", {
  query: "installation",
  tags: ["tutorial"],
  directory: "/tailwind4",
});

// Search with depth limit
const topLevelResults = await mcp.useTool("librarian", "searchDocuments", {
  query: "component",
  directory: "/daisyui",
  depth: 1, // Only search in direct children, not nested subdirectories
});

ドキュメントの取得

// Get a specific document
const document = await mcp.useTool("librarian", "getDocument", {
  filepath: "/daisyui/components/button.md",
});

複数のドキュメントの取得

// Get multiple specific documents
const documents = await mcp.useTool("librarian", "getDocuments", {
  filepaths: ["/daisyui/components/button.md", "/daisyui/components/card.md"],
});

タグの一覧表示

// List all tags
const allTags = await mcp.useTool("librarian", "listTags", {});

// List tags in a specific directory
const tailwindTags = await mcp.useTool("librarian", "listTags", {
  directory: "/tailwind",
});

// List tags with filepaths
const tagsWithFiles = await mcp.useTool("librarian", "listTags", {
  includeFilepaths: true,
});

// List tags with depth limit
const topLevelTags = await mcp.useTool("librarian", "listTags", {
  directory: "/daisyui",
  depth: 1, // Only include tags from direct children, not nested subdirectories
});

LLM との統合

Librarian は、Model Context Protocol を通じて LLM とシームレスに連携するよう設計されています。LLM は次のように Librarian を利用できます。

1. タグの確認：利用可能なタグを一覧表示し、ナレッジの分類体系を把握できます
2. ドキュメントの確認：利用可能なドキュメントを一覧表示し、どのようなナレッジがあるかを把握できます
3. 検索：特定の情報が必要なとき、ドキュメント全体を検索できます
4. 取得：関連するドキュメントを特定した後、その全内容を取得できます
5. コンテキストの構築：取得した内容を使って、応答を生成するためのコンテキストを構築できます

エラー処理

Librarian は、適切なエラーコードとメッセージを含む標準的な MCP エラーレスポンスを使用します。

• INVALID_ARGUMENT：指定されたパラメーターが無効な場合
• NOT_FOUND：要求されたドキュメントまたはディレクトリが存在しない場合
• INTERNAL：予期しないサーバーエラーが発生した場合

各エラーレスポンスには、次の内容が含まれます。

• エラーコード
• 説明的なメッセージ
• デバッグ用の追加情報（任意）

トラブルシューティング

よくある問題

ドキュメントが見つからない

NOT_FOUND エラーが発生する場合：

• ドキュメントのパスが正しいことを確認してください
• --docs-root が正しいディレクトリを指していることを確認してください
• サーバーがファイルを読み取れるアクセス権限があることを確認してください

検索結果が返されない

検索で期待した結果が返されない場合：

• クエリの構文が正しいことを確認してください（特に正規表現検索の場合）
• ドキュメントに期待する内容が含まれていることを確認してください
• 検索語句の範囲を広げるか、より単純なパターンを使用してください

タグによる絞り込みが機能しない

タグによる絞り込みが期待どおりに機能しない場合：

• フロントマターでタグが正しく定義されていることを確認してください
• 継承階層を確認し、どのタグがどのドキュメントに適用されるかを把握してください
• タグ名が完全に一致していることを確認してください（タグでは大文字と小文字が区別されます）

ライセンス

このプロジェクトは MIT License のもとでライセンスされています。詳細については LICENSE ファイルをご覧ください。

貢献

貢献を歓迎します！お気軽にプルリクエストを送ってください。

コードの90％はバイブコーディングで作成されています。このコードの品質は私のものではありません。もっと時間をかければ、もっと良いコードを書けます :)