Saga MCP

Instructions

Implementation Reference

• src/tools/templates.ts:113-157 (handler)

  The handleTemplateApply function implements the logic for the template_apply tool, including fetching the template and epic, performing variable substitution, and inserting new tasks into the database.

  function handleTemplateApply(args: Record<string, unknown>) {
    const db = getDb();
    const templateId = args.template_id as number;
    const epicId = args.epic_id as number;
    const variables = (args.variables as Record<string, string>) ?? {};
  
    const template = db.prepare('SELECT * FROM templates WHERE id = ?').get(templateId) as Record<string, unknown> | undefined;
    if (!template) throw new Error(`Template ${templateId} not found`);
  
    const epic = db.prepare('SELECT id, name FROM epics WHERE id = ?').get(epicId) as { id: number; name: string } | undefined;
    if (!epic) throw new Error(`Epic ${epicId} not found`);
  
    const taskDefs = JSON.parse(template.template_data as string) as Array<Record<string, unknown>>;
  
    const createdTasks = db.transaction(() => {
      return taskDefs.map((taskDef) => {
        const title = substituteVariables(taskDef.title as string, variables);
        const description = taskDef.description
          ? substituteVariables(taskDef.description as string, variables)
          : null;
        const priority = (taskDef.priority as string) ?? 'medium';
        const estimatedHours = (taskDef.estimated_hours as number) ?? null;
        const tags = JSON.stringify((taskDef.tags as string[]) ?? []);
  
        const task = db.prepare(
          `INSERT INTO tasks (epic_id, title, description, priority, estimated_hours, tags)
           VALUES (?, ?, ?, ?, ?, ?) RETURNING *`
        ).get(epicId, title, description, priority, estimatedHours, tags);
  
        const row = task as Record<string, unknown>;
        logActivity(db, 'task', row.id as number, 'created', null, null, null,
          `Task '${title}' created from template '${template.name}'`);
  
        return task;
      });
    })();
  
    return {
      message: `Applied template '${template.name}' to epic '${epic.name}'`,
      template_name: template.name,
      epic_name: epic.name,
      tasks_created: createdTasks.length,
      tasks: createdTasks,
    };
  }

• src/tools/templates.ts:46-63 (schema)

  The definition for the template_apply tool, specifying its name, description, and input schema.

    name: 'template_apply',
    description:
      'Apply a template to create tasks in an epic. Replaces {variable} placeholders with provided values.',
    annotations: { title: 'Apply Template', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
    inputSchema: {
      type: 'object',
      properties: {
        template_id: { type: 'integer', description: 'Template ID to apply' },
        epic_id: { type: 'integer', description: 'Epic to create tasks in' },
        variables: {
          type: 'object',
          description: 'Key-value pairs for {variable} substitution (e.g., {"feature": "auth"})',
          additionalProperties: { type: 'string' },
        },
      },
      required: ['template_id', 'epic_id'],
    },
  },

• src/tools/templates.ts:176-176 (registration)

  Registration of the template_apply tool to its handler function in the exported handlers object.

  template_apply: handleTemplateApply,