Amplify 数据 API MCP 服务器

这个 MCP（模型上下文协议）服务器让你能够通过自然语言与你的 AWS Amplify Gen2 应用程序的数据进行交互。它允许像 Claude 这样的 AI 助手使用对话语言而不是复杂的代码或命令来对你的 Amplify 数据模型执行操作。

特性

• 💬 自然语言接口：用简单的英语提问和发出指令
• 🔍 查看模式信息：列出模型，查看字段详情，探索关系
• 📊 查询数据：运行自定义的 GraphQL 查询以列出和检索你的数据
• ✏️ 修改数据：通过 GraphQL 变更创建、更新和删除记录
• 🔐 安全认证：使用环境变量的 Cognito 认证

重要的认证要求

此 MCP 服务器使用 Cognito 认证来访问你的 Amplify 数据。你的 Amplify 项目必须配置为使用基于 Cognito 的认证。 服务器只能访问经过认证用户有权限访问的数据模型和记录。

为了获得最佳功能，我们强烈建议：

1. 在你的 Cognito 用户池中创建一个 ADMINS 用户组
2. 将合适的用户添加到该组
3. 配置你的 Amplify 模型，赋予 ADMINS 组执行所有操作的权限

管理员访问权限的示例模型授权：

// In your Amplify model definition
authorization: (allow) => [
  allow.authenticated().to(["read"]),
  allow.group("ADMINS").to(["create", "read", "update", "delete"]),
];

没有适当的管理员权限，MCP 服务器在处理你的数据时将会受到限制。

设置说明

前提条件

• Node.js v16 或更高版本
• 一个带有数据模型的 AWS Amplify Gen2 应用
• 对你的 Amplify 输出文件 (amplify_outputs.json) 的访问权限
• 在你的 Amplify 应用中配置了 Cognito 认证
• 一个具有适当权限的用户（理想情况下属于 ADMINS 组）

安装

1. 克隆仓库：

   git clone https://github.com/dbsmith7491/aws-amplify-data-mcp.git
   cd aws-amplify-data-mcp
   

2. 安装依赖：

   npm install
   

3. 构建项目：

   npm run build
   

配置 Claude Desktop

要与 Claude Desktop 一起使用：

1. 打开 Claude 桌面配置文件：

   • Mac/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %AppData%\Claude\claude_desktop_config.json

   如果文件不存在，请创建该文件。

2. 添加 Amplify MCP 服务器配置：

   {
     "mcpServers": {
       "amplify-data-api": {
         "command": "node",
         "args": [
           "/ABSOLUTE/PATH/TO/aws-amplify-data-mcp/build/index.js",
           "--amplify-outputs",
           "/ABSOLUTE/PATH/TO/YOUR/amplify_outputs.json"
         ],
         "env": {
           "AMPLIFY_USERNAME": "your-admin-username",
           "AMPLIFY_PASSWORD": "your-admin-password"
         }
       }
     }
   }
   

   将路径和凭证替换为您自己的。为了获得完整的功能，请使用 ADMINS 组中的用户的凭证。

3. 重启 Claude Desktop

使用自然语言与您的数据交互

配置完成后，您可以在 Claude 中使用日常语言与您的 Amplify 数据进行交互。只需在消息开头包含 @amplify-data-api 标签，即可将问题定向到 Amplify 服务器。

自然语言示例

以下是一些您可以如何与数据交互的示例：

• "@amplify-data-api 我的应用程序中有哪些数据模型？"
• "@amplify-data-api 显示 Story 模型有哪些字段"
• "@amplify-data-api 可以列出我数据库中的所有故事吗？"
• "@amplify-data-api 查找标题中包含 'adventure' 的故事"
• "@amplify-data-api 创建一个名为 'Claude' 的新角色，他是一个 AI 助手"
• "@amplify-data-api 更新 ID 为 'abc123' 的故事，将其标题更改为 'The Journey Begins'"
• "@amplify-data-api 删除 ID 为 'xyz789' 的故事"
• "@amplify-data-api Character 和 Story 之间的关系是什么？"
• "@amplify-data-api 显示故事 'abc123' 中的所有角色"
• "@amplify-data-api 在过去的一个月中创建了多少个故事？"

Claude 会解释这些自然语言请求，并将其转换为适当的 GraphQL 查询和变更。

可用工具

服务器提供以下工具：

1. 列出所有数据模型：

   • 列出您的 Amplify 应用程序中所有可用的数据模型

