AWS Amplify Documentation MCP Server

AWS Amplify 文档 MCP 服务

一种模型上下文协议（MCP）服务，可为 AWS Amplify 文档提供强大的搜索功能。此服务会克隆官方 AWS Amplify 文档仓库，并通过简单的 MCP 工具接口提供搜索功能。

功能

• 强大的搜索功能：使用自然语言查询搜索 AWS Amplify 文档
• 高级搜索语法：支持布尔运算符、通配符、字段专属搜索等
• 智能结果排序：根据搜索结果与查询的相关性智能排序
• 分页：支持分页浏览大量搜索结果
• 性能缓存：缓存搜索结果以提升性能
• 自动更新：自动从官方 AWS Amplify 仓库更新文档
• 代际选择：可选择 Gen 1、Gen 2 或两代文档集，以优化磁盘占用和搜索范围。
• TypeScript 实现：使用 TypeScript 构建，以提供更好的类型安全性和开发体验

免责声明：这是一个个人项目，与 AWS Amplify 或 Amazon Web Services 无关，也未获得其认可，且并非由其官方提供。此工具按原样提供，不作任何保证或担保。

安装

1. 克隆此仓库：

git clone https://github.com/ykethan/amplify-doc-mcp.git
cd amplify-doc-mcp

1. 安装依赖项：

npm install

1. 构建 TypeScript 代码：

npm run build

配置

此服务使用 docs-mcp.config.json 文件进行配置：

{
  "gitUrl": "https://github.com/aws-amplify/docs.git",
  "gitRef": "main",
  "autoUpdateInterval": 60,
  "toolName": "search_amplify_docs",
  "toolDescription": "Search AWS Amplify documentation using the probe search engine.",
  "ignorePatterns": [
    "node_modules",
    ".git",
    "dist",
    "build",
    "coverage",
    ".vitepress/cache",
    "*.jpg",
    "*.jpeg",
    "*.png",
    "*.gif",
    "*.svg",
    "*.mp4",
    "*.webm"
  ],
  "amplifyGeneration": "gen2"
}

配置选项

选项	说明	默认值
gitUrl	要克隆的文档 Git 仓库 URL	"https://github.com/aws-amplify/docs.git"
gitRef	要检出的 Git 分支或标签	"main"
autoUpdateInterval	检查更新的间隔（分钟；设为 0 可禁用）	60
dataDir	存储文档数据的目录	"./data"
toolName	搜索工具的名称	"search_amplify_docs"
toolDescription	搜索工具的说明	"Search AWS Amplify documentation using the probe search engine."
ignorePatterns	搜索时要忽略的模式数组	["node_modules", ".git", ...]
amplifyGeneration	要包含的 Amplify 文档代际	"gen2"

自动更新机制

此服务包含自动更新机制，可确保文档保持最新：

1. 服务启动时，会克隆 gitUrl 指定的文档仓库。
2. 如果 autoUpdateInterval 设置为大于 0 的值，服务将定期检查更新。
3. 每隔 autoUpdateInterval 分钟，服务将：
   • 从远程仓库获取最新更改
   • 检查本地分支是否落后于远程分支
   • 如果有可用更新，则自动拉取更改
   • 如果无需更新，则继续使用当前文档

这样无需重启服务，也能确保文档搜索结果始终包含最新信息。

用法

启动服务

npm start

或者使用提供的启动脚本并指定选项：

./start-server.sh [--gen <1|2|both>] [--rebuild]

选项

• --gen 1：仅包含 Gen 1 文档（减少磁盘空间占用）
• --gen 2：仅包含 Gen 2 文档（默认，减少磁盘空间占用）
• --gen both：同时包含 Gen 1 和 Gen 2 文档
• --rebuild：强制重建数据目录

示例

# Start with Gen 2 documentation (default)
./start-server.sh

# Start with only Gen 1 documentation
./start-server.sh --gen 1

# Start with both Gen 1 and Gen 2 documentation
./start-server.sh --gen both

# Start with only Gen 2 documentation and force rebuild
./start-server.sh --gen 2 --rebuild

重要提示：在不同生成版本之间切换（例如，从 Gen 1 切换到 Gen 2，反之亦然）时，建议使用 --rebuild 标志，以确保仓库干净。此操作会删除数据目录并重新克隆仓库，确保根据所选生成版本包含正确的文件。

例如：

# 通过干净重建从 Gen 2 切换到 Gen 1
./start-server.sh --gen 1 --rebuild

# 通过干净重建从 Gen 1 切换到 Gen 2
./start-server.sh --gen 2 --rebuild

MCP 工具：search_amplify_docs

