このプロジェクトについて

fumasignal-mcpは、Fumadocsで構築されたドキュメントサイトをAIアシスタントが検索して読めるようにする目的の、サードパーティ製で非公式のModel Context Protocol（MCP）サーバーです。デプロイされたFumadocsのURLまたはローカルのFumadocsプロジェクトディレクトリを指定し、MCPを話すあらゆるクライアントに読み取り専用ツールのセットを公開します。プロジェクト名は、Fumadocsの作者ハンドルであるfuma-namaと、AIクライアントと外部ツールの間で煙の信号がメッセージを運ぶというアイデアをかけています。作者は明確に、Fumadocsプロジェクトとは関係がないと述べています。 動作モード サーバーは2つのモードで動作します。リモートモードでは、デプロイされたFumadocsサイトのorigin（スキーム＋ホストのみ、ドキュメントパスは別に設定）を指定し、ローカルでのセットアップは不要です。ローカルモードでは、ディスク上のFumadocsプロジェクトのルートを指定し、オフライン作業やデプロイ前のチェックに適しています。単一のnpxバイナリとして配布され、典型的な呼び出しは `npx -y fumasignal-mcp --url https://your-docs.com` となり、すべてのアクセスは読み取り専用で、ドキュメントを変更することはありません。 公開ツール 7つのツールが提供されます。`search_docs`はサイトのOrama検索APIを通じてフルテキスト検索を行い、クエリが必要です。マルチドキュメントサイト向けに`tag`引数も受け付けます。`list_pages`は既知のドキュメントページを列挙し、URLプレフィックスでフィルタリングできます。`get_page`はページのフルMarkdownコンテンツを取得します。`get_section`は見出しアンカーで識単一のセクションを取得します。`get_toc`はページの見出しとそのアンカーを一覧表示します。`get_meta`はフロントマターまたはページメタデータをJSONで返します。`get_llms_txt`は`llms.txt`を取得し、`full`オプションが設定されている場合は`llms-full.txt`を取得します。ページ参照は、URLパス、同じホストの絶対URL、またはドキュメントプレフィックス下のスラグで指定できます。 クライアント設定 READMEには、Claude Desktop、Claude Code、Cursor、VS Code with GitHub Copilot Chat、Continue.dev向けの設定スニペットが記録されており、各ケースでstdioトランスポートと同じnpxコマンドを使用します。異なるキーで複数のインスタンスを登録することで、複数のドキュメントサイトを提供できます。Continue.devについては、再利用可能なJSONファイルとネイティブなYAML形式の両方が示されています。 設定フラグと環境変数 CLIフラグには、サイトのoriginを指定する`--url`、ローカルプロジェクトのルートを指定する`--local`、デフォルトでない検索APIパスを指定する`--search-path`（デフォルト `/api/search`、originルートから常に解決）、ドキュメントURLプレフィックスを指定する`--docs-prefix`（デフォルト `/docs`）、ローカルコンテンツディレクトリを指定する`--content-dir`（デフォルト `content/docs`）、認証が必要なサイト用の`--auth-header`、リモートレスポンスのキャッシュTTLを指定する`--cache-ttl`（デフォルト 300000 ms）、および`--version`と`--help`があります。各フラグには対応する`FUMASIGNAL_*`環境変数があり、明示的なフラグが優先されます。さらに、`FUMASIGNAL_LOG_LEVEL`というフラグに相当しない環境変数もあります。READMEでは、シェルヒストリやプロセスリストに残らないように、シークレットはコマンドラインではなく環境変数で渡すことを推奨しています。 取得の仕組み リモートモードでは、`search`はサイトのOrama APIを呼び出し、フラット配列とhits/documentの両方のレスポンス形状を処理します。ページの一覧取得は`sitemap.xml`を取得し、ドキュメントプレフィックスでフィルタリングします。ページ取得はまず`.md`、`.mdx`、および`/raw`バリアントのURLを試し、それ以外の場合はレンダリングされたHTMLをスクレイピングし、Turndownを使って`article`または`main`要素をMarkdownに変換します。`llms.txt`は直接取得されます。リモートレスポンスはメモリ内でキャッシュされ、デフォルトのTTLは5分です。ローカルモードでは、サーバーはコンテンツディレクトリ以下のMarkdownとMDXファイルを歩き、`gray-matter`でフロントマターをパースし、インデックスファイルをドキュメントルートにマッピングし、見出し重み付けトークンマッチングで検索結果をスコアリングします。 互換性とテスト プロジェクトはNode.js 20以降が必要で、デフォルトのOrama検索APIと標準的なサイトマップレイアウトに対してテスト済みであると述べています。どんなSTDIO MCPクライアントでも動作し、Claude Desktop、Claude Code、Cursor、VS Codeのオプション、ZedおよびClineなどが挙げられています。さらに、検索、サイトマップ、HTMLパスをカバーするフィクスチャを含む280以上のユニットテストがあると報告しています。 トラブルシューティングと開発 READMEでは一般的な問題について説明しています：サイトマップが欠けていると`list_pages`のみに影響し、検索で404エラーが発生するのは通常、デフォルトでない検索パスまたはパスを含むURLが原因です。MarkdownエンドポイントがないサイトではHTMLスクレイピングがノイズを生む可能性があり、ツールが正しく登録されていることを確認するためのMCP Inspectorスクリプトが提供されています。開発手順は、クローン、インストール、`tsc`による型チェック、`eslint`によるリンティング、`vitest`によるテスト、`tsup`によるビルド、およびこれらを組み合わせたチェックスクリプトです。貢献は歓迎され、非自明な変更についてはまずissueを開くよう求められています。プロジェクトはMITライセンスの下でリリースされています。