Plugin Capabilities

插件 Capability

manifest.capabilities 将一个插件已声明的 HTTP route 映射为 /api/v1 下的公开能力。 内核只提供映射、发现、配额、审计和幂等边界；插件仍拥有原 route 的业务规则。

MCP 投影

插件不定义单独的 MCP server 或 mcp manifest 字段。一项已激活的插件 Capability 会自动成为 MCP 工具：工具名由 capability ID 转换而来（例如 example.records.create 变为 example_records_create），工具实际执行时重新进入同一条 /api/v1 alias。

plugin route
  -> manifest.capabilities
  -> /api/v1 capability
  -> GET /api/v1/capabilities
  -> MCP tools/list and tools/call
  -> same route handler and guard

因此插件不应在自己的代码中复制 MCP 的鉴权、工具分发或业务 handler。

capabilities: [{
  id: 'example.records.read',
  method: 'GET',
  route: '/records',
  path: '/api/v1/example/records',
  summary: 'List records visible to the caller',
  scope: 'example:read',
}]

完整示例：

import { definePlugin } from '@stackpanel/sdk';

export default definePlugin({
  manifest: {
    id: 'example',
    name: 'Example',
    version: '0.1.0',
    permissions: [{ key: 'example.manage', scope: 'example' }],
    capabilities: [
      {
        id: 'example.records.create',
        method: 'POST',
        route: '/example/records',
        path: '/api/v1/example/records',
        summary: 'Create an example record',
        scope: 'example:write',
        mutating: true,
        destructive: false,
      },
    ],
  },
  routes: [
    {
      method: 'POST',
      path: '/example/records',
      auth: 'user',
      permission: 'example.manage',
      handler: createRecord,
    },
  ],
});

规则：route 必须存在且方法相同；path 必须以 /api/v1/ 开头并全局唯一；raw route 不可公开；alias 继承原 route 的 auth 和 permission。scope 只能收紧访问。

MCP 写入规则

当 mutating 为 true，工具只有在调用方使用的平台 API Token 同时具备能力自身 scope 与 mcp.write 时才会出现在 MCP tools/list 中；调用 tools/call 时还必须传入 idempotencyKey，内核将它转成 Idempotency-Key。浏览器会话不需要 mcp.write，但仍须通过 原 route 的权限检查。

destructive 默认跟随 mutating。明确可逆的写入才设置 destructive: false；这个标记会影响 内核 Agent 的审批行为，不能为了减少确认而错误标记。

MCP 工具的当前输入是通用 params、query、body 和 idempotencyKey，并不会从插件 Capability 生成领域 JSON Schema。插件 route 必须自行验证 body、路径参数和资源归属。

验证插件能力时，至少检查：

1. 以对应 scope、包含 mcp.write 的 Token 调用 MCP tools/list，工具可见。
2. 移除 mcp.write 后，该写工具不可见。
3. 调用 tools/call 缺少 idempotencyKey 时被拒绝。
4. 通过 MCP 的成功调用与直接请求 /api/v1/example/records 走同一业务校验与审计路径。

不要在此处描述插件的业务对象、配置或操作手册；这些内容由插件仓库 Wiki 维护。