converse-mcp-server 2.5.2 → 2.6.0

package/docs/API.md

@@ -109,6 +109,11 @@ MCP_TRANSPORT=stdio npm start
       "type": "boolean",
       "default": false,
       "description": "Execute in background mode. Returns continuation_id immediately for status monitoring. Example: true for long-running analysis"
+    },
+    "export": {
+      "type": "boolean",
+      "default": false,
+      "description": "Export conversation to disk. Creates folder with continuation_id name containing numbered request/response files and metadata. Example: true to save for documentation"
     }
   },
   "required": ["prompt"]
@@ -156,6 +161,7 @@ MCP_TRANSPORT=stdio npm start
 
 #### Example Usage
 
+**Basic query:**
 ```json
 {
   "prompt": "Review this authentication function for security issues",
@@ -166,6 +172,26 @@ MCP_TRANSPORT=stdio npm start
 }
 ```
 
+**With conversation export:**
+```json
+{
+  "prompt": "Help me design a scalable architecture for our system",
+  "model": "gpt-5",
+  "export": true,
+  "continuation_id": "conv_architecture_design"
+}
+```
+
+When export is enabled, the conversation will be saved to disk in the following structure:
+```
+conv_architecture_design/
+├── 1_request.txt      # First user prompt
+├── 1_response.txt     # First AI response
+├── 2_request.txt      # Second user prompt (if continuing)
+├── 2_response.txt     # Second AI response
+└── metadata.json      # Conversation metadata and settings
+```
+
 ### Consensus Tool
 
 **Description**: Multi-provider parallel execution with cross-model feedback for gathering perspectives from multiple AI models.
@@ -226,6 +252,11 @@ MCP_TRANSPORT=stdio npm start
       "type": "boolean",
       "default": false,
       "description": "Execute in background mode with per-provider progress tracking. Returns continuation_id immediately for monitoring."
+    },
+    "export": {
+      "type": "boolean",
+      "default": false,
+      "description": "Export conversation to disk. Creates folder with continuation_id name containing numbered request/response files and metadata. Example: true to save consensus results"
     }
   },
   "required": ["prompt", "models"]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "converse-mcp-server",
-  "version": "2.5.2",
+  "version": "2.6.0",
   "description": "Converse MCP Server - Converse with other LLMs with chat and consensus tools",
   "type": "module",
   "main": "src/index.js",

package/src/providers/gemini-cli.js

@@ -203,19 +203,22 @@ function mapFinishReason(finishReason) {
 }
 
 /**
- * Convert messages from Converse internal format to Gemini CLI SDK format
+ * Convert messages from Converse internal format to AI SDK v5 ModelMessage format
  *
  * Converse format (used by other providers like Anthropic):
  * - Images: { type: 'image', source: { type: 'base64', media_type: '...', data: '...' } }
  *
- * Gemini CLI SDK format (from SDK guide):
- * - Images: { type: 'image', data: '...' }  (base64 string)
+ * AI SDK v5 ModelMessage format (required by generateText/streamText):
+ * - Images: { type: 'image', image: '...' }  (base64 string, Buffer, or URL)
  * - Text: { type: 'text', text: '...' }
  *
+ * Note: The AI SDK validates ModelMessage format before passing to providers.
+ * We must use 'image' property (not 'data') for the AI SDK to accept the message.
+ *
  * @param {Array} messages - Messages in Converse internal format
- * @returns {Array} Messages in Gemini CLI SDK format
+ * @returns {Array} Messages in AI SDK v5 ModelMessage format
  */
