@webpieces/core-util 0.4.795 → 0.4.797

package/src/mcp/McpCompileAssertions.js.map

@@ -1 +1 @@
-{"version":3,"file":"McpCompileAssertions.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/mcp/McpCompileAssertions.ts"],"names":[],"mappings":";;;AAAA,+CAA0C;AAC1C,2CAAsE;AAEtE,MAAM,gBAAgB,GAAG,IAAI,6BAAiB,CAC1C,cAAc,EACd,IAAI,EACJ,SAAS,EACT,KAAK,EACL,SAAS,EACT,SAAS;AACT,uEAAuE;AACvE,EAAE,CACL,CAAC;AAEF,0EAA0E;AAC1E,MAAM,eAAe,GAAG,IAAI,gCAAoB,CAAC,aAAa,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;AAE9E,gGAAgG;AAChG,MAAM,eAAe,GAAG,IAAI,gCAAoB,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC;AAEtE,MAAM,qBAAqB,GAAG,IAAI,6BAAiB,CAC/C,2CAA2C,EAC3C,KAAK,EACL,SAAS,EACT,KAAK,EACL,SAAS,EACT,SAAS,EACT,SAAS;AACT,yFAAyF;AACzF,QAAQ,CACX,CAAC;AAEF,MAAe,kBAAkB;IAC7B,uEAAuE;IASvE,OAAO;QACH,MAAM,IAAI,KAAK,CAAC,eAAe,CAAC,CAAC;IACrC,CAAC;CACJ;AAHG;IARC,IAAA,uBAAS,EAAC;QACP,IAAI,EAAE,SAAS;QACf,WAAW,EAAE,sCAAsC;QACnD,YAAY,EAAE,IAAI;QAClB,eAAe,EAAE,IAAI;QACrB,cAAc,EAAE,IAAI;QACpB,aAAa,EAAE,KAAK;KACvB,CAAC;;;;iDAGD;AAGL,MAAe,iBAAiB;IAC5B,6DAA6D;IAQ7D,IAAI;QACA,MAAM,IAAI,KAAK,CAAC,eAAe,CAAC,CAAC;IACrC,CAAC;IAED,6DAA6D;IAQ7D,KAAK,CAAC,MAAc,EAAE,OAAe;QACjC,MAAM,IAAI,KAAK,CAAC,eAAe,CAAC,CAAC;IACrC,CAAC;CACJ;AAfG;IAPC,IAAA,uBAAS,EAAC;QACP,IAAI,EAAE,YAAY;QAClB,WAAW,EAAE,sCAAsC;QACnD,YAAY,EAAE,IAAI;QAClB,cAAc,EAAE,IAAI;QACpB,aAAa,EAAE,KAAK;KACvB,CAAC;;;;6CAGD;AAUD;IAPC,IAAA,uBAAS,EAAC;QACP,IAAI,EAAE,aAAa;QACnB,WAAW,EAAE,sCAAsC;QACnD,YAAY,EAAE,IAAI;QAClB,cAAc,EAAE,IAAI;QACpB,aAAa,EAAE,KAAK;KACvB,CAAC;;;;8CAGD;AAGL,KAAK,kBAAkB,CAAC;AACxB,KAAK,iBAAiB,CAAC;AACvB,KAAK,gBAAgB,CAAC;AACtB,KAAK,eAAe,CAAC;AACrB,KAAK,eAAe,CAAC;AACrB,KAAK,qBAAqB,CAAC","sourcesContent":["import { WpMcpTool } from './McpMetadata';\nimport { WpDtoFieldOptions, WpDtoMapFieldOptions } from './DtoSchema';\n\nconst invalidEmptyEnum = new WpDtoFieldOptions(\n    'invalid enum',\n    true,\n    undefined,\n    false,\n    undefined,\n    undefined,\n    // @ts-expect-error enumValues must contain at least one allowed string\n    [],\n);\n\n// @ts-expect-error a map's value type must be a scalar name or a DtoClass\nconst invalidMapValue = new WpDtoMapFieldOptions('invalid map', true, 'date');\n\n// @ts-expect-error a map value type is mandatory: it is the whole point of WpDtoMapFieldOptions\nconst missingMapValue = new WpDtoMapFieldOptions('invalid map', true);\n\nconst noEighthFieldArgument = new WpDtoFieldOptions(\n    'maps are not a WpDtoFieldOptions argument',\n    false,\n    undefined,\n    false,\n    undefined,\n    undefined,\n    undefined,\n    // @ts-expect-error maps use WpDtoMapFieldOptions; the 8th argument is only a WpMcpHeader\n    'string',\n);\n\nabstract class InvalidMcpContract {\n    // @ts-expect-error read-only tools cannot also claim to be destructive\n    @WpMcpTool({\n        name: 'invalid',\n        description: 'This declaration must never compile.',\n        readOnlyHint: true,\n        destructiveHint: true,\n        idempotentHint: true,\n        openWorldHint: false,\n    })\n    invalid(): Promise<void> {\n        throw new Error('contract only');\n    }\n}\n\nabstract class InvalidMcpArities {\n    // @ts-expect-error MCP tools require exactly one request DTO\n    @WpMcpTool({\n        name: 'zero-arity',\n        description: 'This declaration must never compile.',\n        readOnlyHint: true,\n        idempotentHint: true,\n        openWorldHint: false,\n    })\n    zero(): Promise<object> {\n        throw new Error('contract only');\n    }\n\n    // @ts-expect-error MCP tools require exactly one request DTO\n    @WpMcpTool({\n        name: 'multi-arity',\n        description: 'This declaration must never compile.',\n        readOnlyHint: true,\n        idempotentHint: true,\n        openWorldHint: false,\n    })\n    multi(_first: object, _second: object): Promise<object> {\n        throw new Error('contract only');\n    }\n}\n\nvoid InvalidMcpContract;\nvoid InvalidMcpArities;\nvoid invalidEmptyEnum;\nvoid invalidMapValue;\nvoid missingMapValue;\nvoid noEighthFieldArgument;\n"]}
+{"version":3,"file":"McpCompileAssertions.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/mcp/McpCompileAssertions.ts"],"names":[],"mappings":";;;AAAA,+CAA0C;AAC1C,2CAAsE;AAEtE,MAAM,gBAAgB,GAAG,IAAI,6BAAiB,CAC1C,cAAc,EACd,IAAI,EACJ,SAAS,EACT,KAAK,EACL,SAAS,EACT,SAAS;AACT,uEAAuE;AACvE,EAAE,CACL,CAAC;AAEF,0EAA0E;AAC1E,MAAM,eAAe,GAAG,IAAI,gCAAoB,CAAC,aAAa,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;AAE9E,gGAAgG;AAChG,MAAM,eAAe,GAAG,IAAI,gCAAoB,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC;AAEtE,MAAM,qBAAqB,GAAG,IAAI,6BAAiB,CAC/C,2CAA2C,EAC3C,KAAK,EACL,SAAS,EACT,KAAK,EACL,SAAS,EACT,SAAS,EACT,SAAS;AACT,yFAAyF;AACzF,QAAQ,CACX,CAAC;AAEF,MAAe,kBAAkB;IAQ7B,OAAO,CAAC,QAAgB;QACpB,MAAM,IAAI,KAAK,CAAC,eAAe,CAAC,CAAC;IACrC,CAAC;CACJ;AAHG;IAPC,IAAA,uBAAS,EAAC;QACP,IAAI,EAAE,SAAS;QACf,WAAW,EAAE,sCAAsC;QACnD,sFAAsF;QACtF,YAAY,EAAE,IAAI;QAClB,aAAa,EAAE,KAAK;KACvB,CAAC;;;;iDAGD;AAGL,MAAe,iBAAiB;IAC5B,6DAA6D;IAM7D,IAAI;QACA,MAAM,IAAI,KAAK,CAAC,eAAe,CAAC,CAAC;IACrC,CAAC;IAED,6DAA6D;IAM7D,KAAK,CAAC,MAAc,EAAE,OAAe;QACjC,MAAM,IAAI,KAAK,CAAC,eAAe,CAAC,CAAC;IACrC,CAAC;CACJ;AAbG;IALC,IAAA,uBAAS,EAAC;QACP,IAAI,EAAE,YAAY;QAClB,WAAW,EAAE,sCAAsC;QACnD,aAAa,EAAE,KAAK;KACvB,CAAC;;;;6CAGD;AAQD;IALC,IAAA,uBAAS,EAAC;QACP,IAAI,EAAE,aAAa;QACnB,WAAW,EAAE,sCAAsC;QACnD,aAAa,EAAE,KAAK;KACvB,CAAC;;;;8CAGD;AAGL,KAAK,kBAAkB,CAAC;AACxB,KAAK,iBAAiB,CAAC;AACvB,KAAK,gBAAgB,CAAC;AACtB,KAAK,eAAe,CAAC;AACrB,KAAK,eAAe,CAAC;AACrB,KAAK,qBAAqB,CAAC","sourcesContent":["import { WpMcpTool } from './McpMetadata';\nimport { WpDtoFieldOptions, WpDtoMapFieldOptions } from './DtoSchema';\n\nconst invalidEmptyEnum = new WpDtoFieldOptions(\n    'invalid enum',\n    true,\n    undefined,\n    false,\n    undefined,\n    undefined,\n    // @ts-expect-error enumValues must contain at least one allowed string\n    [],\n);\n\n// @ts-expect-error a map's value type must be a scalar name or a DtoClass\nconst invalidMapValue = new WpDtoMapFieldOptions('invalid map', true, 'date');\n\n// @ts-expect-error a map value type is mandatory: it is the whole point of WpDtoMapFieldOptions\nconst missingMapValue = new WpDtoMapFieldOptions('invalid map', true);\n\nconst noEighthFieldArgument = new WpDtoFieldOptions(\n    'maps are not a WpDtoFieldOptions argument',\n    false,\n    undefined,\n    false,\n    undefined,\n    undefined,\n    undefined,\n    // @ts-expect-error maps use WpDtoMapFieldOptions; the 8th argument is only a WpMcpHeader\n    'string',\n);\n\nabstract class InvalidMcpContract {\n    @WpMcpTool({\n        name: 'invalid',\n        description: 'This declaration must never compile.',\n        // @ts-expect-error side-effect claims belong on @Endpoint.operation, never @WpMcpTool\n        readOnlyHint: true,\n        openWorldHint: false,\n    })\n    invalid(_request: object): Promise<object> {\n        throw new Error('contract only');\n    }\n}\n\nabstract class InvalidMcpArities {\n    // @ts-expect-error MCP tools require exactly one request DTO\n    @WpMcpTool({\n        name: 'zero-arity',\n        description: 'This declaration must never compile.',\n        openWorldHint: false,\n    })\n    zero(): Promise<object> {\n        throw new Error('contract only');\n    }\n\n    // @ts-expect-error MCP tools require exactly one request DTO\n    @WpMcpTool({\n        name: 'multi-arity',\n        description: 'This declaration must never compile.',\n        openWorldHint: false,\n    })\n    multi(_first: object, _second: object): Promise<object> {\n        throw new Error('contract only');\n    }\n}\n\nvoid InvalidMcpContract;\nvoid InvalidMcpArities;\nvoid invalidEmptyEnum;\nvoid invalidMapValue;\nvoid missingMapValue;\nvoid noEighthFieldArgument;\n"]}

