Astro Docs MCP サーバー

AIエージェントにAstroドキュメントへのアクセスを提供するMCPサーバー。このサーバーにより、AIアシスタントはAstro関連のタスクでユーザーを支援する際に、Astroドキュメントを検索・参照できるようになります。

このTypeScriptベースのMCPサーバーは、Astroのドキュメント検索システムを実装しています。以下の機能を提供することで、MCPのコアコンセプトを実証しています。

• URI とメタデータを含む Astro ドキュメント セクションを表すリソース
• Astro ドキュメントを検索するためのツール
• 一般的なAstroの質問とタスクのプロンプト

特徴

リソース

• astro-docs:// URI 経由で Astro ドキュメントの一覧とアクセスを表示します。
• 各ドキュメントセクションにはタイトル、コンテンツ、カテゴリがあります
• シンプルなコンテンツアクセスのためのプレーンテキスト MIME タイプ

ツール

• search_docs - Astro ドキュメントを検索
  • 必須パラメータとして検索クエリを受け取ります
  • 一致するドキュメントセクションを返します

プロンプト

• explain_astro_islands - アストロアイランドの建築の詳細な説明を見る
• astro_project_setup - 新しい Astro プロジェクトを設定するためのガイド
• astro_vs_other_frameworks - Astroと他のWebフレームワークを比較する

プロジェクト構造

• src/ - MCPサーバーのソースコード
  • index.ts - メインMCPサーバーの実装
  • scripts/ - ビルドとテストのためのヘルパースクリプト
    • build.js - TypeScript をトランスパイルし、ランチャー スクリプトを作成するビルド スクリプト
    • test-client.js - サーバー機能を検証するためのテストクライアント
• bin/ - 生成された実行可能スクリプト
  • astro-docs-mcp - MCP サーバーのメイン ランチャー スクリプト
• build/ - コンパイルされたJavaScriptファイル（生成済み）

要件

• Node.js v16以降が必要です
• 最高の互換性を得るにはNode.js v20以上が推奨されます
• サーバーはESモジュール構文を使用する
• pnpm パッケージ マネージャー (npm よりも推奨)

インストール

依存関係のインストール

依存関係をインストールします:

サーバーを構築します。

自動リビルドを使用した開発の場合:

サーバーの実行

Claude Desktop による構成

Claude Desktop で使用するには、サーバー設定を追加します。

MacOS の場合: ~/Library/Application Support/Claude/claude_desktop_config.json Windows の場合: %APPDATA%/Claude/claude_desktop_config.json

重要:構成ではスクリプトへの絶対パスを使用する必要があります。

/full/absolute/path/to/astro-mcp/インストール ディレクトリへの実際の絶対パスに置き換えます。

たとえば、リポジトリが/Users/username/projects/astro-mcpにある場合、コマンドは次のようになります。

デバッグ

MCPサーバーはstdio経由で通信するため、デバッグが困難になる場合があります。パッケージスクリプトとして提供されているMCP Inspectorの使用をお勧めします。

インスペクターは、ブラウザでデバッグ ツールにアクセスするための URL を提供します。

テスト

サーバーが正しく動作していることを確認するためのテスト クライアントが提供されています。

これにより、サーバーにいくつかのコマンドが送信され、応答が表示されます。

トラブルシューティング

サーバーに問題が発生した場合:

1. パスの問題：最も一般的な問題は、設定内のパスが正しくないことです。以下の点を確認してください。
   • claude_desktop_config.json 内のスクリプトへの絶対パスを使用しています
   • パスはbin/astro-docs-mcp （ルートスクリプトではない）を指します
   • ビルドディレクトリが存在し、index.js が含まれている ( ls -la build/ )
   • すべてのスクリプトには実行権限があります
2. 「モジュールが見つかりません」エラー: Cannot find module '/build/index.js'のようなエラーが表示される場合は、以下を確認してください。
   • ビルドステップを実行したこと（ pnpm run build ）
   • スクリプトが正しいディレクトリから実行されているか
   • スクリプト実行に絶対パスが使用されていること
3. Node.js バージョン：Node.js v16 以降を使用していることを確認してください。最適な結果を得るには、v20 以降をご使用ください。
   node --version
4. スクリプトの権限: スクリプトに実行権限があることを確認します。
   chmod +x bin/astro-docs-mcp src/scripts/build.js src/scripts/test-client.js
5. JSON出力の問題：デバッグメッセージがstdoutに送信されると、Claude Desktopは有効なJSONのみを想定しているため、混乱を招きます。弊社のスクリプトは、すべてのデバッグ出力をstderrに適切にリダイレクトします。

Claude Desktopでの使用

1. 上記のインストール手順に従ってサーバーをインストールします。
2. スクリプトへの絶対パスを含めるように構成ファイルを編集して、Claude Desktop を構成します。
   { "mcp_servers": [ { "id": "astro-docs-mcp", "name": "Astro Docs", "command": "/full/absolute/path/to/astro-mcp/bin/astro-docs-mcp", "type": "built-in" } ] }
3. Claude Desktop を再起動します。
4. 次のコマンドを使用して、Astro ドキュメントを操作できるようになりました。
   • list - 利用可能なAstroドキュメントセクションを一覧表示します
   • search <query> - Astroドキュメントを検索
   • read astro-docs:///<id> - 特定のドキュメントセクションを読む

将来の機能強化

• Astroのウェブサイトからリアルタイムドキュメントを取得する
• より包括的なドキュメントセクションを追加する
• ドキュメントのバージョン管理サポートを実装する
• 一般的な Astro パターンのコード例とスニペットを追加します