feat(mcp): add MCP 2025-06-18 compliance with output schemas and annotations

- Add outputSchema to core tools for structured validation
- Add tool annotations (readOnlyHint, idempotentHint, longRunningHint, title)
- Add semantic property descriptions for better LLM tool selection
- Extend ToolRegistry to support outputSchema and annotations
- Update token budgets for MCP 2025-06-18 requirements
- Update release notes with MCP compliance section

Tools updated: auto_optimize, smart_file_read, discover_tools,
code_execute, session_stats, summarize_logs

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: ArthurDEV44

RELEASE_NOTES_v0.8.0.md

@@ -108,6 +108,46 @@ Nouveau mode de résumé pour les fichiers volumineux :
 
 ---
 
+## Conformité MCP 2025-06-18
+
+### Output Schemas
+
+Tous les outils principaux incluent maintenant des schémas de sortie conformes à la spécification MCP 2025-06-18 :
+
+- **Validation structurée** : Les résultats sont validés contre un schéma défini
+- **Documentation automatique** : Chaque champ de sortie est documenté avec sa description et son type
+- **Interopérabilité** : Meilleure intégration avec les clients MCP conformes
+
+Outils mis à jour : `auto_optimize`, `smart_file_read`, `discover_tools`, `code_execute`, `session_stats`, `summarize_logs`.
+
+### Annotations d'outils
+
+Nouveau système d'annotations pour guider les LLMs dans l'utilisation des outils :
+
+- **readOnlyHint** : Indique que l'outil ne modifie pas l'état du système
+- **destructiveHint** : Avertit des opérations potentiellement destructives
+- **idempotentHint** : Signale que le même input produit toujours le même résultat
+- **longRunningHint** : Prévient que l'exécution peut être longue
+- **title** : Titre lisible pour l'affichage dans les interfaces
+
+### Descriptions sémantiques
+
+Les schémas d'entrée incluent maintenant des descriptions détaillées pour chaque propriété :
+
+- Amélioration de la sélection automatique d'outils par les LLMs
+- Documentation inline des paramètres avec valeurs par défaut
+- Contraintes de validation (`minLength`, `minimum`, `maximum`)
+
+### Registre d'outils étendu
+
+Le `ToolRegistry` supporte maintenant :
+
+- `outputSchema` optionnel pour chaque outil
+- `annotations` pour les métadonnées comportementales
+- Sérialisation complète dans la réponse `ListTools`
+
+---
+
 ## Pipeline Builder fluide
 
 Nouvelle API chaînable pour les opérations multi-étapes :

packages/mcp-server/src/tools/auto-optimize.ts

@@ -17,18 +17,66 @@ import { countTokens } from "../utils/token-counter.js";
 
 type OutputFormat = "plain" | "markdown";
 
-// Minimal schema - format rarely used, keep only essential properties
+// Input schema with semantic descriptions for better LLM understanding
 const autoOptimizeSchema = {
   type: "object" as const,
   properties: {
-    content: { type: "string" },
-    hint: { enum: ["build", "logs", "errors", "code", "auto"] },
-    aggressive: { type: "boolean" },
-    format: { enum: ["plain", "markdown"] },
+    content: {
+      type: "string",
+      description: "The content to optimize (build output, logs, errors, or any text)",
+      minLength: 100,
+    },
+    hint: {
+      enum: ["build", "logs", "errors", "code", "auto"],
+      description: "Content type hint: build (compiler errors), logs (server/test logs), errors (stack traces), code (source code), auto (detect)",
+      default: "auto",
+    },
+    aggressive: {
+      type: "boolean",
+      description: "Enable aggressive compression for maximum token savings",
+      default: false,
+    },
+    format: {
+      enum: ["plain", "markdown"],
+      description: "Output format",
+      default: "plain",
+    },
   },
   required: ["content"],
 };
 
