Strapi MCP 服务器

简介

Strapi 的 MCP（模型上下文协议）服务器允许 AI 助手通过标准化接口与 Strapi 实例交互，支持内容类型和 REST API 操作。以下是项目的完整中文翻译：

安装指南

在 Claude Desktop 配置中直接使用 npx 运行以下命令安装服务器：

npx strapi-mcp-server

创建配置文件

创建或编辑配置文件 ~/.mcp/strapi-mcp-server.config.json，添加以下内容：

{
  "apiUrl": "http://localhost:1337", // Strapi 实例的 URL，默认为 http://localhost:1337
  "version": "v5",                 // 支持的 Strapi 版本，可选值：v4, v5
  "jwtToken": "your_jwt_token"     // Strapi 的 JWT 认证令牌
}

功能概述

核心功能

1. 内容查询：

   • 获取单个或多个内容条目。
   • 支持过滤、排序和分页。

2. 媒体上传：

   • 上传图片或其他文件。
   • 自动进行格式转换和优化（如 WebP）。
   • 支持自定义元数据。

3. 版本支持：

   • 支持 Strapi v4 和 v5 的不同 API 结构和数据格式。

示例用法

查询内容

// 获取单个文章
strapi_get_content({
  server: "default",
  endpoint: "articles",
  id: "123"
});

// 获取多篇文章并分页
strapi_get_content({
  server: "default",
  endpoint: "articles",
  params: {
    pagination: { page: 1, pageSize: 25 },
    sort: ["createdAt:desc"]
  }
});

媒体上传

// 上传并优化图片
strapi_upload_media({
  server: "default",
  url: "https://example.com/image.jpg",
  format: "webp",
  quality: 80,
  metadata: {
    name: "My Image",
    caption: "Image Caption",
    alternativeText: "Alt Text"
  }
});

版本差异（v4 vs v5）

v4

• 使用数字 ID。
• 属性结构嵌套。
• 响应数据包含在 data 包裹器中。
• 传统的 REST 模式。
• 外部 i18n 插件。

v5

• 使用文档 ID。
• 数据结构扁平化。
• 直接访问属性。
• 强化的 JWT 安全。
• 集成的 i18n 支持。
• 新的文档服务 API。

安全特性

写保护策略

服务器实施严格的写入保护：

• 所有写入操作（POST、PUT、DELETE）均需明确授权。
• 受保护的操作包括：
  • 创建（POST）
  • 更新（PUT）
  • 删除（DELETE）
  • 媒体上传
• 每次操作均记录日志并进行验证。

最佳实践

1. 检查内容类型：使用 strapi_get_content_types 确认字段和结构。
2. 正确使用 URL 格式：区分复数和单数形式的端点。
3. 包含错误处理机制：在每次请求中添加异常捕获。
4. 设置适当权限：根据角色和权限控制 API 访问。

故障排除

常见问题

1. 401 未认证错误：

   • 检查 JWT 令牌是否正确配置。
   • 确保令牌在 Strapi 实例中启用。

2. 404 资源未找到：

   • 核对端点名称和 ID 是否正确。
   • 确认 Strapi 实例的 API 端点已正确设置。

3. 数据格式错误：

   • 检查请求参数是否与目标版本（v4 或 v5）匹配。
   • 确保传递的数据结构符合要求。

贡献指南

欢迎社区贡献！请通过提交 Pull Request 的方式改进项目。

• 提交问题：GitHub Issues
• 提交功能或修复：Pull Request

通过以上文档，开发者可以快速上手并高效地使用 Strapi MCP 服务器进行内容管理和媒体处理。