Helios-9 MCP Server

Instructions

Implementation Reference

• src/tools/intelligent-search.ts:93-171 (handler)

  Core execution handler for the universal_search tool. Validates inputs, performs parallel searches across multiple content types, aggregates and ranks results with relevance scoring, adds content snippets and analytics.

  export const universalSearch = requireAuth(async (args: any) => {
    const { query, search_types, filters, limit, include_snippets, semantic_search } = UniversalSearchSchema.parse(args)
    
    logger.info('Performing universal search', { query, search_types, semantic_search })
  
    const searchResults: any = {
      query,
      search_types,
      results: {},
      total_results: 0,
      search_time: 0
    }
  
    const startTime = Date.now()
    
    // Perform searches across all requested types
    const searchPromises = search_types.map(async (type) => {
      try {
        let results
        switch (type) {
          case 'projects':
            results = await searchProjects(query, filters, limit, semantic_search)
            break
          case 'tasks':
            results = await searchTasks(query, filters, limit, semantic_search)
            break
          case 'documents':
            results = await searchDocuments(query, filters, limit, semantic_search)
            break
          case 'conversations':
            results = await searchConversations(query, filters, limit, semantic_search)
            break
          case 'profiles':
            results = await searchProfiles(query, filters, limit, semantic_search)
            break
          default:
            results = []
        }
  
        if (include_snippets) {
          results = results.map((item: any) => ({
            ...item,
            snippet: generateSnippet(item, query)
          }))
        }
  
        return { type, results }
      } catch (error) {
        logger.error(`Search failed for type ${type}:`, error)
        return { type, results: [], error: error instanceof Error ? error.message : 'Unknown error' }
      }
    })
  
    const searchTypeResults = await Promise.all(searchPromises)
    
    // Aggregate results
    searchTypeResults.forEach(({ type, results, error }) => {
      searchResults.results[type] = results
      searchResults.total_results += results.length
      if (error) {
        searchResults.errors = searchResults.errors || {}
        searchResults.errors[type] = error
      }
    })
  
    // Rank and combine results
    const combinedResults = combineAndRankResults(searchResults.results, query, semantic_search)
    searchResults.top_results = combinedResults.slice(0, limit)
    searchResults.search_time = Date.now() - startTime
  
    // Add search analytics
    searchResults.analytics = {
      best_match_type: getBestMatchType(searchResults.results),
      relevance_distribution: getRelevanceDistribution(combinedResults),
      search_suggestions: generateSearchSuggestions(query, searchResults.results)
    }
  
    return searchResults
  })

• src/tools/intelligent-search.ts:74-91 (schema)

  Zod validation schema for universal_search tool inputs, defining structure and constraints for query, search types, filters, limits, and options.

  const UniversalSearchSchema = z.object({
    query: z.string().min(1),
    search_types: z.array(z.enum(['projects', 'tasks', 'documents', 'conversations', 'profiles'])).default(['projects', 'tasks', 'documents']),
    filters: z.object({
      project_id: z.string().optional(),
      status: z.string().optional(),
      priority: z.string().optional(),
      assignee_id: z.string().optional(),
      date_range: z.object({
        start: z.string().optional(),
        end: z.string().optional()
      }).optional(),
      tags: z.array(z.string()).optional()
    }).optional(),
    limit: z.number().min(1).max(100).default(20),
    include_snippets: z.boolean().default(true),
    semantic_search: z.boolean().default(false)
  })

• src/tools/intelligent-search.ts:15-72 (registration)

  MCPTool registration object defining the universal_search tool's name, description, and JSON input schema for the MCP protocol.

  export const universalSearchTool: MCPTool = {
    name: 'universal_search',
    description: 'Search across all projects, tasks, documents, and conversations with intelligent ranking',
    inputSchema: {
      type: 'object',
      properties: {
        query: {
          type: 'string',
          description: 'Search query text'
        },
        search_types: {
          type: 'array',
          items: {
            type: 'string',
            enum: ['projects', 'tasks', 'documents', 'conversations', 'profiles']
          },
          default: ['projects', 'tasks', 'documents'],
          description: 'Types of content to search'
        },
        filters: {
          type: 'object',
          properties: {
            project_id: { type: 'string' },
            status: { type: 'string' },
            priority: { type: 'string' },
            assignee_id: { type: 'string' },
            date_range: {
              type: 'object',
              properties: {
                start: { type: 'string', format: 'date' },
                end: { type: 'string', format: 'date' }
              }
            },
            tags: { type: 'array', items: { type: 'string' } }
          },
          description: 'Additional filters to apply'
        },
        limit: {
          type: 'number',
          minimum: 1,
          maximum: 100,
          default: 20,
          description: 'Maximum number of results to return'
        },
        include_snippets: {
          type: 'boolean',
          default: true,
          description: 'Whether to include content snippets in results'
        },
        semantic_search: {
          type: 'boolean',
          default: false,
          description: 'Use semantic similarity instead of keyword matching'
        }
      },
      required: ['query']
    }
  }

• src/tools/intelligent-search.ts:667-672 (registration)

  Maps the 'universal_search' tool name to its handler function, exported for inclusion in the main server handlers.

  export const intelligentSearchHandlers = {
    universal_search: universalSearch,
    semantic_search: semanticSearch,
    get_search_suggestions: getSearchSuggestions,
    get_search_analytics: getSearchAnalytics
  }

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

  Server constructor combines handlers from all tool modules, spreading intelligentSearchHandlers (containing universal_search) into the central allHandlers used for tool execution.

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