+// Output schema per MCP 2025-06-18 spec for structured validation
+const autoOptimizeOutputSchema = {
+  type: "object" as const,
+  properties: {
+    detectedType: {
+      type: "string",
+      description: "Detected or specified content type",
+    },
+    originalTokens: {
+      type: "number",
+      description: "Token count before optimization",
+    },
+    optimizedTokens: {
+      type: "number",
+      description: "Token count after optimization",
+    },
+    savingsPercent: {
+      type: "number",
+      description: "Percentage of tokens saved (0-100)",
+    },
+    method: {
+      type: "string",
+      description: "Compression method used",
+    },
+    optimizedContent: {
+      type: "string",
+      description: "The optimized content",
+    },
+  },
+  required: ["detectedType", "originalTokens", "optimizedTokens", "savingsPercent", "optimizedContent"],
+};
+
 interface AutoOptimizeArgs {
   content: string;
   hint?: "build" | "logs" | "errors" | "code" | "auto";
@@ -229,7 +277,16 @@ async function autoOptimize(
 
 export const autoOptimizeTool: ToolDefinition = {
   name: "auto_optimize",
-  description: "Auto-compress verbose output (build errors, logs). 80-95% token reduction.",
+  description:
+    "Auto-compress verbose output (build errors, logs, stack traces). " +
+    "Detects content type and applies optimal compression. " +
+    "Typical savings: build errors 95%, logs 80-90%, generic 40-60%.",
   inputSchema: autoOptimizeSchema,
+  outputSchema: autoOptimizeOutputSchema,
+  annotations: {
+    title: "Auto Optimize Content",
+    readOnlyHint: true,
+    idempotentHint: true,
+  },
   execute: async (args) => autoOptimize(args as AutoOptimizeArgs),
 };

packages/mcp-server/src/tools/code-execute.ts

@@ -9,17 +9,42 @@ import type { ToolDefinition } from "./registry.js";
 import { executeSandbox, DEFAULT_LIMITS } from "../sandbox/index.js";
 
 /**
- * Minimal schema for token efficiency
+ * Input schema with semantic descriptions
  */
 const codeExecuteSchema = {
   type: "object" as const,
   properties: {
-    code: { type: "string" },
-    timeout: { type: "number" },
+    code: {
+      type: "string",
+      description:
+        "TypeScript code to execute. Use 'return' to output results. " +
+        "Access SDK via 'ctx' object (ctx.files, ctx.compress, ctx.code, etc.)",
+    },
+    timeout: {
+      type: "number",
+      description: "Execution timeout in ms (1000-30000)",
+      minimum: 1000,
+      maximum: 30000,
+      default: 5000,
+    },
   },
   required: ["code"],
 };
 
+/**
+ * Output schema per MCP 2025-06-18 spec
+ */
+const codeExecuteOutputSchema = {
+  type: "object" as const,
+  properties: {
+    success: { type: "boolean", description: "Whether execution succeeded" },
+    output: { type: "string", description: "Execution result or error message" },
+    executionTimeMs: { type: "number", description: "Time taken in milliseconds" },
+    tokensUsed: { type: "number", description: "Tokens in output" },
+  },
+  required: ["success", "output"],
+};
+
 interface CodeExecuteArgs {
   code: string;
   timeout?: number;
@@ -98,5 +123,12 @@ export const codeExecuteTool: ToolDefinition = {
   name: "code_execute",
   description: DESCRIPTION,
   inputSchema: codeExecuteSchema,
+  outputSchema: codeExecuteOutputSchema,
+  annotations: {
+    title: "Execute TypeScript Code",
+    readOnlyHint: false, // Can modify files via ctx.files
+    idempotentHint: false, // Results depend on filesystem state
+    longRunningHint: true, // May take up to 30s
+  },
   execute: executeCodeExecute,
 };

packages/mcp-server/src/tools/discover-tools.ts

@@ -18,17 +18,57 @@ import {
   type ToolMetadataLite,
 } from "../utils/toon-serializer.js";
 
-// Minimal schema - descriptions in tool description, not properties
+// Input schema with semantic descriptions per MCP best practices
 const discoverToolsSchema = {
   type: "object" as const,
   properties: {
-    query: { type: "string" },
-    category: { enum: ["compress", "analyze", "logs", "code", "pipeline"] },
-    load: { type: "boolean" },
-    format: { enum: ["list", "toon", "toon-tabular"] },
+    query: {
+      type: "string",
+      description: "Search query to find tools by name or description",
+    },
+    category: {
+      enum: ["compress", "analyze", "logs", "code", "pipeline"],
+      description: "Filter tools by category",
+    },
+    load: {
+      type: "boolean",
+      description: "Activate matched tools for immediate use",
+      default: false,
+    },
+    format: {
+      enum: ["list", "toon", "toon-tabular"],
+      description: "Output format: list (readable), toon/toon-tabular (token-efficient ~55% savings)",
+      default: "list",
+    },
   },
 };
 
+/**
+ * Output schema per MCP 2025-06-18 spec
+ */
+const discoverToolsOutputSchema = {
+  type: "object" as const,
+  properties: {
+    matchedTools: {
+      type: "array",
+      description: "List of matching tools",
+      items: {
+        type: "object",
+        properties: {
+          name: { type: "string" },
+          category: { type: "string" },
+          description: { type: "string" },
+        },
+      },
+    },
+    loadedCount: {
+      type: "number",
+      description: "Number of tools activated (if load=true)",
+    },
+  },
+  required: ["matchedTools"],
+};
+
 type OutputFormat = "list" | "toon" | "toon-tabular";
 
 interface DiscoverToolsArgs {
@@ -205,7 +245,17 @@ function formatListOutput(
 
 export const discoverToolsTool: ToolDefinition = {
   name: "discover_tools",
-  description: "Find and load optimization tools. Categories: compress, analyze, logs, code, pipeline.",
+  description:
+    "Find and load optimization tools on-demand. " +
+    "Categories: compress (token reduction), analyze (parsing), logs (summarization), " +
+    "code (AST extraction), pipeline (chained operations). " +
+    "Use TOON format for 55% additional token savings.",
   inputSchema: discoverToolsSchema,
+  outputSchema: discoverToolsOutputSchema,
+  annotations: {
+    title: "Discover Tools",
+    readOnlyHint: true,
+    idempotentHint: true,
+  },
   execute: executeDiscoverTools,
 };

packages/mcp-server/src/tools/registry.ts

@@ -8,10 +8,31 @@ import type { ToolContext, ToolResult } from "../middleware/types.js";
 import type { MiddlewareChain } from "../middleware/chain.js";
 import { countTokens } from "../utils/token-counter.js";
 
+/**
+ * Tool annotations per MCP 2025-06-18 specification
+ * @see https://modelcontextprotocol.io/specification/2025-06-18/server/tools
+ */
+export interface ToolAnnotations {
+  /** Tool only reads data, doesn't modify state */
+  readOnlyHint?: boolean;
+  /** Tool may perform destructive operations */
+  destructiveHint?: boolean;
+  /** Tool is idempotent (same input = same result) */
+  idempotentHint?: boolean;
+  /** Tool may take a long time to execute */
+  longRunningHint?: boolean;
+  /** Human-readable title for the tool */
+  title?: string;
+}
+
 export interface ToolDefinition {
   name: string;
   description: string;
   inputSchema: Record<string, unknown>;
+  /** Output schema for structured result validation (MCP 2025-06-18) */
+  outputSchema?: Record<string, unknown>;
+  /** Tool behavior annotations for LLM guidance */
+  annotations?: ToolAnnotations;
   execute: (args: unknown) => Promise<ToolExecuteResult>;
 }
 
@@ -88,17 +109,40 @@ export class ToolRegistry {
 
   /**
    * Get tool definitions for MCP ListTools response
+   * Includes outputSchema and annotations per MCP 2025-06-18 spec
    */
   getToolDefinitions(): Array<{
     name: string;
     description: string;
     inputSchema: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+    annotations?: ToolAnnotations;
   }> {
-    return this.list().map((tool) => ({
-      name: tool.name,
-      description: tool.description,
-      inputSchema: tool.inputSchema,
-    }));
+    return this.list().map((tool) => {
+      const def: {
+        name: string;
+        description: string;
+        inputSchema: Record<string, unknown>;
+        outputSchema?: Record<string, unknown>;
+        annotations?: ToolAnnotations;
+      } = {
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+      };
+
+      // Include outputSchema if defined (MCP 2025-06-18)
+      if (tool.outputSchema) {
+        def.outputSchema = tool.outputSchema;
+      }
+
+      // Include annotations if defined
+      if (tool.annotations) {
+        def.annotations = tool.annotations;
+      }
+
+      return def;
+    });
   }
 
   /**