天文文档MCP服务器

Name: 天文文档MCP服务器
Author: dreyfus92

作者：dreyfus923 星标更新：2025-07-23

安装使用来源：spider==github.com

项目介绍

Astro 文档 MCP 服务器

用于提供 Astro 文档访问给AI代理的MCP服务器。此服务器允许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
# 或直接运行
./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 文档",
      "command": "/full/absolute/path/to/astro-mcp/bin/astro-docs-mcp",
      "type": "内置"
    }
  ]
}

将/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

Inspector将提供一个URL，以便在浏览器中访问调试工具。

测试

提供了一个测试客户端来验证服务器是否正常工作：

pnpm test
# 或直接运行
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 文档",
      "command": "/full/absolute/path/to/astro-mcp/bin/astro-docs-mcp",
      "type": "内置"
    }
  ]
}

重启Claude Desktop。
现在你可以使用以下命令与Astro文档交互：
- list - 列出可用的Astro文档部分
- search <query> - 搜索Astro文档
- read astro-docs:///<id> - 阅读特定的文档部分

未来增强

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