该服务提供一个名为 search_amplify_docs 的工具，可用于搜索 Amplify 文档。

参数

参数	类型	必填	默认值	描述
query	string	是	-	Elasticsearch 查询字符串
page	number	否	1	分页页码
includeContent	boolean	否	false	在结果中包含内容片段
maxResults	number	否	10	返回结果的最大数量
filesOnly	boolean	否	false	仅返回文件路径，不包含内容
useJson	boolean	否	false	以 JSON 格式返回结果
sessionId	string	否	-	关联搜索的会话 ID
fullContent	boolean	否	false	获取特定文件的完整内容
filePath	string	否	-	要获取完整内容的特定文件路径

请求示例

{
  "query": "authentication react",
  "page": 1,
  "includeContent": true,
  "maxResults": 15
}

高级搜索语法

搜索工具支持高级搜索语法：

• 精确短语："authentication flow"
• 排除词语：authentication -flutter
• 指定字段搜索：title:authentication
• 通配符：auth*
• 布尔运算符：authentication AND (react OR javascript) NOT flutter

查询流程的工作原理

提交搜索查询后，服务会通过以下几个步骤进行处理：

1. 查询处理：服务会解析查询，以识别布尔运算符和通配符等高级语法。

2. 目录优化：服务会利用目录结构，根据查询词语和所选的 Amplify 生成版本（Gen 1、Gen 2 或两者）缩小搜索文件范围。

3. 智能排序：系统使用复杂算法对结果排序，并综合考虑以下因素：

   • 查询是否提及特定生成版本（Gen 1 或 Gen 2）
   • 查询是否涉及设置、CLI 命令或资源创建
   • 文档与查询上下文的相关性
   • 文档标题中的精确匹配
   • 匹配数量和文档重要性

4. 内容提取：系统会从每个匹配文件中提取相关内容，并将其格式化以供查看。

5. 缓存：搜索结果会被缓存，以提高重复查询的性能。

这种智能处理可确保最相关的文档显示在搜索结果顶部，为你节省时间和精力。

生成版本选择

该服务支持三种 Amplify 文档生成版本模式：

1. 仅 Gen 2（默认）

"amplifyGeneration": "gen2"

• 优点：专注于现代 Amplify 实现，减少磁盘空间占用
• 推荐用于：使用 Amplify Gen 2 功能的新项目
• 默认设置：Gen 2 是 Amplify 的当前版本，因此这是默认设置

2. 仅 Gen 1

"amplifyGeneration": "gen1"

• 优点：专注于经典 Amplify 实现，减少磁盘空间占用
• 推荐用于：专门使用 Amplify Gen 1 功能的旧项目

3. 两个生成版本

"amplifyGeneration": "both"

• 优点：涵盖完整文档
• 缺点：搜索范围更大；由于 Gen 1 和 Gen 2 的类别相似，可能会造成混淆
• 适用场景：需要同时参考两个生成版本时

项目结构

• src/index.ts：服务器主实现
• src/config.ts：配置加载与处理
• src/git.ts：Git 仓库管理
• src/cache.ts：搜索结果缓存
• src/directory.ts：目录结构管理
• src/types/：TypeScript 类型定义
• scripts/build.js：用于准备文档的构建脚本
• bin/mcp：用于运行服务器的可执行脚本

使用建议

1. 针对你的环境进行优化：

   • 为获得最佳搜索结果，请仅将 "amplifyGeneration" 设置为 "gen1" 或 "gen2"

2. 搜索优化：

   • 使用具体的技术术语，而不是宽泛的短语
   • 加入类别名称以缩小结果范围（例如，使用“storage owner access”而不是仅使用“access”）
   • 使用引号进行精确短语匹配
   • 加入缩写和替代术语以改善结果

3. 性能注意事项：

   • 根据需求设置合适的 autoUpdateInterval（值越大，服务器负载越低）
   • 对频繁访问的查询使用缓存系统
   • 考虑在初始的广泛搜索中使用 filesOnly: true 以提升性能

贡献与反馈

我们欢迎你为改进此 MCP 服务贡献代码并提供反馈。你可以就以下方面提出建议：

• 改进搜索查询结果
• 增强排名算法
• 添加新功能或参数
• 优化性能

请在 GitHub 上提交 issue 或 pull request。你的反馈有助于让此工具更好地服务所有人。过程中也能学到新知识。

系统要求

• Node.js 18.x 或更高版本（已使用 Node.js 20.18.2 测试）
• npm 8.x 或更高版本（已使用 npm 10.8.2 测试）

许可证

本项目采用 MIT 许可证。