converse-mcp-server 2.5.3 → 2.6.1

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.3",
+  "version": "2.6.1",
   "description": "Converse MCP Server - Converse with other LLMs with chat and consensus tools",
   "type": "module",
   "main": "src/index.js",

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,17 +511,43 @@ Please provide your refined response:`;
     }
 
     // Save conversation state
+    let conversationState;
     try {
+      // Build formatted consensus response with actual model responses
+      let formattedContent = '';
+
+      // Add initial responses
+      formattedContent += '## Initial Responses\n\n';
+      for (const result of initialPhase.successful) {
+        formattedContent += `### ${result.model} (initial response):\n${result.response}\n\n---\n\n`;
+      }
+
+      // Add refined responses if cross-feedback was enabled
+      if (refinedPhase) {
+        formattedContent += '## Refined Responses\n\n';
+        for (const result of refinedPhase) {
+          if (result.status === 'success' && result.refined_response) {
+            formattedContent += `### ${result.model} (refined response):\n${result.refined_response}\n\n---\n\n`;
+          } else if (result.status === 'partial') {
+            // Show initial response for models that failed refinement
+            formattedContent += `### ${result.model} (refinement failed, showing initial):\n${result.initial_response}\n\n---\n\n`;
+          }
+        }
+      }
+
+      // Add summary at the end
+      formattedContent += `\n**Summary:** Consensus completed with ${initialPhase.successful.length} successful initial responses`;
+      if (refinedPhase) {
+        const successfulRefinements = refinedPhase.filter(r => r.status === 'success').length;
+        formattedContent += ` and ${successfulRefinements} successful refined responses`;
+      }
+      formattedContent += '.';
       const consensusMessage = {
         role: 'assistant',
-        content:
-          `Consensus completed with ${initialPhase.successful.length} successful responses` +
-          (refinedPhase
-            ? ` and ${refinedPhase.filter((r) => r.status === 'success').length} refined responses`
-            : ''),
+        content: formattedContent,
       };
 
-      const conversationState = {
+      conversationState = {
         messages: [...messages, consensusMessage],
         type: 'consensus',
         lastUpdated: Date.now(),
@@ -540,6 +568,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,
+        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 +869,7 @@ async function executeConsensusWithStreaming(args, dependencies, context) {
     temperature = 0.2,
     reasoning_effort = 'medium',
     use_websearch = false,
+    export: shouldExport = false,
   } = args;
 
   let conversationHistory = [];
@@ -1166,17 +1210,43 @@ Please provide your refined response:`;
   }
 
   // Save conversation state
+  let conversationState;
   try {
+    // Build formatted consensus response with actual model responses
+    let formattedContent = '';
+
+    // Add initial responses
+    formattedContent += '## Initial Responses\n\n';
+    for (const result of initialPhase.successful) {
+      formattedContent += `### ${result.model} (initial response):\n${result.response}\n\n---\n\n`;
+    }
+
+    // Add refined responses if cross-feedback was enabled
+    if (refinedPhase) {
+      formattedContent += '## Refined Responses\n\n';
+      for (const result of refinedPhase) {
+        if (result.status === 'success' && result.refined_response) {
+          formattedContent += `### ${result.model} (refined response):\n${result.refined_response}\n\n---\n\n`;
+        } else if (result.status === 'partial') {
+          // Show initial response for models that failed refinement
+          formattedContent += `### ${result.model} (refinement failed, showing initial):\n${result.initial_response}\n\n---\n\n`;
+        }
+      }
+    }
+
+    // Add summary at the end
+    formattedContent += `\n**Summary:** Consensus completed with ${initialPhase.successful.length} successful initial responses`;
+    if (refinedPhase) {
+      const successfulRefinements = refinedPhase.filter(r => r.status === 'success').length;
+      formattedContent += ` and ${successfulRefinements} successful refined responses`;
+    }
+    formattedContent += '.';
     const consensusMessage = {
       role: 'assistant',
-      content:
-        `Consensus completed with ${initialPhase.successful.length} successful responses` +
-        (refinedPhase
-          ? ` and ${refinedPhase.filter((r) => r.status === 'success').length} refined responses`
-          : ''),
+      content: formattedContent,
     };
 
-    const conversationState = {
+    conversationState = {
       messages: [...messages, consensusMessage],
       type: 'consensus',
       lastUpdated: Date.now(),
@@ -1193,6 +1263,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,
+      temperature,
+      reasoning_effort,
+      use_websearch,
+      files,
+      images,
+      enable_cross_feedback,
+    });
+  }
+
   const consensusExecutionTime = (Date.now() - consensusStartTime) / 1000;
 
   // Generate final summary from combined responses
@@ -1575,6 +1660,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,278 @@
+/**
+ * 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,
+    models,
+    enable_cross_feedback,
+  } = 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,
+      models,
+      enable_cross_feedback,
+    });
+
+    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 });
+  }
+}