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这将向服务器发送几个命令并显示响应。
故障排除
如果您遇到服务器问题：
- 路径问题：最常见的问题是配置中的路径不正确。确保：
- 您正在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"
}
]
}- 重新启动克劳德桌面。
- 现在，您可以使用以下命令与Astro文档进行交互：
- list -列出可用的Astro文档部分 - search -搜索Astro文档 - read astro-docs:/// -阅读特定的文档部分
未来的增强功能
- 从Astro网站获取实时文档
- 添加更全面的文档部分
- 实施文档版本控制支持
- 为常见的Astro模式添加代码示例和片段