Astro 文档 MCP 服务器

这是一个为 AI代理提供访问 Astro 文档的 MCP 服务器。该服务器允许 AI 助手查找并参考 Astro 相关文档，以帮助用户完成与 Astro 相关的任务。

此基于 TypeScript 的 MCP 服务器实现了一个用于检索 Astro 文档的系统。它通过以下方式演示了核心 MCP 概念：

• 使用 astro-docs:// URI 和元数据表示 Astro 文档部分
• 提供搜索 Astro 文档的工具
• 提供常见 Astro 问题和任务的提示

特性

资源

• 列出并访问 Astro 文档中的各个部分
• 每个文档部分都有标题、内容和类别
• 使用纯文本 MIME 类型提供简单的内容访问

工具

• search_docs - 搜索 Astro 文档
  • 接受搜索查询作为必填参数
  • 返回匹配的文档部分

提示语

• explain_astro_islands - 获取 Astro 岛屿架构的详细解释
• astro_project_setup - 新建 Astro 项目的指南
• astro_vs_other_frameworks - 比较 Astro 和其他 Web 框架

项目结构

• src/ - 服务器源代码
  • index.ts - 主 MCP 服务器实现
  • scripts/ - 辅助构建和测试的脚本
    • build.js - 构建脚本，用于转译 TypeScript 并生成启动脚本
    • test-client.js - 测试客户端，用于验证服务器功能
• bin/ - 生成的可执行脚本
  • astro-docs-mcp - 主启动脚本
• build/ - 编译后的 JavaScript 文件（自动生成）

配置要求

• 需要 Node.js v16 或更高版本
• 推荐使用 Node.js v20+ 以获得最佳兼容性
• 服务器使用 ES 模块语法
• 配置文件示例：config.json

安装与配置

安装步骤

1. 克隆此仓库到本地：

   git clone https://github.com/yourusername/astro-docs-mcp.git
   cd astro-docs-mcp
   

2. 安装依赖项：

   pnpm install
   

3. 启动服务器：

   npm start
   

配置示例

{
  "mcp_server": {
    "port": 3000,
    "documentation_path": "./docs",
    "logging": {
      "level": "info",
      "enabled": true
    }
  }
}

使用说明

基本命令

1. 列出可用文档部分：

   npm run list
   

2. 搜索文档内容：

   npm run search <查询>
   

3. 查看特定文档：

   npm run read astro-docs:///<id>
   

故障排除

1. 端口冲突：如果默认端口 3000 被占用，尝试在其他端口运行：

   npm start -- --port=3001
   

2. 依赖问题：确保所有依赖项已正确安装：

   pnpm install
   

3. 日志输出：检查 config.json 中的日志设置是否启用：

   "logging": {
     "level": "debug",
     "enabled": true
   }
   

未来改进

• 实现从 Astro 官网实时获取文档
• 增加更多详细的文档部分
• 支持文档版本控制
• 添加常见 Astro 模式的代码示例和片段