Strapi MCP服务器

一个用于与Strapi CMS交互的模型上下文协议服务器,支持AI助手通过标准化接口与Strapi实例进行交互,包括内容类型管理和REST API操作。

  • by misterboe
  • TypeScript
  • 本地部署
  • 75 星标
  • 更新于
在 GitHub 查看 misterboe/strapi-mcp-server

使用说明

Strapi MCP服务器

用于与Strapi CMS交互的模型上下文协议服务器。该服务器使人工智能助手能够通过标准化界面与Strapi实例交互,支持内容类型和REST API操作。

⚠️ 重要免责声明:该软件是在人工智能技术的帮助下开发的。它按原样提供,未经彻底测试和验证,不得在生产环境中使用。代码可能包含错误、安全漏洞或意外行为。仅用于研究、学习或开发目的,风险自负。

更新日志

版本2.6.0-增强的验证和调试更新

  • 🔧 使用McpError和ErrorCode实现了结构化错误处理
  • ✅ 为运行时类型安全添加了全面的Zod验证
  • 📊 具有请求跟踪功能的集成综合日志记录系统
  • 🐛 添加了带有环境变量的调试模式配置
  • 🧹 删除了未使用的提示处理程序,以实现更清晰的代码库
  • ⬆️ 将所有依赖项更新为最新版本
  • 📖 为开发工作流程添加了DEBUGG.md指南
  • 🛡️ 通过更好的输入验证增强安全性
  • 🚀 通过详细的错误消息改善开发人员体验

有关完整的版本历史记录,请参阅 更改日志.md.

特性

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

安装

您可以在Claude Desktop配置中直接将此服务器与npx一起使用:

{
  "mcpServers": {
    "strapi": {
      "command": "npx",
      "args": ["-y", "@bschauer/strapi-mcp-server@2.6.0"]
    }
  }
}

配置

在以下位置创建配置文件 ~/.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插件

版本5

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

安全功能

写保护策略

服务器实施了严格的写保护策略:

  • 所有写入操作都需要明确授权
  • 受保护的操作包括:
    • POST(创建)
    • PUT(更新)
    • 删除
    • 媒体上传
  • 每个操作都会被记录和验证

最佳实践

  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. 写保护错误

    • 确保操作获得授权
    • 检查操作是否受到保护
    • 验证请求是否符合安全策略

贡献

欢迎投稿!请随时提交拉取请求。

许可证

麻省理工学院