Misterboe Strapi MCP Server

🚀 Strapi MCP 服務器

Strapi 的 MCP（模型上下文協議）服務器為 AI 助手提供了一個標準化接口，使其能夠與 Strapi 實例進行交互。該服務器支持多種內容類型和 REST API 操作，極大地提升了內容管理和媒體處理的效率。

🚀 快速開始

Strapi MCP 服務器允許 AI 助手通過標準化接口與 Strapi 實例交互，支持內容類型和 REST API 操作。你可以按照以下步驟快速開始使用。

📦 安裝指南

使用 npx 安裝

在 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 結構和數據格式，具有良好的兼容性。

版本差異（v4 vs v5）

v4

• 使用數字 ID。
• 屬性結構嵌套。
• 響應數據包含在 data 包裹器中。
• 採用傳統的 REST 模式。
• 需要外部 i18n 插件。

v5

• 使用文檔 ID。
• 數據結構扁平化，便於直接訪問屬性。
• 強化了 JWT 安全。
• 集成了 i18n 支持。
• 擁有新的文檔服務 API。

安全特性

寫保護策略

服務器實施嚴格的寫入保護：

• 所有寫入操作（POST、PUT、DELETE）均需明確授權。
• 受保護的操作包括創建（POST）、更新（PUT）、刪除（DELETE）和媒體上傳。
• 每次操作均會記錄日誌並進行驗證，確保數據安全。

💻 使用示例

基礎用法

查詢內容

// 獲取單個文章
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"
  }
});

📚 詳細文檔

最佳實踐

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