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）

安装

安装依赖项

安装依赖项：

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

这将向服务器发送几个命令并显示响应。

故障排除

如果您遇到服务器问题：

路径问题：最常见的问题是配置中的路径不正确。请确保：
- 您正在使用 claude_desktop_config.json 中脚本的绝对路径
- 该路径指向bin/astro-docs-mcp （不是根脚本）
- 构建目录存在并包含 index.js ( ls -la build/ )
- 所有脚本均具有可执行权限
“找不到模块”错误：如果您看到类似Cannot find module '/build/index.js'错误，请检查：
- 您已运行构建步骤（ pnpm run build ）
- 脚本正在从正确的目录运行
- 脚本执行时使用绝对路径
Node.js 版本：请确保您使用的是 Node.js v16 或更高版本。为了获得最佳效果，请使用 v20 及以上版本。
node --version
脚本权限：确保脚本具有可执行权限：
chmod +x bin/astro-docs-mcp src/scripts/build.js src/scripts/test-client.js
JSON 输出问题：发送到标准输出 (stdout) 的调试消息会导致 Claude Desktop 出现问题，因为它只接受有效的 JSON 格式。我们的脚本可以正确地将所有调试输出重定向到标准输出 (stderr)。

与 Claude Desktop 一起使用

按照上述安装步骤安装服务器。
通过编辑配置文件来配置 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" } ] }
重新启动 Claude Desktop。
您现在可以使用以下命令与 Astro 文档进行交互：
- list ——列出可用的 Astro 文档部分
- search <query> - 搜索 Astro 文档
- read astro-docs:///<id> - 阅读特定文档部分

未来的增强功能

从 Astro 网站获取实时文档
添加更全面的文档部分
实施文档版本控制支持
添加常见 Astro 模式的代码示例和片段

Astro Docs MCP Server

Integrations