Helios-9 MCP Server

Instructions

Implementation Reference

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

  The main handler function that implements the universal_search tool logic. Parses arguments, performs parallel searches across specified types (projects, tasks, etc.), aggregates and ranks results, and returns structured search output.
  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:15-72 (schema)

  MCPTool definition for universal_search including the input schema (JSON Schema) used for tool listing and validation in 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:74-91 (schema)

  Internal Zod schema used for runtime input validation within the handler.
  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:667-672 (registration)

  Local registration of the universal_search handler in the module's handlers object, which is imported and merged into the global allHandlers.
  export const intelligentSearchHandlers = { universal_search: universalSearch, semantic_search: semanticSearch, get_search_suggestions: getSearchSuggestions, get_search_analytics: getSearchAnalytics }
• src/index.ts:143-156 (registration)

  Central registration in the MCP server where intelligentSearchHandlers (including universal_search) are merged into allHandlers, and tools into allTools for MCP tool listing and execution.
  this.allHandlers = { ...projectHandlers, ...taskHandlers, ...documentHandlers, ...conversationHandlers, ...contextAggregationHandlers, ...workflowAutomationHandlers, ...intelligentSearchHandlers, ...analyticsInsightsHandlers, ...initiativeHandlers, ...promptToProjectTools.reduce((acc, tool) => ({ ...acc, [tool.name]: tool.handler }), {}), ...debugHandlers, }