Helios-9 MCP Server

Instructions

Implementation Reference

• src/tools/initiatives.ts:236-265 (handler)

  The core handler function for the 'create_initiative' MCP tool. Validates input with Zod, logs activity, creates the initiative via supabaseService, and returns the result with success message.

  export const createInitiative = requireAuth(async (args: any) => {
    const initiativeData = CreateInitiativeSchema.parse(args)
    
    logger.info('Creating new initiative', { 
      name: initiativeData.name,
      project_ids: initiativeData.project_ids 
    })
    
    // Create the initiative with project_ids included
    const initiative = await supabaseService.createInitiative({
      name: initiativeData.name,
      objective: initiativeData.objective,
      description: initiativeData.description || null,
      status: initiativeData.status,
      priority: initiativeData.priority,
      owner_id: initiativeData.owner_id,
      start_date: initiativeData.start_date || null,
      target_date: initiativeData.target_date || null,
      metadata: initiativeData.metadata || {},
      tags: initiativeData.tags || [],
      project_ids: initiativeData.project_ids // Pass project_ids to API
    } as any)
    
    logger.info('Initiative created successfully', { initiative_id: initiative.id, name: initiative.name })
    
    return {
      initiative,
      message: `Initiative "${initiative.name}" created successfully`
    }
  })

• src/tools/initiatives.ts:26-38 (schema)

  Zod validation schema used by the createInitiative handler to parse and validate tool input arguments.

  const CreateInitiativeSchema = z.object({
    name: z.string().min(1).max(255),
    objective: z.string().min(1),
    description: z.string().optional(),
    status: z.enum(['planning', 'active', 'on_hold', 'completed', 'cancelled']).default('planning'),
    priority: z.enum(['critical', 'high', 'medium', 'low']).default('medium'),
    owner_id: z.string().uuid(),
    project_ids: z.array(z.string().uuid()).min(1), // Required: at least one project
    start_date: z.string().datetime().optional(),
    target_date: z.string().datetime().optional(),
    metadata: z.object({}).optional(),
    tags: z.array(z.string()).optional()
  })

• src/tools/initiatives.ts:163-234 (registration)

  MCPTool object registration defining the 'create_initiative' tool with its name, description, and detailed inputSchema for the protocol.

  export const createInitiativeTool: MCPTool = {
    name: 'create_initiative',
    description: 'Create a new initiative',
    inputSchema: {
      type: 'object',
      properties: {
        name: {
          type: 'string',
          minLength: 1,
          maxLength: 255,
          description: 'The name of the initiative'
        },
        objective: {
          type: 'string',
          minLength: 1,
          description: 'The strategic objective of the initiative'
        },
        description: {
          type: 'string',
          description: 'Optional detailed description'
        },
        status: {
          type: 'string',
          enum: ['planning', 'active', 'on_hold', 'completed', 'cancelled'],
          default: 'planning',
          description: 'Initial status of the initiative'
        },
        priority: {
          type: 'string',
          enum: ['critical', 'high', 'medium', 'low'],
          default: 'medium',
          description: 'Priority level'
        },
        owner_id: {
          type: 'string',
          format: 'uuid',
          description: 'ID of the initiative owner'
        },
        project_ids: {
          type: 'array',
          items: {
            type: 'string',
            format: 'uuid'
          },
          minItems: 1,
          description: 'IDs of projects this initiative belongs to (at least one required)'
        },
        start_date: {
          type: 'string',
          format: 'date-time',
          description: 'Optional start date'
        },
        target_date: {
          type: 'string',
          format: 'date-time',
          description: 'Optional target completion date'
        },
        metadata: {
          type: 'object',
          description: 'Optional metadata'
        },
        tags: {
          type: 'array',
          items: {
            type: 'string'
          },
          description: 'Optional tags'
        }
      },
      required: ['name', 'objective', 'owner_id', 'project_ids']
    }
  }

• src/tools/initiatives.ts:630-642 (registration)

  Exported object mapping tool names (snake_case) to their handler functions, including 'create_initiative' to createInitiative. Used by other modules like prompt-to-project.ts.

  export const initiativeHandlers = {
    list_initiatives: listInitiatives,
    get_initiative: getInitiative,
    create_initiative: createInitiative,
    update_initiative: updateInitiative,
    get_initiative_context: getInitiativeContext,
    get_initiative_insights: getInitiativeInsights,
    search_workspace: searchWorkspace,
    get_enhanced_project_context: getEnhancedProjectContext,
    get_workspace_context: getWorkspaceContext,
    associate_document_with_initiative: associateDocumentWithInitiative,
    disassociate_document_from_initiative: disassociateDocumentFromInitiative
  }

• src/tools/initiatives.ts:616-628 (registration)

  Exported object collecting all initiative-related MCPTool objects, including createInitiativeTool for registration in the broader toolset.

  export const initiativeTools = {
    listInitiativesTool,
    getInitiativeTool,
    createInitiativeTool,
    updateInitiativeTool,
    getInitiativeContextTool,
    getInitiativeInsightsTool,
    searchWorkspaceTool,
    getEnhancedProjectContextTool,
    getWorkspaceContextTool,
    associateDocumentWithInitiativeTool,
    disassociateDocumentFromInitiativeTool
  }