Amplify Docs MCP Server

AWS Amplify Gen 2文档MCP服务器

MCP（模型上下文提供程序）服务器，提供对AWS Amplify Gen 2 Next.js文档的全面访问，使AI助手能够为使用Amplify构建应用程序提供准确、最新的指导。

主要特点

• 准确的类别搜索：所有10个文档类别都是可搜索的（api数据、身份验证、后端、部署、前端、通用、入门、参考、存储、故障排除）
• 增强型Amplify数据搜索：Amplify主要数据解决方案的专业搜索优化（defineData、a.model、实时订阅）
• 正确的图案匹配：API模式返回REST/HTTP API内容，而Data模式返回Amplify Data内容
• CRUD表单生成：Amplify自动表单生成功能的完整文档
• 清晰的架构理解：区分核心服务（身份验证、数据、存储）和其他AWS服务
• 有用的错误消息：无效类别显示可用选项，而不是通用错误

MCP Python SDK文档\ 此服务器基于以下MCP Python SDK文档构建：https://github.com/modelcontextprotocol/python-sdk

特性

• 文件报废：自动抓取和索引AWS Amplify Gen 2文档
• 智能搜索：按查询和类别搜索索引文档
• 模式发现：查找auth、API、存储等的常见模式和示例
• 类别式组织：文档会自动分类（入门、后端、前端、部署等）
• SQLite存储：具有全文搜索功能的高效本地存储
• Markdown转换：HTML文档转换为干净的markdown格式

安装

先决条件

• Python 3.12或更高版本
• uv（Python包管理器）： curl -LsSf https://astral.sh/uv/install.sh | sh
• 已安装克劳德桌面和/或克劳德代码

版本兼容性

AWS Amplify Gen 2与以下设备兼容：

• Next.js：14.x或15.x（应用路由器和页面路由器）
• TypeScript：5.0或更高（可选，但推荐）
• Node.js：18.x或更高

使用 uv run python amplify_cli.py check-versions 以验证兼容性。

开始使用兼容版本

⚠️ 重要：手动安装软件包通常会导致版本冲突！

对于具有保证兼容版本的新项目：

1. 使用Amplify的Next.js启动模板 （强烈推荐）：

   npx create-amplify@latest --template nextjs

或者等效地：

   npm create amplify@latest --template nextjs

这将创建一个完整的Next.js项目，其中预先配置了所有兼容版本。

1. 为什么手动安装有问题:

- 跑步 npm create amplify@latest 随后 npm install next react react-dom 经常导致依赖冲突 - Amplify软件包具有特定的对等依赖要求 - 版本不匹配可能导致ERESOLVE警告和运行时问题

1. 如果你必须使用现有的Next.js项目:

- 确保Next.js是14.x或15.x版本 - 跑 npm create amplify@latest - 安装与您的Amplify软件包完全匹配的版本 - 准备好解决依赖冲突

1. 验证兼容性:

   uv run python amplify_cli.py check-versions

快速安装

# Clone the repository
git clone https://github.com/your-username/amplify-gen-2-nextjs-docs.git
cd amplify-gen-2-nextjs-docs

# Install all dependencies automatically (like npm install)
uv sync

# Initialize the documentation database
uv run python amplify_docs_server.py
# Press Ctrl+C after it starts successfully

备注: uv sync 自动安装来自的所有依赖项 pyproject.toml -无需手动安装软件包！

配置

适用于克劳德桌面

1. 打开您的Claude Desktop配置文件：

- macOS： ~/Library/Application Support/Claude/claude_desktop_config.json - 窗户： %APPDATA%\Claude\claude_desktop_config.json - Linux： ~/.config/claude/claude_desktop_config.json

1. 添加服务器配置：

   {
     "mcpServers": {
       "amplify-docs": {
         "command": "uv",
         "args": ["run", "python", "/full/path/to/amplify_docs_server.py"],
         "env": {}
       }
     }
   }

1. 重新启动克劳德桌面

克劳德代码

Claude Code会自动发现MCP服务器。只需确保服务器正在运行或在项目的MCP设置中对其进行配置。

可用工具

1.获取文档概述

通过摘要和快速导航全面了解所有文档。

参数：

• format （字符串，可选）：输出格式-“完整”或“摘要”（默认值：“摘要”）

例子：

Get documentation overview in summary format

2.搜索文档

搜索索引的Amplify文档。

参数：

• query （字符串，必填）：搜索查询（搜索标题和内容）
• category （字符串，可选）：按类别筛选
• limit （整数，可选）：最大结果数（默认值：10）

类别：

• api-data-数据层和api文档
• 身份验证-用户身份验证和授权
• 后端-后端配置和服务
• 部署-部署和托管
• 前端-前端组件和UI
• 概述-一般概念和概述
• 入门-快速入门指南
• 参考文件-API参考文件
• storage-文件存储和管理
• 故障排除-常见问题和解决方案

例子：

Search for "authentication" in category "backend"

3.获取文档

通过URL检索特定文档。

参数：

• url （string，必填）：文档的完整URL

例子：

Get document at https://docs.amplify.aws/nextjs/build-a-backend/auth/

4.列表类别

列出所有可用的文档类别。

例子：

List all categories

5.getStats

获取有关索引文档的统计信息。

例子：

Show documentation statistics

6.查找模式

查找常见的Amplify Gen 2模式和示例。

参数：

• pattern_type （string，必填）：要查找的模式类型

图案类型：

