Astro Docs MCP Server

Astro Docs MCP 服务器

一个 MCP 服务器，用于向 AI 代理提供 Astro 文档访问权限。该服务器允许 AI 助手在帮助用户执行 Astro 相关任务时查找和参考 Astro 文档。

这个基于 TypeScript 的 MCP 服务器为 Astro 实现了一个文档检索系统。它通过提供以下功能演示了 MCP 的核心概念：

• 代表 Astro 文档部分的资源，包含 URI 和元数据
• Astro 文档搜索工具
• 常见 Astro 问题和任务的提示

特征

资源

• 通过astro-docs:// URI 列出并访问 Astro 文档
• 每个文档部分都有标题、内容和类别
• 用于简单内容访问的纯文本 MIME 类型

工具

• search_docs - 搜索 Astro 文档
  • 将搜索查询作为必需参数
  • 返回匹配的文档部分

提示

• explain_astro_islands - 获取 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 模式的代码示例和片段