Saga MCP

Instructions

Implementation Reference

• src/tools/epics.ts:90-124 (handler)

  Handler function for the 'epic_list' tool. Executes a SQL query to fetch epics with task count statistics.

  function handleEpicList(args: Record<string, unknown>) {
    const db = getDb();
    const projectId = args.project_id as number;
    const status = args.status as string | undefined;
    const priority = args.priority as string | undefined;
  
    const whereClauses = ['e.project_id = ?'];
    const params: unknown[] = [projectId];
  
    if (status) {
      whereClauses.push('e.status = ?');
      params.push(status);
    }
    if (priority) {
      whereClauses.push('e.priority = ?');
      params.push(priority);
    }
  
    const sql = `
      SELECT e.*,
        COUNT(t.id) as task_count,
        SUM(CASE WHEN t.status = 'done' THEN 1 ELSE 0 END) as done_count,
        SUM(CASE WHEN t.status = 'blocked' THEN 1 ELSE 0 END) as blocked_count,
        CASE WHEN COUNT(t.id) > 0
          THEN ROUND(SUM(CASE WHEN t.status = 'done' THEN 1 ELSE 0 END) * 100.0 / COUNT(t.id), 1)
          ELSE 0 END as completion_pct
      FROM epics e
      LEFT JOIN tasks t ON t.epic_id = e.id
      WHERE ${whereClauses.join(' AND ')}
      GROUP BY e.id
      ORDER BY e.sort_order, e.created_at
    `;
  
    return db.prepare(sql).all(...params);
  }

• src/tools/epics.ts:33-47 (schema)

  MCP Tool definition for 'epic_list' including description and input schema.

  {
    name: 'epic_list',
    description:
      'List epics for a project with task counts and completion stats. Optionally filter by status or priority.',
    annotations: { title: 'List Epics', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
    inputSchema: {
      type: 'object',
      properties: {
        project_id: { type: 'integer', description: 'Project ID' },
        status: { type: 'string', enum: ['planned', 'in_progress', 'completed', 'cancelled'] },
        priority: { type: 'string', enum: ['low', 'medium', 'high', 'critical'] },
      },
      required: ['project_id'],
    },
  },

• src/tools/epics.ts:142-146 (registration)

  Registration map of tool names to their corresponding handler functions.

  export const handlers: Record<string, ToolHandler> = {
    epic_create: handleEpicCreate,
    epic_list: handleEpicList,
    epic_update: handleEpicUpdate,
  };