@lark-apaas/nestjs-mcp 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,360 @@
+import { Request } from 'express';
+import { Tool, Resource, ServerRequest, ServerNotification, ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
+import { AnySchema, SchemaOutput, ZodRawShapeCompat, ShapeOutput, AnyObjectSchema } from '@modelcontextprotocol/sdk/server/zod-compat.js';
+import { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol.js';
+import { DynamicModule } from '@nestjs/common';
+
+/**
+ * MCP 端点相对应用根的挂载路径。
+ *
+ * 与 `/__innerapi__/automation/invoke` 同属平台内部端点：不走 `/api/*` 的 CSRF 与响应包装，
+ * 由 MCP Gateway 完成凭证校验后以当前用户身份转发到此路径。
+ * 应用设置了 `CLIENT_BASE_PATH`（如 `/app/<appId>`）时，完整路径为 `${CLIENT_BASE_PATH}/__innerapi__/mcp`。
+ */
+declare const MCP_ENDPOINT_PATH = "/__innerapi__/mcp";
+/**
+ * Nest 控制器路径（不带前导斜杠，与仓库内其他 `__innerapi__` 控制器写法一致）。
+ */
+declare const MCP_CONTROLLER_PATH = "__innerapi__/mcp";
+/**
+ * 清单文件在用户工程内的相对路径（相对 process.cwd()）。
+ *
+ * 代码是唯一事实来源，清单由 SDK 在开发态启动时以及 `miaoda-mcp validate` 命令导出，
+ * 用于离线校验；在线面板通过运行时 manifest 接口读取。
+ */
+declare const MCP_MANIFEST_PATH = ".spark/mcp/manifest.json";
+/**
+ * MCP Apps 单文件 HTML 产物目录（相对 process.cwd()），由构建预设产出 `<entry>.html`。
+ */
+declare const MCP_UI_DIST_DIR = "dist/mcp-ui";
+/**
+ * MCP Apps 资源 URI 约定前缀。
+ */
+declare const MCP_UI_RESOURCE_SCHEME = "ui://";
+/** 类装饰器元数据键：标记一个类为 MCP 工具类 */
+declare const MCP_TOOLS_METADATA_KEY = "mcp:tools";
+/** 方法装饰器元数据键：标记一个方法为 MCP 工具 */
+declare const MCP_TOOL_METADATA_KEY = "mcp:tool";
+/** 方法装饰器元数据键：标记一个方法为 MCP Apps 资源 */
+declare const MCP_UI_RESOURCE_METADATA_KEY = "mcp:ui-resource";
+/** 模块配置注入令牌 */
+declare const MCP_MODULE_OPTIONS: unique symbol;
+/** 服务端默认名称（可通过模块配置覆盖） */
+declare const MCP_DEFAULT_SERVER_NAME = "miaoda-app";
+/** 服务端默认版本 */
+declare const MCP_DEFAULT_SERVER_VERSION = "1.0.0";
+/** 清单文件格式版本 */
+declare const MCP_MANIFEST_VERSION = 1;
+/**
+ * 工具名合法字符（MCP 规范 SEP-986）：1~128 位，字母、数字、下划线、连字符、点。
+ */
+declare const MCP_TOOL_NAME_PATTERN: RegExp;
+/** 应用使用说明：普通 Markdown Resource，不声明 Skills 扩展能力。 */
+declare const MCP_SKILL_PATH = "server/mcp/SKILL.md";
+declare const MCP_SKILL_URI = "skill://app/SKILL.md";
+
+/**
+ * zod 原始形状：`{ field: z.string() }`，与 `@modelcontextprotocol/sdk` 的 `registerTool` 保持一致。
+ * 类型来自 SDK 的 zod 兼容层，zod v3（3.25+）与 v4 均可。
+ */
+type McpRawShape = ZodRawShapeCompat;
+/**
+ * 工具入参 / 出参 schema：既可以是原始形状，也可以是 `z.object(...)`。
+ */
+type McpSchema = McpRawShape | AnyObjectSchema;
+/**
+ * 从 schema 推导 TypeScript 类型。
+ *
+ * @example
+ * const Input = { orderId: z.string() };
+ * type Input = Infer<typeof Input>; // { orderId: string }
+ */
+type Infer<S> = S extends AnySchema ? SchemaOutput<S> : S extends ZodRawShapeCompat ? ShapeOutput<S> : never;
+/**
+ * 当前调用者身份，来源于网关注入并由 `UserContextMiddleware` 解析的 `req.userContext`。
+ */
+interface McpUser {
+    userId?: string;
+    tenantId?: number;
+    appId?: string;
+    userType?: string;
+    env?: 'preview' | 'runtime';
+    userName?: string;
+    userNameEn?: string;
+    userNameI18n?: Record<string, string>;
+    isSystemAccount?: boolean;
+    roles?: string[];
+}
+/**
+ * 工具执行上下文，作为工具方法的第二个参数传入。
+ */
+interface McpContext {
+    /** 当前用户身份，与 REST 接口中的 `req.userContext` 一致 */
+    user: McpUser;
+    /** 原始 HTTP 请求，用于读取 header、logid 等 */
+    request: Request;
+    /** 客户端取消调用时触发 */
+    signal: AbortSignal;
+    /** MCP 请求 id */
+    requestId: string | number;
+    /** SDK 透传的完整附加信息（进度通知、会话信息等） */
+    extra: RequestHandlerExtra<ServerRequest, ServerNotification>;
+}
+/**
+ * 工具返回的内容块（文本 / 图片 / 资源链接），与 MCP `CallToolResult.content` 对齐。
+ */
+type McpContentBlock = {
+    type: 'text';
+    text: string;
+    _meta?: Record<string, unknown>;
+} | {
+    type: 'image';
+    data: string;
+    mimeType: string;
+    _meta?: Record<string, unknown>;
+} | {
+    type: 'audio';
+    data: string;
+    mimeType: string;
+    _meta?: Record<string, unknown>;
+} | {
+    type: 'resource_link';
+    uri: string;
+    name: string;
+    title?: string;
+    description?: string;
+    mimeType?: string;
+    _meta?: Record<string, unknown>;
+};
+/**
+ * 工具方法的返回值。
+ *
+ * - 声明了 `outputSchema` 时，`structuredContent` 必填且类型受 schema 约束；
+ *   `content` 可省略，SDK 会自动补一份 JSON 文本供不支持结构化输出的客户端使用。
+ * - 未声明 `outputSchema` 时，可直接返回 `{ content: [...] }`。
+ */
+type McpToolResult<O = undefined> = O extends undefined ? {
+    content: McpContentBlock[];
+    structuredContent?: Record<string, unknown>;
+    isError?: boolean;
+    _meta?: Record<string, unknown>;
+} : {
+    structuredContent: Infer<O>;
+    content?: McpContentBlock[];
+    isError?: boolean;
+    _meta?: Record<string, unknown>;
+};
+/**
+ * MCP Apps 关联配置：声明该工具的结果由哪个 `ui://` 资源渲染。
+ */
+interface McpToolUiOptions {
+    /** 关联的 MCP Apps 资源 URI，如 `ui://order/detail` */
+    resourceUri: string;
+    /**
+     * 可见范围：`model` 表示模型可调用，`app` 表示仅供界面内调用。
+     * 默认 `['model', 'app']`。
+     */
+    visibility?: Array<'model' | 'app'>;
+}
+/**
+ * `@McpTool()` 装饰器配置。
+ */
+interface McpToolOptions<I extends McpSchema | undefined = undefined, O extends McpSchema | undefined = undefined> {
+    /** 工具名，默认取方法名；需满足 `^[A-Za-z0-9_.-]{1,128}$` */
+    name?: string;
+    /** 面向人的标题 */
+    title?: string;
+    /** 面向模型的描述，应说明用途、何时调用与返回内容 */
+    description: string;
+    /** 入参 schema（zod） */
+    inputSchema?: I;
+    /** 出参 schema（zod），声明后返回值需带 `structuredContent` */
+    outputSchema?: O;
+    /** MCP 工具注解（readOnlyHint / destructiveHint / idempotentHint / openWorldHint） */
+    annotations?: ToolAnnotations;
+    /** MCP Apps：结果由指定 `ui://` 资源渲染 */
+    ui?: McpToolUiOptions;
+    /** 额外 `_meta`，与 `ui` 生成的字段合并 */
+    meta?: Record<string, unknown>;
+}
+/**
+ * `@McpTools()` 类装饰器配置。
+ */
+interface McpToolsOptions {
+    /** 为该类下所有工具名加前缀，如 `order_` */
+    prefix?: string;
+}
+/**
+ * `@McpUiResource()` 方法装饰器配置。方法需返回单文件 HTML 字符串。
+ */
+interface McpUiResourceOptions {
+    /** 资源 URI，须以 `ui://` 开头 */
+    uri: string;
+    /** 资源名，默认取方法名 */
+    name?: string;
+    title?: string;
+    description?: string;
+    /** 内容安全策略：允许连接 / 加载资源的域 */
+    csp?: {
+        connectDomains?: string[];
+        resourceDomains?: string[];
+        frameDomains?: string[];
+        baseUriDomains?: string[];
+    };
+    /** 宿主权限声明 */
+    permissions?: Record<string, unknown>;
+    /** 额外 `_meta.ui` 字段 */
+    meta?: Record<string, unknown>;
+}
+/**
+ * 工具方法签名（装饰器用于校验方法类型）。
+ */
+type McpToolHandler<I extends McpSchema | undefined, O extends McpSchema | undefined> = (input: I extends undefined ? Record<string, never> : Infer<I>, ctx: McpContext) => McpToolResult<O> | Promise<McpToolResult<O>>;
+/**
+ * MCP Apps 资源方法签名。
+ */
+type McpUiResourceHandler = (ctx: McpContext) => string | Promise<string>;
+/**
+ * 模块配置。
+ */
+interface McpModuleOptions {
+    /** 是否启用 MCP 端点，默认 true */
+    enabled?: boolean;
+    /**
+     * 执行工具 / 读取资源时是否要求携带用户身份（`req.userContext.userId`），默认 true。
+     * 正常链路由 MCP Gateway 或开发服务入口注入身份；缺失时返回 isError 结果而不执行业务代码。
+     */
+    requireUser?: boolean;
+    /** 对外声明的服务端名称，默认取 `SUDA_APP_ID` 或 `miaoda-app` */
+    serverName?: string;
+    /** 对外声明的服务端版本，默认 `1.0.0` */
+    serverVersion?: string;
+    /** 服务端说明（initialize 响应中的 `instructions`） */
+    instructions?: string;
+    /**
+     * 清单导出配置。默认在非生产环境启动时写入 `.spark/mcp/manifest.json`。
+     */
+    manifest?: {
+        /** 是否在启动时写文件，默认 `NODE_ENV !== 'production'` */
+        writeOnBoot?: boolean;
+        /** 清单路径（相对 cwd），默认 `.spark/mcp/manifest.json` */
+        path?: string;
+    };
+}
+/** 平台面板聚合协议；标准 MCP 客户端使用 tools/list、resources/list/read。 */
+interface McpSkill {
+    uri: string;
+    path: string;
+    content: string;
+}
+interface McpSourceLocation {
+    path: string;
+    line?: number;
+}
+interface McpSources {
+    tools: Record<string, McpSourceLocation>;
+    resources: Record<string, McpSourceLocation>;
+}
+interface McpCatalog {
+    version: number;
+    generatedAt: string;
+    endpoint: string;
+    tools: Tool[];
+    resources: Resource[];
+    skill: McpSkill | null;
+    sources: McpSources;
+}
+
+/**
+ * 工具执行期间可预期的业务错误。
+ *
+ * 在工具方法中抛出该错误时，SDK 会将其转换为 `isError: true` 的工具结果并把 message 原样返回给 Agent，
+ * 适合表达“订单不存在”“无权访问”这类需要 Agent 感知并调整策略的失败。
+ * 其他未捕获异常会被记录日志，并以通用的失败提示返回，避免泄露内部细节。
+ */
+declare class McpToolError extends Error {
+    /** 可选的机器可读错误码，会一并放入返回内容 */
+    readonly code?: string;
+    /** 附加数据，会以 JSON 形式放入返回内容 */
+    readonly data?: unknown;
+    constructor(message: string, options?: {
+        code?: string;
+        data?: unknown;
+    });
+}
+
+/**
+ * `@McpTools()` 类装饰器：标记一个类为 MCP 工具类。
+ *
+ * 自动附加 `@Injectable()`，类内可正常注入业务 Service。
+ * 工具类需作为 provider 注册到所属业务模块，应用启动时由 `McpModule` 自动发现，
+ * 无需改动 `app.module.ts`。
+ *
+ * @example
+ * ```typescript
+ * @McpTools({ prefix: 'order_' })
+ * export class OrderMcpTools {
+ *   constructor(private readonly orders: OrderService) {}
+ *
+ *   @McpTool({ description: '按 ID 查询订单', inputSchema: GetOrderInput, outputSchema: GetOrderOutput })
+ *   async get(input: Infer<typeof GetOrderInput>, ctx: McpContext): Promise<McpToolResult<typeof GetOrderOutput>> {
+ *     const order = await this.orders.findById(input.orderId, ctx.user);
+ *     return { structuredContent: order };
+ *   }
+ * }
+ * ```
+ */
+declare const McpTools: (options?: McpToolsOptions) => ClassDecorator;
+
+/**
+ * `@McpTool()` 方法装饰器：把工具类中的一个方法注册为 MCP 工具。
+ *
+ * 方法签名约定为 `(input, ctx) => McpToolResult`：
+ * - `input` 已按 `inputSchema` 校验并推导类型，可写作 `Infer<typeof InputSchema>`；
+ * - `ctx.user` 为网关注入的当前用户身份，与 REST 接口中的 `req.userContext` 一致；
+ * - 声明 `outputSchema` 时返回 `{ structuredContent }`，否则返回 `{ content: [...] }`。
+ *
+ * TypeScript 方法装饰器只能校验、不能改写方法类型，因此入参与返回值类型需在方法签名上显式标注。
+ */
+declare function McpTool<I extends McpSchema | undefined = undefined, O extends McpSchema | undefined = undefined>(options: McpToolOptions<I, O>): <M extends McpToolHandler<I, O>>(target: object, propertyKey: string | symbol, descriptor: TypedPropertyDescriptor<M>) => void;
+
+/**
+ * `@McpUiResource()` 方法装饰器：把方法注册为 MCP Apps 资源（`ui://` 单文件 HTML）。
+ *
+ * 方法返回完整 HTML 字符串。界面源码放在 `client/mcp-ui/<entry>/` 下（浏览器代码归客户端 tsconfig 管），
+ * 由构建预设打包为 `dist/mcp-ui/<entry>.html`，方法内通过 `readMcpUiTemplate('<entry>')` 读取即可。
+ *
+ * @example
+ * ```typescript
+ * @McpUiResource({ uri: 'ui://order/detail', title: '订单详情' })
+ * orderDetailView() {
+ *   return readMcpUiTemplate('order-detail');
+ * }
+ * ```
+ */
+declare function McpUiResource(options: McpUiResourceOptions): <M extends McpUiResourceHandler>(target: object, propertyKey: string | symbol, descriptor: TypedPropertyDescriptor<M>) => void;
+
+/**
+ * McpModule
+ *
+ * 为全栈应用提供 MCP Server 能力：自动发现 `@McpTools()` 类，
+ * 在 `/__innerapi__/mcp` 暴露无状态 Streamable HTTP 端点，并导出 `.spark/mcp/manifest.json`。
+ *
+ * 由 `PlatformModule` 默认引入，业务工程无需手动导入；
+ * 需要关闭时传 `PlatformModule.forRoot({ mcp: { enabled: false } })`。
+ */
+declare class McpModule {
+    static forRoot(options?: McpModuleOptions): DynamicModule;
+}
+
+/**
+ * 读取构建预设产出的 MCP Apps 单文件 HTML（`dist/mcp-ui/<entry>.html`）。
+ *
+ * 生产环境读取一次后缓存；开发环境每次重新读取，配合预设的 watch 构建实现界面热更新。
+ *
+ * @param entry `client/mcp-ui/<entry>/` 目录名
+ * @param cwd 工程根目录，默认 process.cwd()
+ */
+declare function readMcpUiTemplate(entry: string, cwd?: string): Promise<string>;
+
+export { type Infer, MCP_CONTROLLER_PATH, MCP_DEFAULT_SERVER_NAME, MCP_DEFAULT_SERVER_VERSION, MCP_ENDPOINT_PATH, MCP_MANIFEST_PATH, MCP_MANIFEST_VERSION, MCP_MODULE_OPTIONS, MCP_SKILL_PATH, MCP_SKILL_URI, MCP_TOOLS_METADATA_KEY, MCP_TOOL_METADATA_KEY, MCP_TOOL_NAME_PATTERN, MCP_UI_DIST_DIR, MCP_UI_RESOURCE_METADATA_KEY, MCP_UI_RESOURCE_SCHEME, type McpCatalog, type McpContentBlock, type McpContext, McpModule, type McpModuleOptions, type McpRawShape, type McpSchema, type McpSkill, type McpSourceLocation, type McpSources, McpTool, McpToolError, type McpToolHandler, type McpToolOptions, type McpToolResult, type McpToolUiOptions, McpTools, type McpToolsOptions, McpUiResource, type McpUiResourceHandler, type McpUiResourceOptions, type McpUser, readMcpUiTemplate };