@ian-pascoe/pi-mcp 0.3.2 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ian-pascoe/pi-mcp",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "private": false,
   "description": "A complete Model Context Protocol Host for Pi",
   "keywords": [

package/src/mcp-presentation.ts

@@ -1,4 +1,5 @@
 /* oxlint-disable anti-slop/no-conditional-empty-object-spread, anti-slop/no-known-value-widening, anti-slop/no-runtime-typeof, anti-slop/no-unknown-parameters, anti-slop/no-unknown-returns, anti-slop/no-unsafe-dictionary-type -- MCP Transcript Presentation owns Pi's untyped historical result, tool-argument, and custom-message rendering boundaries. */
+import type { JSONValue } from "@modelcontextprotocol/client";
 import {
   DEFAULT_MAX_BYTES,
   DEFAULT_MAX_LINES,
@@ -32,24 +33,23 @@ const MCP_PRESENTATION_TEXT_STYLE_RESET = "\u001b[22;39m";
 const MCP_PRESENTATION_METADATA_LIMIT = 20;
 const MCP_PRESENTATION_RESERVED_BYTES = 8 * 1024;
 const MCP_PRESENTATION_RESERVED_LINES = 64;
-const McpResultDetailsMarkerSchema = Type.Object(
+/** MCP result marker schema shared by persisted-result parsing and tool output metadata. */
+export const McpResultMarkerSchema = Type.Object(
   {
-    mcp: Type.Object(
-      {
-        isError: Type.Boolean(),
-        operation: Type.Optional(Type.String()),
-        outputSchemaError: Type.Optional(Type.String()),
-        outputSchemaValid: Type.Optional(Type.Boolean()),
-        owner: Type.Literal(MCP_DETAILS_OWNER),
-        serverId: Type.Optional(Type.String()),
-        toolName: Type.Optional(Type.String()),
-      },
-      { additionalProperties: true },
-    ),
-    result: Type.Any(),
+    isError: Type.Boolean(),
+    operation: Type.Optional(Type.String()),
+    outputSchemaError: Type.Optional(Type.String()),
+    outputSchemaValid: Type.Optional(Type.Boolean()),
+    owner: Type.Literal(MCP_DETAILS_OWNER),
+    serverId: Type.Optional(Type.String()),
+    toolName: Type.Optional(Type.String()),
   },
   { additionalProperties: true },
 );
+const McpResultDetailsMarkerSchema = Type.Object(
+  { mcp: McpResultMarkerSchema, result: Type.Any() },
+  { additionalProperties: true },
+);
 
 /** Theme operations used by MCP Transcript Presentation and custom-message renderers. */
 export type McpRenderTheme = Pick<Theme, "bg" | "bold" | "fg">;
@@ -68,10 +68,11 @@ export interface McpResultMarker {
   readonly toolName?: string;
 }
 
-/** Existing persisted MCP tool details consumed without changing their stored shape. */
+/** MCP tool details containing host metadata, mapped result details, and optional structured output. */
 export interface McpResultDetails {
   readonly mcp: McpResultMarker;
   readonly result: unknown;
+  readonly structuredContent?: JSONValue;
 }
 
 /** One role-faithful Prompt message persisted for context replay and TUI presentation. */

package/src/mcp-tool-catalog.ts

@@ -15,6 +15,7 @@ import type {
 } from "@earendil-works/pi-coding-agent";
 import type { TSchema } from "typebox";
 import {
+  McpResultMarkerSchema,
   parseMcpResultDetails,
   renderMcpResourceToolCall,
   renderMcpServerToolCall,
@@ -45,6 +46,69 @@ const ReadResourceSchema = {
   additionalProperties: false,
 } as const;
 
+type McpOutputSchemaToolDefinition<TParameters extends TSchema = TSchema> = ToolDefinition<
+  TParameters,
+  unknown
+> & {
+  readonly outputSchema: JsonSchemaType;
+};
+
+function mcpResultDetailsOutputSchema(structuredContentSchema?: JsonSchemaType): JsonSchemaType {
+  return {
+    type: "object",
+    properties: {
+      mcp: McpResultMarkerSchema,
+      result: {},
+      ...(structuredContentSchema === undefined
+        ? {}
+        : { structuredContent: structuredContentSchema }),
+    },
+    required: ["mcp", "result"],
+    additionalProperties: false,
+  };
+}
+
+function validatedMcpResultDetailsOutputSchema(
+  structuredContentSchema: JsonSchemaType,
+): JsonSchemaType {
+  const validationMarker = (valid: boolean): JsonSchemaType => ({
+    allOf: [
+      McpResultMarkerSchema,
+      {
+        type: "object",
+        properties: { outputSchemaValid: { const: valid } },
+        required: ["outputSchemaValid"],
+      },
+    ],
+  });
+  return {
+    anyOf: [
+      {
+        type: "object",
+        properties: {
+          mcp: validationMarker(true),
+          result: {},
+          structuredContent: structuredContentSchema,
+        },
+        required: ["mcp", "result"],
+        additionalProperties: false,
+      },
+      {
+        type: "object",
+        properties: {
+          mcp: validationMarker(false),
+          result: {},
+          structuredContent: {},
+        },
+        required: ["mcp", "result"],
+        additionalProperties: false,
+      },
+    ],
+  };
+}
+
+const RESOURCE_RESULT_DETAILS_OUTPUT_SCHEMA = mcpResultDetailsOutputSchema();
+
 /** Minimal public Pi surface required to register and activate MCP tools. */
 export interface McpToolCatalogPi {
   /** Register or replace one Pi tool by name. */
@@ -298,9 +362,16 @@ export class McpToolCatalog {
     this.syncActiveTools(activeNames);
   }
 
-  private serverToolDefinition(compiled: CompiledServerTool, piToolName: string): ToolDefinition {
+  private serverToolDefinition(
+    compiled: CompiledServerTool,
+    piToolName: string,
+  ): McpOutputSchemaToolDefinition {
     // SAFETY: MCP's parsed Tool contract requires inputSchema to be JSON Schema; fromJsonSchema compiled this exact object above. Pi accepts the same structural schema without TypeBox metadata.
     const parameters = compiled.definition.inputSchema as TSchema;
+    const outputSchema =
+      compiled.outputValidator !== undefined && compiled.definition.outputSchema !== undefined
+        ? validatedMcpResultDetailsOutputSchema(compiled.definition.outputSchema)
+        : mcpResultDetailsOutputSchema({});
     return {
       name: piToolName,
       label:
@@ -310,6 +381,7 @@ export class McpToolCatalog {
       description:
         compiled.definition.description ?? `Call MCP Server Tool ${compiled.definition.name}.`,
       parameters,
+      outputSchema,
       renderCall: (arguments_, theme, context) =>
         renderMcpServerToolCall(
           compiled.serverId,
@@ -378,7 +450,16 @@ export class McpToolCatalog {
         ? {}
         : { serverId: compiled.serverId, toolName: compiled.definition.name }),
     };
-    return { content, details: { mcp, result: result.details } };
+    return {
+      content,
+      details: {
+        mcp,
+        result: result.details,
+        ...(result.structuredContent === undefined
+          ? {}
+          : { structuredContent: result.structuredContent }),
+      },
+    };
   }
 
   private registerResourceTools(): void {
@@ -387,6 +468,7 @@ export class McpToolCatalog {
       label: "List MCP Resources",
       description: "List Resources advertised by connected MCP Servers.",
       parameters: ListResourcesSchema,
+      outputSchema: RESOURCE_RESULT_DETAILS_OUTPUT_SCHEMA,
       renderCall: (parameters, theme, context) =>
         renderMcpResourceToolCall(
           "list_resources",
@@ -411,6 +493,7 @@ export class McpToolCatalog {
       label: "List MCP Resource Templates",
       description: "List Resource Templates advertised by connected MCP Servers.",
       parameters: ListResourcesSchema,
+      outputSchema: RESOURCE_RESULT_DETAILS_OUTPUT_SCHEMA,
       renderCall: (parameters, theme, context) =>
         renderMcpResourceToolCall(
           "list_resource_templates",
@@ -435,6 +518,7 @@ export class McpToolCatalog {
       label: "Read MCP Resource",
       description: "Read one Resource from a connected MCP Server.",
       parameters: ReadResourceSchema,
+      outputSchema: RESOURCE_RESULT_DETAILS_OUTPUT_SCHEMA,
       renderCall: (parameters, theme, context) =>
         renderMcpResourceToolCall(
           "read_resource",
@@ -457,7 +541,7 @@ export class McpToolCatalog {
   }
 
   private registerResourceTool<TParameters extends TSchema>(
-    tool: ToolDefinition<TParameters, unknown>,
+    tool: McpOutputSchemaToolDefinition<TParameters>,
   ): void {
     this.ownedToolNames.add(tool.name);
     this.pi.registerTool(tool);