strapi-mcp-capabilities

Strapi MCP の機能

カスタムの MCP ツール／プロンプト／リソースを登録すると、AI クライアントから実行中の Strapi インスタンス上でプラグイン固有のアクションを呼び出せます。Strapi 5.47.0 以降。API の信頼できる情報源：@strapi/types で mcp を検索してください。

厳守事項

1. サーバーを有効にする：config/server.ts で mcp: { enabled: true } を設定する必要があります。エンドポイントは POST /mcp です。
2. register() フェーズでのみ登録する。 MCP サーバーの起動時（bootstrap 中）に機能の一覧がロックされます。それ以降に登録しようとすると例外が発生します。
3. @strapi/utils の Zod を使用する（import { z } from '@strapi/utils'）。単独の zod は使用しないでください。
4. モジュールのトップレベルでグローバルな strapi を使用しない。 インラインで登録する（strapi が使える状態にする）か、ai.mcp.defineTool(...) でモジュールスコープに定義してから、注入された strapi を使って登録してください。

2 つの登録パターン

インライン — strapi がスコープ内にある場合（register() から呼び出される関数内）：

// mcp/tools/get-store-kpis.ts
import type { Core } from '@strapi/strapi';
import { z } from '@strapi/utils';

export const registerGetStoreKpisTool = (strapi: Core.Strapi) => {
  strapi.ai.mcp.registerTool({ /* definition */ });
};

ビルダー — モジュールスコープで定義し（strapi は不要）、後から登録します。defineTool は型推論のためにアクセスバリアントを絞り込む恒等ヘルパーです。

// mcp/tools/get-top-products.ts
import { ai } from '@strapi/strapi';
import { z } from '@strapi/utils';

export const getTopProductsTool = ai.mcp.defineTool({ /* definition */ });

// register.ts
strapi.ai.mcp.registerTool(getTopProductsTool);

プラグインの register() から両方を接続します。

// register.ts
export const register = ({ strapi }: { strapi: Core.Strapi }) => {
  registerGetStoreKpisTool(strapi);          // inline
  strapi.ai.mcp.registerTool(getTopProductsTool); // builder
};

ツール定義（中核となる単位）

strapi.ai.mcp.registerTool({
  name: 'get_store_kpis',          // snake_case, unique
  title: 'Get Store KPIs',
  description: 'What it returns + when to use it. The AI reads this to choose the tool.',
  auth: { policies: [{ action: 'plugin::store-analytics.read' }] }, // OR devModeOnly: true
  resolveInputSchema: () => inputSchema,   // optional; omit if no args
  resolveOutputSchema: () => outputSchema, // required; a z.object
  createHandler: (strapi, context) => async ({ args, extra }) => {
    const result = await strapi
      .plugin('store-analytics')
      .service('analytics')
      .getStoreKpis(args);

    return {
      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
      structuredContent: result, // must match resolveOutputSchema
    };
  },
});

要点：

• createHandler(strapi, context) => handler。ハンドラーは { args, extra } という単一のオブジェクトを受け取ります。args は z.infer<inputSchema>（型付け済み）です。resolveInputSchema がない場合は、args を省略します。
• context: { userAbility, user } — エンティティ／フィールドの権限チェックには userAbility を使用し、書き込み時に setCreatorFields を設定するには user（トークンの所有者）を使用します。
• ハンドラーは薄く保ちます。プラグインの サービス に処理を委譲してください。ツールは MCP のインターフェースに徹します。
• name／title／description／resolveOutputSchema は必須です。description の品質は AI によるツール選択に影響するため、何を返すのか、いつ使うのかを明記してください。

スキーマ

• z.object の入力／出力スキーマを定義し、共有フィールドスキーマ（例：.describe(...) を使った isoDateSchema）を再利用します。
• 分かりにくいフィールドにはすべて .describe() を付けてください。説明は AI クライアントに伝わります。
• ハンドラーが返す structuredContent は resolveOutputSchema を満たす必要があります。

認証（アクセスバリアントを 1 つだけ選択）

• auth: { policies: [{ action, subject? }] } — CASL によるチェックです。トークンの権限がいずれかのポリシーを満たせば、セッションが許可されます。action は通常、登録済みの管理者権限です（例：plugin::<plugin-id>.<permission>）。
• devModeOnly: true — 認証はありません。autoReload が有効な場合（開発時）にのみ利用できます。デバッグツールに使用してください。

トークンに auth を付与できるようにするには、bootstrap() で権限アクションを登録します。

await strapi.service('admin::permission').actionProvider.registerMany([
  { section: 'plugins', displayName: 'Access store analytics',
    uid: 'read', pluginName: 'store-analytics' },
]);
// → action becomes 'plugin::store-analytics.read'

ハンドラーの戻り値の形式

// success
return { content: [{ type: 'text', text }], structuredContent: result };
// error
return { content: [{ type: 'text', text: 'message' }], isError: true };

structuredContent と isError は同時に指定できません。

フォルダーの規則

server/src/
├── register.ts            # calls registrations (register phase only)
├── bootstrap.ts           # registerMany permission actions
├── mcp/
│   ├── index.ts           # registerAllMcpTools(strapi)
│   ├── schemas.ts         # shared zod field schemas
│   └── tools/<tool>.ts    # one capability per file
└── services/              # business logic the handlers call

確認

1. config/server.ts で mcp: { enabled: true } を設定し、Strapi を再起動します。
2. ツールの auth アクションを含む権限を持つ Authorization: Bearer <admin-token> を使って、クライアントを http://localhost:1337/mcp に接続します。
3. ツールが表示され、出力スキーマに一致する structuredContent を返すことを確認します。

プロンプトとリソース

ライフサイクルと認証の規則は同じで、ビルダーが異なります：ai.mcp.definePrompt／strapi.ai.mcp.registerPrompt および ai.mcp.defineResource／strapi.ai.mcp.registerResource。各フィールドの表とシグネチャについては、reference.md を参照してください。

ドキュメント

• MCP サーバー（設定、権限の境界、ステートレスアーキテクチャ、制限事項）
• API の型：@strapi/types