MCP 服务器

Astro Docs MCP Server

一个 MCP 服务器，为 AI 助手提供访问 Astro 文档的权限，使其能够在帮助用户处理与 Astro 相关的任务时搜索和参考 Astro 文档。

README

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 直接
./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

Inspector 将提供一个 URL，用于访问浏览器中的调试工具。

测试

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

pnpm test
# OR 直接
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"
    }
  ]
}