@silkweave/nestjs 2.2.0 → 2.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Silkweave
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -117,6 +117,21 @@ Exposes the decorated controller route as an MCP tool. Every option is optional.
 | `description` | `string` | `@ApiOperation` summary/description, else generated | Tool description |
 | `input` | `Record<string, z.ZodType>` | - | Zod raw-shape override merged over the reflected fields (per-field). The escape hatch for shapes reflection can't express - discriminated unions, custom validators, `@Transform` |
 | `pipes` | `'apply' \| 'skip'` | `'apply'` | Whether to run parameter-bound pipes (`@Param('id', ParseIntPipe)`) when re-binding |
+| `result` | `'json' \| 'smart'` | `'smart'` | Default MCP result format - `'json'` returns compact JSON text (`jsonToolResult`); `'smart'` inlines small payloads and offloads large ones to an embedded resource (`smartToolResult`). A client that sends `_meta.disposition` on the call overrides it |
+
+### Result format
+
+`@Mcp({ result })` sets the format for one tool. To set a default for **every** tool, pass `defaultResult` to the module:
+
+```ts
+SilkweaveModule.forRoot({
+  silkweave: { name: 'my-api', version: '1.0.0' },
+  adapters: [mcp()],
+  defaultResult: 'json'   // module-wide default; a per-method @Mcp({ result }) still wins
+})
+```
+
+Precedence (highest first): a client's per-call `_meta.disposition` → `@Mcp({ result })` → module `defaultResult` → `'smart'`.
 
 ## How reflection works
 

package/build/index.d.mts

@@ -150,6 +150,13 @@ interface SilkweaveModuleOptions {
    * authentication still works.
    */
   globalGuards?: Type<CanActivate>[];
+  /**
+   * Default MCP result format for every `@Mcp` tool - `'json'` (compact JSON,
+   * `jsonToolResult`) or `'smart'` (inline small / embedded-resource large,
+   * `smartToolResult`). Defaults to `'smart'`. A per-method `@Mcp({ result })`
+   * overrides this, and a client's per-call `_meta.disposition` overrides both.
+   */
+  defaultResult?: 'json' | 'smart';
 }
 declare const SILKWEAVE_MODULE_OPTIONS = "__silkweave_module_options__";
 //#endregion
@@ -217,6 +224,14 @@ interface McpMetadata {
    * the method is invoked directly, not through Nest's HTTP request pipeline.
    */
   pipes?: 'apply' | 'skip';
+  /**
+   * Default MCP result format for this tool. `'json'` returns compact JSON text
+   * (`jsonToolResult`); `'smart'` (the default when unset) inlines small
+   * payloads and offloads large ones to an embedded resource (`smartToolResult`).
+   * This is only a default - a client that sends `_meta.disposition` on the tool
+   * call overrides it.
+   */
+  result?: 'json' | 'smart';
 }
 //#endregion
 //#region src/decorator/mcp.d.ts
@@ -271,7 +286,7 @@ declare class ControllerDiscovery {
    * arguments (with `@UseGuards` guards - and any opted-in `globalGuards` -
    * applied first).
    */
-  discover(openapi?: OpenApiDocument, globalGuards?: Type<CanActivate>[]): Action[];
+  discover(openapi?: OpenApiDocument, globalGuards?: Type<CanActivate>[], defaultResult?: 'json' | 'smart'): Action[];
   private toAction;
   /** Build the merged Zod input shape and the per-argument re-bind plan. */
   private buildInput;

package/build/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/lib/reflect/schema.ts","../src/lib/reflect/openapi.ts","../src/lib/types.ts","../src/adapter/mcp.ts","../src/lib/metadata.ts","../src/decorator/mcp.ts","../src/lib/controllerDiscovery.ts","../src/lib/guards.ts","../src/lib/rebind.ts","../src/lib/silkweave.module.ts"],"mappings":"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"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/lib/reflect/schema.ts","../src/lib/reflect/openapi.ts","../src/lib/types.ts","../src/adapter/mcp.ts","../src/lib/metadata.ts","../src/decorator/mcp.ts","../src/lib/controllerDiscovery.ts","../src/lib/guards.ts","../src/lib/rebind.ts","../src/lib/silkweave.module.ts"],"mappings":"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"}

package/build/index.mjs

@@ -9377,7 +9377,7 @@ let ControllerDiscovery = class ControllerDiscovery {
 	* arguments (with `@UseGuards` guards - and any opted-in `globalGuards` -
 	* applied first).
 	*/
-	discover(openapi, globalGuards = []) {
+	discover(openapi, globalGuards = [], defaultResult) {
 		const lookup = openapi ? buildOpenApiLookup(openapi) : void 0;
 		const discovered = [];
 		for (const wrapper of this.discovery.getProviders().concat(this.discovery.getControllers())) {
@@ -9400,9 +9400,9 @@ let ControllerDiscovery = class ControllerDiscovery {
 				});
 			}
 		}
-		return discovered.map((d) => this.toAction(d, lookup, globalGuards));
+		return discovered.map((d) => this.toAction(d, lookup, globalGuards, defaultResult));
 	}
-	toAction(d, lookup, globalGuards) {
+	toAction(d, lookup, globalGuards, defaultResult) {
 		const proto = Object.getPrototypeOf(d.instance);
 		const route = reflectRoute(d.classRef, d.method);
 		const slots = readParamSlots(d.classRef, d.methodName, proto);
@@ -9437,6 +9437,7 @@ let ControllerDiscovery = class ControllerDiscovery {
 			name,
 			description,
 			input: z.object(shape),
+			...d.meta.result ?? defaultResult ? { disposition: d.meta.result ?? defaultResult } : {},
 			isEnabled: (ctx) => ctx.getOptional("adapter") === "mcp",
 			run: async (input, context) => {
 				await applyGuards(context, input);
@@ -9599,7 +9600,7 @@ let SilkweaveModule = _SilkweaveModule = class SilkweaveModule {
 	configure(_consumer) {
 		const httpAdapter = this.httpAdapterHost.httpAdapter;
 		if (!httpAdapter) throw new Error("@silkweave/nestjs: HttpAdapterHost.httpAdapter is not available.");
-		const allActions = this.discovery.discover(this.options.openapi, this.options.globalGuards);
+		const allActions = this.discovery.discover(this.options.openapi, this.options.globalGuards, this.options.defaultResult);
 		for (const adapter of this.options.adapters) {
 			const baseContext = createContext({
 				...this.options.context ?? {},