Skip to main content
Glama
enesjakozh
dreyfus92

Astro Docs MCP Server

by dreyfus92
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

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フレームワークを比較する

Related MCP server: Dedalus MCP Documentation Server

プロジェクト構造

  • 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 よりも推奨)

インストール

依存関係のインストール

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

pnpm install

サーバーを構築します。

pnpm run build

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

pnpm run watch

サーバーの実行

pnpm start
# OR directly
./bin/astro-docs-mcp

Claude Desktop による構成

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

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

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

{
  "mcp_servers": [
    {
      "id": "astro-docs-mcp",
      "name": "Astro Docs",
      "command": "/full/absolute/path/to/astro-mcp/bin/astro-docs-mcp",
      "type": "built-in"
    }
  ]
}

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

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

"/Users/username/projects/astro-mcp/bin/astro-docs-mcp"

デバッグ

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

pnpm run inspector

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

テスト

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

pnpm test
# OR directly
node src/scripts/test-client.js

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

トラブルシューティング

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

  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 パターンのコード例とスニペットを追加します

Available Tools

1 tool
search_docsC

Search Astro documentation

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesSearch term to find in Astro documentation

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action but reveals nothing about how the search works (e.g., scope, ranking, pagination), what the output looks like, or any constraints like rate limits or authentication needs. This leaves significant gaps for a tool with undocumented behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise at just three words, front-loading the essential action and resource without any wasted text. Every word earns its place, making it efficient and straightforward for an agent to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of annotations and output schema, the description is incomplete for a search tool. It doesn't explain what the search returns, how results are structured, or any behavioral nuances, leaving the agent with insufficient context to use the tool effectively beyond the basic parameter.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, with the single parameter 'query' clearly documented as 'Search term to find in Astro documentation'. The description adds no additional parameter details beyond what the schema provides, so it meets the baseline for high schema coverage without compensating value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with a specific verb ('Search') and resource ('Astro documentation'), making it immediately understandable. However, with no sibling tools mentioned, there's no opportunity to demonstrate differentiation from alternatives, which prevents a perfect score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives, prerequisites, or contextual limitations. While the absence of sibling tools reduces the need for differentiation, it still lacks any usage instructions or exclusions, leaving the agent with minimal operational context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool updatev1.0.0
    • First observedsearch_docs
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.1/5.0

Scored across 1 tool

Disambiguation5/5

With only one tool, there is no possibility of confusion or overlap between tools. The single tool 'search_docs' has a clearly distinct and unambiguous purpose.

Naming Consistency5/5

The single tool name 'search_docs' follows a clear verb_noun pattern, and with only one tool, consistency is inherently perfect as there are no other names to compare against.

Tool Count2/5

A single tool for an 'Astro Docs MCP Server' feels too thin for the apparent scope. While search is a core function, documentation servers typically benefit from additional tools like browsing, filtering, or retrieving specific pages, making this count borderline inadequate.

Completeness2/5

The tool surface is severely incomplete for a documentation server. It only provides search functionality, lacking obvious gaps such as retrieving documentation pages, listing categories, or navigating content, which are essential for comprehensive agent interaction with documentation.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

Appeared in Searches