Strapi MCP Server

Strapi MCP サーバー

Strapi CMS と連携するための Model Context Protocol サーバーです。このサーバーを通じて、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 サポートを統合
• 新しい Document Service API

セキュリティ機能

書き込み保護ポリシー

このサーバーは、厳格な書き込み保護ポリシーを実装しています。

• すべての書き込み操作には、明示的な認可が必要です
• 保護される操作は次のとおりです。
  • POST（作成）
  • PUT（更新）
  • DELETE
  • メディアのアップロード
• 各操作はログに記録され、検証されます

ベストプラクティス

1. strapi_get_content_types で最初に必ずスキーマを確認してください
2. エンドポイントには適切な複数形・単数形を使用してください
3. クエリにはエラーハンドリングを含めてください
4. アップロードの前に URL を検証してください
5. 最小限のクエリから始め、必要に応じて populate を追加してください
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
  }
}

populate

// 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