pi-mcp-adapter 3.1.0 → 3.3.0

package/prompts.ts

@@ -122,6 +122,64 @@ function stripQuotes(value: string): string {
   return value;
 }
 
+function findCurrentPromptTokenStart(input: string): number {
+  let quote: '"' | "'" | null = null;
+  let escaped = false;
+  let start = 0;
+
+  for (let i = 0; i < input.length; i++) {
+    const char = input.charAt(i);
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+    if (char === "\\" && quote !== "'") {
+      escaped = true;
+      continue;
+    }
+    if (quote) {
+      if (char === quote) quote = null;
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = char;
+      continue;
+    }
+    if (/\s/.test(char)) start = i + 1;
+  }
+
+  return start;
+}
+
+export function completePromptArgs(
+  metadata: PromptMetadata,
+  input: string,
+): Array<{ value: string; label: string; description?: string }> | null {
+  const tokenStart = findCurrentPromptTokenStart(input);
+  const current = input.slice(tokenStart);
+  if (current.includes("=") || current.startsWith('"') || current.startsWith("'")) return null;
+
+  const committed = input.slice(0, tokenStart);
+  const parsed = parsePromptArgs(committed);
+  const used = new Set(Object.keys(parsed.named));
+  let positionalIndex = 0;
+
+  for (const arg of metadata.arguments) {
+    if (Object.hasOwn(parsed.named, arg.name)) continue;
+    const positional = parsed.positional[positionalIndex++];
+    if (positional !== undefined && positional !== "") used.add(arg.name);
+  }
+
+  const matches = metadata.arguments.filter(arg => !used.has(arg.name) && arg.name.startsWith(current));
+  if (matches.length === 0) return null;
+
+  return matches.map(arg => ({
+    value: committed + arg.name + "=",
+    label: arg.name + "=",
+    ...(arg.description ? { description: arg.description } : {}),
+  }));
+}
+
 export interface ResolvedPromptArgs {
   ok: boolean;
   /** Present when `ok === true`. */
@@ -249,6 +307,16 @@ export function createPromptCommand(
 
   return {
     description,
+    getArgumentCompletions: (prefix: string) => {
+      const state = getState();
+      if (!state) return completePromptArgs(metadata, prefix);
+      const definition = state.config.mcpServers[metadata.serverName];
+      if (!definition || isServerDisabled(definition)) return null;
+
+      const liveMetadata = findLivePromptMetadata(state, metadata.serverName, metadata.originalName);
+      if (state.promptMetadataLive?.has(metadata.serverName) && !liveMetadata) return null;
+      return completePromptArgs(liveMetadata ?? metadata, prefix);
+    },
     handler: async (args: string, ctx: ExtensionCommandContext) => {
       let state = getState();
       if (!state && runtime.ensureState) {

package/proxy-modes.ts

@@ -9,6 +9,7 @@ import { abortable, throwIfAborted } from "./abort.ts";
 import { combineAbortSignals, isAbortError } from "./runtime-owner.ts";
 import { buildToolMetadata, getToolNames, formatSchema } from "./tool-metadata.ts";
 import { renderTsShape } from "./ts-shape.ts";
+import { getObservedOutput, recordObservedOutput, renderOutputShape } from "./output-shape.ts";
 import { reconstructPromptMetadata } from "./metadata-cache.ts";
 import { resolveMcpResultContent, transformMcpResourceContents } from "./tool-registrar.ts";
 import { guardMcpOutput, guardedMcpDetails, resolveMcpOutputGuardOptions } from "./mcp-output-guard.ts";
@@ -17,6 +18,7 @@ import { formatAuthRequiredMessage, formatMcpStatus, normalizeToolArguments, res
 import { authenticate, completeAuthFromInput, getAuthStatus, startAuth, supportsOAuth } from "./mcp-auth-flow.ts";
 import { SessionRecoveryAuthRequiredError, withSessionRecovery } from "./session-recovery.ts";
 import { callToolViaTaskSession } from "./mcp-tasks.ts";
+import { callToolPausingForElicitation } from "./elicitation-handler.ts";
 import { paginate, rankSuggestions, rankToolMatches, resolveSearchKeywords } from "./search-ranking.ts";
 import { ensureToolCallApproved, isToolCallApprovalRequired } from "./tool-approval.ts";
 import { describeFailure, isServerInActiveFailureBackoff } from "./failure-backoff.ts";
@@ -704,6 +706,22 @@ export async function executeAuthComplete(state: McpExtensionState, serverName:
   }
 }
 
+function formatToolHints(toolMeta: ToolMetadata): string {
+  const annotations = toolMeta.annotations;
+  if (!annotations) return "";
+  const hints: string[] = [];
+  const flag = (value: boolean | undefined, yes: string, no: string) => {
+    if (value !== undefined) hints.push(value ? yes : no);
+  };
+  flag(annotations.readOnlyHint, "read-only", "not read-only");
+  flag(annotations.destructiveHint, "destructive", "non-destructive");
+  flag(annotations.idempotentHint, "idempotent", "not idempotent");
+  flag(annotations.openWorldHint, "open-world", "closed-world");
+  const title = annotations.title?.trim();
+  if (title && title !== toolMeta.originalName && title !== toolMeta.name) hints.push(`title ${JSON.stringify(title)}`);
+  return hints.join(", ");
+}
+
 export function executeDescribe(state: McpExtensionState, toolName: string, serverOverride?: string): ProxyToolResult {
   let serverName: string | undefined;
   let toolMeta: ToolMetadata | undefined;
@@ -770,6 +788,8 @@ export function executeDescribe(state: McpExtensionState, toolName: string, serv
   if (toolMeta.resourceUri) {
     text += `Type: Resource (reads from ${toolMeta.resourceUri})\n`;
   }
+  const hints = formatToolHints(toolMeta);
+  if (hints) text += `Hints: ${hints}\n`;
   text += `\n${toolMeta.description || "(no description)"}\n`;
 
   if (toolMeta.inputSchema && !toolMeta.resourceUri) {
@@ -781,6 +801,12 @@ export function executeDescribe(state: McpExtensionState, toolName: string, serv
     text += `\nNo parameters defined.`;
   }
 
+  const observed = toolMeta.resourceUri ? undefined : getObservedOutput(state, serverName, toolMeta);
+  if (observed) {
+    const source = observed.source === "structuredContent" ? "structuredContent" : "JSON text result";
+    text += `\n\nObserved output (${source}, from ${observed.calls} call${observed.calls === 1 ? "" : "s"} this session, not a contract):\n${renderOutputShape(observed.shape)}`;
+  }
+
   return {
     content: [{ type: "text" as const, text: text.trim() }],
     details: { mode: "describe", tool: toolMeta, server: serverName },
@@ -1629,13 +1655,14 @@ export async function executeCall(
             requestTimeoutMs: requestOptions?.timeout,
           }) as unknown as ClientCallToolResult;
         }
-        return abortable(conn.client.callTool({
+        return abortable(callToolPausingForElicitation(conn.client, {
           name: toolMeta.originalName,
           arguments: normalizedArgs,
           _meta: requestMeta,
         }, requestOptions), ownedSignal);
       },
     );
+    if (!result.isError) recordObservedOutput(state, serverName, toolMeta.originalName, result as Record<string, unknown>);
 
     if (toolMeta.uiResourceUri) {
       uiSession?.sendToolResult(result as unknown as import("@modelcontextprotocol/client").CallToolResult);

package/skills/mcp-scripting/SKILL.md

@@ -34,6 +34,8 @@ Descriptors include `inputTypeScript` (a compact parameter shape, or formatted s
 
 When advertised by the server, `outputSchema` is the original JSON Schema and `outputSchemaTarget` is `"data.structuredContent"`: it describes structured output inside the successful `{ ok: true, data }` call envelope, not the envelope itself. Inspect this schema for result fields and constraints; unsupported constructs remain intact rather than being presented as an approximate TypeScript type. Both output fields are absent when no output schema is advertised. Discovery and cache refresh preserve these optional schemas; old cache entries gain them on the next server metadata refresh. Ordinary search results do not include schemas.
 
+When no output schema is advertised but the tool already returned structured content or a JSON text result earlier in this session, `observedOutput` gives `{ target, typeScript, calls }`: the path inside the call envelope (`"data.structuredContent"` or `"JSON.parse(data.content[0].text)"`), the field names and types seen so far, and how many calls they came from. It is a hint, not a contract: fields missing from some results are optional, and wide objects appear as `Record<string, ...>`.
+
 Calls resolve to `{ ok: true, data }` or `{ ok: false, error }`; handle failed calls instead of expecting them to stop the script. `emit(value)` adds user-visible output before the final `return` value. `console` output is captured too.
 
 With `settings.jev.scriptEvaluation` enabled, call `jev.evaluate({ state, questions, sources })`; declare every MCP server represented in state. The host conservatively taints the whole script with every server-attributed call result or error, so every declared or observed source must remain enabled and allowed for later direct evaluations and semantic searches. Semantic search requires `searchMode: "semantic"`. Direct and semantic attempts share count, UTF-8 request-byte, deadline, and provider-reported token budgets. Scores do not bypass `tools.call` approval. Action loops must use fresh observations, positive step/time/evaluation budgets, validated operations and targets, and stop on uncertainty, staleness, no progress, no match, or missing information. Do not retry a possibly side-effectful action.

package/state.ts

@@ -3,11 +3,12 @@ import type { ConsentManager } from "./consent-manager.ts";
 import type { McpLifecycleManager } from "./lifecycle.ts";
 import type { McpServerManager } from "./server-manager.ts";
 import type { AuthStorageOptions } from "./mcp-auth.ts";
-import type { ServerDefinition, ToolMetadata, PromptMetadata, McpConfig, UiSessionMessages, UiStreamSummary, McpStatusEventBus, UiServerHandle, ProjectServerBlock } from "./types.ts";
+import type { ServerDefinition, ToolMetadata, PromptMetadata, ServerCacheEntry, McpConfig, UiSessionMessages, UiStreamSummary, McpStatusEventBus, UiServerHandle, ProjectServerBlock } from "./types.ts";
 import type { UiResourceHandler } from "./ui-resource-handler.ts";
 import type { McpRuntimeOwner } from "./runtime-owner.ts";
 import type { McpOAuthRuntime } from "./mcp-auth-flow.ts";
 import type { SessionApprovalWriter } from "./session-approvals.ts";
+import type { ObservedOutput } from "./output-shape.ts";
 
 export interface CompletedUiSession {
   serverName: string;
@@ -33,6 +34,7 @@ export interface McpExtensionState {
   manager: McpServerManager;
   lifecycle: McpLifecycleManager;
   toolMetadata: Map<string, ToolMetadata[]>;
+  sessionMetadata?: Map<string, ServerCacheEntry>;
   /** Number of tools currently registered directly with Pi, by server. */
   directToolCounts: Map<string, number>;
   /** Resource counts retained separately because tool metadata includes resource tools. */
@@ -53,6 +55,9 @@ export interface McpExtensionState {
   failureMessages: Map<string, string>;
   /** Session-only approvals keyed by server, tool definition, and arguments. */
   approvedToolCalls: Map<string, true>;
+  /** Session-only output shapes learned from successful calls to tools without an outputSchema, by tool name.
+   * Keyed by the server's config entry so a replaced or reconfigured server starts over. Never persisted. */
+  observedOutputs?: WeakMap<ServerDefinition, Map<string, ObservedOutput>>;
   /** Configured project servers disabled by trust or approval policy for this session. */
   blockedProjectServers?: Map<string, ProjectServerBlock>;
   /** Runtime-only server grants. Never persisted or restored from session entries. */

package/tool-approval.ts

@@ -1,4 +1,5 @@
 import { randomUUID } from "node:crypto";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { abortable } from "./abort.ts";
 import { combineAbortSignals } from "./runtime-owner.ts";
 import type { McpExtensionState } from "./state.ts";
@@ -24,15 +25,23 @@ export type ToolCallApprovalResult =
 export function isToolCallApprovalRequired(
   config: McpConfig,
   serverName: string,
-  toolMeta: Pick<ToolMetadata, "originalName">,
+  toolMeta: Pick<ToolMetadata, "originalName" | "annotations" | "resourceUri">,
   toolMetadata?: ReadonlyMap<string, readonly ToolMetadata[]>,
 ): boolean {
   const definition = config.mcpServers[serverName];
   const serverApproval = definition?.approveTools;
   const approval = serverApproval !== undefined ? serverApproval : config.settings?.approveTools;
 
-  if (approval === true) return true;
-  if (!Array.isArray(approval) || approval.length === 0) return false;
+  if (approval === undefined || approval === false) return false;
+  // MCP treats a tool as possibly destructive unless it says otherwise; reading a resource never is.
+  if (approval === "destructive") {
+    return toolMeta.resourceUri === undefined
+      && toolMeta.annotations?.readOnlyHint !== true
+      && toolMeta.annotations?.destructiveHint !== false;
+  }
+  // Values from unvalidated sources (imports, runtime registration) fail closed.
+  if (!Array.isArray(approval)) return true;
+  if (approval.length === 0) return false;
 
   const prefix = resolveToolPrefix(definition, config.settings?.toolPrefix);
   const currentCandidates = getToolNameCandidates(toolMeta.originalName, serverName, prefix, false);
@@ -88,15 +97,19 @@ function isMcpToolApprovalDecision(value: unknown): value is McpToolApprovalDeci
     || value === "abstain";
 }
 
-async function requestBrokerApproval(
-  state: McpExtensionState,
+/**
+ * Returns "abstain" when no handler claims the request. A handler that throws
+ * or returns an unknown value counts as "deny". Rethrows only when `signal` aborted.
+ */
+export async function requestBrokerApproval(
+  events: ExtensionAPI["events"] | undefined,
   serverName: string,
-  toolMeta: ToolMetadata,
+  toolMeta: Pick<ToolMetadata, "name" | "originalName">,
   args: Record<string, unknown> | undefined,
   origin: McpToolApprovalOrigin,
   signal?: AbortSignal,
 ): Promise<McpToolApprovalDecision> {
-  if (!state.approvalEvents) return "abstain";
+  if (!events) return "abstain";
 
   let acceptingClaim = true;
   let handler: McpToolApprovalHandler | undefined;
@@ -115,7 +128,7 @@ async function requestBrokerApproval(
     },
   };
 
-  state.approvalEvents.emit(MCP_TOOL_APPROVAL_REQUEST_EVENT, request);
+  events.emit(MCP_TOOL_APPROVAL_REQUEST_EVENT, request);
   acceptingClaim = false;
   if (!handler) return "abstain";
 
@@ -140,7 +153,7 @@ export async function ensureToolCallApproved(
   const ownedSignal = combineAbortSignals(state.owner?.signal, signal);
   const approvedServers = state.approvedServers ??= new Map();
   const serverIdentity = getServerApprovalIdentity(state, serverName);
-  const brokerDecision = await requestBrokerApproval(state, serverName, toolMeta, args, origin, signal);
+  const brokerDecision = await requestBrokerApproval(state.approvalEvents, serverName, toolMeta, args, origin, signal);
   if (brokerDecision === "allow_once") return { ok: true };
   if (brokerDecision === "allow_for_session") {
     rememberToolApproval(state, serverName, toolMeta, args);
@@ -175,10 +188,15 @@ export async function ensureToolCallApproved(
   const sanitized = sanitizeTerminalText(json);
   const preview = sanitized.length > 500 ? `${sanitized.slice(0, 500)}...` : sanitized;
   const title = `MCP: ${sanitizeTerminalText(serverName)} wants to run ${sanitizeTerminalText(toolMeta.originalName)}`;
+  const hint = toolMeta.annotations?.destructiveHint === true
+    ? "\n\nThe server marks this tool as destructive: it may delete or overwrite data."
+    : toolMeta.annotations?.readOnlyHint === true
+      ? "\n\nThe server marks this tool as read-only."
+      : "";
   const serverScope = "Allow server for this session permits all tools and arguments on this server until reload or session/branch change. Other security and UI consent checks still apply.";
   const decision = await abortable(
     state.ui.select(
-      `${title}\n\nArguments:\n${preview}\n\n${serverScope}`,
+      `${title}${hint}\n\nArguments:\n${preview}\n\n${serverScope}`,
       ["Allow once", "Allow for session", "Allow server for this session", "Deny"],
     ),
     ownedSignal,

package/tool-metadata.ts

@@ -3,7 +3,7 @@ import type { McpExtensionState } from "./state.ts";
 import type { ToolMetadata, McpTool, McpResource, ServerEntry, ToolPrefix } from "./types.ts";
 import { createToolSelectorCandidateIndex, formatToolName, getToolNameCandidates, isToolAllowed, resolveToolPrefix, resolveUniqueNameOwnership } from "./types.ts";
 import { resourceNameToToolName } from "./resource-tools.ts";
-import { extractToolUiStreamMode } from "./utils.ts";
+import { extractToolAnnotations, extractToolUiStreamMode } from "./utils.ts";
 import { extractUiToolVisibility, isUiToolVisibleToModel } from "./ui-tool-visibility.ts";
 
 export function buildToolMetadata(
@@ -96,6 +96,7 @@ export function buildToolMetadata(
       failedTools.push(tool.name);
     }
     const uiStreamMode = extractToolUiStreamMode(tool._meta);
+    const annotations = extractToolAnnotations(tool.annotations);
     metadata.push({
       name,
       originalName: tool.name,
@@ -105,6 +106,7 @@ export function buildToolMetadata(
       ...(uiResourceUri !== undefined ? { uiResourceUri } : {}),
       ...(uiVisibility !== undefined ? { uiVisibility } : {}),
       ...(uiStreamMode !== undefined ? { uiStreamMode } : {}),
+      ...(annotations !== undefined ? { annotations } : {}),
     });
   }
 

package/tool-parameters.ts

@@ -0,0 +1,11 @@
+import { Type } from "typebox";
+
+// OMP remaps `typebox` to a host shim that historically lacked Type.Unsafe.
+// Prefer Unsafe when present (real TypeBox / fixed OMP shim); otherwise pass
+// the normalized JSON Schema through as a plain object so toolWireSchema and
+// validateToolArguments still treat it as JSON Schema.
+export function toToolParameters(schema: Record<string, unknown>): unknown {
+  return typeof (Type as { Unsafe?: (value: never) => unknown }).Unsafe === "function"
+    ? (Type as { Unsafe: (value: never) => unknown }).Unsafe(schema as never)
+    : schema;
+}

package/ts-shape.ts

@@ -140,7 +140,7 @@ function renderLiteral(value: unknown): string | null {
   return typeof value === "number" && Number.isFinite(value) ? String(value) : null;
 }
 
-function formatPropertyName(name: string): string {
+export function formatPropertyName(name: string): string {
   return /^[A-Za-z_$][\w$]*$/.test(name) ? name : JSON.stringify(name);
 }
 

package/types.ts

@@ -97,6 +97,7 @@ export interface McpTool {
   description?: SdkTool["description"];
   inputSchema?: SdkTool["inputSchema"]; // JSON Schema
   outputSchema?: SdkTool["outputSchema"]; // JSON Schema for structuredContent
+  annotations?: SdkTool["annotations"];
   _meta?: SdkTool["_meta"];
 }
 
@@ -488,7 +489,7 @@ export interface ServerEntry {
    */
   searchKeywords?: Record<string, string[]>;
   // Require interactive approval before calling matching MCP tools/resources.
-  approveTools?: boolean | string[];
+  approveTools?: boolean | "destructive" | string[];
   // Debug
   debug?: boolean;  // Show server stderr (default: false)
   /** Enable metadata-only JSONL protocol tracing for this server. */
@@ -661,7 +662,7 @@ export interface McpSettings {
   /** Number of result text lines to show before expansion. Supports 1, 2, or 3. Defaults to 1 in compact mode and 3 in boxed mode. */
   collapsedResultLines?: 1 | 2 | 3;
   /** Default approval gate for matching tools/resources; per-server settings override it. */
-  approveTools?: boolean | string[];
+  approveTools?: boolean | "destructive" | string[];
   disableProxyTool?: boolean;
   /** Freeze direct-tool registration after the initial sync. Automatic metadata updates
    * and explicit reconnects won't rebuild the system prompt, preserving the
@@ -739,6 +740,16 @@ export interface ToolMetadata {
   inputSchema?: unknown;  // JSON Schema for parameters (stored for describe/errors)
   outputSchema?: unknown; // Server schema for structuredContent (stored for describe)
   uiStreamMode?: UiStreamMode;
+  annotations?: McpToolAnnotations;
+}
+
+/** Behavior hints a server declared on a tool. Hints, not guarantees. */
+export interface McpToolAnnotations {
+  title?: string;
+  readOnlyHint?: boolean;
+  destructiveHint?: boolean;
+  idempotentHint?: boolean;
+  openWorldHint?: boolean;
 }
 
 export interface PromptMetadata {
@@ -782,6 +793,7 @@ export interface CachedTool {
   uiResourceUri?: string;
   uiVisibility?: UiToolVisibility[];
   uiStreamMode?: "eager" | "stream-first";
+  annotations?: McpToolAnnotations;
 }
 
 export interface CachedResource {

package/ui-server.ts

@@ -10,7 +10,7 @@ import {
 import { ContentBlockSchema } from "@modelcontextprotocol/core";
 import type { ConsentManager } from "./consent-manager.ts";
 import { ServerError, wrapError } from "./errors.ts";
-import { formatAuthRequiredMessage, normalizeToolArguments } from "./utils.ts";
+import { extractToolAnnotations, formatAuthRequiredMessage, normalizeToolArguments } from "./utils.ts";
 import { buildHostHtmlTemplate, buildSandboxResourceCsp } from "./host-html-template.ts";
 import {
   buildSandboxProxyCsp,
@@ -24,6 +24,7 @@ import type { McpExtensionState } from "./state.ts";
 import { SessionRecoveryAuthRequiredError, withSessionRecovery, type SessionRecoveryDeps } from "./session-recovery.ts";
 import { ensureToolCallApproved, isToolCallApprovalRequired } from "./tool-approval.ts";
 import { callToolViaTaskSession } from "./mcp-tasks.ts";
+import { callToolPausingForElicitation } from "./elicitation-handler.ts";
 import { extractUiToolVisibility, isUiToolCallableByApp, isUiToolVisibleToModel } from "./ui-tool-visibility.ts";
 import { resourceNameToToolName } from "./resource-tools.ts";
 import {
@@ -471,6 +472,7 @@ export async function startUiServer(options: UiServerOptions): Promise<UiServerH
         } catch {
           // Preserve the endpoint's existing behavior for malformed declarations.
         }
+        const annotations = extractToolAnnotations(toolDefinition.annotations);
         const toolMeta = {
           name: callParams.name,
           originalName: callParams.name,
@@ -478,6 +480,7 @@ export async function startUiServer(options: UiServerOptions): Promise<UiServerH
           ...(toolDefinition?.inputSchema !== undefined ? { inputSchema: toolDefinition.inputSchema } : {}),
           ...(uiResourceUri !== undefined ? { uiResourceUri } : {}),
           ...(uiVisibility !== undefined ? { uiVisibility } : {}),
+          ...(annotations !== undefined ? { annotations } : {}),
         };
         const approvalMetadata = new Map(options.state?.toolMetadata);
         const definition = options.config?.mcpServers[options.serverName] ?? options.state?.config.mcpServers[options.serverName];
@@ -542,7 +545,7 @@ export async function startUiServer(options: UiServerOptions): Promise<UiServerH
                 signal: requestOptions?.signal,
               });
             }
-            return conn.client.callTool(callArgs, requestOptions);
+            return callToolPausingForElicitation(conn.client, callArgs, requestOptions);
           };
           const result = options.config
             ? await withSessionRecovery(

package/unix-socket-transport.ts

@@ -30,7 +30,7 @@ export class UnixSocketClientTransport implements Transport {
       });
       socket.on("data", chunk => {
         try {
-          this.readBuffer.append(chunk);
+          this.readBuffer.append(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
           while (true) {
             const message = this.readBuffer.readMessage();
             if (message === null) break;

package/utils.ts

@@ -4,7 +4,7 @@ import { existsSync, realpathSync } from "node:fs";
 import { homedir, platform } from "node:os";
 import { dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import stripJsonComments from "strip-json-comments";
-import type { McpConfig, ServerEntry } from "./types.ts";
+import type { McpConfig, McpToolAnnotations, ServerEntry } from "./types.ts";
 
 export function stripUtf8Bom(raw: string): string {
   return raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw;
@@ -477,3 +477,18 @@ export function extractToolUiStreamMode(toolMeta: Record<string, unknown> | unde
   }
   return undefined;
 }
+
+/**
+ * Keep only the spec tool annotations with the right types. Server and cache
+ * input is untrusted, so a malformed field is dropped instead of failing the tool list.
+ */
+export function extractToolAnnotations(annotations: unknown): McpToolAnnotations | undefined {
+  if (!annotations || typeof annotations !== "object") return undefined;
+  const source = annotations as Record<string, unknown>;
+  const kept: McpToolAnnotations = {};
+  if (typeof source.title === "string") kept.title = source.title;
+  for (const key of ["readOnlyHint", "destructiveHint", "idempotentHint", "openWorldHint"] as const) {
+    if (typeof source[key] === "boolean") kept[key] = source[key];
+  }
+  return Object.keys(kept).length > 0 ? kept : undefined;
+}