Strapi MCP Server

Strapi MCP 服务

一个用于与 Strapi CMS 交互的模型上下文协议服务。此服务可让 AI 助手通过标准化接口与您的 Strapi 实例交互，并支持内容类型和 REST API 操作。

⚠️ 重要免责声明：此软件是在 AI 技术的辅助下开发的。本软件按原样提供，未经全面测试和验证，请勿用于生产环境。代码可能包含错误、安全漏洞或意外行为。仅可自行承担风险，将其用于研究、学习或开发。

更新日志

版本 2.6.0 - 验证与调试功能增强更新

• 🔧 使用 McpError 和 ErrorCode 实现结构化错误处理
• ✅ 添加全面的 Zod 验证，确保运行时类型安全
• 📊 集成全面的日志系统，支持请求跟踪
• 🐛 添加基于环境变量的调试模式配置
• 🧹 移除未使用的提示词处理程序，使代码库更简洁
• ⬆️ 将所有依赖项更新至最新版本
• 📖 添加 DEBUGGING.md 指南，介绍开发工作流
• 🛡️ 改进输入验证，增强安全性
• 🚀 提供详细的错误消息，改善开发者体验

完整的版本历史记录请参阅 CHANGELOG.md。

功能

• 🔍 架构内省
• 🔄 支持带验证的 REST API
• 📸 媒体上传处理
• 🔐 JWT 身份验证
• 📝 内容类型管理
• 🖼️ 图像处理与格式转换
• 🌐 支持多个服务
• ✅ 自动架构验证
• 🔒 写入保护策略
• 📚 集成文档
• 🔄 版本兼容性管理

安装

您可以在 Claude Desktop 配置中直接通过 npx 使用此服务：

{
  "mcpServers": {
    "strapi": {
      "command": "npx",
      "args": ["-y", "@bschauer/[email protected]"]
    }
  }
}

配置

在 ~/.mcp/strapi-mcp-server.config.json 创建配置文件：

{
  "myserver": {
    "api_url": "http://localhost:1337",
    "api_key": "your-jwt-token-from-strapi-admin",
    "version": "5.*" // Optional: Specify Strapi version (e.g., "5.*", "4.1.5", "v4")
  }
}

您可以将多个 Strapi 实例添加到此文件中进行配置。

版本配置

此服务现在支持多种版本格式：

• 通配符："5."、"4."
• 指定版本："4.1.5"、"5.0.0"
• 简写："v4"、"v5"

这有助于服务提供特定版本的指导，并妥善处理 API 差异。

获取 JWT 令牌

1. 登录 Strapi 管理面板
2. 创建具有适当权限的 API 令牌
3. 将令牌添加到配置文件中对应的服务名称下

使用

列出可用服务

strapi_list_servers();
// Now includes version information and differences between v4 and v5

内容类型

// Get all content types from a specific server
strapi_get_content_types({
  server: "myserver",
});

// Get components with pagination
strapi_get_components({
  server: "myserver",
  page: 1,
  pageSize: 25,
});

REST API

REST API 提供全面的 CRUD 操作，内置验证和特定版本的处理逻辑：

// Query content with filters
strapi_rest({
  server: "myserver",
  endpoint: "api/articles",
  method: "GET",
  params: {
    filters: {
      title: {
        $contains: "search term",
      },
    },
  },
});

// Create new content
strapi_rest({
  server: "myserver",
  endpoint: "api/articles",
  method: "POST",
  body: {
    data: {
      title: "New Article",
      content: "Article content",
      category: "news",
    },
  },
});

// Update content
strapi_rest({
  server: "myserver",
  endpoint: "api/articles/123",
  method: "PUT",
  body: {
    data: {
      title: "Updated Title",
      content: "Updated content",
    },
  },
});

// Delete content
strapi_rest({
  server: "myserver",
  endpoint: "api/articles/123",
  method: "DELETE",
});

媒体上传

// Upload image with automatic optimization
strapi_upload_media({
  server: "myserver",
  url: "https://example.com/image.jpg",
  format: "webp",
  quality: 80,
  metadata: {
    name: "My Image",
    caption: "Image Caption",
    alternativeText: "Alt Text",
  },
});

版本差异（v4 与 v5）

服务会自动处理 Strapi 不同版本间的主要差异：

v4

• 使用数字 ID
• 嵌套属性结构
• 响应中包含数据包装层
• 传统 REST 模式
• 外部 i18n 插件

v5

• 基于文档的 ID
• 扁平数据结构
• 可直接访问属性
• 增强的 JWT 安全性
• 集成 i18n 支持
• 新的文档服务 API

安全功能

写入保护策略

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

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

最佳实践

1. 始终先使用 strapi_get_content_types 检查架构
2. 为端点使用正确的复数或单数形式
3. 在查询中加入错误处理
4. 上传前验证 URL
5. 从最简查询开始，仅在需要时添加关联填充
6. 更新时始终包含完整的数据对象
7. 使用筛选条件优化查询性能
8. 利用内置的架构验证
9. 检查操作的版本兼容性
10. 遵循写入保护政策指南

REST API 提示

筛选

// Filter by field value
params: {
  filters: {
    title: "Exact Match";
  }
}

// Contains filter
params: {
  filters: {
    title: {
      $contains: "partial";
    }
  }
}

// Multiple conditions
params: {
  filters: {
    $and: [{ category: "news" }, { published: true }];
  }
}

排序

params: {
  sort: ["createdAt:desc"];
}

分页

params: {
  pagination: {
    page: 1,
    pageSize: 25
  }
}

关联填充

// Basic request without population
params: {
}

// Selective population when needed
params: {
  populate: ["category"];
}

// Detailed population with field selection
params: {
  populate: {
    category: {
      fields: ["name", "slug"];
    }
  }
}

故障排除

常见问题及解决方案：

1. 404 错误

   • 检查端点的复数或单数形式
   • 确认内容类型存在
   • 确保 API URL 正确
   • 检查是否使用了正确的 ID 格式（数字型还是基于文档的）

2. 身份验证问题

   • 确认 JWT 令牌有效
   • 检查令牌权限
   • 确保令牌尚未过期

3. 版本相关问题

   • 确认配置中的版本指定正确
   • 检查数据结构是否与版本匹配
   • 查阅版本差异文档

4. 写入保护错误

   • 确保操作已获授权
   • 检查操作是否受到保护
   • 确认请求符合安全政策

贡献

欢迎贡献！请随时提交 Pull Request。

许可证

MIT