save_conversation

Instructions

Implementation Reference

• src/tools/ai-conversations.ts:153-208 (handler)

  Main handler function for save_conversation tool. Parses args via SaveConversationSchema, processes messages, generates title, analyzes content, saves to database, extracts action items, and returns the saved conversation with analysis and insights.

  export const saveConversation = requireAuth(async (args: any) => {
    const { project_id, title, messages, context, metadata } = SaveConversationSchema.parse(args)
    
    logger.info('Saving AI conversation', { 
      project_id, 
      message_count: messages.length,
      conversation_type: context?.conversation_type 
    })
  
    // Process messages and add timestamps if missing
    const processedMessages = messages.map(msg => ({
      ...msg,
      timestamp: msg.timestamp || new Date().toISOString(),
      metadata: msg.metadata || {}
    }))
  
    // Generate title if not provided
    const conversationTitle = title || generateConversationTitle(processedMessages, context?.conversation_type)
  
    // Analyze conversation for insights
    const analysis = analyzeConversationContent(processedMessages)
  
    // Create conversation record
    const conversationData = {
      project_id,
      title: conversationTitle,
      messages: processedMessages,
      metadata: {
        ...metadata,
        context: context || {},
        analysis,
        created_via: 'mcp',
        message_count: processedMessages.length,
        total_tokens: context?.tokens_used || estimateTokenCount(processedMessages)
      }
    }
  
    // Save to database (extend the supabase service to handle conversations)
    const conversation = await saveConversationToDatabase(conversationData)
  
    // Extract and optionally create action items
    const actionItems = extractActionItemsFromConversation(processedMessages, context)
  
    logger.info('Conversation saved successfully', { 
      conversation_id: conversation.id,
      action_items_found: actionItems.length 
    })
  
    return {
      conversation,
      analysis,
      action_items: actionItems,
      insights: generateConversationInsights(analysis, context),
      message: `Conversation "${conversationTitle}" saved successfully`
    }
  })

• src/tools/ai-conversations.ts:20-38 (schema)

  Zod validation schema for save_conversation. Defines required project_id (UUID), optional title, required messages array (role, content), optional context (task_id, document_id, conversation_type, ai_model, temperature, tokens_used), and optional metadata.

  const SaveConversationSchema = z.object({
    project_id: z.string().uuid(),
    title: z.string().min(1).max(500).optional(),
    messages: z.array(z.object({
      role: z.enum(['user', 'assistant', 'system']),
      content: z.string(),
      timestamp: z.string().datetime().optional(),
      metadata: z.record(z.any()).optional()
    })),
    context: z.object({
      task_id: z.string().uuid().optional(),
      document_id: z.string().uuid().optional(),
      conversation_type: z.enum(['task_discussion', 'document_review', 'project_planning', 'troubleshooting', 'general']).default('general'),
      ai_model: z.string().optional(),
      temperature: z.number().min(0).max(2).optional(),
      tokens_used: z.number().positive().optional()
    }).optional(),
    metadata: z.record(z.any()).optional()
  })

• src/tools/ai-conversations.ts:65-151 (registration)

  Tool registration object for save_conversation. Defines the tool name, description, and JSON Schema input schema. Exported and later combined into conversationTools and registered in src/index.ts.

  export const saveConversationTool: MCPTool = {
    name: 'save_conversation',
    description: 'Save an AI conversation with project context for future reference and analysis',
    inputSchema: {
      type: 'object',
      properties: {
        project_id: {
          type: 'string',
          format: 'uuid',
          description: 'The project ID this conversation relates to'
        },
        title: {
          type: 'string',
          maxLength: 500,
          description: 'Optional title for the conversation (auto-generated if not provided)'
        },
        messages: {
          type: 'array',
          items: {
            type: 'object',
            properties: {
              role: {
                type: 'string',
                enum: ['user', 'assistant', 'system'],
                description: 'The role of the message sender'
              },
              content: {
                type: 'string',
                description: 'The message content'
              },
              timestamp: {
                type: 'string',
                format: 'date-time',
                description: 'When the message was sent (auto-generated if not provided)'
              },
              metadata: {
                type: 'object',
                description: 'Additional metadata for the message'
              }
            },
            required: ['role', 'content']
          },
          description: 'Array of conversation messages'
        },
        context: {
          type: 'object',
          properties: {
            task_id: {
              type: 'string',
              format: 'uuid',
              description: 'Related task ID if conversation is about a specific task'
            },
            document_id: {
              type: 'string',
              format: 'uuid',
              description: 'Related document ID if conversation is about a specific document'
            },
            conversation_type: {
              type: 'string',
              enum: ['task_discussion', 'document_review', 'project_planning', 'troubleshooting', 'general'],
              description: 'Type of conversation for better categorization'
            },
            ai_model: {
              type: 'string',
              description: 'AI model used in the conversation'
            },
            temperature: {
              type: 'number',
              minimum: 0,
              maximum: 2,
              description: 'AI temperature setting used'
            },
            tokens_used: {
              type: 'number',
              description: 'Total tokens consumed in the conversation'
            }
          },
          description: 'Context information about the conversation'
        },
        metadata: {
          type: 'object',
          description: 'Additional metadata for the conversation'
        }
      },
      required: ['project_id', 'messages']
    }
  }

• src/tools/ai-conversations.ts:851-857 (registration)

  Exports mapping of the handler function to the tool name 'save_conversation', which is imported and spread into allHandlers in src/index.ts for dispatching tool calls.

  export const conversationHandlers = {
    save_conversation: saveConversation,
    get_conversations: getConversations,
    analyze_conversation: analyzeConversation,
    extract_action_items: extractActionItems,
    generate_conversation_summary: generateConversationSummary
  }

• src/tools/ai-conversations.ts:605-613 (helper)

  Helper function called by the saveConversation handler to persist conversation data. Currently a placeholder that returns mock data with generated UUID and timestamps, intended to be replaced with actual Supabase database logic.

  async function saveConversationToDatabase(conversationData: any): Promise<any> {
    // This would be implemented in the supabase service
    return {
      id: 'generated-uuid',
      ...conversationData,
      created_at: new Date().toISOString(),
      updated_at: new Date().toISOString()
    }
  }