epic_list
Read-onlyIdempotent
List project epics with task counts and completion statistics. Filter by status or priority to track progress in structured project management.
Instructions
List epics for a project with task counts and completion stats. Optionally filter by status or priority.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | Project ID | |
| status | No | ||
| priority | No |
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, };