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, }