Bucketeer Docs Local MCP Server

Bucketeer Docs ローカル MCP サーバー

概要

このプロジェクトは、Bucketeer のドキュメント向けに Model Context Protocol（MCP）サーバーを提供します。Bucketeer の機能フラグおよび実験プラットフォームのドキュメントを検索・取得するためのインターフェースを提供し、AI アシスタントが Bucketeer の機能や使い方について正確な情報を提供できるようにします。

環境のセットアップ

要件

• Node.js 18+
• npm

インストール手順

1. リポジトリをクローンします。

git clone <repository-url>
cd bucketeer-docs-local-mcp-server

2. 依存関係をインストールします。

npm install

3. プロジェクトをビルドします。

npm run build

4. ドキュメントインデックスをビルドします。

npm run build:index

サーバーの起動

npm start

ドキュメントのソース

サーバーは、bucketeer-io/bucketeer-docs リポジトリからドキュメントを自動的に取得してインデックスを作成します。

• GitHub リポジトリとの連携：

  • docs/ ディレクトリとすべてのサブディレクトリから .mdx ファイルを自動的に取得します
  • 検索インデックスを最適化するため、フロントマターと Markdown のコンテンツを処理します
  • 取得したコンテンツを SHA ハッシュを使用してキャッシュし、ファイルが変更された場合にのみ更新します
  • 再帰的なディレクトリ走査に対応し、すべてのドキュメントファイルを取得します

• インテリジェントなインデックス作成：

  • タイトル、説明、見出し、コンテンツからキーワードを抽出します
  • キーワードの一致と全文検索に基づく関連度スコアリングを使用して、検索可能なインデックスを作成します
  • Bucketeer 固有の用語（機能フラグ、実験、SDK、ターゲティングなど）向けに最適化されています
  • MDX ファイルからフロントマター（タイトル、説明）を抽出します

• キャッシュ管理：

  • ファイルは files/docs/ ディレクトリに JSON ファイルとしてローカルにキャッシュされます
  • ドキュメントインデックスは files/index/document-index.json に保存されます
  • GitHub のキャッシュは files/docs/github_cache.json に保存され、SHA に基づく変更検出を行います
  • インデックス全体を強制的に再構築するには、npm run build:index:force を使用します

npx を使用する

初回セットアップ

1. ドキュメントインデックスをビルドします。

npx @bucketeer/docs-local-mcp-server build-index

2. 次のセクションの説明に従って、MCP の設定に追加します。

インデックスの更新

ドキュメントインデックスを更新するには（たとえば、新しいドキュメントが追加された場合）：

npx @bucketeer/docs-local-mcp-server build-index --force

Cursor と Claude Desktop の設定

Cursor（https://docs.cursor.com/context/model-context-protocol#configuring-mcp-servers）および Claude Desktop（https://modelcontextprotocol.io/quickstart/user）のドキュメントを参照し、`mcp.json` または claude_desktop_config.json ファイルに以下を追加して MCP サーバーを設定します。

Cursor ディープリンクを使ったクイックインストール

Cursor ユーザーは、以下のディープリンクを使って、ワンクリックで MCP サーバーをインストールできます。

これにより、Cursor の設定で MCP サーバーが自動的に構成されます。リンクをクリックすると、Cursor からサーバーのインストールを求められます。

オプション 1：npx を使用する（推奨）

{
  "mcpServers": {
    "bucketeer-docs": {
      "type": "stdio",
      "command": "npx",
      "args": ["@bucketeer/docs-local-mcp-server"]
    }
  }
}

オプション 2：ローカルインストールを使用する

{
  "mcpServers": {
    "bucketeer-docs": {
      "type": "stdio",
      "command": "npm",
      "args": ["start", "--prefix", "/path/to/bucketeer-docs-local-mcp-server"]
    }
  }
}

使い方

MCP サーバーの実行中は、次のツールを使用できます。

1. search_docs - Bucketeer ドキュメントを検索する

• パラメーター：query（文字列）- 検索クエリ
• パラメーター：limit（数値、任意）- 返す結果の最大数（デフォルト：5）

例：

{
  "name": "search_docs",
  "arguments": {
    "query": "feature flags SDK integration",
    "limit": 5
  }
}

レスポンス：タイトル、URL、パス、説明、抜粋、関連度スコアを含む検索結果の配列を返します。

2. get_document - 特定のドキュメントの内容を取得する

• パラメーター：path（文字列）- 検索結果から取得したドキュメントのパス

例：

{
  "name": "get_document",
  "arguments": {
    "path": "getting-started/create-feature-flag"
  }
}

レスポンス：タイトル、説明、URL、Markdown コンテンツ全体を含む、ドキュメントの完全な内容を返します。

開発コマンド

• npm run build - TypeScript ファイルを dist/ ディレクトリにコンパイルします
• npm run build:index - GitHub リポジトリからドキュメントインデックスを作成／更新します
• npm run build:index:force - インデックス全体を強制的に再構築します（キャッシュを無視します）
• npx @bucketeer/docs-local-mcp-server build-index - npx を使用してインデックスを作成します
• npx @bucketeer/docs-local-mcp-server build-index --force - npx を使用してインデックスを強制的に再構築します
• npm run dev:index - 開発モードでインデックスを作成・更新します
• npm run dev - 開発モードでビルドしてサーバーを起動します
• npm run lint - Biome によるリンティングを実行します
• npm run lint:fix - Biome によるリンティングを実行し、リンティングエラーを修正します

設定

サーバーは src/config/index.ts で設定します。

• siteName: "Bucketeer"
• websiteUrl: "https://docs.bucketeer.io"
• githubRepo: "https://github.com/bucketeer-io/bucketeer-docs"
• docsDirectory: "docs"（ドキュメントを含む GitHub リポジトリ内のディレクトリ）
• searchLimitDefault: 5（検索結果のデフォルト件数）
• useGithubSource: true（常に GitHub をソースとして使用します）

ファイル構成

files/
├── docs/           # Cached JSON files from GitHub repository
├── index/          # Document search index
│   └── document-index.json
└── [created automatically when building index]

アーキテクチャ

サーバーはいくつかの主要なコンポーネントで構成されています。

1. GithubDocumentFetcher: GitHub リポジトリから .mdx ファイルを再帰的に取得します
2. IndexManager: 検索可能なドキュメントインデックスを作成・管理します
3. SearchService: キーワードマッチングと全文検索による検索機能を提供します
4. MCP Server: Model Context Protocol を介してツールを公開します

ライセンス

Apache License 2.0。詳細は LICENSE をご覧ください。

コントリビューション

Bucketeer に貢献し、改善に協力していただけるとうれしいです！どなたでもご利用いただけます！

コントリビューションガイドはこちらをご覧ください。