Astro Docs MCP Server

An MCP server for providing Astro documentation access to AI agents. This server allows AI assistants to look up and reference Astro documentation when helping users with Astro-related tasks.

This TypeScript-based MCP server implements a documentation retrieval system for Astro. It demonstrates core MCP concepts by providing:

• Resources representing Astro documentation sections with URIs and metadata
• Tools for searching Astro documentation
• Prompts for common Astro questions and tasks

Features

Resources

• List and access Astro documentation via astro-docs:// URIs
• Each doc section has a title, content, and category
• Plain text mime type for simple content access

Tools

• search_docs - Search Astro documentation
  • Takes a search query as required parameter
  • Returns matching documentation sections

Prompts

• explain_astro_islands - Get detailed explanations of Astro Islands architecture
• astro_project_setup - Guide for setting up a new Astro project
• astro_vs_other_frameworks - Compare Astro with other web frameworks

Project Structure

• src/ - Source code for the MCP server
  • index.ts - Main MCP server implementation
  • scripts/ - Helper scripts for building and testing
    • build.js - Build script that transpiles TypeScript and creates launcher scripts
    • test-client.js - Test client for verifying server functionality
• bin/ - Generated executable scripts
  • astro-docs-mcp - Main launcher script for the MCP server
• build/ - Compiled JavaScript files (generated)

Requirements

• Node.js v16 or later is required
• Node.js v20+ is recommended for best compatibility
• The server uses ES modules syntax
• pnpm package manager (preferred over npm)

Installation

Installing Dependencies

Install dependencies:

pnpm install

Build the server:

pnpm run build

For development with auto-rebuild:

pnpm run watch

Running the Server

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

Configuration with Claude Desktop

To use with Claude Desktop, add the server config:

On MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json On Windows: %APPDATA%/Claude/claude_desktop_config.json

Important: The configuration must use the absolute path to the script:

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

Replace /full/absolute/path/to/astro-mcp/ with the actual absolute path to your installation directory.

For example, if the repository is at /Users/username/projects/astro-mcp, the command would be:

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

Debugging

Since MCP servers communicate over stdio, debugging can be challenging. We recommend using the MCP Inspector, which is available as a package script:

pnpm run inspector

The Inspector will provide a URL to access debugging tools in your browser.

Testing

A test client is provided to verify the server is working correctly:

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

This will send several commands to the server and display the responses.

Troubleshooting

If you encounter issues with the server:

1. Path Issues: The most common problem is incorrect paths in the configuration. Make sure:

   • You’re using an absolute path to the script in claude_desktop_config.json
   • The path points to bin/astro-docs-mcp (not the root script)
   • The build directory exists and contains index.js (ls -la build/)
   • All scripts have executable permissions

2. “Module not found” errors: If you see errors like Cannot find module '/build/index.js', check:

   • That you’ve run the build step (pnpm run build)
   • That the script is being run from the correct directory
   • That absolute paths are being used for the script execution

3. Node.js Version: Make sure you’re using Node.js v16 or later. For best results, use v20+.

   node --version
   

4. Script Permissions: Ensure the scripts have executable permissions:

   chmod +x bin/astro-docs-mcp src/scripts/build.js src/scripts/test-client.js
   

5. JSON Output Issues: Debug messages being sent to stdout will confuse Claude Desktop because it expects only valid JSON. Our scripts properly redirect all debug output to stderr.

Usage with Claude Desktop

1. Install the server by following the installation steps above.

2. Configure Claude Desktop by editing the configuration file to include the absolute path to the script:

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

3. Restart Claude Desktop.

4. You can now interact with the Astro documentation using the following commands:

   • list - List available Astro documentation sections
   • search <query> - Search the Astro documentation
   • read astro-docs:///<id> - Read a specific documentation section

Future Enhancements

• Fetch real-time documentation from Astro’s website
• Add more comprehensive documentation sections
• Implement documentation versioning support
• Add code examples and snippets for common Astro patterns