@fgv/ts-extras-mcp 5.1.0-36 → 5.1.0-39

package/dist/ts-extras-mcp.d.ts

@@ -232,6 +232,31 @@ export declare interface IMcpStdioTransportParams {
     readonly cwd?: string;
 }
 
+/**
+ * Normalized MCP `Tool.annotations` — the five known host-advisory behavior hints.
+ *
+ * @remarks
+ * Field names mirror MCP's `ToolAnnotations` 1:1 (and map straight onto
+ * `AiAssist.IAiToolAnnotations`). Per the MCP spec these are hints only, and per the
+ * untrusted-server warning they are validated/normalized (known fields kept, malformed
+ * or unknown fields dropped) before they reach {@link IMcpToolDescriptor} — the raw
+ * server blob is never propagated.
+ *
+ * @public
+ */
+export declare interface IMcpToolAnnotations {
+    /** Optional human-readable display title for the tool. */
+    readonly title?: string;
+    /** Hint: the tool does not modify its environment (read-only). */
+    readonly readOnlyHint?: boolean;
+    /** Hint: the tool may perform destructive updates (only meaningful when not read-only). */
+    readonly destructiveHint?: boolean;
+    /** Hint: repeated calls with the same arguments have no additional effect. */
+    readonly idempotentHint?: boolean;
+    /** Hint: the tool interacts with an open world of external entities. */
+    readonly openWorldHint?: boolean;
+}
+
 /**
  * Successful projection of an MCP `CallToolResult` produced by {@link callMcpTool}.
  *
@@ -264,6 +289,12 @@ export declare interface IMcpToolDescriptor {
      * supported subset).
      */
     readonly inputSchema: JsonValue;