• auth-身份验证模式（Cognito集成）
• 数据-放大数据模式（定义数据、模型、实时）
• api-REST/HTTP api模式（api网关，自定义端点）
• 存储-文件操作（S3集成）
• 部署-CI/CD模式
• 配置-放大/后端.ts模式
• 数据库-高级DynamoDB模式
• 函数-Lambda函数
• ui-ui构建模式（CRUD表单、组件）
• ssr-服务器端渲染模式
• typescript-typescript优先模式
• 工作流-开发工作流

例子：

Find patterns for "auth"

7.getCreateCommand

获取用于创建新的Amplify Gen 2+Next.js应用程序的CORRECT命令。

例子：

Get the correct create command

8.获取快速入门模式

准备好将代码模式用于常见的Amplify任务。

参数：

• task （string，必填）：您要完成的任务

可用任务：

• 创建应用程序-创建新的Amplify+Next.js应用程序
• add auth-向您的应用程序添加身份验证
• add-api-添加带有数据模型的GraphQL api
• 添加存储-配置文件存储
• 文件上传-实现文件上传功能
• crud表单-从数据模型生成自动crud表单
• 用户配置文件-用户配置文件管理
• 实时数据-实时数据同步
• 部署应用程序-部署您的应用程序
• 自定义身份验证ui
• 数据关系.数据关系和查询

例子：

Get quick start pattern for "add-auth"

使用示例

初始设置

1. 首先，获取最新文档：

   Use the fetchLatestDocs tool to index Amplify documentation

1. 查看统计数据：

   Use getStats to see how many documents were indexed

搜索信息

Search for "cognito authentication" using searchDocs

查找代码示例

Use findPatterns with pattern_type "auth" to find authentication examples

获取特定文档

Use getDocument with url "https://docs.amplify.aws/nextjs/build-a-backend/data/"

运行服务器

单独模式

uv run python amplify_docs_server.py

使用Shell脚本

./run_server.sh

命令行界面（CLI）

该项目包括一个CLI工具(amplify_cli.py)用于在不运行MCP服务器的情况下与文档数据库直接交互。

自动更新提醒

当您运行以下任何命令时，CLI会自动检查您的文档是否已过时（超过30天） fetch。如果需要更新，系统将提示您进行更新。如果您拒绝，系统将至少等待24小时再再次询问。

CLI命令

获取文档

uv run python amplify_cli.py fetch [--force]

• --force：强制刷新现有文档

搜索文档

uv run python amplify_cli.py search "your query" [--category CATEGORY] [--limit N]

• --category：按类别筛选（后端、前端等）
• --limit：最大结果数（默认值：10）

列表类别

uv run python amplify_cli.py categories

显示统计信息

uv run python amplify_cli.py stats

查找模式

uv run python amplify_cli.py patterns TYPE

其中TYPE是以下之一：auth、api、存储、部署、配置、数据库、函数

CLI示例

# Fetch all available documentation
uv run python amplify_cli.py fetch

# Force refresh all documents
uv run python amplify_cli.py fetch --force

# Fetch with markdown export
uv run python amplify_cli.py fetch --save-markdown

# Search for authentication docs
uv run python amplify_cli.py search "cognito authentication" --category backend

# Get full document content
uv run python amplify_cli.py get-document "https://docs.amplify.aws/nextjs/..."

# Show database statistics
uv run python amplify_cli.py stats

# Find auth patterns
uv run python amplify_cli.py patterns auth

# List all categories
uv run python amplify_cli.py categories

# Export all documents to markdown files
uv run python amplify_cli.py export-markdown

# Check version compatibility
uv run python amplify_cli.py check-versions

数据库

服务器使用SQLite在本地存储文档。数据库文件 amplify_docs.db 在与服务器相同的目录中创建。

数据库模式

• 文件 表：

- url（唯一标识符） - 标题 - 内容（原始文本） - markdown内容 - 类别 - last_scrated - embedding_vector（保留供将来使用）

• scrape_元数据 表：

- 跟踪抓取会话和状态

发展

测试服务器

使用附带的测试脚本：

uv run python test_server.py

日志记录

服务器使用Python的日志模块。在代码中设置日志级别：

logging.basicConfig(level=logging.INFO)

更新跟踪

CLI跟踪文档更新 last_updated.json 文件（首次使用时自动创建）。此文件包含：

• last_updated：上次取文件的时间
• last_prompted：上次询问用户有关更新的时间
• user_declined：用户是否拒绝了上次更新提示

此文件是gitignored的，并且是每个安装的本地文件。

故障排除

版本冲突（ERESOLVE警告）

如果你在手动安装后看到关于对等依赖的npm警告：

• 解决方案：使用 npx create-amplify@latest --template nextjs 相反
• 这些警告表示软件包版本不兼容
• 之后手动安装React/Next.js npx create-amplify 经常引发冲突
• 两者 npm create 和 npx 命令是等效的

服务器无法启动

• 确保安装了所有依赖项： uv sync
• 检查Python版本： python --version （要求3.8+）
• 验证MCP客户端配置中的文件路径

未找到文档

• 跑 fetchLatestDocs 首先填充数据库
• 检查是否 amplify_docs.db 存在于项目目录中
• 在日志中查找错误消息

搜索不起作用

• 确保文档已编入索引（请与 getStats)
• 尝试更广泛的搜索词
• 检查类别筛选器

贡献

请随时提交问题或拉取请求以改进服务器。

许可证

该项目根据MIT许可证获得许可。