Helios-9 MCP Server

Instructions

Implementation Reference

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

  The main handler function for the save_conversation tool. It validates input using SaveConversationSchema, processes messages by adding timestamps if missing, generates a title if not provided, performs content analysis, constructs conversation data, saves it to the database via saveConversationToDatabase, extracts action items, logs the operation, and returns the saved conversation along with analysis, action items, insights, and a success message.
  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 input validation schema for the save_conversation tool, defining parameters like project_id (required UUID), optional title, array of messages with role/content/timestamp/metadata, optional context object with task/document IDs, conversation type, AI model settings, 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)

  MCPTool object registration for 'save_conversation', including the tool name, description, and detailed JSON Schema for input validation matching the Zod schema.
  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-856 (registration)

  Object exporting handlers mapped by tool name, registering 'save_conversation' to the saveConversation handler function for use in the MCP system.
  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)

  Placeholder helper function for saving conversation data to the database, called by the main handler. Currently returns mock data; intended to integrate with supabaseService.
  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() } }