AI导哈

Astro文档检索服务

一个为AI代理提供Astro文档访问的MCP服务器，支持文档搜索和常见问题解答。

  • by dreyfus92
  • JavaScript
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 dreyfus92/astro-docs-mcp

使用说明

Astro Docs MCP服务器

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

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

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

特性

资源

  • 通过以下方式列出和访问Astro文档 astro-docs:// URI
  • 每个文档部分都有一个标题、内容和类别
  • 纯文本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检查员，可作为包脚本使用：

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. 重新启动克劳德桌面。

  4. 现在，您可以使用以下命令与Astro文档进行交互：

    • list -列出可用的Astro文档部分
    • search <query> -搜索Astro文档
    • read astro-docs:///<id> -阅读特定的文档部分

未来的增强功能

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

相关 MCP