2. 获取模型详细信息：

   • 显示特定模型的字段和关系的详细信息

3. 运行 GraphQL 查询和变更：

   • 执行自定义的 GraphQL 查询和变更，以实现最大的灵活性
   • 处理所有数据操作（列表、获取、创建、更新、删除）

4. 获取关系详细信息：

   • 显示模型之间的关系，适用于复杂的数据结构

5. 列出枚举：

   • 显示您的数据模型中所有可用的枚举类型

6. 手动登录（如果需要）：

   • 如果自动身份验证失败，则手动进行身份验证

示例对话

以下是一个典型的与 Claude 对话的流程：

你: @amplify-data-api 我有哪些可用的数据模型？

Claude: 我会检查你的 Amplify 应用程序以查找可用的数据模型。

我找到了以下模型：

• Story
• Character
• Location
• World
  [每个模型的更多详细信息...]

你: @amplify-data-api 请告诉我关于 Story 模型的信息

Claude: 这是 Story 模型的详细信息：

字段：

• id: ID (必填)
• title: String (必填)
• description: String
• numberOfPages: Int
  [其他字段...]

你: @amplify-data-api 你能创建一个名为 "Claude's Adventure" 的新故事吗？这个故事讲述了一个 AI 探索魔法世界的故事。

Claude: 我将使用 GraphQL 变更来为你创建这个故事。这是我要提交的内容：

mutation CreateStory {
  createStory(
    input: {
      title: "Claude's Adventure"
      description: "A tale about an AI exploring a magical world"
      status: "draft"
    }
  ) {
    id
    title
    description
    status
    createdAt
    updatedAt
  }
}

你: 好的，请创建它

Claude: 我已经创建了这个故事！这是新的记录：

{
  "id": "abc123",
  "title": "Claude's Adventure",
  "description": "A tale about an AI exploring a magical world",
  "status": "draft",
  "createdAt": "2023-06-15T10:30:45Z",
  "updatedAt": "2023-06-15T10:30:45Z"
}

你: @amplify-data-api 现在让我们给这个故事添加一个角色

Claude: [自然地继续互动...]

安全考虑

• 环境变量中的凭证：使用环境变量以更好地保护凭证安全
• 权限：使用适当的 Cognito 组来控制访问（ADMINS 组具有完全访问权限）
• 数据敏感性：注意通过 AI 助手访问的数据
• 访问控制：MCP 服务器只能访问经过身份验证的用户有权限访问的数据
• 用户角色：为了获得完整功能，请使用具有管理员权限的用户的凭证

故障排除

• 认证问题：验证你的 Cognito 凭证和用户池设置
• 缺少模型：确保你的 amplify_outputs.json 文件是最新的
• 连接问题：查看 Claude Desktop 日志中的错误
• 权限错误：验证你的用户在 Cognito 中具有适当的权限
• 有限的访问权限：如果你无法看到某些模型或记录，请检查你的用户是否有权限访问它们

开发者指南

• TypeScript 源代码位于 src/ 目录中
• 编译后的 JavaScript 输出到 build/ 目录
• 在任何源代码更改后运行 npm run build

作为 ZIP 文件分发

如果你收到的是 ZIP 文件形式的项目，请按照以下步骤操作以使其正常工作：

1. 解压ZIP文件到您计算机上的一个目录
2. 打开终端并导航到解压后的目录
3. 安装依赖项：

   npm install
   

4. 构建项目：

   npm run build
   

5. 按照上面“Claude Desktop配置”部分所示，使用正确的路径和环境变量配置Claude Desktop
6. 重启Claude Desktop以应用更改

如果您想将此项目分发给其他人：

1. 确保所有更改都已提交
2. 包含所有必要的文件：
   • 包含所有TypeScript源文件的src/目录
   • package.json及其他配置文件
   • 本README.md文件
   • （可选）如果您已经构建了项目，则包括build/目录
3. 创建整个目录的ZIP文件
4. 分享ZIP文件并附上上述步骤的操作指南

命令行选项

Options:
  --amplify-outputs <path>   Path to the amplify_outputs.json file
  --help, -h                 Show this help message

Environment Variables:
  AMPLIFY_USERNAME           Cognito username for automatic login
  AMPLIFY_PASSWORD           Cognito password for automatic login

额外资源

• Amplify Gen2 文档
• Amplify 身份验证文档
• 模型上下文协议文档
• Claude Desktop 文档

---

需要更多帮助？请联系您的开发团队获取支持。