@cyanheads/mcp-ts-core 0.9.13 → 0.9.15

package/dist/mcp-server/tools/utils/toolDefinition.d.ts

@@ -47,6 +47,33 @@ export interface ToolAnnotations {
     title?: string;
     [key: string]: unknown;
 }
+/**
+ * Per-field rendering config for the `enrichment` block's `content[]` trailer,
+ * keyed to the declared enrichment field names. The success-path analogue of how
+ * `format()` controls `output` rendering: `enrichment` is the data contract,
+ * `enrichmentTrailer` is its presentation.
+ *
+ * Scope: this shapes the `content[]` trailer text ONLY. It never affects
+ * `structuredContent`, which always carries the raw validated enrichment value
+ * (the object/array/scalar exactly as declared) — never the rendered markdown.
+ *
+ * Each entry is optional and may set:
+ *   - `render` — maps the field's validated value to trailer markdown. Wins over
+ *     the kind-tag and the generic `**key:** value` fallback. Use it to stop a
+ *     structured (object/array) field from collapsing to a JSON blob in
+ *     `content[]`; `structuredContent` always keeps the full structured value.
+ *   - `label` — overrides the field-name shown in the generic / `delta` rendering
+ *     (e.g. `Total Found` for a `totalFound` field, instead of the raw key).
+ *
+ * Resolves to `never` when no `enrichment` block is declared — `enrichmentTrailer`
+ * requires one.
+ */
+export type EnrichmentTrailerConfig<TEnrich extends ZodRawShape | undefined> = TEnrich extends ZodRawShape ? {
+    [K in keyof TEnrich]?: {
+        label?: string;
+        render?: (value: z.infer<TEnrich[K]>) => string;
+    };
+} : never;
 /**
  * Represents the complete, self-contained definition of an MCP tool.
  *
@@ -54,8 +81,12 @@ export interface ToolAnnotations {
  * definition (or `undefined` when none are declared). The reason union extracted
  * from `TErrors` flows into the handler's `ctx.fail` for compile-time-checked
  * error throws.
+ *
+ * `TEnrich` is the `ZodRawShape` of the `enrichment` block (or `undefined` when
+ * none is declared). Its inferred fields type `ctx.enrich(...)` and are advertised
+ * to clients as part of `outputSchema`.
  */
