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 注册。

两种注册模式

内联 — 在作用域内有 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 检查实体/字段权限；写入时使用 user（令牌所有者）调用 setCreatorFields。
• 保持处理程序精简：将工作委托给插件服务；工具只是 MCP 接口。
• name/title/description/resolveOutputSchema 为必填项。description 的质量会影响 AI 的工具选择 — 应说明工具的返回内容和适用场景。

架构

• 定义 z.object 输入/输出架构；复用共享字段架构（例如带有 .describe(...) 的 isoDateSchema）。
• 为每个不明显的字段添加 .describe() — 描述会传递给 AI 客户端。
• 处理程序返回的 structuredContent 必须符合 resolveOutputSchema。

身份验证（严格选择一种访问变体）

• 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. 使用 Authorization: Bearer <admin-token> 连接客户端到 http://localhost:1337/mcp，该令牌的权限须包含工具的 auth 操作。
3. 确认工具已显示，并返回符合其输出架构的 structuredContent。

提示词和资源

生命周期/身份验证规则相同，但使用不同的构建器：ai.mcp.definePrompt / strapi.ai.mcp.registerPrompt 和 ai.mcp.defineResource / strapi.ai.mcp.registerResource。字段表和签名请参阅 reference.md。

文档

• MCP 服务（配置、权限边界、无状态架构、限制）
• API 类型：@strapi/types