Helios-9 MCP Server

Instructions

Implementation Reference

• src/tools/projects.ts:511-608 (handler)

  Main handler function for get_project_timeline tool. Parses input, fetches project, tasks, and documents, constructs timeline events, applies time filtering, identifies milestones, and returns structured timeline data.
  export const getProjectTimeline = requireAuth(async (args: any) => { const { project_id, include_completed, time_range } = GetProjectTimelineSchema.parse(args) logger.info('Getting project timeline', { project_id, time_range }) const project = await supabaseService.getProject(project_id) if (!project) { throw new Error('Project not found') } // Get tasks and documents with dates const tasks = await supabaseService.getTasks({ project_id }) const documents = await supabaseService.getDocuments({ project_id }) // Create timeline events const timelineEvents = [] // Add project creation timelineEvents.push({ date: project.created_at, type: 'project_created', title: 'Project Created', description: `Project "${project.name}" was created`, metadata: { project_id } }) // Add task events tasks.forEach(task => { if (task.created_at) { timelineEvents.push({ date: task.created_at, type: 'task_created', title: `Task Created: ${task.title}`, description: task.description, metadata: { task_id: task.id, status: task.status } }) } // started_at property doesn't exist in the database schema // completed_at property doesn't exist in the database schema if (task.due_date) { timelineEvents.push({ date: task.due_date, type: 'task_due', title: `Task Due: ${task.title}`, description: task.status === 'done' ? 'Completed on time' : 'Due date', metadata: { task_id: task.id, is_overdue: new Date(task.due_date) < new Date() && task.status !== 'done' } }) } }) // Add document events documents.forEach(doc => { timelineEvents.push({ date: doc.created_at, type: 'document_created', title: `Document Created: ${doc.title}`, metadata: { document_id: doc.id, document_type: doc.document_type } }) if (doc.updated_at !== doc.created_at) { timelineEvents.push({ date: doc.updated_at, type: 'document_updated', title: `Document Updated: ${doc.title}`, metadata: { document_id: doc.id } }) } }) // Filter by time range const filteredEvents = filterTimelineByRange(timelineEvents, time_range) // Sort by date filteredEvents.sort((a, b) => new Date(a.date).getTime() - new Date(b.date).getTime()) // Identify milestones (significant events) const milestones = identifyMilestones(filteredEvents, tasks) return { project: { id: project.id, name: project.name, status: project.status }, timeline: filteredEvents, milestones, summary: { total_events: filteredEvents.length, tasks_created: filteredEvents.filter(e => e.type === 'task_created').length, tasks_completed: filteredEvents.filter(e => e.type === 'task_completed').length, documents_created: filteredEvents.filter(e => e.type === 'document_created').length, overdue_tasks: filteredEvents.filter(e => e.type === 'task_due' && e.metadata?.is_overdue).length } } })
• src/tools/projects.ts:505-509 (schema)

  Zod schema for validating input parameters: project_id (required), include_completed (boolean, default true), time_range (enum, default 'all').
  const GetProjectTimelineSchema = z.object({ project_id: z.string().min(1), include_completed: z.boolean().default(true), time_range: z.enum(['all', 'past_month', 'next_month', 'current_quarter']).default('all') })
• src/tools/projects.ts:479-503 (registration)

  MCPTool registration object defining the tool name, description, and input schema for MCP protocol.
  export const getProjectTimelineTool: MCPTool = { name: 'get_project_timeline', description: 'Get project timeline with milestones and key events', inputSchema: { type: 'object', properties: { project_id: { type: 'string', description: 'ID of the project' }, include_completed: { type: 'boolean', default: true, description: 'Whether to include completed items' }, time_range: { type: 'string', enum: ['all', 'past_month', 'next_month', 'current_quarter'], default: 'all', description: 'Time range filter' } }, required: ['project_id'] } }
• src/tools/projects.ts:778-787 (registration)

  Object exporting all project handlers, including get_project_timeline mapped to its handler function for registration in the MCP server.
  export const projectHandlers = { list_projects: listProjects, get_project: getProject, create_project: createProject, update_project: updateProject, get_project_context: getProjectContext, archive_project: archiveProject, duplicate_project: duplicateProject, get_project_timeline: getProjectTimeline, bulk_update_projects: bulkUpdateProjects
• src/tools/projects.ts:698-726 (helper)

  Helper function to filter timeline events by specified time range (all, past_month, next_month, current_quarter). Used in the handler.
  function filterTimelineByRange(events: any[], timeRange: string): any[] { if (timeRange === 'all') return events const now = new Date() let startDate: Date let endDate: Date = now switch (timeRange) { case 'past_month': startDate = new Date(now.getFullYear(), now.getMonth() - 1, now.getDate()) break case 'next_month': startDate = now endDate = new Date(now.getFullYear(), now.getMonth() + 1, now.getDate()) break case 'current_quarter': const quarter = Math.floor(now.getMonth() / 3) startDate = new Date(now.getFullYear(), quarter * 3, 1) endDate = new Date(now.getFullYear(), quarter * 3 + 3, 0) break default: return events } return events.filter(event => { const eventDate = new Date(event.date) return eventDate >= startDate && eventDate <= endDate }) }