Helios-9 MCP Server

Instructions

Implementation Reference

• src/tools/documents.ts:87-114 (handler)

  The core handler function for the 'list_documents' tool. It validates input using ListDocumentsSchema, fetches documents from Supabase with optional filters (project_id, document_type, search, limit), computes basic analytics (total count, type distribution, average length), and returns the documents list with analytics and applied filters.
  export const listDocuments = requireAuth(async (args: any) => { const { project_id, document_type, search, limit } = ListDocumentsSchema.parse(args) logger.info('Listing documents', { project_id, document_type, search, limit }) const documents = await supabaseService.getDocuments( { project_id, type: document_type, search }, { limit }, { field: 'updated_at', order: 'desc' } ) // Add document analytics const documentAnalytics = { total_documents: documents.length, document_types: documents.reduce((acc, doc) => { acc[doc.document_type] = (acc[doc.document_type] || 0) + 1 return acc }, {} as Record<string, number>), ai_ready_count: 0, // Metadata not available in current schema average_content_length: documents.reduce((sum, doc) => sum + doc.content.length, 0) / (documents.length || 1) } return { documents, analytics: documentAnalytics, filters_applied: { project_id, document_type, search } } })
• src/tools/documents.ts:18-23 (schema)

  Zod schema used for input validation in the listDocuments handler. Defines optional project_id (UUID), document_type (enum), search string, and limit (1-100, default 20).
  const ListDocumentsSchema = z.object({ project_id: z.string().uuid().optional(), document_type: z.enum(['requirement', 'design', 'technical', 'meeting_notes', 'other']).optional(), search: z.string().optional(), limit: z.number().int().positive().max(100).default(20) })
• src/tools/documents.ts:56-85 (registration)

  MCPTool definition for 'list_documents' including name, description, and inputSchema for MCP protocol compatibility. This tool object is collected into documentTools and registered in the server.
  export const listDocumentsTool: MCPTool = { name: 'list_documents', description: 'List documents with optional filtering by project or document type', inputSchema: { type: 'object', properties: { project_id: { type: 'string', format: 'uuid', description: 'Filter documents by project ID' }, document_type: { type: 'string', enum: ['requirement', 'design', 'technical', 'meeting_notes', 'other'], description: 'Filter documents by type' }, search: { type: 'string', description: 'Search documents by title or content' }, limit: { type: 'number', minimum: 1, maximum: 100, default: 20, description: 'Maximum number of documents to return' } } } }
• src/tools/documents.ts:1346-1358 (registration)

  Local registration of document handlers including list_documents mapped to the listDocuments function. This object is imported into src/index.ts and spread into allHandlers.
  export const documentHandlers = { list_documents: listDocuments, create_document: createDocument, get_document: getDocument, update_document: updateDocument, search_documents: searchDocuments, get_document_context: getDocumentContext, add_document_collaborator: addDocumentCollaborator, analyze_document_content: analyzeDocumentContent, get_document_collaboration: getDocumentCollaboration, generate_document_template: generateDocumentTemplate, bulk_document_operations: bulkDocumentOperations }
• src/index.ts:143-155 (registration)

  Main server registration where documentHandlers (including list_documents) is spread into the central allHandlers object used for tool execution in CallToolRequestHandler.
  this.allHandlers = { ...projectHandlers, ...taskHandlers, ...documentHandlers, ...conversationHandlers, ...contextAggregationHandlers, ...workflowAutomationHandlers, ...intelligentSearchHandlers, ...analyticsInsightsHandlers, ...initiativeHandlers, ...promptToProjectTools.reduce((acc, tool) => ({ ...acc, [tool.name]: tool.handler }), {}), ...debugHandlers, }