Helios-9 MCP Server

Instructions

Implementation Reference

• src/tools/ai-conversations.ts:251-287 (handler)

  Main execution logic for the get_conversations tool: validates input with Zod schema, fetches conversations from database using helper function, computes analytics, and returns structured response.

  export const getConversations = requireAuth(async (args: any) => {
    const { project_id, limit, conversation_type, related_to, include_messages } = GetConversationsSchema.parse(args)
    
    logger.info('Getting conversations', { project_id, conversation_type, related_to, limit })
  
    // Get conversations from database
    const conversations = await getConversationsFromDatabase({
      project_id,
      limit,
      conversation_type,
      related_to,
      include_messages
    })
  
    // Add analytics
    const analytics = {
      total_conversations: conversations.length,
      conversation_types: conversations.reduce((acc, conv) => {
        const type = conv.metadata?.context?.conversation_type || 'general'
        acc[type] = (acc[type] || 0) + 1
        return acc
      }, {} as Record<string, number>),
      total_messages: conversations.reduce((sum, conv) => sum + (conv.metadata?.message_count || 0), 0),
      average_length: conversations.length > 0 
        ? conversations.reduce((sum, conv) => sum + (conv.metadata?.message_count || 0), 0) / conversations.length 
        : 0,
      recent_activity: conversations.filter(conv => 
        new Date(conv.created_at).getTime() > Date.now() - (7 * 24 * 60 * 60 * 1000)
      ).length
    }
  
    return {
      conversations,
      analytics,
      filters_applied: { conversation_type, related_to }
    }
  })

• src/tools/ai-conversations.ts:40-46 (schema)

  Zod schema for input validation of get_conversations tool parameters.

  const GetConversationsSchema = z.object({
    project_id: z.string().uuid(),
    limit: z.number().int().positive().max(100).default(20),
    conversation_type: z.enum(['task_discussion', 'document_review', 'project_planning', 'troubleshooting', 'general']).optional(),
    related_to: z.string().uuid().optional(), // task_id or document_id
    include_messages: z.boolean().default(true)
  })

• src/tools/ai-conversations.ts:213-249 (registration)

  MCPTool object definition registering the get_conversations tool with MCP protocol schema.

  export const getConversationsTool: MCPTool = {
    name: 'get_conversations',
    description: 'Retrieve AI conversations for a project with optional filtering',
    inputSchema: {
      type: 'object',
      properties: {
        project_id: {
          type: 'string',
          format: 'uuid',
          description: 'The project ID to get conversations for'
        },
        limit: {
          type: 'number',
          minimum: 1,
          maximum: 100,
          default: 20,
          description: 'Maximum number of conversations to return'
        },
        conversation_type: {
          type: 'string',
          enum: ['task_discussion', 'document_review', 'project_planning', 'troubleshooting', 'general'],
          description: 'Filter by conversation type'
        },
        related_to: {
          type: 'string',
          format: 'uuid',
          description: 'Filter by related task or document ID'
        },
        include_messages: {
          type: 'boolean',
          default: true,
          description: 'Whether to include full message content'
        }
      },
      required: ['project_id']
    }
  }

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

  Maps tool name 'get_conversations' to its handler function for use in top-level handler registry.

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

• src/index.ts:143-155 (registration)

  Top-level registry in main server where conversationHandlers (including get_conversations) is merged into allHandlers for MCP tool call dispatching.

  this.allHandlers = {
    ...projectHandlers,
    ...taskHandlers,
    ...documentHandlers,
    ...conversationHandlers,
    ...contextAggregationHandlers,
    ...workflowAutomationHandlers,
    ...intelligentSearchHandlers,
    ...analyticsInsightsHandlers,
    ...initiativeHandlers,
    ...promptToProjectTools.reduce((acc, tool) => ({ ...acc, [tool.name]: tool.handler }), {}),
    ...debugHandlers,
  }

• src/tools/ai-conversations.ts:615-618 (helper)

  Database helper function called by handler to fetch conversations (currently a placeholder).

  async function getConversationsFromDatabase(filters: any): Promise<any[]> {
    // This would be implemented in the supabase service
    return []
  }