-function convertToGeminiCliMessages(messages) {
+function convertToModelMessages(messages) {
   return messages.map((message) => {
     // If content is a string, no conversion needed
     if (typeof message.content === 'string') {
@@ -230,20 +233,20 @@ function convertToGeminiCliMessages(messages) {
           return part;
         }
 
-        // Convert image from Converse format to Gemini CLI SDK format
+        // Convert image from Converse format to AI SDK v5 ModelMessage format
         if (part.type === 'image' && part.source) {
           return {
             type: 'image',
-            data: part.source.data, // Extract base64 data (use 'data' not 'image')
+            image: part.source.data, // AI SDK v5 expects 'image' property (not 'data')
           };
         }
 
-        // If already in Gemini CLI format, return as-is
-        if (part.type === 'image' && part.data) {
+        // If already in AI SDK v5 format, return as-is
+        if (part.type === 'image' && part.image) {
           return part;
         }
 
-        // Handle file parts (future-proofing)
+        // Handle file parts (already in correct format)
         if (part.type === 'file' && part.data) {
           return part;
         }
@@ -326,8 +329,8 @@ export const geminiCliProvider = {
       // Create model instance with SDK model name
       const modelInstance = gemini(sdkModelName);
 
-      // Convert messages from Converse format to Gemini CLI SDK format
-      const convertedMessages = convertToGeminiCliMessages(messages);
+      // Convert messages from Converse format to AI SDK v5 ModelMessage format
+      const convertedMessages = convertToModelMessages(messages);
 
       // Build AI SDK options
       const aiOptions = {

package/src/tools/chat.js

@@ -20,6 +20,7 @@ import { CHAT_PROMPT } from '../systemPrompts.js';
 import { applyTokenLimit, getTokenLimit } from '../utils/tokenLimiter.js';
 import { validateAllPaths } from '../utils/fileValidator.js';
 import { SummarizationService } from '../services/summarizationService.js';
+import { exportConversation } from '../utils/conversationExporter.js';
 
 const logger = createLogger('chat');
 
@@ -57,6 +58,7 @@ export async function chatTool(args, dependencies) {
       reasoning_effort = 'medium',
       verbosity = 'medium',
       async = false,
+      export: shouldExport = false,
     } = args;
 
     // Handle async execution mode
@@ -356,6 +358,27 @@ export async function chatTool(args, dependencies) {
       // Continue even if save fails
     }
 
+    // Export conversation if requested
+    if (shouldExport) {
+      await exportConversation({
+        messages: updatedMessages,
+        provider: providerName,
+        model,
+        lastUpdated: Date.now(),
+        codexThreadId: response.metadata?.threadId,
+      }, {
+        clientCwd: config.server?.client_cwd,
+        continuation_id: continuationId,
+        model,
+        temperature,
+        reasoning_effort,
+        verbosity,
+        use_websearch,
+        files,
+        images,
+      });
+    }
+
     // Create unified status line (similar to async status display)
     const statusLine =
       config.environment?.nodeEnv !== 'test'
@@ -577,6 +600,7 @@ async function executeChatWithStreaming(args, dependencies, context) {
     images = [],
     reasoning_effort = 'medium',
     verbosity = 'medium',
+    export: shouldExport = false,
   } = args;
 
   // Initialize SummarizationService
@@ -916,6 +940,27 @@ async function executeChatWithStreaming(args, dependencies, context) {
     // Continue even if save fails
   }
 
+  // Export conversation if requested
+  if (shouldExport) {
+    await exportConversation({
+      messages: updatedMessages,
+      provider: providerName,
+      model,
+      lastUpdated: Date.now(),
+      codexThreadId: response.metadata?.threadId,
+    }, {
+      clientCwd: config.server?.client_cwd,
+      continuation_id: continuationId,
+      model,
+      temperature,
+      reasoning_effort,
+      verbosity,
+      use_websearch,
+      files,
+      images,
+    });
+  }
+
   // Return complete result for job completion
   return {
     content: response.content,
@@ -1000,6 +1045,12 @@ chatTool.inputSchema = {
         'Execute chat in background. When true, returns continuation_id immediately and processes request asynchronously. Default: false',
       default: false,
     },
+    export: {
+      type: 'boolean',
+      description:
+        'Export conversation to disk. Creates folder with continuation_id name containing numbered request/response files and metadata. Default: false',
+      default: false,
+    },
     prompt: {
       type: 'string',
       description:

package/src/tools/consensus.js

@@ -24,6 +24,7 @@ import { CONSENSUS_PROMPT } from '../systemPrompts.js';
 import { applyTokenLimit, getTokenLimit } from '../utils/tokenLimiter.js';
 import { validateAllPaths } from '../utils/fileValidator.js';
 import { SummarizationService } from '../services/summarizationService.js';
+import { exportConversation } from '../utils/conversationExporter.js';
 
 const logger = createLogger('consensus');
 
@@ -72,6 +73,7 @@ export async function consensusTool(args, dependencies) {
       reasoning_effort = 'medium',
       use_websearch = false,
       async = false,
+      export: shouldExport = false,
     } = args;
 
     // Handle async execution mode
@@ -509,6 +511,7 @@ Please provide your refined response:`;
     }
 
     // Save conversation state
+    let conversationState;
     try {
       const consensusMessage = {
         role: 'assistant',
@@ -519,7 +522,7 @@ Please provide your refined response:`;
             : ''),
       };
 
-      const conversationState = {
+      conversationState = {
         messages: [...messages, consensusMessage],
         type: 'consensus',
         lastUpdated: Date.now(),
@@ -540,6 +543,21 @@ Please provide your refined response:`;
       // Continue even if save fails
     }
 
+    // Export conversation if requested
+    if (shouldExport && conversationState) {
+      await exportConversation(conversationState, {
+        clientCwd: dependencies.config.server?.client_cwd,
+        continuation_id: continuationId,
+        models: models.join(','),
+        temperature,
+        reasoning_effort,
+        use_websearch,
+        files,
+        images,
+        enable_cross_feedback,
+      });
+    }
+
     const consensusExecutionTime = (Date.now() - consensusStartTime) / 1000; // Convert to seconds
 
     // Calculate final success count and collect failure details
@@ -826,6 +844,7 @@ async function executeConsensusWithStreaming(args, dependencies, context) {
     temperature = 0.2,
     reasoning_effort = 'medium',
     use_websearch = false,
+    export: shouldExport = false,
   } = args;
 
   let conversationHistory = [];
@@ -1166,6 +1185,7 @@ Please provide your refined response:`;
   }
 
   // Save conversation state
+  let conversationState;
   try {
     const consensusMessage = {
       role: 'assistant',
@@ -1176,7 +1196,7 @@ Please provide your refined response:`;
           : ''),
     };
 
-    const conversationState = {
+    conversationState = {
       messages: [...messages, consensusMessage],
       type: 'consensus',
       lastUpdated: Date.now(),
@@ -1193,6 +1213,21 @@ Please provide your refined response:`;
     logger.error('Error saving consensus conversation', { error });
   }
 
+  // Export conversation if requested
+  if (shouldExport && conversationState) {
+    await exportConversation(conversationState, {
+      clientCwd: config.server?.client_cwd,
+      continuation_id: continuationId,
+      models: models.join(','),
+      temperature,
+      reasoning_effort,
+      use_websearch,
+      files,
+      images,
+      enable_cross_feedback,
+    });
+  }
+
   const consensusExecutionTime = (Date.now() - consensusStartTime) / 1000;
 
   // Generate final summary from combined responses
@@ -1575,6 +1610,12 @@ consensusTool.inputSchema = {
         'Execute consensus in background with detailed progress tracking. When true, returns continuation_id immediately and processes request asynchronously with per-provider status updates. Default: false',
       default: false,
     },
+    export: {
+      type: 'boolean',
+      description:
+        'Export conversation to disk. Creates folder with continuation_id name containing numbered request/response files and metadata. Default: false',
+      default: false,
+    },
     prompt: {
       type: 'string',
       description:

package/src/utils/conversationExporter.js

@@ -0,0 +1,274 @@
+/**
+ * Conversation Exporter
+ *
+ * Exports chat conversations to disk with incremental file writes
+ * and atomic metadata updates. Follows functional architecture patterns.
+ */
+
+import { promises as fs } from 'fs';
+import path from 'path';
+import { createLogger } from './logger.js';
+
+const logger = createLogger('conversationExporter');
+
+/**
+ * Write file only if it doesn't exist (write-if-missing pattern)
+ * @param {string} filePath - Path to file
+ * @param {string} content - Content to write
+ * @returns {Promise<boolean>} True if written, false if skipped
+ */
+async function writeIfMissing(filePath, content) {
+  try {
+    // Check if file exists
+    await fs.access(filePath);
+    // File exists, skip writing
+    return false;
+  } catch {
+    // File doesn't exist, write it
+    try {
+      await fs.writeFile(filePath, content, 'utf8');
+      return true;
+    } catch (error) {
+      logger.warn(`Failed to write file ${filePath}`, { error });
+      return false;
+    }
+  }
+}
+
+/**
+ * Write file atomically (write to temp, then rename)
+ * @param {string} filePath - Target file path
+ * @param {string} content - Content to write
+ * @returns {Promise<void>}
+ */
+async function writeAtomic(filePath, content) {
+  const tempPath = `${filePath}.tmp`;
+  try {
+    await fs.writeFile(tempPath, content, 'utf8');
+    await fs.rename(tempPath, filePath);
+  } catch (error) {
+    // Try to clean up temp file if rename failed
+    try {
+      await fs.unlink(tempPath);
+    } catch {
+      // Ignore cleanup error
+    }
+    throw error;
+  }
+}
+
+/**
+ * Extract turn pairs from conversation messages
+ * @param {Array} messages - Conversation messages array
+ * @returns {Array} Array of {user, assistant} turn pairs
+ */
+function extractTurns(messages) {
+  const turns = [];
+  let currentTurn = null;
+
+  for (const msg of messages) {
+    // Skip system messages
+    if (msg.role === 'system') continue;
+
+    if (msg.role === 'user') {
+      // Start new turn
+      if (currentTurn && !currentTurn.assistant) {
+        // Previous turn incomplete, save it anyway
+        turns.push(currentTurn);
+      }
+      currentTurn = { user: msg, assistant: null };
+    } else if (msg.role === 'assistant' && currentTurn) {
+      // Complete current turn
+      currentTurn.assistant = msg;
+      turns.push(currentTurn);
+      currentTurn = null;
+    }
+  }
+
+  // Handle incomplete final turn
+  if (currentTurn && currentTurn.user) {
+    turns.push(currentTurn);
+  }
+
+  return turns;
+}
+
+/**
+ * Extract content from message (handles both string and complex content)
+ * @param {object} message - Message object
+ * @returns {string} Extracted content
+ */
+function extractMessageContent(message) {
+  if (!message) return '';
+
+  const content = message.content;
+
+  // Handle simple string content
+  if (typeof content === 'string') {
+    return content;
+  }
+
+  // Handle complex content array (files/images + text)
+  if (Array.isArray(content)) {
+    const textParts = [];
+
+    for (const part of content) {
+      if (part.type === 'text' && part.text) {
+        textParts.push(part.text);
+      } else if (part.type === 'file' && part.file_content) {
+        // Include file reference in export
+        textParts.push(`[File: ${part.file_name || 'unknown'}]`);
+      } else if (part.type === 'image' && part.image_url) {
+        // Include image reference in export
+        const imageName = part.image_url.startsWith('data:')
+          ? 'embedded image'
+          : path.basename(part.image_url);
+        textParts.push(`[Image: ${imageName}]`);
+      }
+    }
+
+    return textParts.join('\n\n');
+  }
+
+  return '';
+}
+
+/**
+ * Generate metadata for the conversation
+ * @param {object} conversationState - Current conversation state
+ * @param {number} totalTurns - Total number of turns
+ * @param {object} params - Additional parameters from chat tool
+ * @returns {object} Metadata object
+ */
+function generateMetadata(conversationState, totalTurns, params) {
+  const metadata = {
+    continuation_id: params.continuation_id,
+    model: params.model || 'auto',
+    provider: conversationState.provider,
+    temperature: params.temperature || 0.5,
+    total_turns: totalTurns,
+    created_at: conversationState.createdAt
+      ? new Date(conversationState.createdAt).toISOString()
+      : new Date().toISOString(),
+    last_updated: new Date(conversationState.lastUpdated || Date.now()).toISOString(),
+  };
+
+  // Add optional parameters if present
+  if (params.reasoning_effort) {
+    metadata.reasoning_effort = params.reasoning_effort;
+  }
+  if (params.verbosity) {
+    metadata.verbosity = params.verbosity;
+  }
+  if (params.use_websearch !== undefined) {
+    metadata.use_websearch = params.use_websearch;
+  }
+  if (params.files && params.files.length > 0) {
+    metadata.files = params.files;
+  }
+  if (params.images && params.images.length > 0) {
+    // Don't store base64 data, just file paths or indicators
+    metadata.images = params.images.map(img =>
+      img.startsWith('data:') ? '[base64 image]' : img
+    );
+  }
+  // Consensus-specific metadata
+  if (params.models) {
+    metadata.models = params.models;
+  }
+  if (params.enable_cross_feedback !== undefined) {
+    metadata.enable_cross_feedback = params.enable_cross_feedback;
+  }
+
+  return metadata;
+}
+
+/**
+ * Export conversation to disk
+ * @param {object} conversationState - Conversation state from continuation store
+ * @param {object} options - Export options
+ * @returns {Promise<void>}
+ */
+export async function exportConversation(conversationState, options = {}) {
+  const {
+    clientCwd,
+    continuation_id,
+    model,
+    temperature,
+    reasoning_effort,
+    verbosity,
+    use_websearch,
+    files,
+    images,
+  } = options;
+
+  if (!continuation_id) {
+    logger.warn('Export skipped: no continuation_id provided');
+    return;
+  }
+
+  try {
+    // 1. Sanitize continuation ID for folder name
+    const safeId = path.basename(continuation_id);
+    const exportDir = path.resolve(clientCwd || process.cwd(), safeId);
+
+    // 2. Ensure directory exists
+    await fs.mkdir(exportDir, { recursive: true });
+    logger.debug(`Export directory created/verified: ${exportDir}`);
+
+    // 3. Extract turns from conversation
+    const turns = extractTurns(conversationState.messages);
+
+    if (turns.length === 0) {
+      logger.debug('No turns to export');
+      return;
+    }
+
+    // 4. Write request/response files (skip existing)
+    let filesWritten = 0;
+    for (const [index, turn] of turns.entries()) {
+      const turnNum = index + 1;
+
+      // Write request file if missing
+      if (turn.user) {
+        const requestPath = path.join(exportDir, `${turnNum}_request.txt`);
+        const userContent = extractMessageContent(turn.user);
+        const written = await writeIfMissing(requestPath, userContent);
+        if (written) filesWritten++;
+      }
+
+      // Write response file if missing
+      if (turn.assistant) {
+        const responsePath = path.join(exportDir, `${turnNum}_response.txt`);
+        const assistantContent = extractMessageContent(turn.assistant);
+        const written = await writeIfMissing(responsePath, assistantContent);
+        if (written) filesWritten++;
+      }
+    }
+
+    // 5. Always update metadata atomically
+    const metadata = generateMetadata(conversationState, turns.length, {
+      continuation_id,
+      model,
+      temperature,
+      reasoning_effort,
+      verbosity,
+      use_websearch,
+      files,
+      images,
+    });
+
+    const metadataPath = path.join(exportDir, 'metadata.json');
+    await writeAtomic(metadataPath, JSON.stringify(metadata, null, 2));
+
+    logger.info('Conversation exported', {
+      continuation_id,
+      exportDir,
+      totalTurns: turns.length,
+      filesWritten,
+    });
+  } catch (error) {
+    // Log error but don't interrupt conversation
+    logger.error('Export failed', { error, continuation_id });
+  }
+}