package/src/mcp/McpMetadata.d.ts

@@ -1,4 +1,5 @@
 import 'reflect-metadata';
+import { EndpointOperation } from '../http/HttpEndpointOptions';
 /** The immutable hints MCP clients use when deciding whether and how to call a tool. */
 export declare class WpMcpToolHints {
     readonly readOnlyHint: boolean;
@@ -12,19 +13,10 @@ type CommonToolOptions = {
     name: string;
     /** Tool-level documentation published verbatim by tools/list. */
     description: string;
-    idempotentHint: boolean;
     openWorldHint: boolean;
 };
-type ReadOnlyToolOptions = CommonToolOptions & {
-    readOnlyHint: true;
-    destructiveHint?: never;
-};
-type MutatingToolOptions = CommonToolOptions & {
-    readOnlyHint: false;
-    destructiveHint: boolean;
-};
-/** Compiler-enforced exposure: a read-only tool cannot also claim to be destructive. */
-export type WpMcpToolOptions = ReadOnlyToolOptions | MutatingToolOptions;
+/** Tool-specific declarations. Side-effect hints come only from the endpoint operation. */
+export type WpMcpToolOptions = CommonToolOptions;
 type AsyncObjectMethod = (...args: never[]) => Promise<object>;
 type ExactOneParameter<TMethod extends AsyncObjectMethod> = Parameters<TMethod>['length'] extends 1 ? object : never;
 type ExactOneMethodDescriptor<TMethod extends AsyncObjectMethod> = TypedPropertyDescriptor<TMethod> & ExactOneParameter<TMethod>;
@@ -35,17 +27,19 @@ export declare class WpMcpToolMetadata {
     readonly methodName: string;
     readonly name: string;
     readonly description: string;
-    readonly hints: WpMcpToolHints;
-    constructor(methodName: string, name: string, description: string, hints: WpMcpToolHints);
+    readonly openWorldHint: boolean;
+    constructor(methodName: string, name: string, description: string, openWorldHint: boolean);
 }
 /**
- * Explicitly publishes an existing `@Endpoint(..., 'rpc')` method as an MCP tool.
+ * Explicitly publishes an existing `@Endpoint(POST, path, WRITE, RPC)` method as an MCP tool.
  *
  * This annotation owns tool-level documentation only. Input/output field documentation and JSON
  * Schema come from the request/response DTO metadata. The endpoint's `@WpAuth*` annotation remains
  * the sole runtime authorization policy.
  */
 export declare function WpMcpTool(options: WpMcpToolOptions): WpMcpMethodDecorator;
+/** The one mapping from endpoint side effects to MCP advisory annotations. */
+export declare function mcpHintsForOperation(operation: EndpointOperation, openWorldHint: boolean): WpMcpToolHints;
 /** Returns only methods explicitly opted in through {@link WpMcpTool}. */
 export declare function getWpMcpTools(apiClass: Function): WpMcpToolMetadata[];
 export {};

package/src/mcp/McpMetadata.js

@@ -2,9 +2,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WpMcpToolMetadata = exports.WpMcpToolHints = void 0;
 exports.WpMcpTool = WpMcpTool;
+exports.mcpHintsForOperation = mcpHintsForOperation;
 exports.getWpMcpTools = getWpMcpTools;
 require("reflect-metadata");
 const decorators_1 = require("../http/decorators");
+const HttpEndpointOptions_1 = require("../http/HttpEndpointOptions");
 /** The immutable hints MCP clients use when deciding whether and how to call a tool. */
 class WpMcpToolHints {
     readOnlyHint;
@@ -24,17 +26,17 @@ class WpMcpToolMetadata {
     methodName;
     name;
     description;
-    hints;
-    constructor(methodName, name, description, hints) {
+    openWorldHint;
+    constructor(methodName, name, description, openWorldHint) {
         this.methodName = methodName;
         this.name = name;
         this.description = description;
-        this.hints = hints;
+        this.openWorldHint = openWorldHint;
     }
 }
 exports.WpMcpToolMetadata = WpMcpToolMetadata;
 /**
- * Explicitly publishes an existing `@Endpoint(..., 'rpc')` method as an MCP tool.
+ * Explicitly publishes an existing `@Endpoint(POST, path, WRITE, RPC)` method as an MCP tool.
  *
  * This annotation owns tool-level documentation only. Input/output field documentation and JSON
  * Schema come from the request/response DTO metadata. The endpoint's `@WpAuth*` annotation remains
@@ -51,10 +53,22 @@ function WpMcpTool(options) {
         const apiClass = target.constructor;
         const tools = Reflect.getMetadata(decorators_1.METADATA_KEYS.MCP_TOOLS, apiClass) ?? {};
         const methodName = String(propertyKey);
-        tools[methodName] = new WpMcpToolMetadata(methodName, options.name, options.description, new WpMcpToolHints(options.readOnlyHint, options.readOnlyHint ? false : options.destructiveHint, options.idempotentHint, options.openWorldHint));
+        tools[methodName] = new WpMcpToolMetadata(methodName, options.name, options.description, options.openWorldHint);
         Reflect.defineMetadata(decorators_1.METADATA_KEYS.MCP_TOOLS, tools, apiClass);
     };
 }
+/** The one mapping from endpoint side effects to MCP advisory annotations. */
+// webpieces-disable no-function-outside-class -- pure metadata mapping shared by MCP registration
+function mcpHintsForOperation(operation, openWorldHint) {
+    switch (operation) {
+        case HttpEndpointOptions_1.READ:
+            return new WpMcpToolHints(true, false, true, openWorldHint);
+        case HttpEndpointOptions_1.WRITE_IDEMPOTENT:
+            return new WpMcpToolHints(false, true, true, openWorldHint);
+        case HttpEndpointOptions_1.WRITE:
+            return new WpMcpToolHints(false, true, false, openWorldHint);
+    }
+}
 /** Returns only methods explicitly opted in through {@link WpMcpTool}. */
 // webpieces-disable no-function-outside-class -- metadata reader paired with the decorator
 function getWpMcpTools(apiClass) {

package/src/mcp/McpMetadata.js.map

@@ -1 +1 @@
-{"version":3,"file":"McpMetadata.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/mcp/McpMetadata.ts"],"names":[],"mappings":";;;AAmEA,8BA2BC;AAID,sCAIC;AAtGD,4BAA0B;AAC1B,mDAAmD;AAEnD,wFAAwF;AACxF,MAAa,cAAc;IAEH;IACA;IACA;IACA;IAJpB,YACoB,YAAqB,EACrB,eAAwB,EACxB,cAAuB,EACvB,aAAsB;QAHtB,iBAAY,GAAZ,YAAY,CAAS;QACrB,oBAAe,GAAf,eAAe,CAAS;QACxB,mBAAc,GAAd,cAAc,CAAS;QACvB,kBAAa,GAAb,aAAa,CAAS;IACvC,CAAC;CACP;AAPD,wCAOC;AAsCD,4DAA4D;AAC5D,MAAa,iBAAiB;IAEN;IACA;IACA;IACA;IAJpB,YACoB,UAAkB,EAClB,IAAY,EACZ,WAAmB,EACnB,KAAqB;QAHrB,eAAU,GAAV,UAAU,CAAQ;QAClB,SAAI,GAAJ,IAAI,CAAQ;QACZ,gBAAW,GAAX,WAAW,CAAQ;QACnB,UAAK,GAAL,KAAK,CAAgB;IACtC,CAAC;CACP;AAPD,8CAOC;AAED;;;;;;GAMG;AACH,iGAAiG;AACjG,SAAgB,SAAS,CAAC,OAAyB;IAC/C,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAC;IAChG,IAAI,OAAO,CAAC,WAAW,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;IACzE,CAAC;IACD,OAAO,CACH,MAAc,EACd,WAA4B,EAC5B,WAA8C,EAC1C,EAAE;QACN,MAAM,QAAQ,GAAG,MAAM,CAAC,WAAW,CAAC;QACpC,MAAM,KAAK,GACP,OAAO,CAAC,WAAW,CAAC,0BAAa,CAAC,SAAS,EAAE,QAAQ,CAAC,IAAI,EAAE,CAAC;QACjE,MAAM,UAAU,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC;QACvC,KAAK,CAAC,UAAU,CAAC,GAAG,IAAI,iBAAiB,CACrC,UAAU,EACV,OAAO,CAAC,IAAI,EACZ,OAAO,CAAC,WAAW,EACnB,IAAI,cAAc,CACd,OAAO,CAAC,YAAY,EACpB,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,eAAe,EACtD,OAAO,CAAC,cAAc,EACtB,OAAO,CAAC,aAAa,CACxB,CACJ,CAAC;QACF,OAAO,CAAC,cAAc,CAAC,0BAAa,CAAC,SAAS,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;IACrE,CAAC,CAAC;AACN,CAAC;AAED,0EAA0E;AAC1E,2FAA2F;AAC3F,SAAgB,aAAa,CAAC,QAAkB;IAC5C,MAAM,KAAK,GACP,OAAO,CAAC,WAAW,CAAC,0BAAa,CAAC,SAAS,EAAE,QAAQ,CAAC,IAAI,EAAE,CAAC;IACjE,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAChC,CAAC","sourcesContent":["import 'reflect-metadata';\nimport { METADATA_KEYS } from '../http/decorators';\n\n/** The immutable hints MCP clients use when deciding whether and how to call a tool. */\nexport class WpMcpToolHints {\n    constructor(\n        public readonly readOnlyHint: boolean,\n        public readonly destructiveHint: boolean,\n        public readonly idempotentHint: boolean,\n        public readonly openWorldHint: boolean,\n    ) {}\n}\n\ntype CommonToolOptions = {\n    /** Stable protocol name. Renaming this breaks saved agent workflows. */\n    name: string;\n    /** Tool-level documentation published verbatim by tools/list. */\n    description: string;\n    idempotentHint: boolean;\n    openWorldHint: boolean;\n};\n\ntype ReadOnlyToolOptions = CommonToolOptions & {\n    readOnlyHint: true;\n    destructiveHint?: never;\n};\n\ntype MutatingToolOptions = CommonToolOptions & {\n    readOnlyHint: false;\n    destructiveHint: boolean;\n};\n\n/** Compiler-enforced exposure: a read-only tool cannot also claim to be destructive. */\nexport type WpMcpToolOptions = ReadOnlyToolOptions | MutatingToolOptions;\n\ntype AsyncObjectMethod = (...args: never[]) => Promise<object>;\ntype ExactOneParameter<TMethod extends AsyncObjectMethod> = Parameters<TMethod>['length'] extends 1\n    ? object\n    : never;\ntype ExactOneMethodDescriptor<TMethod extends AsyncObjectMethod> = TypedPropertyDescriptor<TMethod> &\n    ExactOneParameter<TMethod>;\n\n/** Method decorator restricted to one request DTO and one async response DTO. */\nexport type WpMcpMethodDecorator = <TMethod extends AsyncObjectMethod>(\n    target: object,\n    propertyKey: string | symbol,\n    descriptor: ExactOneMethodDescriptor<TMethod>,\n) => void;\n\n/** Runtime metadata for one explicitly exposed endpoint. */\nexport class WpMcpToolMetadata {\n    constructor(\n        public readonly methodName: string,\n        public readonly name: string,\n        public readonly description: string,\n        public readonly hints: WpMcpToolHints,\n    ) {}\n}\n\n/**\n * Explicitly publishes an existing `@Endpoint(..., 'rpc')` method as an MCP tool.\n *\n * This annotation owns tool-level documentation only. Input/output field documentation and JSON\n * Schema come from the request/response DTO metadata. The endpoint's `@WpAuth*` annotation remains\n * the sole runtime authorization policy.\n */\n// webpieces-disable no-function-outside-class -- decorator factories are inherently module-scope\nexport function WpMcpTool(options: WpMcpToolOptions): WpMcpMethodDecorator {\n    if (options.name.trim() === '') throw new Error('@WpMcpTool requires a non-empty stable name.');\n    if (options.description.trim() === '') {\n        throw new Error('@WpMcpTool requires non-empty tool documentation.');\n    }\n    return <TMethod extends AsyncObjectMethod>(\n        target: object,\n        propertyKey: string | symbol,\n        _descriptor: ExactOneMethodDescriptor<TMethod>,\n    ): void => {\n        const apiClass = target.constructor;\n        const tools: Record<string, WpMcpToolMetadata> =\n            Reflect.getMetadata(METADATA_KEYS.MCP_TOOLS, apiClass) ?? {};\n        const methodName = String(propertyKey);\n        tools[methodName] = new WpMcpToolMetadata(\n            methodName,\n            options.name,\n            options.description,\n            new WpMcpToolHints(\n                options.readOnlyHint,\n                options.readOnlyHint ? false : options.destructiveHint,\n                options.idempotentHint,\n                options.openWorldHint,\n            ),\n        );\n        Reflect.defineMetadata(METADATA_KEYS.MCP_TOOLS, tools, apiClass);\n    };\n}\n\n/** Returns only methods explicitly opted in through {@link WpMcpTool}. */\n// webpieces-disable no-function-outside-class -- metadata reader paired with the decorator\nexport function getWpMcpTools(apiClass: Function): WpMcpToolMetadata[] {\n    const tools: Record<string, WpMcpToolMetadata> =\n        Reflect.getMetadata(METADATA_KEYS.MCP_TOOLS, apiClass) ?? {};\n    return Object.values(tools);\n}\n"]}
+{"version":3,"file":"McpMetadata.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/mcp/McpMetadata.ts"],"names":[],"mappings":";;;AA8DA,8BAsBC;AAID,oDAYC;AAID,sCAIC;AA5GD,4BAA0B;AAC1B,mDAAmD;AACnD,qEAKqC;AAErC,wFAAwF;AACxF,MAAa,cAAc;IAEH;IACA;IACA;IACA;IAJpB,YACoB,YAAqB,EACrB,eAAwB,EACxB,cAAuB,EACvB,aAAsB;QAHtB,iBAAY,GAAZ,YAAY,CAAS;QACrB,oBAAe,GAAf,eAAe,CAAS;QACxB,mBAAc,GAAd,cAAc,CAAS;QACvB,kBAAa,GAAb,aAAa,CAAS;IACvC,CAAC;CACP;AAPD,wCAOC;AA2BD,4DAA4D;AAC5D,MAAa,iBAAiB;IAEN;IACA;IACA;IACA;IAJpB,YACoB,UAAkB,EAClB,IAAY,EACZ,WAAmB,EACnB,aAAsB;QAHtB,eAAU,GAAV,UAAU,CAAQ;QAClB,SAAI,GAAJ,IAAI,CAAQ;QACZ,gBAAW,GAAX,WAAW,CAAQ;QACnB,kBAAa,GAAb,aAAa,CAAS;IACvC,CAAC;CACP;AAPD,8CAOC;AAED;;;;;;GAMG;AACH,iGAAiG;AACjG,SAAgB,SAAS,CAAC,OAAyB;IAC/C,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAC;IAChG,IAAI,OAAO,CAAC,WAAW,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;IACzE,CAAC;IACD,OAAO,CACH,MAAc,EACd,WAA4B,EAC5B,WAA8C,EAC1C,EAAE;QACN,MAAM,QAAQ,GAAG,MAAM,CAAC,WAAW,CAAC;QACpC,MAAM,KAAK,GACP,OAAO,CAAC,WAAW,CAAC,0BAAa,CAAC,SAAS,EAAE,QAAQ,CAAC,IAAI,EAAE,CAAC;QACjE,MAAM,UAAU,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC;QACvC,KAAK,CAAC,UAAU,CAAC,GAAG,IAAI,iBAAiB,CACrC,UAAU,EACV,OAAO,CAAC,IAAI,EACZ,OAAO,CAAC,WAAW,EACnB,OAAO,CAAC,aAAa,CACxB,CAAC;QACF,OAAO,CAAC,cAAc,CAAC,0BAAa,CAAC,SAAS,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;IACrE,CAAC,CAAC;AACN,CAAC;AAED,8EAA8E;AAC9E,kGAAkG;AAClG,SAAgB,oBAAoB,CAChC,SAA4B,EAC5B,aAAsB;IAEtB,QAAQ,SAAS,EAAE,CAAC;QAChB,KAAK,0BAAI;YACL,OAAO,IAAI,cAAc,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,aAAa,CAAC,CAAC;QAChE,KAAK,sCAAgB;YACjB,OAAO,IAAI,cAAc,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,aAAa,CAAC,CAAC;QAChE,KAAK,2BAAK;YACN,OAAO,IAAI,cAAc,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,aAAa,CAAC,CAAC;IACrE,CAAC;AACL,CAAC;AAED,0EAA0E;AAC1E,2FAA2F;AAC3F,SAAgB,aAAa,CAAC,QAAkB;IAC5C,MAAM,KAAK,GACP,OAAO,CAAC,WAAW,CAAC,0BAAa,CAAC,SAAS,EAAE,QAAQ,CAAC,IAAI,EAAE,CAAC;IACjE,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAChC,CAAC","sourcesContent":["import 'reflect-metadata';\nimport { METADATA_KEYS } from '../http/decorators';\nimport {\n    EndpointOperation,\n    READ,\n    WRITE_IDEMPOTENT,\n    WRITE,\n} from '../http/HttpEndpointOptions';\n\n/** The immutable hints MCP clients use when deciding whether and how to call a tool. */\nexport class WpMcpToolHints {\n    constructor(\n        public readonly readOnlyHint: boolean,\n        public readonly destructiveHint: boolean,\n        public readonly idempotentHint: boolean,\n        public readonly openWorldHint: boolean,\n    ) {}\n}\n\ntype CommonToolOptions = {\n    /** Stable protocol name. Renaming this breaks saved agent workflows. */\n    name: string;\n    /** Tool-level documentation published verbatim by tools/list. */\n    description: string;\n    openWorldHint: boolean;\n};\n\n/** Tool-specific declarations. Side-effect hints come only from the endpoint operation. */\nexport type WpMcpToolOptions = CommonToolOptions;\n\ntype AsyncObjectMethod = (...args: never[]) => Promise<object>;\ntype ExactOneParameter<TMethod extends AsyncObjectMethod> = Parameters<TMethod>['length'] extends 1\n    ? object\n    : never;\ntype ExactOneMethodDescriptor<TMethod extends AsyncObjectMethod> =\n    TypedPropertyDescriptor<TMethod> & ExactOneParameter<TMethod>;\n\n/** Method decorator restricted to one request DTO and one async response DTO. */\nexport type WpMcpMethodDecorator = <TMethod extends AsyncObjectMethod>(\n    target: object,\n    propertyKey: string | symbol,\n    descriptor: ExactOneMethodDescriptor<TMethod>,\n) => void;\n\n/** Runtime metadata for one explicitly exposed endpoint. */\nexport class WpMcpToolMetadata {\n    constructor(\n        public readonly methodName: string,\n        public readonly name: string,\n        public readonly description: string,\n        public readonly openWorldHint: boolean,\n    ) {}\n}\n\n/**\n * Explicitly publishes an existing `@Endpoint(POST, path, WRITE, RPC)` method as an MCP tool.\n *\n * This annotation owns tool-level documentation only. Input/output field documentation and JSON\n * Schema come from the request/response DTO metadata. The endpoint's `@WpAuth*` annotation remains\n * the sole runtime authorization policy.\n */\n// webpieces-disable no-function-outside-class -- decorator factories are inherently module-scope\nexport function WpMcpTool(options: WpMcpToolOptions): WpMcpMethodDecorator {\n    if (options.name.trim() === '') throw new Error('@WpMcpTool requires a non-empty stable name.');\n    if (options.description.trim() === '') {\n        throw new Error('@WpMcpTool requires non-empty tool documentation.');\n    }\n    return <TMethod extends AsyncObjectMethod>(\n        target: object,\n        propertyKey: string | symbol,\n        _descriptor: ExactOneMethodDescriptor<TMethod>,\n    ): void => {\n        const apiClass = target.constructor;\n        const tools: Record<string, WpMcpToolMetadata> =\n            Reflect.getMetadata(METADATA_KEYS.MCP_TOOLS, apiClass) ?? {};\n        const methodName = String(propertyKey);\n        tools[methodName] = new WpMcpToolMetadata(\n            methodName,\n            options.name,\n            options.description,\n            options.openWorldHint,\n        );\n        Reflect.defineMetadata(METADATA_KEYS.MCP_TOOLS, tools, apiClass);\n    };\n}\n\n/** The one mapping from endpoint side effects to MCP advisory annotations. */\n// webpieces-disable no-function-outside-class -- pure metadata mapping shared by MCP registration\nexport function mcpHintsForOperation(\n    operation: EndpointOperation,\n    openWorldHint: boolean,\n): WpMcpToolHints {\n    switch (operation) {\n        case READ:\n            return new WpMcpToolHints(true, false, true, openWorldHint);\n        case WRITE_IDEMPOTENT:\n            return new WpMcpToolHints(false, true, true, openWorldHint);\n        case WRITE:\n            return new WpMcpToolHints(false, true, false, openWorldHint);\n    }\n}\n\n/** Returns only methods explicitly opted in through {@link WpMcpTool}. */\n// webpieces-disable no-function-outside-class -- metadata reader paired with the decorator\nexport function getWpMcpTools(apiClass: Function): WpMcpToolMetadata[] {\n    const tools: Record<string, WpMcpToolMetadata> =\n        Reflect.getMetadata(METADATA_KEYS.MCP_TOOLS, apiClass) ?? {};\n    return Object.values(tools);\n}\n"]}