+    /**
+     * The tool's normalized behavior annotations, when the server provided any usable ones.
+     * Absent when the server declared no annotations (or only malformed/unknown fields).
+     * See {@link IMcpToolAnnotations}.
+     */
+    readonly annotations?: IMcpToolAnnotations;
 }
 
 /**

package/dist/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.58.7"
+      "packageVersion": "7.58.9"
     }
   ]
 }

package/etc/ts-extras-mcp.api.md

@@ -81,6 +81,15 @@ export interface IMcpStdioTransportParams {
     readonly env?: Record<string, string>;
 }
 
+// @public
+export interface IMcpToolAnnotations {
+    readonly destructiveHint?: boolean;
+    readonly idempotentHint?: boolean;
+    readonly openWorldHint?: boolean;
+    readonly readOnlyHint?: boolean;
+    readonly title?: string;
+}
+
 // @public
 export interface IMcpToolCallResult {
     readonly content: string;
@@ -88,6 +97,7 @@ export interface IMcpToolCallResult {
 
 // @public
 export interface IMcpToolDescriptor {
+    readonly annotations?: IMcpToolAnnotations;
     readonly description: string | undefined;
     readonly inputSchema: JsonValue;
     readonly name: string;

package/lib/packlets/mcp/adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../src/packlets/mcp/adapter.ts"],"names":[],"mappings":"AAsBA;;;;;GAKG;AAEH,OAAO,EAAE,KAAK,MAAM,EAAW,MAAM,eAAe,CAAC;AAIrD,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,WAAW,EAGjB,MAAM,SAAS,CAAC;AA+DjB;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,WAAW,EACpB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC,CAuBvC"}
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../src/packlets/mcp/adapter.ts"],"names":[],"mappings":"AAsBA;;;;;GAKG;AAEH,OAAO,EAAE,KAAK,MAAM,EAAW,MAAM,eAAe,CAAC;AAIrD,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,WAAW,EAGjB,MAAM,SAAS,CAAC;AAkEjB;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,WAAW,EACpB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC,CAuBvC"}

package/lib/packlets/mcp/adapter.js

@@ -53,7 +53,7 @@ function _makeExecute(session, name) {
  * tool's `inputSchema` is not a JSON object or is outside the `JsonSchema.fromJson` subset.
  */
 function _adaptOne(session, descriptor) {
-    const { name, description, inputSchema } = descriptor;
+    const { name, description, inputSchema, annotations } = descriptor;
     const skip = (reason, schema) => ({
         kind: 'skipped',
         skipped: { name, reason, schema }
@@ -66,12 +66,7 @@ function _adaptOne(session, descriptor) {
     if (schemaResult.isFailure()) {
         return skip(schemaResult.message, inputSchema);
     }
-    const config = {
-        type: 'client_tool',
-        name,
-        description: description !== null && description !== void 0 ? description : name,
-        parametersSchema: schemaResult.value
-    };
+    const config = Object.assign({ type: 'client_tool', name, description: description !== null && description !== void 0 ? description : name, parametersSchema: schemaResult.value }, (annotations !== undefined ? { annotations } : {}));
     return {
         kind: 'tool',
         tool: { config, execute: _makeExecute(session, name) }

package/lib/packlets/mcp/adapter.js.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../../../src/packlets/mcp/adapter.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\n/**\n * The headline adapter — discovers an MCP server's tools and adapts each into an\n * `AiAssist.IAiClientTool`, gracefully degrading (Constraint 1) on any tool whose `inputSchema`\n * is outside the JSON Schema subset that `JsonSchema.fromJson` supports.\n * @packageDocumentation\n */\n\nimport { type Result, succeed } from '@fgv/ts-utils';\nimport { AiAssist } from '@fgv/ts-extras';\nimport { Converters, JsonSchema, type JsonValue } from '@fgv/ts-json-base';\n\nimport {\n  type IAdaptMcpToolsOptions,\n  type IAdaptMcpToolsResult,\n  type IMcpSession,\n  type IMcpSkippedTool,\n  type IMcpToolDescriptor\n} from './model';\nimport { callMcpTool, listMcpTools } from './operations';\n\n/**\n * Per-tool adaptation outcome: either an adapted client tool, or a structurally-surfaced skip.\n * `adaptMcpTools` never short-circuits on a skip — degradation is structural, not a failure.\n */\ntype IAdaptOutcome =\n  | { readonly kind: 'tool'; readonly tool: AiAssist.IAiClientTool }\n  | { readonly kind: 'skipped'; readonly skipped: IMcpSkippedTool };\n\n/**\n * Builds the `execute` callback for an adapted MCP tool. Args arrive already validated against\n * the tool's `parametersSchema` by `executeClientToolTurn`; here we narrow to a `JsonObject`\n * (MCP arguments are always an object) and forward to {@link callMcpTool}, returning the\n * projected text content. A tool error surfaces as a `Failure` (never swallowed).\n */\nfunction _makeExecute(session: IMcpSession, name: string): (args: unknown) => Promise<Result<unknown>> {\n  return async (args: unknown): Promise<Result<unknown>> => {\n    const objResult = Converters.jsonObject\n      .convert(args)\n      .withErrorFormat((msg) => `tool '${name}': arguments must be a JSON object: ${msg}`);\n    if (objResult.isFailure()) {\n      return objResult;\n    }\n    return (await callMcpTool(session, name, objResult.value)).onSuccess((called) => succeed(called.content));\n  };\n}\n\n/**\n * Adapts a single discovered tool. Returns a `skipped` outcome (never a failure) when the\n * tool's `inputSchema` is not a JSON object or is outside the `JsonSchema.fromJson` subset.\n */\nfunction _adaptOne(session: IMcpSession, descriptor: IMcpToolDescriptor): IAdaptOutcome {\n  const { name, description, inputSchema } = descriptor;\n\n  const skip = (reason: string, schema: JsonValue): IAdaptOutcome => ({\n    kind: 'skipped',\n    skipped: { name, reason, schema }\n  });\n\n  const asObject = Converters.jsonObject.convert(inputSchema);\n  if (asObject.isFailure()) {\n    return skip(`inputSchema is not a JSON object (${asObject.message})`, inputSchema);\n  }\n\n  const schemaResult = JsonSchema.fromJson(asObject.value);\n  if (schemaResult.isFailure()) {\n    return skip(schemaResult.message, inputSchema);\n  }\n\n  const config: AiAssist.IAiClientToolConfig = {\n    type: 'client_tool',\n    name,\n    description: description ?? name,\n    parametersSchema: schemaResult.value\n  };\n  return {\n    kind: 'tool',\n    tool: { config, execute: _makeExecute(session, name) }\n  };\n}\n\n/**\n * Discovers an MCP server's tools and adapts each into an `AiAssist.IAiClientTool` that drops\n * directly into `AiAssist.executeClientToolTurn`.\n *\n * @remarks\n * **Constraint 1 — graceful degradation with NOISY warnings.** A tool whose `inputSchema` is\n * outside the JSON Schema subset supported by `JsonSchema.fromJson` is NOT adapted (the model\n * must never be offered a tool whose args we can't validate). Instead it is:\n * 1. excluded from {@link IAdaptMcpToolsResult.tools};\n * 2. surfaced structurally on {@link IAdaptMcpToolsResult.skipped} with the tool name, the\n *    JSON-pointer reason, and the raw failing schema; and\n * 3. logged as a NOISY `warning` (name + reason + raw schema) when an `options.logger` is\n *    supplied — so pointing this at a new server immediately reveals every subset feature to\n *    extend, with the schema in hand.\n *\n * The whole catalog never fails on a single bad schema; the only failure mode is an upstream\n * `listMcpTools` error.\n *\n * @param session - A connected session from `connectMcpSession`.\n * @param options - Optional logger for the NOISY skip warnings.\n * @returns `Success` with `{ tools, skipped }`, or `Failure` only if tool discovery fails.\n * @public\n */\nexport async function adaptMcpTools(\n  session: IMcpSession,\n  options?: IAdaptMcpToolsOptions\n): Promise<Result<IAdaptMcpToolsResult>> {\n  return (await listMcpTools(session))\n    .onSuccess((descriptors) => {\n      const tools: AiAssist.IAiClientTool[] = [];\n      const skipped: IMcpSkippedTool[] = [];\n\n      for (const descriptor of descriptors) {\n        const outcome = _adaptOne(session, descriptor);\n        if (outcome.kind === 'tool') {\n          tools.push(outcome.tool);\n        } else {\n          skipped.push(outcome.skipped);\n          options?.logger?.warn(\n            `mcp: skipping tool '${outcome.skipped.name}': inputSchema is outside the supported ` +\n              `JSON Schema subset: ${outcome.skipped.reason}. ` +\n              `Raw schema: ${JSON.stringify(outcome.skipped.schema)}`\n          );\n        }\n      }\n\n      return succeed<IAdaptMcpToolsResult>({ tools, skipped });\n    })\n    .withErrorFormat((msg) => `adaptMcpTools: ${msg}`);\n}\n"]}
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../../../src/packlets/mcp/adapter.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;AA4GH,sCA0BC;AApID;;;;;GAKG;AAEH,4CAAqD;AAErD,oDAA2E;AAS3E,6CAAyD;AAUzD;;;;;GAKG;AACH,SAAS,YAAY,CAAC,OAAoB,EAAE,IAAY;IACtD,OAAO,KAAK,EAAE,IAAa,EAA4B,EAAE;QACvD,MAAM,SAAS,GAAG,yBAAU,CAAC,UAAU;aACpC,OAAO,CAAC,IAAI,CAAC;aACb,eAAe,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,SAAS,IAAI,uCAAuC,GAAG,EAAE,CAAC,CAAC;QACvF,IAAI,SAAS,CAAC,SAAS,EAAE,EAAE,CAAC;YAC1B,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,OAAO,CAAC,MAAM,IAAA,wBAAW,EAAC,OAAO,EAAE,IAAI,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,IAAA,kBAAO,EAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;IAC5G,CAAC,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,SAAS,SAAS,CAAC,OAAoB,EAAE,UAA8B;IACrE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,WAAW,EAAE,WAAW,EAAE,GAAG,UAAU,CAAC;IAEnE,MAAM,IAAI,GAAG,CAAC,MAAc,EAAE,MAAiB,EAAiB,EAAE,CAAC,CAAC;QAClE,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE;KAClC,CAAC,CAAC;IAEH,MAAM,QAAQ,GAAG,yBAAU,CAAC,UAAU,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAC5D,IAAI,QAAQ,CAAC,SAAS,EAAE,EAAE,CAAC;QACzB,OAAO,IAAI,CAAC,qCAAqC,QAAQ,CAAC,OAAO,GAAG,EAAE,WAAW,CAAC,CAAC;IACrF,CAAC;IAED,MAAM,YAAY,GAAG,yBAAU,CAAC,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IACzD,IAAI,YAAY,CAAC,SAAS,EAAE,EAAE,CAAC;QAC7B,OAAO,IAAI,CAAC,YAAY,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;IACjD,CAAC;IAED,MAAM,MAAM,mBACV,IAAI,EAAE,aAAa,EACnB,IAAI,EACJ,WAAW,EAAE,WAAW,aAAX,WAAW,cAAX,WAAW,GAAI,IAAI,EAChC,gBAAgB,EAAE,YAAY,CAAC,KAAK,IAGjC,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CACtD,CAAC;IACF,OAAO;QACL,IAAI,EAAE,MAAM;QACZ,IAAI,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE;KACvD,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACI,KAAK,UAAU,aAAa,CACjC,OAAoB,EACpB,OAA+B;IAE/B,OAAO,CAAC,MAAM,IAAA,yBAAY,EAAC,OAAO,CAAC,CAAC;SACjC,SAAS,CAAC,CAAC,WAAW,EAAE,EAAE;;QACzB,MAAM,KAAK,GAA6B,EAAE,CAAC;QAC3C,MAAM,OAAO,GAAsB,EAAE,CAAC;QAEtC,KAAK,MAAM,UAAU,IAAI,WAAW,EAAE,CAAC;YACrC,MAAM,OAAO,GAAG,SAAS,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;YAC/C,IAAI,OAAO,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;gBAC5B,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YAC3B,CAAC;iBAAM,CAAC;gBACN,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;gBAC9B,MAAA,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,MAAM,0CAAE,IAAI,CACnB,uBAAuB,OAAO,CAAC,OAAO,CAAC,IAAI,0CAA0C;oBACnF,uBAAuB,OAAO,CAAC,OAAO,CAAC,MAAM,IAAI;oBACjD,eAAe,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAC1D,CAAC;YACJ,CAAC;QACH,CAAC;QAED,OAAO,IAAA,kBAAO,EAAuB,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC;IAC3D,CAAC,CAAC;SACD,eAAe,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,kBAAkB,GAAG,EAAE,CAAC,CAAC;AACvD,CAAC","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\n/**\n * The headline adapter — discovers an MCP server's tools and adapts each into an\n * `AiAssist.IAiClientTool`, gracefully degrading (Constraint 1) on any tool whose `inputSchema`\n * is outside the JSON Schema subset that `JsonSchema.fromJson` supports.\n * @packageDocumentation\n */\n\nimport { type Result, succeed } from '@fgv/ts-utils';\nimport { AiAssist } from '@fgv/ts-extras';\nimport { Converters, JsonSchema, type JsonValue } from '@fgv/ts-json-base';\n\nimport {\n  type IAdaptMcpToolsOptions,\n  type IAdaptMcpToolsResult,\n  type IMcpSession,\n  type IMcpSkippedTool,\n  type IMcpToolDescriptor\n} from './model';\nimport { callMcpTool, listMcpTools } from './operations';\n\n/**\n * Per-tool adaptation outcome: either an adapted client tool, or a structurally-surfaced skip.\n * `adaptMcpTools` never short-circuits on a skip — degradation is structural, not a failure.\n */\ntype IAdaptOutcome =\n  | { readonly kind: 'tool'; readonly tool: AiAssist.IAiClientTool }\n  | { readonly kind: 'skipped'; readonly skipped: IMcpSkippedTool };\n\n/**\n * Builds the `execute` callback for an adapted MCP tool. Args arrive already validated against\n * the tool's `parametersSchema` by `executeClientToolTurn`; here we narrow to a `JsonObject`\n * (MCP arguments are always an object) and forward to {@link callMcpTool}, returning the\n * projected text content. A tool error surfaces as a `Failure` (never swallowed).\n */\nfunction _makeExecute(session: IMcpSession, name: string): (args: unknown) => Promise<Result<unknown>> {\n  return async (args: unknown): Promise<Result<unknown>> => {\n    const objResult = Converters.jsonObject\n      .convert(args)\n      .withErrorFormat((msg) => `tool '${name}': arguments must be a JSON object: ${msg}`);\n    if (objResult.isFailure()) {\n      return objResult;\n    }\n    return (await callMcpTool(session, name, objResult.value)).onSuccess((called) => succeed(called.content));\n  };\n}\n\n/**\n * Adapts a single discovered tool. Returns a `skipped` outcome (never a failure) when the\n * tool's `inputSchema` is not a JSON object or is outside the `JsonSchema.fromJson` subset.\n */\nfunction _adaptOne(session: IMcpSession, descriptor: IMcpToolDescriptor): IAdaptOutcome {\n  const { name, description, inputSchema, annotations } = descriptor;\n\n  const skip = (reason: string, schema: JsonValue): IAdaptOutcome => ({\n    kind: 'skipped',\n    skipped: { name, reason, schema }\n  });\n\n  const asObject = Converters.jsonObject.convert(inputSchema);\n  if (asObject.isFailure()) {\n    return skip(`inputSchema is not a JSON object (${asObject.message})`, inputSchema);\n  }\n\n  const schemaResult = JsonSchema.fromJson(asObject.value);\n  if (schemaResult.isFailure()) {\n    return skip(schemaResult.message, inputSchema);\n  }\n\n  const config: AiAssist.IAiClientToolConfig = {\n    type: 'client_tool',\n    name,\n    description: description ?? name,\n    parametersSchema: schemaResult.value,\n    // IMcpToolAnnotations maps 1:1 onto AiAssist.IAiToolAnnotations. Only set the field when the\n    // server provided usable annotations, so a tool without them stays exactly as before.\n    ...(annotations !== undefined ? { annotations } : {})\n  };\n  return {\n    kind: 'tool',\n    tool: { config, execute: _makeExecute(session, name) }\n  };\n}\n\n/**\n * Discovers an MCP server's tools and adapts each into an `AiAssist.IAiClientTool` that drops\n * directly into `AiAssist.executeClientToolTurn`.\n *\n * @remarks\n * **Constraint 1 — graceful degradation with NOISY warnings.** A tool whose `inputSchema` is\n * outside the JSON Schema subset supported by `JsonSchema.fromJson` is NOT adapted (the model\n * must never be offered a tool whose args we can't validate). Instead it is:\n * 1. excluded from {@link IAdaptMcpToolsResult.tools};\n * 2. surfaced structurally on {@link IAdaptMcpToolsResult.skipped} with the tool name, the\n *    JSON-pointer reason, and the raw failing schema; and\n * 3. logged as a NOISY `warning` (name + reason + raw schema) when an `options.logger` is\n *    supplied — so pointing this at a new server immediately reveals every subset feature to\n *    extend, with the schema in hand.\n *\n * The whole catalog never fails on a single bad schema; the only failure mode is an upstream\n * `listMcpTools` error.\n *\n * @param session - A connected session from `connectMcpSession`.\n * @param options - Optional logger for the NOISY skip warnings.\n * @returns `Success` with `{ tools, skipped }`, or `Failure` only if tool discovery fails.\n * @public\n */\nexport async function adaptMcpTools(\n  session: IMcpSession,\n  options?: IAdaptMcpToolsOptions\n): Promise<Result<IAdaptMcpToolsResult>> {\n  return (await listMcpTools(session))\n    .onSuccess((descriptors) => {\n      const tools: AiAssist.IAiClientTool[] = [];\n      const skipped: IMcpSkippedTool[] = [];\n\n      for (const descriptor of descriptors) {\n        const outcome = _adaptOne(session, descriptor);\n        if (outcome.kind === 'tool') {\n          tools.push(outcome.tool);\n        } else {\n          skipped.push(outcome.skipped);\n          options?.logger?.warn(\n            `mcp: skipping tool '${outcome.skipped.name}': inputSchema is outside the supported ` +\n              `JSON Schema subset: ${outcome.skipped.reason}. ` +\n              `Raw schema: ${JSON.stringify(outcome.skipped.schema)}`\n          );\n        }\n      }\n\n      return succeed<IAdaptMcpToolsResult>({ tools, skipped });\n    })\n    .withErrorFormat((msg) => `adaptMcpTools: ${msg}`);\n}\n"]}

package/lib/packlets/mcp/model.d.ts

@@ -82,6 +82,30 @@ export interface IMcpSession {
     /** Server identity reported by the handshake, when the server provided one. */
     readonly serverInfo: IMcpServerInfo | undefined;
 }
+/**
+ * Normalized MCP `Tool.annotations` — the five known host-advisory behavior hints.
+ *
+ * @remarks
+ * Field names mirror MCP's `ToolAnnotations` 1:1 (and map straight onto
+ * `AiAssist.IAiToolAnnotations`). Per the MCP spec these are hints only, and per the
+ * untrusted-server warning they are validated/normalized (known fields kept, malformed
+ * or unknown fields dropped) before they reach {@link IMcpToolDescriptor} — the raw
+ * server blob is never propagated.
+ *
+ * @public
+ */
+export interface IMcpToolAnnotations {
+    /** Optional human-readable display title for the tool. */
+    readonly title?: string;
+    /** Hint: the tool does not modify its environment (read-only). */
+    readonly readOnlyHint?: boolean;
+    /** Hint: the tool may perform destructive updates (only meaningful when not read-only). */
+    readonly destructiveHint?: boolean;
+    /** Hint: repeated calls with the same arguments have no additional effect. */
+    readonly idempotentHint?: boolean;
+    /** Hint: the tool interacts with an open world of external entities. */
+    readonly openWorldHint?: boolean;
+}
 /**
  * A tool descriptor discovered from an MCP server via {@link listMcpTools}.
  * @public
@@ -98,6 +122,12 @@ export interface IMcpToolDescriptor {
      * supported subset).
      */
     readonly inputSchema: JsonValue;
+    /**
+     * The tool's normalized behavior annotations, when the server provided any usable ones.
+     * Absent when the server declared no annotations (or only malformed/unknown fields).
+     * See {@link IMcpToolAnnotations}.
+     */
+    readonly annotations?: IMcpToolAnnotations;
 }
 /**
  * Successful projection of an MCP `CallToolResult` produced by {@link callMcpTool}.

package/lib/packlets/mcp/model.d.ts.map

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

package/lib/packlets/mcp/model.js.map

@@ -1 +1 @@
-{"version":3,"file":"model.js","sourceRoot":"","sources":["../../../src/packlets/mcp/model.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\n/**\n * Public types for the MCP → ai-assist client-tools boundary.\n * @packageDocumentation\n */\n\nimport { type Logging } from '@fgv/ts-utils';\nimport { type AiAssist } from '@fgv/ts-extras';\nimport { type JsonValue } from '@fgv/ts-json-base';\n\n// ============================================================================\n// Transport\n// ============================================================================\n\n/**\n * Parameters for {@link createStdioTransport}. The transport spawns `command` as a\n * subprocess and speaks MCP over its stdin/stdout.\n *\n * @remarks\n * **Security:** stdio transport executes a consumer-supplied command. Treat `command`/`args`\n * as a trust boundary — never source them from untrusted input. See the package README.\n *\n * @public\n */\nexport interface IMcpStdioTransportParams {\n  /** Executable to spawn (e.g. `'npx'`, `'node'`, an absolute path). */\n  readonly command: string;\n  /** Arguments passed to the command. */\n  readonly args?: ReadonlyArray<string>;\n  /** Environment variables for the spawned process. When omitted, the SDK's safe default set is used. */\n  readonly env?: Record<string, string>;\n  /** Working directory for the spawned process. */\n  readonly cwd?: string;\n}\n\n/**\n * Parameters for {@link createHttpTransport}. The transport connects to a Streamable-HTTP MCP\n * endpoint.\n * @public\n */\nexport interface IMcpHttpTransportParams {\n  /** Absolute `http`/`https` URL of the MCP server endpoint. */\n  readonly url: string;\n  /** Optional static headers (e.g. an `Authorization` bearer token). OAuth/managed auth is out of scope at v0.1. */\n  readonly headers?: Record<string, string>;\n}\n\n/**\n * Opaque handle to an MCP transport produced by {@link createStdioTransport} or\n * {@link createHttpTransport}. Hand it to {@link connectMcpSession}; do not construct directly.\n * @public\n */\nexport interface IMcpTransport {\n  /** Which transport kind this handle wraps. */\n  readonly transportKind: 'stdio' | 'http';\n}\n\n// ============================================================================\n// Session\n// ============================================================================\n\n/**\n * Parameters for {@link connectMcpSession}.\n * @public\n */\nexport interface IConnectMcpSessionParams {\n  /** A transport produced by {@link createStdioTransport} / {@link createHttpTransport}. */\n  readonly transport: IMcpTransport;\n  /** Client name advertised to the server during the initialize handshake. Default `'@fgv/ts-extras-mcp'`. */\n  readonly clientName?: string;\n  /** Client version advertised to the server. Default the package version. */\n  readonly clientVersion?: string;\n  /** Optional logger for connection diagnostics. */\n  readonly logger?: Logging.ILogger;\n}\n\n/**\n * Server identity reported during the MCP initialize handshake.\n * @public\n */\nexport interface IMcpServerInfo {\n  /** Server-advertised name. */\n  readonly name: string;\n  /** Server-advertised version. */\n  readonly version: string;\n}\n\n/**\n * Opaque handle to a connected MCP session. Pass it to {@link listMcpTools},\n * {@link callMcpTool}, {@link adaptMcpTools}, and {@link closeMcpSession}.\n * @public\n */\nexport interface IMcpSession {\n  /** Client name advertised during the handshake. */\n  readonly clientName: string;\n  /** Client version advertised during the handshake. */\n  readonly clientVersion: string;\n  /** Server identity reported by the handshake, when the server provided one. */\n  readonly serverInfo: IMcpServerInfo | undefined;\n}\n\n// ============================================================================\n// Tool discovery + invocation\n// ============================================================================\n\n/**\n * A tool descriptor discovered from an MCP server via {@link listMcpTools}.\n * @public\n */\nexport interface IMcpToolDescriptor {\n  /** Tool name (unique within a server). */\n  readonly name: string;\n  /** Human-readable description, when the server provided one. */\n  readonly description: string | undefined;\n  /**\n   * The tool's declared input schema as raw JSON. Per the MCP spec this is normally a JSON\n   * Schema object; carried verbatim so {@link adaptMcpTools} can run it through\n   * `JsonSchema.fromJson` (and surface it on {@link IMcpSkippedTool} when it is outside the\n   * supported subset).\n   */\n  readonly inputSchema: JsonValue;\n}\n\n/**\n * Successful projection of an MCP `CallToolResult` produced by {@link callMcpTool}.\n *\n * @remarks\n * `content` is the text concatenation of the result's `text` blocks; non-text blocks\n * (image / audio / resource) are projected to a one-line `[<type> block]` summary\n * (multimodal passthrough is out of scope at v0.1). A result with `isError: true` is mapped\n * to `Result.fail(content)` rather than returned here, so it is never silently swallowed.\n *\n * @public\n */\nexport interface IMcpToolCallResult {\n  /** The projected text content of the tool result. */\n  readonly content: string;\n}\n\n// ============================================================================\n// Adapter (Constraint 1)\n// ============================================================================\n\n/**\n * A tool that was discovered but could NOT be adapted into an `AiAssist.IAiClientTool`,\n * because its `inputSchema` is outside the JSON Schema subset supported by\n * `JsonSchema.fromJson`. Surfaced structurally so callers/the probe can enumerate exactly which\n * subset features a server needs (with the raw schema in hand to extend `fromJson` later).\n * @public\n */\nexport interface IMcpSkippedTool {\n  /** The tool's name. */\n  readonly name: string;\n  /** Why the tool was skipped — the JSON-pointer reason from `JsonSchema.fromJson`, or a structural reason. */\n  readonly reason: string;\n  /** The raw failing input schema, verbatim, in hand for additively widening `JsonSchema.fromJson`. */\n  readonly schema: JsonValue;\n}\n\n/**\n * Options for {@link adaptMcpTools}.\n * @public\n */\nexport interface IAdaptMcpToolsOptions {\n  /**\n   * Logger for the NOISY per-tool skip warnings. When a tool is skipped, a `warning` is emitted\n   * including the tool name, the JSON-pointer reason, and the raw failing schema. When omitted,\n   * skips are still surfaced structurally on {@link IAdaptMcpToolsResult.skipped}.\n   */\n  readonly logger?: Logging.ILogger;\n}\n\n/**\n * The result of {@link adaptMcpTools}: cleanly-adapted client tools plus the structurally-surfaced\n * set of tools that could not be adapted (graceful degradation, Constraint 1).\n * @public\n */\nexport interface IAdaptMcpToolsResult {\n  /** Tools adapted into `IAiClientTool` — safe to hand to `AiAssist.executeClientToolTurn`. */\n  readonly tools: ReadonlyArray<AiAssist.IAiClientTool>;\n  /** Tools excluded because their `inputSchema` is outside the supported JSON Schema subset. */\n  readonly skipped: ReadonlyArray<IMcpSkippedTool>;\n}\n"]}
+{"version":3,"file":"model.js","sourceRoot":"","sources":["../../../src/packlets/mcp/model.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\n/**\n * Public types for the MCP → ai-assist client-tools boundary.\n * @packageDocumentation\n */\n\nimport { type Logging } from '@fgv/ts-utils';\nimport { type AiAssist } from '@fgv/ts-extras';\nimport { type JsonValue } from '@fgv/ts-json-base';\n\n// ============================================================================\n// Transport\n// ============================================================================\n\n/**\n * Parameters for {@link createStdioTransport}. The transport spawns `command` as a\n * subprocess and speaks MCP over its stdin/stdout.\n *\n * @remarks\n * **Security:** stdio transport executes a consumer-supplied command. Treat `command`/`args`\n * as a trust boundary — never source them from untrusted input. See the package README.\n *\n * @public\n */\nexport interface IMcpStdioTransportParams {\n  /** Executable to spawn (e.g. `'npx'`, `'node'`, an absolute path). */\n  readonly command: string;\n  /** Arguments passed to the command. */\n  readonly args?: ReadonlyArray<string>;\n  /** Environment variables for the spawned process. When omitted, the SDK's safe default set is used. */\n  readonly env?: Record<string, string>;\n  /** Working directory for the spawned process. */\n  readonly cwd?: string;\n}\n\n/**\n * Parameters for {@link createHttpTransport}. The transport connects to a Streamable-HTTP MCP\n * endpoint.\n * @public\n */\nexport interface IMcpHttpTransportParams {\n  /** Absolute `http`/`https` URL of the MCP server endpoint. */\n  readonly url: string;\n  /** Optional static headers (e.g. an `Authorization` bearer token). OAuth/managed auth is out of scope at v0.1. */\n  readonly headers?: Record<string, string>;\n}\n\n/**\n * Opaque handle to an MCP transport produced by {@link createStdioTransport} or\n * {@link createHttpTransport}. Hand it to {@link connectMcpSession}; do not construct directly.\n * @public\n */\nexport interface IMcpTransport {\n  /** Which transport kind this handle wraps. */\n  readonly transportKind: 'stdio' | 'http';\n}\n\n// ============================================================================\n// Session\n// ============================================================================\n\n/**\n * Parameters for {@link connectMcpSession}.\n * @public\n */\nexport interface IConnectMcpSessionParams {\n  /** A transport produced by {@link createStdioTransport} / {@link createHttpTransport}. */\n  readonly transport: IMcpTransport;\n  /** Client name advertised to the server during the initialize handshake. Default `'@fgv/ts-extras-mcp'`. */\n  readonly clientName?: string;\n  /** Client version advertised to the server. Default the package version. */\n  readonly clientVersion?: string;\n  /** Optional logger for connection diagnostics. */\n  readonly logger?: Logging.ILogger;\n}\n\n/**\n * Server identity reported during the MCP initialize handshake.\n * @public\n */\nexport interface IMcpServerInfo {\n  /** Server-advertised name. */\n  readonly name: string;\n  /** Server-advertised version. */\n  readonly version: string;\n}\n\n/**\n * Opaque handle to a connected MCP session. Pass it to {@link listMcpTools},\n * {@link callMcpTool}, {@link adaptMcpTools}, and {@link closeMcpSession}.\n * @public\n */\nexport interface IMcpSession {\n  /** Client name advertised during the handshake. */\n  readonly clientName: string;\n  /** Client version advertised during the handshake. */\n  readonly clientVersion: string;\n  /** Server identity reported by the handshake, when the server provided one. */\n  readonly serverInfo: IMcpServerInfo | undefined;\n}\n\n// ============================================================================\n// Tool discovery + invocation\n// ============================================================================\n\n/**\n * Normalized MCP `Tool.annotations` — the five known host-advisory behavior hints.\n *\n * @remarks\n * Field names mirror MCP's `ToolAnnotations` 1:1 (and map straight onto\n * `AiAssist.IAiToolAnnotations`). Per the MCP spec these are hints only, and per the\n * untrusted-server warning they are validated/normalized (known fields kept, malformed\n * or unknown fields dropped) before they reach {@link IMcpToolDescriptor} — the raw\n * server blob is never propagated.\n *\n * @public\n */\nexport interface IMcpToolAnnotations {\n  /** Optional human-readable display title for the tool. */\n  readonly title?: string;\n  /** Hint: the tool does not modify its environment (read-only). */\n  readonly readOnlyHint?: boolean;\n  /** Hint: the tool may perform destructive updates (only meaningful when not read-only). */\n  readonly destructiveHint?: boolean;\n  /** Hint: repeated calls with the same arguments have no additional effect. */\n  readonly idempotentHint?: boolean;\n  /** Hint: the tool interacts with an open world of external entities. */\n  readonly openWorldHint?: boolean;\n}\n\n/**\n * A tool descriptor discovered from an MCP server via {@link listMcpTools}.\n * @public\n */\nexport interface IMcpToolDescriptor {\n  /** Tool name (unique within a server). */\n  readonly name: string;\n  /** Human-readable description, when the server provided one. */\n  readonly description: string | undefined;\n  /**\n   * The tool's declared input schema as raw JSON. Per the MCP spec this is normally a JSON\n   * Schema object; carried verbatim so {@link adaptMcpTools} can run it through\n   * `JsonSchema.fromJson` (and surface it on {@link IMcpSkippedTool} when it is outside the\n   * supported subset).\n   */\n  readonly inputSchema: JsonValue;\n  /**\n   * The tool's normalized behavior annotations, when the server provided any usable ones.\n   * Absent when the server declared no annotations (or only malformed/unknown fields).\n   * See {@link IMcpToolAnnotations}.\n   */\n  readonly annotations?: IMcpToolAnnotations;\n}\n\n/**\n * Successful projection of an MCP `CallToolResult` produced by {@link callMcpTool}.\n *\n * @remarks\n * `content` is the text concatenation of the result's `text` blocks; non-text blocks\n * (image / audio / resource) are projected to a one-line `[<type> block]` summary\n * (multimodal passthrough is out of scope at v0.1). A result with `isError: true` is mapped\n * to `Result.fail(content)` rather than returned here, so it is never silently swallowed.\n *\n * @public\n */\nexport interface IMcpToolCallResult {\n  /** The projected text content of the tool result. */\n  readonly content: string;\n}\n\n// ============================================================================\n// Adapter (Constraint 1)\n// ============================================================================\n\n/**\n * A tool that was discovered but could NOT be adapted into an `AiAssist.IAiClientTool`,\n * because its `inputSchema` is outside the JSON Schema subset supported by\n * `JsonSchema.fromJson`. Surfaced structurally so callers/the probe can enumerate exactly which\n * subset features a server needs (with the raw schema in hand to extend `fromJson` later).\n * @public\n */\nexport interface IMcpSkippedTool {\n  /** The tool's name. */\n  readonly name: string;\n  /** Why the tool was skipped — the JSON-pointer reason from `JsonSchema.fromJson`, or a structural reason. */\n  readonly reason: string;\n  /** The raw failing input schema, verbatim, in hand for additively widening `JsonSchema.fromJson`. */\n  readonly schema: JsonValue;\n}\n\n/**\n * Options for {@link adaptMcpTools}.\n * @public\n */\nexport interface IAdaptMcpToolsOptions {\n  /**\n   * Logger for the NOISY per-tool skip warnings. When a tool is skipped, a `warning` is emitted\n   * including the tool name, the JSON-pointer reason, and the raw failing schema. When omitted,\n   * skips are still surfaced structurally on {@link IAdaptMcpToolsResult.skipped}.\n   */\n  readonly logger?: Logging.ILogger;\n}\n\n/**\n * The result of {@link adaptMcpTools}: cleanly-adapted client tools plus the structurally-surfaced\n * set of tools that could not be adapted (graceful degradation, Constraint 1).\n * @public\n */\nexport interface IAdaptMcpToolsResult {\n  /** Tools adapted into `IAiClientTool` — safe to hand to `AiAssist.executeClientToolTurn`. */\n  readonly tools: ReadonlyArray<AiAssist.IAiClientTool>;\n  /** Tools excluded because their `inputSchema` is outside the supported JSON Schema subset. */\n  readonly skipped: ReadonlyArray<IMcpSkippedTool>;\n}\n"]}

package/lib/packlets/mcp/operations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"operations.d.ts","sourceRoot":"","sources":["../../../src/packlets/mcp/operations.ts"],"names":[],"mappings":"AAsBA;;;;GAIG;AAEH,OAAO,EAAE,KAAK,MAAM,EAAqC,MAAM,eAAe,CAAC;AAC/E,OAAO,EAAc,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEhE,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,kBAAkB,EAAE,KAAK,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAgC7F;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAyB3G;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,WAAW,EACpB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,UAAU,GACf,OAAO,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC,CAkBrC"}
+{"version":3,"file":"operations.d.ts","sourceRoot":"","sources":["../../../src/packlets/mcp/operations.ts"],"names":[],"mappings":"AAsBA;;;;GAIG;AAEH,OAAO,EAAiC,KAAK,MAAM,EAAqC,MAAM,eAAe,CAAC;AAC9G,OAAO,EAAc,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEhE,OAAO,EACL,KAAK,WAAW,EAEhB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACxB,MAAM,SAAS,CAAC;AAsEjB;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAyB3G;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,WAAW,EACpB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,UAAU,GACf,OAAO,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC,CAkBrC"}

package/lib/packlets/mcp/operations.js

@@ -31,17 +31,42 @@ exports.callMcpTool = callMcpTool;
 const ts_utils_1 = require("@fgv/ts-utils");
 const ts_json_base_1 = require("@fgv/ts-json-base");
 const session_1 = require("./session");
+/**
+ * Validates/normalizes a raw (untrusted) MCP `Tool.annotations` blob into an
+ * {@link IMcpToolAnnotations}, keeping only the five known fields that convert cleanly.
+ *
+ * @remarks
+ * Each known field is converted independently with its own Converter, so a present-but-malformed
+ * field is dropped (never failing the whole blob) and unknown keys are ignored. Returns
+ * `undefined` when the blob is absent, not a JSON object, or normalizes to no usable known
+ * fields — so a tool with no (usable) annotations leaves {@link IMcpToolDescriptor.annotations}
+ * absent. The raw server value is never propagated verbatim (per the MCP untrusted-server
+ * warning).
+ */
+function _normalizeAnnotations(raw) {
+    const objResult = ts_json_base_1.Converters.jsonObject.convert(raw);
+    if (objResult.isFailure()) {
+        return undefined;
+    }
+    const obj = objResult.value;
+    const title = ts_utils_1.Converters.string.convert(obj.title).orDefault();
+    const readOnlyHint = ts_utils_1.Converters.boolean.convert(obj.readOnlyHint).orDefault();
+    const destructiveHint = ts_utils_1.Converters.boolean.convert(obj.destructiveHint).orDefault();
+    const idempotentHint = ts_utils_1.Converters.boolean.convert(obj.idempotentHint).orDefault();
+    const openWorldHint = ts_utils_1.Converters.boolean.convert(obj.openWorldHint).orDefault();
+    const normalized = Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({}, (title !== undefined ? { title } : {})), (readOnlyHint !== undefined ? { readOnlyHint } : {})), (destructiveHint !== undefined ? { destructiveHint } : {})), (idempotentHint !== undefined ? { idempotentHint } : {})), (openWorldHint !== undefined ? { openWorldHint } : {}));
+    return Object.keys(normalized).length > 0 ? normalized : undefined;
+}
 /**
  * Projects a single SDK tool descriptor into a public {@link IMcpToolDescriptor}. The
  * `inputSchema` field is validated as a `JsonValue`; an absent/non-JSON schema becomes `null`
  * (which {@link adaptMcpTools} then reports as un-adaptable rather than offering it to the model).
+ * The raw `annotations` blob is validated/normalized (never propagated raw) per the MCP
+ * untrusted-server warning.
  */
 function _toDescriptor(tool) {
-    return {
-        name: tool.name,
-        description: tool.description,
-        inputSchema: ts_json_base_1.Converters.jsonValue.convert(tool.inputSchema).orDefault(null)
-    };
+    const annotations = _normalizeAnnotations(tool.annotations);
+    return Object.assign({ name: tool.name, description: tool.description, inputSchema: ts_json_base_1.Converters.jsonValue.convert(tool.inputSchema).orDefault(null) }, (annotations !== undefined ? { annotations } : {}));
 }
 /**
  * Projects the SDK `CallToolResult` content blocks to a single string: `text` blocks are

package/lib/packlets/mcp/operations.js.map

@@ -1 +1 @@
-{"version":3,"file":"operations.js","sourceRoot":"","sources":["../../../src/packlets/mcp/operations.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;AAoDH,oCAyBC;AAkBD,kCAsBC;AAnHD;;;;GAIG;AAEH,4CAA+E;AAC/E,oDAAgE;AAIhE,uCAAuC;AAEvC;;;;GAIG;AACH,SAAS,aAAa,CAAC,IAAwB;IAC7C,OAAO;QACL,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,WAAW,EAAE,yBAAU,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC;KAC5E,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,SAAS,eAAe,CAAC,MAAmD;IAC1E,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChD,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,MAAM;SACV,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CACb,KAAK,CAAC,IAAI,KAAK,MAAM,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,IAAI,SAAS,CACzF;SACA,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAED;;;;;;;;GAQG;AACI,KAAK,UAAU,YAAY,CAAC,OAAoB;IACrD,MAAM,aAAa,GAAG,oBAAU,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;IACrD,IAAI,aAAa,CAAC,SAAS,EAAE,EAAE,CAAC;QAC9B,OAAO,IAAA,eAAI,EAAC,iBAAiB,aAAa,CAAC,OAAO,EAAE,CAAC,CAAC;IACxD,CAAC;IACD,MAAM,EAAE,MAAM,EAAE,GAAG,aAAa,CAAC,KAAK,CAAC;IAEvC,MAAM,GAAG,GAAyB,EAAE,CAAC;IACrC,IAAI,MAA0B,CAAC;IAE/B,0FAA0F;IAC1F,GAAG,CAAC;QACF,MAAM,UAAU,GAAG,MAAM,IAAA,6BAAkB,EAAC,GAAG,EAAE,CAC/C,MAAM,CAAC,SAAS,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAChE,CAAC,eAAe,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,iBAAiB,GAAG,EAAE,CAAC,CAAC;QACnD,IAAI,UAAU,CAAC,SAAS,EAAE,EAAE,CAAC;YAC3B,OAAO,IAAA,eAAI,EAAC,UAAU,CAAC,OAAO,CAAC,CAAC;QAClC,CAAC;QACD,KAAK,MAAM,IAAI,IAAI,UAAU,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;YAC1C,GAAG,CAAC,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC;QAChC,CAAC;QACD,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC,UAAU,CAAC;IACvC,CAAC,QAAQ,MAAM,KAAK,SAAS,EAAE;IAE/B,OAAO,IAAA,kBAAO,EAAC,GAAG,CAAC,CAAC;AACtB,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACI,KAAK,UAAU,WAAW,CAC/B,OAAoB,EACpB,IAAY,EACZ,IAAgB;IAEhB,MAAM,aAAa,GAAG,oBAAU,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;IACrD,IAAI,aAAa,CAAC,SAAS,EAAE,EAAE,CAAC;QAC9B,OAAO,IAAA,eAAI,EAAC,gBAAgB,aAAa,CAAC,OAAO,EAAE,CAAC,CAAC;IACvD,CAAC;IACD,+FAA+F;IAC/F,0FAA0F;IAC1F,2FAA2F;IAC3F,iDAAiD;IACjD,OAAO,IAAA,6BAAkB,EAAC,GAAG,EAAE,CAAC,aAAa,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;SAC5F,eAAe,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,gBAAgB,IAAI,MAAM,GAAG,EAAE,CAAC;SACzD,SAAS,CAAC,CAAC,GAAG,EAA8B,EAAE;QAC7C,MAAM,OAAO,GAAG,eAAe,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAC7C,IAAI,GAAG,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;YACzB,OAAO,IAAA,eAAI,EAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,IAAI,qBAAqB,CAAC,CAAC;QACjF,CAAC;QACD,OAAO,IAAA,kBAAO,EAAC,EAAE,OAAO,EAAE,CAAC,CAAC;IAC9B,CAAC,CAAC,CAAC;AACP,CAAC","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\n/**\n * Tool discovery (`listMcpTools`, paginated) and invocation (`callMcpTool`, with `CallToolResult`\n * projection), converting the throwing SDK calls into `Result<T>`.\n * @packageDocumentation\n */\n\nimport { type Result, captureAsyncResult, fail, succeed } from '@fgv/ts-utils';\nimport { Converters, type JsonObject } from '@fgv/ts-json-base';\n\nimport { type IMcpSession, type IMcpToolCallResult, type IMcpToolDescriptor } from './model';\nimport { type ISdkContentBlock, type ISdkToolDescriptor } from './sdk';\nimport { McpSession } from './session';\n\n/**\n * Projects a single SDK tool descriptor into a public {@link IMcpToolDescriptor}. The\n * `inputSchema` field is validated as a `JsonValue`; an absent/non-JSON schema becomes `null`\n * (which {@link adaptMcpTools} then reports as un-adaptable rather than offering it to the model).\n */\nfunction _toDescriptor(tool: ISdkToolDescriptor): IMcpToolDescriptor {\n  return {\n    name: tool.name,\n    description: tool.description,\n    inputSchema: Converters.jsonValue.convert(tool.inputSchema).orDefault(null)\n  };\n}\n\n/**\n * Projects the SDK `CallToolResult` content blocks to a single string: `text` blocks are\n * concatenated; every other block type becomes a one-line `[<type> block]` summary.\n */\nfunction _projectContent(blocks: ReadonlyArray<ISdkContentBlock> | undefined): string {\n  if (blocks === undefined || blocks.length === 0) {\n    return '';\n  }\n  return blocks\n    .map((block) =>\n      block.type === 'text' && block.text !== undefined ? block.text : `[${block.type} block]`\n    )\n    .join('\\n');\n}\n\n/**\n * Lists every tool a connected MCP server advertises, following the SDK's `nextCursor`\n * pagination until the full catalog is accumulated.\n *\n * @param session - A session from `connectMcpSession`.\n * @returns `Success` with the full tool catalog, or `Failure` on a foreign handle or a\n * transport/protocol error.\n * @public\n */\nexport async function listMcpTools(session: IMcpSession): Promise<Result<ReadonlyArray<IMcpToolDescriptor>>> {\n  const sessionResult = McpSession.fromHandle(session);\n  if (sessionResult.isFailure()) {\n    return fail(`listMcpTools: ${sessionResult.message}`);\n  }\n  const { client } = sessionResult.value;\n\n  const all: IMcpToolDescriptor[] = [];\n  let cursor: string | undefined;\n\n  // Cursor-paginated loop: fetch each page, accumulate, advance until nextCursor is absent.\n  do {\n    const pageResult = await captureAsyncResult(() =>\n      client.listTools(cursor !== undefined ? { cursor } : undefined)\n    ).withErrorFormat((msg) => `listMcpTools: ${msg}`);\n    if (pageResult.isFailure()) {\n      return fail(pageResult.message);\n    }\n    for (const tool of pageResult.value.tools) {\n      all.push(_toDescriptor(tool));\n    }\n    cursor = pageResult.value.nextCursor;\n  } while (cursor !== undefined);\n\n  return succeed(all);\n}\n\n/**\n * Calls a named tool on a connected MCP server.\n *\n * @remarks\n * The SDK `CallToolResult` is projected to {@link IMcpToolCallResult} (text-block concatenation;\n * non-text blocks summarized). A result flagged `isError: true` is mapped to `Result.fail` with\n * the projected content — it is never swallowed, so `executeClientToolTurn` routes it back to the\n * model as a provider-native error tool-result.\n *\n * @param session - A session from `connectMcpSession`.\n * @param name - The tool name to invoke.\n * @param args - The tool arguments (a JSON object).\n * @returns `Success` with the projected content, or `Failure` on tool error / transport error /\n * foreign handle.\n * @public\n */\nexport async function callMcpTool(\n  session: IMcpSession,\n  name: string,\n  args: JsonObject\n): Promise<Result<IMcpToolCallResult>> {\n  const sessionResult = McpSession.fromHandle(session);\n  if (sessionResult.isFailure()) {\n    return fail(`callMcpTool: ${sessionResult.message}`);\n  }\n  // The `withErrorFormat` wraps only transport/throw failures (it transforms the failure flowing\n  // out of `captureAsyncResult`); the `isError` failure created in the later `onSuccess` is\n  // downstream and stays clean, so the model-facing tool-error text is the server's verbatim\n  // content rather than a doubly-prefixed message.\n  return captureAsyncResult(() => sessionResult.value.client.callTool({ name, arguments: args }))\n    .withErrorFormat((msg) => `callMcpTool '${name}': ${msg}`)\n    .onSuccess((raw): Result<IMcpToolCallResult> => {\n      const content = _projectContent(raw.content);\n      if (raw.isError === true) {\n        return fail(content.length > 0 ? content : `tool '${name}' reported an error`);\n      }\n      return succeed({ content });\n    });\n}\n"]}
+{"version":3,"file":"operations.js","sourceRoot":"","sources":["../../../src/packlets/mcp/operations.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\n/**\n * Tool discovery (`listMcpTools`, paginated) and invocation (`callMcpTool`, with `CallToolResult`\n * projection), converting the throwing SDK calls into `Result<T>`.\n * @packageDocumentation\n */\n\nimport { Converters as UtilsConverters, type Result, captureAsyncResult, fail, succeed } from '@fgv/ts-utils';\nimport { Converters, type JsonObject } from '@fgv/ts-json-base';\n\nimport {\n  type IMcpSession,\n  type IMcpToolAnnotations,\n  type IMcpToolCallResult,\n  type IMcpToolDescriptor\n} from './model';\nimport { type ISdkContentBlock, type ISdkToolDescriptor } from './sdk';\nimport { McpSession } from './session';\n\n/**\n * Validates/normalizes a raw (untrusted) MCP `Tool.annotations` blob into an\n * {@link IMcpToolAnnotations}, keeping only the five known fields that convert cleanly.\n *\n * @remarks\n * Each known field is converted independently with its own Converter, so a present-but-malformed\n * field is dropped (never failing the whole blob) and unknown keys are ignored. Returns\n * `undefined` when the blob is absent, not a JSON object, or normalizes to no usable known\n * fields — so a tool with no (usable) annotations leaves {@link IMcpToolDescriptor.annotations}\n * absent. The raw server value is never propagated verbatim (per the MCP untrusted-server\n * warning).\n */\nfunction _normalizeAnnotations(raw: unknown): IMcpToolAnnotations | undefined {\n  const objResult = Converters.jsonObject.convert(raw);\n  if (objResult.isFailure()) {\n    return undefined;\n  }\n  const obj = objResult.value;\n  const title = UtilsConverters.string.convert(obj.title).orDefault();\n  const readOnlyHint = UtilsConverters.boolean.convert(obj.readOnlyHint).orDefault();\n  const destructiveHint = UtilsConverters.boolean.convert(obj.destructiveHint).orDefault();\n  const idempotentHint = UtilsConverters.boolean.convert(obj.idempotentHint).orDefault();\n  const openWorldHint = UtilsConverters.boolean.convert(obj.openWorldHint).orDefault();\n\n  const normalized: IMcpToolAnnotations = {\n    ...(title !== undefined ? { title } : {}),\n    ...(readOnlyHint !== undefined ? { readOnlyHint } : {}),\n    ...(destructiveHint !== undefined ? { destructiveHint } : {}),\n    ...(idempotentHint !== undefined ? { idempotentHint } : {}),\n    ...(openWorldHint !== undefined ? { openWorldHint } : {})\n  };\n  return Object.keys(normalized).length > 0 ? normalized : undefined;\n}\n\n/**\n * Projects a single SDK tool descriptor into a public {@link IMcpToolDescriptor}. The\n * `inputSchema` field is validated as a `JsonValue`; an absent/non-JSON schema becomes `null`\n * (which {@link adaptMcpTools} then reports as un-adaptable rather than offering it to the model).\n * The raw `annotations` blob is validated/normalized (never propagated raw) per the MCP\n * untrusted-server warning.\n */\nfunction _toDescriptor(tool: ISdkToolDescriptor): IMcpToolDescriptor {\n  const annotations = _normalizeAnnotations(tool.annotations);\n  return {\n    name: tool.name,\n    description: tool.description,\n    inputSchema: Converters.jsonValue.convert(tool.inputSchema).orDefault(null),\n    ...(annotations !== undefined ? { annotations } : {})\n  };\n}\n\n/**\n * Projects the SDK `CallToolResult` content blocks to a single string: `text` blocks are\n * concatenated; every other block type becomes a one-line `[<type> block]` summary.\n */\nfunction _projectContent(blocks: ReadonlyArray<ISdkContentBlock> | undefined): string {\n  if (blocks === undefined || blocks.length === 0) {\n    return '';\n  }\n  return blocks\n    .map((block) =>\n      block.type === 'text' && block.text !== undefined ? block.text : `[${block.type} block]`\n    )\n    .join('\\n');\n}\n\n/**\n * Lists every tool a connected MCP server advertises, following the SDK's `nextCursor`\n * pagination until the full catalog is accumulated.\n *\n * @param session - A session from `connectMcpSession`.\n * @returns `Success` with the full tool catalog, or `Failure` on a foreign handle or a\n * transport/protocol error.\n * @public\n */\nexport async function listMcpTools(session: IMcpSession): Promise<Result<ReadonlyArray<IMcpToolDescriptor>>> {\n  const sessionResult = McpSession.fromHandle(session);\n  if (sessionResult.isFailure()) {\n    return fail(`listMcpTools: ${sessionResult.message}`);\n  }\n  const { client } = sessionResult.value;\n\n  const all: IMcpToolDescriptor[] = [];\n  let cursor: string | undefined;\n\n  // Cursor-paginated loop: fetch each page, accumulate, advance until nextCursor is absent.\n  do {\n    const pageResult = await captureAsyncResult(() =>\n      client.listTools(cursor !== undefined ? { cursor } : undefined)\n    ).withErrorFormat((msg) => `listMcpTools: ${msg}`);\n    if (pageResult.isFailure()) {\n      return fail(pageResult.message);\n    }\n    for (const tool of pageResult.value.tools) {\n      all.push(_toDescriptor(tool));\n    }\n    cursor = pageResult.value.nextCursor;\n  } while (cursor !== undefined);\n\n  return succeed(all);\n}\n\n/**\n * Calls a named tool on a connected MCP server.\n *\n * @remarks\n * The SDK `CallToolResult` is projected to {@link IMcpToolCallResult} (text-block concatenation;\n * non-text blocks summarized). A result flagged `isError: true` is mapped to `Result.fail` with\n * the projected content — it is never swallowed, so `executeClientToolTurn` routes it back to the\n * model as a provider-native error tool-result.\n *\n * @param session - A session from `connectMcpSession`.\n * @param name - The tool name to invoke.\n * @param args - The tool arguments (a JSON object).\n * @returns `Success` with the projected content, or `Failure` on tool error / transport error /\n * foreign handle.\n * @public\n */\nexport async function callMcpTool(\n  session: IMcpSession,\n  name: string,\n  args: JsonObject\n): Promise<Result<IMcpToolCallResult>> {\n  const sessionResult = McpSession.fromHandle(session);\n  if (sessionResult.isFailure()) {\n    return fail(`callMcpTool: ${sessionResult.message}`);\n  }\n  // The `withErrorFormat` wraps only transport/throw failures (it transforms the failure flowing\n  // out of `captureAsyncResult`); the `isError` failure created in the later `onSuccess` is\n  // downstream and stays clean, so the model-facing tool-error text is the server's verbatim\n  // content rather than a doubly-prefixed message.\n  return captureAsyncResult(() => sessionResult.value.client.callTool({ name, arguments: args }))\n    .withErrorFormat((msg) => `callMcpTool '${name}': ${msg}`)\n    .onSuccess((raw): Result<IMcpToolCallResult> => {\n      const content = _projectContent(raw.content);\n      if (raw.isError === true) {\n        return fail(content.length > 0 ? content : `tool '${name}' reported an error`);\n      }\n      return succeed({ content });\n    });\n}\n"]}

package/lib/packlets/mcp/sdk.d.ts

@@ -29,6 +29,12 @@ export interface ISdkToolDescriptor {
     readonly name: string;
     readonly description?: string;
     readonly inputSchema?: unknown;
+    /**
+     * Raw MCP `Tool.annotations` (untrusted). Declared as `unknown` so the SDK field survives
+     * narrowing; the operations layer validates/normalizes it (never propagates raw) per the MCP
+     * spec's untrusted-server warning.
+     */
+    readonly annotations?: unknown;
 }
 /**
  * Projection of the SDK's `ListToolsResult` (one page).

package/lib/packlets/mcp/sdk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sdk.d.ts","sourceRoot":"","sources":["../../../src/packlets/mcp/sdk.ts"],"names":[],"mappings":"AAwCA;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC;AAEnC;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC,gBAAgB,CAAC,CAAC;IACnD,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;CAChC;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAC;IAClD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,OAAO,CAAC,SAAS,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD,gBAAgB,IAAI,kBAAkB,GAAG,SAAS,CAAC;IACnD,SAAS,CAAC,MAAM,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACtE,QAAQ,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACrG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACtC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,UAAU,CAEpE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,eAAe,GAAG,aAAa,CAOzE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,aAAa,CAI3F"}
+{"version":3,"file":"sdk.d.ts","sourceRoot":"","sources":["../../../src/packlets/mcp/sdk.ts"],"names":[],"mappings":"AAwCA;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC;AAEnC;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC,gBAAgB,CAAC,CAAC;IACnD,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;CAChC;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAC;IAClD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,OAAO,CAAC,SAAS,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD,gBAAgB,IAAI,kBAAkB,GAAG,SAAS,CAAC;IACnD,SAAS,CAAC,MAAM,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACtE,QAAQ,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACrG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACtC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,UAAU,CAEpE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,eAAe,GAAG,aAAa,CAOzE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,aAAa,CAI3F"}

package/lib/packlets/mcp/sdk.js.map

@@ -1 +1 @@
-{"version":3,"file":"sdk.js","sourceRoot":"","sources":["../../../src/packlets/mcp/sdk.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;AAsGH,gCAEC;AAMD,gDAOC;AAMD,8CAIC;AA7HD;;;;;;;;;;;;GAYG;AAEH,wEAAmE;AACnE,wEAAiF;AACjF,0FAAmG;AA+EnG;;;;GAIG;AACH,SAAgB,UAAU,CAAC,IAAY,EAAE,OAAe;IACtD,OAAO,IAAI,iBAAM,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,YAAY,EAAE,EAAE,EAAE,CAA0B,CAAC;AACtF,CAAC;AAED;;;GAGG;AACH,SAAgB,kBAAkB,CAAC,MAAuB;IACxD,OAAO,IAAI,+BAAoB,CAAC;QAC9B,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS;QAChD,GAAG,EAAE,MAAM,CAAC,GAAG;QACf,GAAG,EAAE,MAAM,CAAC,GAAG;KAChB,CAA6B,CAAC;AACjC,CAAC;AAED;;;GAGG;AACH,SAAgB,iBAAiB,CAAC,GAAQ,EAAE,OAAgC;IAC1E,OAAO,IAAI,iDAA6B,CAAC,GAAG,EAAE;QAC5C,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,SAAS;KAC/C,CAA6B,CAAC;AACjC,CAAC","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\n/**\n * **The single `@modelcontextprotocol/sdk` import site for the entire package.**\n *\n * Every other module in `@fgv/ts-extras-mcp` depends only on the minimal local projection\n * exported here (`ISdkClient`, `ISdkTransport`, the three `make*` factories) — never on the SDK\n * directly. This keeps the announced v2 client-package rename a one-file change and lets unit\n * tests mock this module instead of the SDK internals (no live server required).\n *\n * The only `as unknown as` casts in the package live here, at the boundary where the real SDK\n * objects are narrowed to the local projection.\n *\n * @internal\n */\n\nimport { Client } from '@modelcontextprotocol/sdk/client/index.js';\nimport { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';\nimport { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';\n\n/**\n * Opaque transport handle. The concrete value is an SDK `Transport`; consumers of this module\n * treat it as opaque and only ever hand it back to {@link makeClient}-produced clients.\n * @internal\n */\nexport type ISdkTransport = object;\n\n/**\n * A single content block in an MCP `CallToolResult`. Only `text` blocks carry inline content;\n * all other block types are projected to a structural summary by the operations layer.\n * @internal\n */\nexport interface ISdkContentBlock {\n  readonly type: string;\n  readonly text?: string;\n}\n\n/**\n * Projection of the SDK's `CallToolResult`.\n * @internal\n */\nexport interface ISdkCallToolResult {\n  readonly content?: ReadonlyArray<ISdkContentBlock>;\n  readonly isError?: boolean;\n}\n\n/**\n * Projection of a single tool descriptor in the SDK's `ListToolsResult`.\n * @internal\n */\nexport interface ISdkToolDescriptor {\n  readonly name: string;\n  readonly description?: string;\n  readonly inputSchema?: unknown;\n}\n\n/**\n * Projection of the SDK's `ListToolsResult` (one page).\n * @internal\n */\nexport interface ISdkListToolsResult {\n  readonly tools: ReadonlyArray<ISdkToolDescriptor>;\n  readonly nextCursor?: string;\n}\n\n/**\n * Server identity returned by the SDK's `getServerVersion()` after the initialize handshake.\n * @internal\n */\nexport interface ISdkImplementation {\n  readonly name: string;\n  readonly version: string;\n}\n\n/**\n * Minimal projection of the SDK `Client` surface the package depends on.\n * @internal\n */\nexport interface ISdkClient {\n  connect(transport: ISdkTransport): Promise<void>;\n  getServerVersion(): ISdkImplementation | undefined;\n  listTools(params?: { cursor?: string }): Promise<ISdkListToolsResult>;\n  callTool(params: { name: string; arguments?: Record<string, unknown> }): Promise<ISdkCallToolResult>;\n  close(): Promise<void>;\n}\n\n/**\n * Parameters for the stdio transport factory.\n * @internal\n */\nexport interface ISdkStdioParams {\n  readonly command: string;\n  readonly args?: ReadonlyArray<string>;\n  readonly env?: Record<string, string>;\n  readonly cwd?: string;\n}\n\n/**\n * Constructs an MCP client. The `as unknown as` cast is the package's single SDK-type\n * bridge — the runtime object is a real SDK `Client`.\n * @internal\n */\nexport function makeClient(name: string, version: string): ISdkClient {\n  return new Client({ name, version }, { capabilities: {} }) as unknown as ISdkClient;\n}\n\n/**\n * Constructs a stdio transport that spawns the given command as a subprocess.\n * @internal\n */\nexport function makeStdioTransport(params: ISdkStdioParams): ISdkTransport {\n  return new StdioClientTransport({\n    command: params.command,\n    args: params.args ? [...params.args] : undefined,\n    env: params.env,\n    cwd: params.cwd\n  }) as unknown as ISdkTransport;\n}\n\n/**\n * Constructs a Streamable-HTTP transport for the given URL, with optional static headers.\n * @internal\n */\nexport function makeHttpTransport(url: URL, headers?: Record<string, string>): ISdkTransport {\n  return new StreamableHTTPClientTransport(url, {\n    requestInit: headers ? { headers } : undefined\n  }) as unknown as ISdkTransport;\n}\n"]}
+{"version":3,"file":"sdk.js","sourceRoot":"","sources":["../../../src/packlets/mcp/sdk.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;AA4GH,gCAEC;AAMD,gDAOC;AAMD,8CAIC;AAnID;;;;;;;;;;;;GAYG;AAEH,wEAAmE;AACnE,wEAAiF;AACjF,0FAAmG;AAqFnG;;;;GAIG;AACH,SAAgB,UAAU,CAAC,IAAY,EAAE,OAAe;IACtD,OAAO,IAAI,iBAAM,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,YAAY,EAAE,EAAE,EAAE,CAA0B,CAAC;AACtF,CAAC;AAED;;;GAGG;AACH,SAAgB,kBAAkB,CAAC,MAAuB;IACxD,OAAO,IAAI,+BAAoB,CAAC;QAC9B,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS;QAChD,GAAG,EAAE,MAAM,CAAC,GAAG;QACf,GAAG,EAAE,MAAM,CAAC,GAAG;KAChB,CAA6B,CAAC;AACjC,CAAC;AAED;;;GAGG;AACH,SAAgB,iBAAiB,CAAC,GAAQ,EAAE,OAAgC;IAC1E,OAAO,IAAI,iDAA6B,CAAC,GAAG,EAAE;QAC5C,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,SAAS;KAC/C,CAA6B,CAAC;AACjC,CAAC","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\n/**\n * **The single `@modelcontextprotocol/sdk` import site for the entire package.**\n *\n * Every other module in `@fgv/ts-extras-mcp` depends only on the minimal local projection\n * exported here (`ISdkClient`, `ISdkTransport`, the three `make*` factories) — never on the SDK\n * directly. This keeps the announced v2 client-package rename a one-file change and lets unit\n * tests mock this module instead of the SDK internals (no live server required).\n *\n * The only `as unknown as` casts in the package live here, at the boundary where the real SDK\n * objects are narrowed to the local projection.\n *\n * @internal\n */\n\nimport { Client } from '@modelcontextprotocol/sdk/client/index.js';\nimport { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';\nimport { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';\n\n/**\n * Opaque transport handle. The concrete value is an SDK `Transport`; consumers of this module\n * treat it as opaque and only ever hand it back to {@link makeClient}-produced clients.\n * @internal\n */\nexport type ISdkTransport = object;\n\n/**\n * A single content block in an MCP `CallToolResult`. Only `text` blocks carry inline content;\n * all other block types are projected to a structural summary by the operations layer.\n * @internal\n */\nexport interface ISdkContentBlock {\n  readonly type: string;\n  readonly text?: string;\n}\n\n/**\n * Projection of the SDK's `CallToolResult`.\n * @internal\n */\nexport interface ISdkCallToolResult {\n  readonly content?: ReadonlyArray<ISdkContentBlock>;\n  readonly isError?: boolean;\n}\n\n/**\n * Projection of a single tool descriptor in the SDK's `ListToolsResult`.\n * @internal\n */\nexport interface ISdkToolDescriptor {\n  readonly name: string;\n  readonly description?: string;\n  readonly inputSchema?: unknown;\n  /**\n   * Raw MCP `Tool.annotations` (untrusted). Declared as `unknown` so the SDK field survives\n   * narrowing; the operations layer validates/normalizes it (never propagates raw) per the MCP\n   * spec's untrusted-server warning.\n   */\n  readonly annotations?: unknown;\n}\n\n/**\n * Projection of the SDK's `ListToolsResult` (one page).\n * @internal\n */\nexport interface ISdkListToolsResult {\n  readonly tools: ReadonlyArray<ISdkToolDescriptor>;\n  readonly nextCursor?: string;\n}\n\n/**\n * Server identity returned by the SDK's `getServerVersion()` after the initialize handshake.\n * @internal\n */\nexport interface ISdkImplementation {\n  readonly name: string;\n  readonly version: string;\n}\n\n/**\n * Minimal projection of the SDK `Client` surface the package depends on.\n * @internal\n */\nexport interface ISdkClient {\n  connect(transport: ISdkTransport): Promise<void>;\n  getServerVersion(): ISdkImplementation | undefined;\n  listTools(params?: { cursor?: string }): Promise<ISdkListToolsResult>;\n  callTool(params: { name: string; arguments?: Record<string, unknown> }): Promise<ISdkCallToolResult>;\n  close(): Promise<void>;\n}\n\n/**\n * Parameters for the stdio transport factory.\n * @internal\n */\nexport interface ISdkStdioParams {\n  readonly command: string;\n  readonly args?: ReadonlyArray<string>;\n  readonly env?: Record<string, string>;\n  readonly cwd?: string;\n}\n\n/**\n * Constructs an MCP client. The `as unknown as` cast is the package's single SDK-type\n * bridge — the runtime object is a real SDK `Client`.\n * @internal\n */\nexport function makeClient(name: string, version: string): ISdkClient {\n  return new Client({ name, version }, { capabilities: {} }) as unknown as ISdkClient;\n}\n\n/**\n * Constructs a stdio transport that spawns the given command as a subprocess.\n * @internal\n */\nexport function makeStdioTransport(params: ISdkStdioParams): ISdkTransport {\n  return new StdioClientTransport({\n    command: params.command,\n    args: params.args ? [...params.args] : undefined,\n    env: params.env,\n    cwd: params.cwd\n  }) as unknown as ISdkTransport;\n}\n\n/**\n * Constructs a Streamable-HTTP transport for the given URL, with optional static headers.\n * @internal\n */\nexport function makeHttpTransport(url: URL, headers?: Record<string, string>): ISdkTransport {\n  return new StreamableHTTPClientTransport(url, {\n    requestInit: headers ? { headers } : undefined\n  }) as unknown as ISdkTransport;\n}\n"]}

package/lib/test/unit/mcp.test.js

@@ -412,5 +412,118 @@ describe('adaptMcpTools', () => {
             expect(await execute({ q: 'hello' })).toFailWith(/denied/);
         });
     });
+    // ==========================================================================
+    // C2 — MCP Tool.annotations passthrough (normalized, never raw)
+    // ==========================================================================
+    describe('annotations passthrough (C2)', () => {
+        const goodSchema2 = { type: 'object', properties: { q: { type: 'string' } }, required: ['q'] };
+        test('all five hints round-trip onto descriptor.annotations and config.annotations', async () => {
+            const annotations = {
+                title: 'Recall Memory',
+                readOnlyHint: true,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false
+            };
+            const fake = makeFakeClient({
+                listTools: jest.fn(async () => ({
+                    tools: [{ name: 'recall', description: 'r', inputSchema: goodSchema2, annotations }]
+                }))
+            });
+            const session = await connectWith(fake);
+            expect(await (0, mcp_1.listMcpTools)(session)).toSucceedAndSatisfy((tools) => {
+                expect(tools[0].annotations).toEqual(annotations);
+            });
+            const session2 = await connectWith(makeFakeClient({
+                listTools: jest.fn(async () => ({
+                    tools: [{ name: 'recall', description: 'r', inputSchema: goodSchema2, annotations }]
+                }))
+            }));
+            expect(await (0, mcp_1.adaptMcpTools)(session2)).toSucceedAndSatisfy((result) => {
+                expect(result.tools[0].config.annotations).toEqual(annotations);
+            });
+        });
+        test('a tool with no annotations leaves the field absent', async () => {
+            const fake = makeFakeClient({
+                listTools: jest.fn(async () => ({ tools: [{ name: 'plain', inputSchema: goodSchema2 }] }))
+            });
+            const session = await connectWith(fake);
+            expect(await (0, mcp_1.listMcpTools)(session)).toSucceedAndSatisfy((tools) => {
+                expect(tools[0]).not.toHaveProperty('annotations');
+            });
+            const session2 = await connectWith(makeFakeClient({
+                listTools: jest.fn(async () => ({ tools: [{ name: 'plain', inputSchema: goodSchema2 }] }))
+            }));
+            expect(await (0, mcp_1.adaptMcpTools)(session2)).toSucceedAndSatisfy((result) => {
+                expect(result.tools[0].config).not.toHaveProperty('annotations');
+            });
+        });
+        test('a malformed annotations blob is normalized (known fields kept, junk dropped), never raw-propagated', async () => {
+            // readOnlyHint is the wrong type (dropped); bogusField is unknown (dropped); title is valid (kept).
+            const rawAnnotations = {
+                title: 'Keep Me',
+                readOnlyHint: 'yes-please',
+                destructiveHint: true,
+                bogusField: { nested: 42 }
+            };
+            const fake = makeFakeClient({
+                listTools: jest.fn(async () => ({
+                    tools: [{ name: 'messy', inputSchema: goodSchema2, annotations: rawAnnotations }]
+                }))
+            });
+            const session = await connectWith(fake);
+            expect(await (0, mcp_1.listMcpTools)(session)).toSucceedAndSatisfy((tools) => {
+                // Only the well-typed known fields survive; the malformed readOnlyHint and unknown
+                // bogusField are dropped; the raw blob is never propagated.
+                expect(tools[0].annotations).toEqual({ title: 'Keep Me', destructiveHint: true });
+                expect(tools[0].annotations).not.toHaveProperty('readOnlyHint');
+                expect(tools[0].annotations).not.toHaveProperty('bogusField');
+            });
+        });
+        test('an all-junk annotations blob normalizes to an absent field (not an empty object)', async () => {
+            const fake = makeFakeClient({
+                listTools: jest.fn(async () => ({
+                    tools: [
+                        { name: 'junk', inputSchema: goodSchema2, annotations: { unknownOnly: 1, readOnlyHint: 3 } }
+                    ]
+                }))
+            });
+            const session = await connectWith(fake);
+            expect(await (0, mcp_1.listMcpTools)(session)).toSucceedAndSatisfy((tools) => {
+                expect(tools[0]).not.toHaveProperty('annotations');
+            });
+        });
+        test('a non-object annotations value is dropped', async () => {
+            const fake = makeFakeClient({
+                listTools: jest.fn(async () => ({
+                    tools: [{ name: 'weird', inputSchema: goodSchema2, annotations: 'not-an-object' }]
+                }))
+            });
+            const session = await connectWith(fake);
+            expect(await (0, mcp_1.listMcpTools)(session)).toSucceedAndSatisfy((tools) => {
+                expect(tools[0]).not.toHaveProperty('annotations');
+            });
+        });
+        test('the skipped-tool path is unaffected by annotations', async () => {
+            // A tool with annotations but an unsupported inputSchema is still skipped; annotations do
+            // not rescue it or leak onto the skip record.
+            const forbidden = {
+                type: 'object',
+                properties: { name: { type: 'string', pattern: '^a' } }
+            };
+            const fake = makeFakeClient({
+                listTools: jest.fn(async () => ({
+                    tools: [{ name: 'blocked', inputSchema: forbidden, annotations: { destructiveHint: true } }]
+                }))
+            });
+            const session = await connectWith(fake);
+            expect(await (0, mcp_1.adaptMcpTools)(session)).toSucceedAndSatisfy((result) => {
+                expect(result.tools).toHaveLength(0);
+                expect(result.skipped).toHaveLength(1);
+                expect(result.skipped[0].name).toBe('blocked');
+                expect(result.skipped[0]).not.toHaveProperty('annotations');
+            });
+        });
+    });
 });
 //# sourceMappingURL=mcp.test.js.map