-export interface ToolDefinition<TInput extends ZodObject<ZodRawShape> = ZodObject<ZodRawShape>, TOutput extends ZodObject<ZodRawShape> = ZodObject<ZodRawShape>, TErrors extends readonly ErrorContract[] | undefined = undefined> {
+export interface ToolDefinition<TInput extends ZodObject<ZodRawShape> = ZodObject<ZodRawShape>, TOutput extends ZodObject<ZodRawShape> = ZodObject<ZodRawShape>, TErrors extends readonly ErrorContract[] | undefined = undefined, TEnrich extends ZodRawShape | undefined = undefined> {
     /** Protocol-level metadata (e.g., MCP Apps extension). */
     _meta?: Record<string, unknown>;
     /** UI/behavior hints for clients. */
@@ -64,6 +95,40 @@ export interface ToolDefinition<TInput extends ZodObject<ZodRawShape> = ZodObjec
     auth?: string[];
     /** LLM-facing description. */
     description: string;
+    /**
+     * Declarative contract for agent-facing context on the success path — the
+     * counterpart to `errors[]`. A `ZodRawShape` (`{ <name>: <ZodType> }`) of
+     * fields the handler populates via `ctx.enrich(...)`: empty-result notices,
+     * the query/filter as the server parsed it, pagination totals.
+     *
+     * **Reaches both client surfaces.** Enrichment is merged into the validated
+     * output (→ `structuredContent`) and mirrored into `content[]` as a trailer —
+     * so `structuredContent`-only clients (e.g. Claude Code) and `content[]`-only
+     * clients (e.g. Claude Desktop) both see it, even when the tool defines no
+     * `format()`. The extended schema (`output.extend(enrichment)`) is advertised
+     * as the tool's `outputSchema` in `tools/list`.
+     *
+     * **Type-driven.** When declared, `ctx.enrich(...)` is typed to a `Partial` of
+     * these fields. Enrichment is not part of `output`, so `format-parity` never
+     * touches it. A *required* enrichment field that is never populated fails the
+     * effective-output parse — surfacing the bug rather than dropping it silently.
+     * Keys must be disjoint from `output` keys (lint-enforced; `.extend` would
+     * otherwise silently override).
+     */
+    enrichment?: TEnrich;
+    /**
+     * Per-field `content[]` trailer rendering for the `enrichment` block — the
+     * presentation layer to `enrichment`'s data contract (mirrors `output` /
+     * `format`).
+     *
+     * Supply a `render` to stop a structured (object/array) enrichment field from
+     * collapsing to a JSON blob in `content[]` (it renders as bulleted markdown
+     * instead; `structuredContent` is unaffected), or a `label` to show a
+     * human-readable field name. Keyed to the declared `enrichment` fields and
+     * type-checked against them. The `enrichment-trailer-render` lint rule requires
+     * a `render` for any non-scalar enrichment field that isn't a `delta` shape.
+     */
+    enrichmentTrailer?: EnrichmentTrailerConfig<TEnrich>;
     /**
      * Declarative contract describing the failure modes this tool can surface.
      *
@@ -95,8 +160,13 @@ export interface ToolDefinition<TInput extends ZodObject<ZodRawShape> = ZodObjec
      * clients can see. The `format-parity` lint rule enforces this at startup.
      *
      * If omitted, the handler factory JSON-stringifies the output as a fallback.
+     *
+     * Declared as a method (not an arrow property) for the same reason as `handler`:
+     * method parameters are checked bivariantly, so a concrete tool's narrow `format`
+     * stays assignable to the type-erased `AnyToolDefinition` (whose `format` param is
+     * the widened `Record<string, unknown>`).
      */
-    format?: (result: z.infer<TOutput>) => ContentBlock[];
+    format?(result: z.infer<TOutput>): ContentBlock[];
     /**
      * The core handler function. Receives validated input and unified Context.
      * Throw on failure — no try/catch needed.
@@ -105,11 +175,15 @@ export interface ToolDefinition<TInput extends ZodObject<ZodRawShape> = ZodObjec
      * helper keyed by the declared reason union — `ctx.fail('typo')` is a TS error.
      * Without `errors[]`, `ctx` is plain `Context` and you throw `McpError` directly.
      *
+     * When `enrichment` is declared, `ctx.enrich(...)` is typed to a `Partial` of
+     * the declared fields; without it, the loose base `enrich` is available (a
+     * no-op merge, since nothing reads it).
+     *
      * Declared as a method (not an arrow property) so TypeScript checks the
-     * signature bivariantly — concrete tools with narrow `ctx.fail` types remain
-     * assignable to the type-erased `AnyToolDefinition` array.
+     * signature bivariantly — concrete tools with narrow `ctx.fail` / `ctx.enrich`
+     * types remain assignable to the type-erased `AnyToolDefinition` array.
      */
-    handler(input: z.infer<TInput>, ctx: HandlerContext<ReasonOf<TErrors>>): Promise<z.infer<TOutput>> | z.infer<TOutput>;
+    handler(input: z.infer<TInput>, ctx: HandlerContext<ReasonOf<TErrors>, TEnrich>): Promise<z.infer<TOutput>> | z.infer<TOutput>;
     /** Zod schema for input validation. All fields need `.describe()`. */
     input: TInput;
     /** Programmatic unique name (snake_case). */
@@ -130,7 +204,7 @@ export interface ToolDefinition<TInput extends ZodObject<ZodRawShape> = ZodObjec
     title?: string;
 }
 /** Type-erased union for mixed arrays passed to createApp(). */
-export type AnyToolDefinition = ToolDefinition<ZodObject<ZodRawShape>, ZodObject<ZodRawShape>, readonly ErrorContract[] | undefined>;
+export type AnyToolDefinition = ToolDefinition<ZodObject<ZodRawShape>, ZodObject<ZodRawShape>, readonly ErrorContract[] | undefined, ZodRawShape | undefined>;
 /**
  * Creates a tool definition with full type inference from Zod schemas.
  *
@@ -178,5 +252,5 @@ export type AnyToolDefinition = ToolDefinition<ZodObject<ZodRawShape>, ZodObject
  * });
  * ```
  */
-export declare function tool<TInput extends ZodObject<ZodRawShape>, TOutput extends ZodObject<ZodRawShape>, const TErrors extends readonly ErrorContract[] | undefined = undefined>(name: string, options: Omit<ToolDefinition<TInput, TOutput, TErrors>, 'name'>): ToolDefinition<TInput, TOutput, TErrors>;
+export declare function tool<TInput extends ZodObject<ZodRawShape>, TOutput extends ZodObject<ZodRawShape>, const TErrors extends readonly ErrorContract[] | undefined = undefined, const TEnrich extends ZodRawShape | undefined = undefined>(name: string, options: Omit<ToolDefinition<TInput, TOutput, TErrors, TEnrich>, 'name'>): ToolDefinition<TInput, TOutput, TErrors, TEnrich>;
 //# sourceMappingURL=toolDefinition.d.ts.map

package/dist/mcp-server/tools/utils/toolDefinition.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toolDefinition.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/utils/toolDefinition.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"toolDefinition.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/utils/toolDefinition.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/tools/utils/toolDefinition.js.map

@@ -1 +1 @@
-{"version":3,"file":"toolDefinition.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/utils/toolDefinition.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAQH,OAAO,EAAyB,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAuIzE,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,MAAM,UAAU,IAAI,CAKlB,IAAY,EACZ,OAA+D;IAE/D,OAAO,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC;AAC9B,CAAC"}
+{"version":3,"file":"toolDefinition.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/utils/toolDefinition.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAQH,OAAO,EAAyB,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAuNzE,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,MAAM,UAAU,IAAI,CAMlB,IAAY,EACZ,OAAwE;IAExE,OAAO,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC;AAC9B,CAAC"}

package/dist/mcp-server/tools/utils/toolHandlerFactory.d.ts

@@ -4,7 +4,9 @@
  * @module src/mcp-server/tools/utils/toolHandlerFactory
  */
 import type { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol.js';
-import type { CallToolResult, ServerNotification, ServerRequest } from '@modelcontextprotocol/sdk/types.js';
+import type { CallToolResult, ContentBlock, ServerNotification, ServerRequest } from '@modelcontextprotocol/sdk/types.js';
+import { type ZodObject, type ZodRawShape } from 'zod';
+import type { Context } from '../../../core/context.js';
 import type { StorageService } from '../../../storage/core/StorageService.js';
 import { type JsonRpcErrorCode } from '../../../types-global/errors.js';
 import type { Logger } from '../../../utils/internal/logger.js';
@@ -62,6 +64,26 @@ export declare function buildToolErrorResult(code: JsonRpcErrorCode, message: st
  * effects — this helper does not log.
  */
 export declare function classifyAndBuildToolErrorResult(error: unknown): CallToolResult;
+/**
+ * The output schema advertised to clients in `tools/list`. When a tool declares
+ * an `enrichment` block, that's `output.extend(enrichment)` so enrichment fields
+ * appear in the advertised `outputSchema`; otherwise the bare `output`.
+ */
+export declare function effectiveOutputSchema(def: AnyToolDefinition): ZodObject<ZodRawShape>;
+/**
+ * Shapes the success `CallToolResult` surfaces from the validated domain payload
+ * plus any accumulated enrichment:
+ * - `structuredContent` — domain output merged with enrichment (validated against
+ *   `output.extend(enrichment)`); the bare domain output when no enrichment block.
+ * - `content[]` — the caller-rendered domain content (from `format()` or the
+ *   JSON-stringify default, applied to the **domain payload only**) with the
+ *   enrichment trailer always appended. Rendering the domain payload — never the
+ *   merged object — keeps enrichment out of the JSON blob and avoids double-render.
+ *
+ * A required enrichment field the handler never populated fails the parse here,
+ * surfacing the authoring bug as a loud error rather than dropping it silently.
+ */
+export declare function buildToolSuccessResult(def: AnyToolDefinition, ctx: Context, domainValidated: Record<string, unknown>, domainContent: ContentBlock[]): Pick<CallToolResult, 'content' | 'structuredContent'>;
 /**
  * Creates an MCP tool handler from a tool definition.
  * The returned function is compatible with the MCP SDK's ToolCallback type.

package/dist/mcp-server/tools/utils/toolHandlerFactory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toolHandlerFactory.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/utils/toolHandlerFactory.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8CAA8C,CAAC;AACxF,OAAO,KAAK,EACV,cAAc,EAEd,kBAAkB,EAClB,aAAa,EACd,MAAM,oCAAoC,CAAC;AAQ5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AACvE,OAAO,EAAE,KAAK,gBAAgB,EAAY,MAAM,0BAA0B,CAAC;AAE3E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAGzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAM7D,KAAK,QAAQ,GAAG,mBAAmB,CAAC,aAAa,EAAE,kBAAkB,CAAC,CAAC;AAOvE,qEAAqE;AACrE,MAAM,WAAW,sBAAsB;IACrC;;;;;OAKG;IACH,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,cAAc,CAAC;CACzB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,uBAAuB,CAAC,EAAE,MAAM,IAAI,CAAC;IACrC,yBAAyB,CAAC,EAAE,MAAM,IAAI,CAAC;IACvC,qBAAqB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9C,qBAAqB,CAAC,EAAE,MAAM,IAAI,CAAC;CACpC;AAyBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GACxC,cAAc,CAchB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CAO9E;AAwBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,iBAAiB,EACtB,QAAQ,EAAE,sBAAsB,EAChC,SAAS,EAAE,gBAAgB,GAC1B,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,QAAQ,KAAK,OAAO,CAAC,cAAc,CAAC,CAmG9E"}
+{"version":3,"file":"toolHandlerFactory.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/utils/toolHandlerFactory.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8CAA8C,CAAC;AACxF,OAAO,KAAK,EACV,cAAc,EACd,YAAY,EACZ,kBAAkB,EAClB,aAAa,EACd,MAAM,oCAAoC,CAAC;AAE5C,OAAO,EAAY,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,KAAK,CAAC;AAGjE,OAAO,KAAK,EAAE,OAAO,EAAiC,MAAM,mBAAmB,CAAC;AAGhF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AACvE,OAAO,EAAE,KAAK,gBAAgB,EAAY,MAAM,0BAA0B,CAAC;AAE3E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAIzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAM7D,KAAK,QAAQ,GAAG,mBAAmB,CAAC,aAAa,EAAE,kBAAkB,CAAC,CAAC;AAOvE,qEAAqE;AACrE,MAAM,WAAW,sBAAsB;IACrC;;;;;OAKG;IACH,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,cAAc,CAAC;CACzB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,uBAAuB,CAAC,EAAE,MAAM,IAAI,CAAC;IACrC,yBAAyB,CAAC,EAAE,MAAM,IAAI,CAAC;IACvC,qBAAqB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9C,qBAAqB,CAAC,EAAE,MAAM,IAAI,CAAC;CACpC;AAyBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GACxC,cAAc,CAchB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CAO9E;AAMD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,iBAAiB,GAAG,SAAS,CAAC,WAAW,CAAC,CAGpF;AAmED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,iBAAiB,EACtB,GAAG,EAAE,OAAO,EACZ,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,aAAa,EAAE,YAAY,EAAE,GAC5B,IAAI,CAAC,cAAc,EAAE,SAAS,GAAG,mBAAmB,CAAC,CAkBvD;AAwBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,iBAAiB,EACtB,QAAQ,EAAE,sBAAsB,EAChC,SAAS,EAAE,gBAAgB,GAC1B,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,QAAQ,KAAK,OAAO,CAAC,cAAc,CAAC,CA6G9E"}

package/dist/mcp-server/tools/utils/toolHandlerFactory.js

@@ -5,12 +5,13 @@
  */
 import { ZodError } from 'zod';
 import { config } from '../../../config/index.js';
-import { attachTypedFail, createContext } from '../../../core/context.js';
+import { attachTypedFail, createContext, readEnrichmentStore } from '../../../core/context.js';
 import { withRequiredScopes } from '../../../mcp-server/transports/auth/lib/authUtils.js';
 import { McpError } from '../../../types-global/errors.js';
 import { ErrorHandler } from '../../../utils/internal/error-handler/errorHandler.js';
 import { measureToolExecution } from '../../../utils/internal/performance.js';
 import { requestContextService } from '../../../utils/internal/requestContext.js';
+import { ATTR_MCP_TOOL_ENRICHED } from '../../../utils/telemetry/attributes.js';
 // ---------------------------------------------------------------------------
 // Default formatter
 // ---------------------------------------------------------------------------
@@ -79,6 +80,110 @@ export function classifyAndBuildToolErrorResult(error) {
     return buildToolErrorResult(code, message, data);
 }
 // ---------------------------------------------------------------------------
+// Success response shaping — enrichment merge + trailer
+// ---------------------------------------------------------------------------
+/**
+ * The output schema advertised to clients in `tools/list`. When a tool declares
+ * an `enrichment` block, that's `output.extend(enrichment)` so enrichment fields
+ * appear in the advertised `outputSchema`; otherwise the bare `output`.
+ */
+export function effectiveOutputSchema(def) {
+    if (!def.enrichment)
+        return def.output;
+    return def.output.extend(def.enrichment);
+}
+/** Renders a non-kind-tagged enrichment value as compact trailer text. */
+function formatEnrichmentScalar(value) {
+    if (value == null)
+        return String(value);
+    if (typeof value === 'object')
+        return JSON.stringify(value);
+    return String(value);
+}
+/**
+ * Renders accumulated enrichment as a single `content[]` trailer block, so
+ * `content[]`-only clients see the same context `structuredContent` clients get
+ * from the merged output. Per field, rendering resolves in order:
+ *   1. a per-field `enrichmentTrailer.render` (the author's full control; wins
+ *      over everything — the escape hatch for structured fields that would
+ *      otherwise JSON-blob),
+ *   2. the kind-tag set by a field-helper (notice → blockquote, total →
+ *      "N total", echo → "Query: …", delta → "field: before → after"),
+ *   3. the generic `**key:** value` fallback (key overridable via `label`),
+ *      `JSON.stringify`-ing non-scalars.
+ *
+ * `parsed` is the validated effective output, so renderers receive the typed,
+ * post-parse value rather than the raw accumulator entry. The rendered markdown
+ * is appended to `content[]` only — `structuredContent` is built separately from
+ * the raw merged values and never carries this trailer text. Returns `[]` when
+ * nothing was enriched.
+ */
+function renderEnrichmentTrailer(store, trailer, parsed) {
+    const lines = [];
+    for (const key of Object.keys(store.values)) {
+        // Skip keys the effective-output parse stripped (enriched but not declared in
+        // the block) — the trailer mirrors what reached structuredContent.
+        if (!(key in parsed))
+            continue;
+        const value = parsed[key];
+        const cfg = trailer?.[key];
+        if (cfg?.render) {
+            lines.push(cfg.render(value));
+            continue;
+        }
+        switch (store.kinds.get(key)) {
+            case 'notice':
+                lines.push(`> ${String(value)}`);
+                break;
+            case 'total':
+                lines.push(`**${String(value)} total**`);
+                break;
+            case 'echo':
+                lines.push(`Query: ${String(value)}`);
+                break;
+            case 'delta': {
+                const d = (value ?? {});
+                lines.push(`**${cfg?.label ?? key}:** ${formatEnrichmentScalar(d.before)} → ${formatEnrichmentScalar(d.after)}`);
+                break;
+            }
+            default:
+                lines.push(`**${cfg?.label ?? key}:** ${formatEnrichmentScalar(value)}`);
+        }
+    }
+    return lines.length > 0 ? [{ type: 'text', text: lines.join('\n') }] : [];
+}
+/**
+ * Shapes the success `CallToolResult` surfaces from the validated domain payload
+ * plus any accumulated enrichment:
+ * - `structuredContent` — domain output merged with enrichment (validated against
+ *   `output.extend(enrichment)`); the bare domain output when no enrichment block.
+ * - `content[]` — the caller-rendered domain content (from `format()` or the
+ *   JSON-stringify default, applied to the **domain payload only**) with the
+ *   enrichment trailer always appended. Rendering the domain payload — never the
+ *   merged object — keeps enrichment out of the JSON blob and avoids double-render.
+ *
+ * A required enrichment field the handler never populated fails the parse here,
+ * surfacing the authoring bug as a loud error rather than dropping it silently.
+ */
+export function buildToolSuccessResult(def, ctx, domainValidated, domainContent) {
+    if (!def.enrichment) {
+        return { structuredContent: domainValidated, content: domainContent };
+    }
+    const store = readEnrichmentStore(ctx);
+    const values = store?.values ?? {};
+    const structuredContent = effectiveOutputSchema(def).parse({
+        ...domainValidated,
+        ...values,
+    });
+    const trailer = store && Object.keys(values).length > 0
+        ? renderEnrichmentTrailer(store, def.enrichmentTrailer, structuredContent)
+        : [];
+    return {
+        structuredContent,
+        content: trailer.length > 0 ? [...domainContent, ...trailer] : domainContent,
+    };
+}
+// ---------------------------------------------------------------------------
 // Capability detection helpers
 // ---------------------------------------------------------------------------
 function wrapElicit(sdkContext) {
@@ -165,20 +270,24 @@ export function createToolHandler(def, services, notifiers) {
             }), def.errors);
             // Execute handler with performance measurement.
             // Wrap with Promise.resolve — handler may return sync or async.
-            const result = await measureToolExecution(() => Promise.resolve(def.handler(validatedInput, ctx)), { ...appContext, toolName: def.name }, validatedInput);
+            const result = await measureToolExecution(() => Promise.resolve(def.handler(validatedInput, ctx)), { ...appContext, toolName: def.name }, validatedInput, () => {
+                const store = readEnrichmentStore(ctx);
+                return store && Object.keys(store.values).length > 0
+                    ? { [ATTR_MCP_TOOL_ENRICHED]: true }
+                    : {};
+            });
             const validatedResult = def.output.parse(result);
-            // Isolate formatter errors from handler errors so they get classified correctly
-            let content;
+            // Render content[] from the domain payload only (Resolution B). Isolate
+            // formatter errors from handler errors so they get classified correctly.
+            let domainContent;
             try {
-                content = formatter(validatedResult);
+                domainContent = formatter(validatedResult);
             }
             catch (formatError) {
                 throw new Error(`Output formatting failed: ${formatError instanceof Error ? formatError.message : String(formatError)}`);
             }
-            return {
-                structuredContent: validatedResult,
-                content,
-            };
+            // Merge enrichment into structuredContent and append the content[] trailer.
+            return buildToolSuccessResult(def, ctx, validatedResult, domainContent);
         }
         catch (error) {
             ErrorHandler.handleError(error, {

package/dist/mcp-server/tools/utils/toolHandlerFactory.js.map

@@ -1 +1 @@
-{"version":3,"file":"toolHandlerFactory.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/utils/toolHandlerFactory.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"toolHandlerFactory.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/utils/toolHandlerFactory.ts"],"names":[],"mappings":"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"}

package/dist/testing/index.d.ts

@@ -98,6 +98,19 @@ export declare function createMockLogger(): MockContextLogger;
  * ```
  */
 export declare function createMockContext(options?: MockContextOptions): Context;
+/**
+ * Reads the enrichment a handler accumulated via `ctx.enrich(...)` on a mock
+ * context, for assertions. Returns the merged field values (empty object when
+ * nothing was enriched).
+ *
+ * @example
+ * ```ts
+ * const ctx = createMockContext();
+ * await search.handler(search.input.parse({ query: 'x' }), ctx);
+ * expect(getEnrichment(ctx)).toMatchObject({ effectiveQuery: 'x', totalCount: 0 });
+ * ```
+ */
+export declare function getEnrichment(ctx: Context): Record<string, unknown>;
 /**
  * Build a real `StorageService` backed by an in-memory provider, suitable for
  * unit-testing services that accept a `StorageService` dependency.

package/dist/testing/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,mBAAmB,EACnB,YAAY,EACZ,eAAe,EAChB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,KAAK,EAAW,CAAC,EAAE,MAAM,KAAK,CAAC;AACtC,OAAO,KAAK,EACV,WAAW,EACX,OAAO,EACP,aAAa,EAGb,YAAY,EACb,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAClE,OAAO,EAEL,KAAK,uBAAuB,EAC7B,MAAM,kDAAkD,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAM9D,MAAM,WAAW,kBAAkB;IACjC,oBAAoB;IACpB,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,gCAAgC;IAChC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;IACxF;;;;;OAKG;IACH,MAAM,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IAClC,yCAAyC;IACzC,uBAAuB,CAAC,EAAE,MAAM,IAAI,CAAC;IACrC,2CAA2C;IAC3C,yBAAyB,CAAC,EAAE,MAAM,IAAI,CAAC;IACvC,sCAAsC;IACtC,qBAAqB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9C,uCAAuC;IACvC,qBAAqB,CAAC,EAAE,MAAM,IAAI,CAAC;IACnC,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6BAA6B;IAC7B,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE,eAAe,EAAE,EAAE,IAAI,CAAC,EAAE,YAAY,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAC5F;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wEAAwE;IACxE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iDAAiD;IACjD,GAAG,CAAC,EAAE,GAAG,CAAC;CACX;AAMD,iFAAiF;AACjF,MAAM,MAAM,iBAAiB,GAAG,aAAa,GAAG;IAC9C,mFAAmF;IACnF,KAAK,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CAC9D,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,IAAI,iBAAiB,CAiBpD;AAwGD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CA+B3E;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,CAAC,EAAE,uBAAuB,GAAG,cAAc,CAEvF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,mBAAmB,EACnB,YAAY,EACZ,eAAe,EAChB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,KAAK,EAAW,CAAC,EAAE,MAAM,KAAK,CAAC;AACtC,OAAO,KAAK,EACV,WAAW,EACX,OAAO,EACP,aAAa,EAGb,YAAY,EACb,MAAM,mBAAmB,CAAC;AAQ3B,OAAO,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAClE,OAAO,EAEL,KAAK,uBAAuB,EAC7B,MAAM,kDAAkD,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAM9D,MAAM,WAAW,kBAAkB;IACjC,oBAAoB;IACpB,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,gCAAgC;IAChC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;IACxF;;;;;OAKG;IACH,MAAM,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IAClC,yCAAyC;IACzC,uBAAuB,CAAC,EAAE,MAAM,IAAI,CAAC;IACrC,2CAA2C;IAC3C,yBAAyB,CAAC,EAAE,MAAM,IAAI,CAAC;IACvC,sCAAsC;IACtC,qBAAqB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9C,uCAAuC;IACvC,qBAAqB,CAAC,EAAE,MAAM,IAAI,CAAC;IACnC,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6BAA6B;IAC7B,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE,eAAe,EAAE,EAAE,IAAI,CAAC,EAAE,YAAY,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAC5F;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wEAAwE;IACxE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iDAAiD;IACjD,GAAG,CAAC,EAAE,GAAG,CAAC;CACX;AAMD,iFAAiF;AACjF,MAAM,MAAM,iBAAiB,GAAG,aAAa,GAAG;IAC9C,mFAAmF;IACnF,KAAK,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CAC9D,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,IAAI,iBAAiB,CAiBpD;AAwGD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAsC3E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEnE;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,CAAC,EAAE,uBAAuB,GAAG,cAAc,CAEvF"}

package/dist/testing/index.js

@@ -5,7 +5,7 @@
  * `createInMemoryStorage()` for unit-testing services in isolation.
  * @module src/testing/index
  */
-import { attachTypedFail } from '../core/context.js';
+import { attachTypedFail, createEnrich, createEnrichmentStore, readEnrichmentStore, stashEnrichmentStore, } from '../core/context.js';
 import { StorageService } from '../storage/core/StorageService.js';
 import { InMemoryProvider, } from '../storage/providers/inMemory/inMemoryProvider.js';
 /**
@@ -157,6 +157,7 @@ export function createMockContext(options = {}) {
     const log = createMockLogger();
     const state = createMockState(options.tenantId);
     const progress = options.progress ? createMockProgress() : undefined;
+    const enrichmentStore = createEnrichmentStore();
     const ctx = {
         requestId: options.requestId ?? 'test-request-id',
         timestamp: new Date().toISOString(),
@@ -174,15 +175,34 @@ export function createMockContext(options = {}) {
         notifyToolListChanged: options.notifyToolListChanged,
         progress,
         uri: options.uri,
+        enrich: createEnrich(enrichmentStore),
         // No-op resolver for definitions without a contract. `attachTypedFail` below
         // overwrites it with a contract-aware resolver when `options.errors` is set.
         recoveryFor: () => ({}),
     };
+    // Stash the enrichment store so `getEnrichment(ctx)` can read what a handler
+    // (or the service layer) accumulated via `ctx.enrich(...)` during the test.
+    stashEnrichmentStore(ctx, enrichmentStore);
     // Mirror the production handler factory: when a contract is declared, attach
     // a typed `fail` and `recoveryFor` keyed by the contract's reasons. Empty
     // contracts leave the no-op resolver in place.
     return attachTypedFail(ctx, options.errors);
 }
+/**
+ * Reads the enrichment a handler accumulated via `ctx.enrich(...)` on a mock
+ * context, for assertions. Returns the merged field values (empty object when
+ * nothing was enriched).
+ *
+ * @example
+ * ```ts
+ * const ctx = createMockContext();
+ * await search.handler(search.input.parse({ query: 'x' }), ctx);
+ * expect(getEnrichment(ctx)).toMatchObject({ effectiveQuery: 'x', totalCount: 0 });
+ * ```
+ */
+export function getEnrichment(ctx) {
+    return readEnrichmentStore(ctx)?.values ?? {};
+}
 // ---------------------------------------------------------------------------
 // Storage helpers
 // ---------------------------------------------------------------------------

package/dist/testing/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"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"}

package/dist/utils/internal/performance.d.ts

@@ -63,11 +63,15 @@ export declare const nowMs: () => number;
  * @param toolLogicFn - Zero-argument async function containing the tool's business logic.
  * @param context - Request context extended with `toolName`; used for span/log correlation.
  * @param inputPayload - The raw input object passed to the tool, serialized to compute byte size.
+ * @param successAttributes - Optional thunk evaluated after a successful run; its
+ *   returned key/value map is set on the span as extra attributes. Lets callers
+ *   attach post-hoc signals (e.g. `mcp.tool.enriched`) without coupling this
+ *   function to their domain. Not called on the error path.
  * @returns A promise that resolves with the tool's return value or rejects with the original error.
  */
 export declare function measureToolExecution<T>(toolLogicFn: () => Promise<T>, context: RequestContext & {
     toolName: string;
-}, inputPayload: unknown): Promise<T>;
+}, inputPayload: unknown, successAttributes?: () => Record<string, boolean | number | string>): Promise<T>;
 /**
  * Wraps a resource handler with observability: OTel span, metric counters/histogram,
  * and a structured log. Mirrors {@link measureToolExecution} but tuned for resource reads.

package/dist/utils/internal/performance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"performance.d.ts","sourceRoot":"","sources":["../../../src/utils/internal/performance.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,WAAW,IAAI,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAO3E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AA8DzE,kGAAkG;AAClG,wBAAgB,kBAAkB,IAAI,IAAI,CAKzC;AAcD;;;;;;GAMG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC;IAC7C,WAAW,EAAE,OAAO,oBAAoB,CAAC;CAC1C,CAAC,CAID;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,gBAAgB,CACpC,UAAU,GAAE,OAAO,aAA6B,GAC/C,OAAO,CAAC,IAAI,CAAC,CAmBf;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,KAAK,QAAO,MAA0B,CAAC;AAuFpD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,oBAAoB,CAAC,CAAC,EAC1C,WAAW,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC7B,OAAO,EAAE,cAAc,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,EAC9C,YAAY,EAAE,OAAO,GACpB,OAAO,CAAC,CAAC,CAAC,CAmHZ;AAoCD;;;;;;;;;GASG;AACH,wBAAsB,wBAAwB,CAAC,CAAC,EAC9C,eAAe,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACjC,OAAO,EAAE,cAAc,GAAG;IAAE,YAAY,EAAE,MAAM,CAAA;CAAE,EAClD,IAAI,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACtC,OAAO,CAAC,CAAC,CAAC,CA8EZ;AAkDD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,uBAAuB,CAAC,CAAC,EAC7C,aAAa,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC/B,OAAO,EAAE,cAAc,GAAG;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,EAChD,YAAY,EAAE,OAAO,GACpB,OAAO,CAAC,CAAC,CAAC,CA8FZ"}
+{"version":3,"file":"performance.d.ts","sourceRoot":"","sources":["../../../src/utils/internal/performance.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,WAAW,IAAI,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAO3E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AA8DzE,kGAAkG;AAClG,wBAAgB,kBAAkB,IAAI,IAAI,CAKzC;AAcD;;;;;;GAMG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC;IAC7C,WAAW,EAAE,OAAO,oBAAoB,CAAC;CAC1C,CAAC,CAID;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,gBAAgB,CACpC,UAAU,GAAE,OAAO,aAA6B,GAC/C,OAAO,CAAC,IAAI,CAAC,CAmBf;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,KAAK,QAAO,MAA0B,CAAC;AAuFpD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,oBAAoB,CAAC,CAAC,EAC1C,WAAW,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC7B,OAAO,EAAE,cAAc,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,EAC9C,YAAY,EAAE,OAAO,EACrB,iBAAiB,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC,GAClE,OAAO,CAAC,CAAC,CAAC,CAwHZ;AAoCD;;;;;;;;;GASG;AACH,wBAAsB,wBAAwB,CAAC,CAAC,EAC9C,eAAe,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACjC,OAAO,EAAE,cAAc,GAAG;IAAE,YAAY,EAAE,MAAM,CAAA;CAAE,EAClD,IAAI,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACtC,OAAO,CAAC,CAAC,CAAC,CA8EZ;AAkDD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,uBAAuB,CAAC,CAAC,EAC7C,aAAa,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC/B,OAAO,EAAE,cAAc,GAAG;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,EAChD,YAAY,EAAE,OAAO,GACpB,OAAO,CAAC,CAAC,CAAC,CA8FZ"}

package/dist/utils/internal/performance.js

@@ -203,9 +203,13 @@ const toBytes = (payload) => {
  * @param toolLogicFn - Zero-argument async function containing the tool's business logic.
  * @param context - Request context extended with `toolName`; used for span/log correlation.
  * @param inputPayload - The raw input object passed to the tool, serialized to compute byte size.
+ * @param successAttributes - Optional thunk evaluated after a successful run; its
+ *   returned key/value map is set on the span as extra attributes. Lets callers
+ *   attach post-hoc signals (e.g. `mcp.tool.enriched`) without coupling this
+ *   function to their domain. Not called on the error path.
  * @returns A promise that resolves with the tool's return value or rejects with the original error.
  */
-export async function measureToolExecution(toolLogicFn, context, inputPayload) {
+export async function measureToolExecution(toolLogicFn, context, inputPayload, successAttributes) {
     const tracer = trace.getTracer(config.openTelemetry.serviceName, config.openTelemetry.serviceVersion);
     const { toolName } = context;
     return await tracer.startActiveSpan(`tool_execution:${toolName}`, async (span) => {
@@ -249,6 +253,11 @@ export async function measureToolExecution(toolLogicFn, context, inputPayload) {
                 if (batchSucceeded !== undefined)
                     span.setAttribute(ATTR_MCP_TOOL_BATCH_SUCCEEDED, batchSucceeded);
             }
+            if (successAttributes) {
+                for (const [key, value] of Object.entries(successAttributes())) {
+                    span.setAttribute(key, value);
+                }
+            }
             return result;
         }
         catch (err) {