@dalmasonto/taskflow-mcp 1.0.0

package/dist/sse.js

@@ -0,0 +1,282 @@
+import { createServer } from 'http';
+import { getDb } from './db.js';
+import { logActivity } from './helpers.js';
+const clients = new Set();
+function resolvePort() {
+    // CLI arg takes priority: --port 4000
+    const portArgIdx = process.argv.indexOf('--port');
+    if (portArgIdx !== -1 && process.argv[portArgIdx + 1]) {
+        return parseInt(process.argv[portArgIdx + 1], 10);
+    }
+    // Then env var
+    if (process.env.TASKFLOW_SSE_PORT) {
+        return parseInt(process.env.TASKFLOW_SSE_PORT, 10);
+    }
+    return 3456;
+}
+const PORT = resolvePort();
+function jsonResponse(res, status, data) {
+    res.writeHead(status, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(data));
+}
+function readBody(req) {
+    return new Promise((resolve) => {
+        let body = '';
+        req.on('data', (chunk) => { body += chunk.toString(); });
+        req.on('end', () => resolve(body));
+    });
+}
+export function startSSEServer() {
+    const server = createServer(async (req, res) => {
+        // CORS headers for all requests
+        res.setHeader('Access-Control-Allow-Origin', '*');
+        res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PATCH, DELETE, OPTIONS');
+        res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+        if (req.method === 'OPTIONS') {
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+        if (req.url === '/events' && req.method === 'GET') {
+            res.writeHead(200, {
+                'Content-Type': 'text/event-stream',
+                'Cache-Control': 'no-cache',
+                'Connection': 'keep-alive',
+            });
+            // Send initial connection event
+            res.write('event: connected\ndata: {}\n\n');
+            clients.add(res);
+            req.on('close', () => {
+                clients.delete(res);
+            });
+            return;
+        }
+        if (req.url === '/sync' && req.method === 'GET') {
+            const db = getDb();
+            const tasks = db.prepare('SELECT * FROM tasks').all();
+            const projects = db.prepare('SELECT * FROM projects').all();
+            const sessions = db.prepare('SELECT * FROM sessions').all();
+            const settings = db.prepare('SELECT * FROM settings').all();
+            const activityLogs = db.prepare('SELECT * FROM activity_logs ORDER BY created_at DESC LIMIT 200').all();
+            jsonResponse(res, 200, { tasks, projects, sessions, settings, activityLogs });
+            return;
+        }
+        // ─── Mutation endpoints ───────────────────────────────────────────
+        if (req.url === '/api/clear-data' && req.method === 'POST') {
+            const db = getDb();
+            db.exec('DELETE FROM sessions');
+            db.exec('DELETE FROM tasks');
+            db.exec('DELETE FROM projects');
+            db.exec('DELETE FROM notifications');
+            db.exec('DELETE FROM activity_logs');
+            logActivity('data_cleared', 'All data cleared via UI', { entityType: 'system' });
+            broadcast('data_cleared', { entity: 'system', action: 'data_cleared', payload: {} });
+            jsonResponse(res, 200, { cleared: true });
+            return;
+        }
+        // PATCH /api/tasks/:id — partial update
+        const taskPatchMatch = req.url?.match(/^\/api\/tasks\/(\d+)$/);
+        if (taskPatchMatch && req.method === 'PATCH') {
+            const db = getDb();
+            const id = Number(taskPatchMatch[1]);
+            const task = db.prepare('SELECT * FROM tasks WHERE id = ?').get(id);
+            if (!task) {
+                jsonResponse(res, 404, { error: 'Task not found' });
+                return;
+            }
+            const body = JSON.parse(await readBody(req));
+            const fieldMap = {
+                title: 'title', description: 'description', status: 'status',
+                priority: 'priority', projectId: 'project_id', dueDate: 'due_date',
+                estimatedTime: 'estimated_time', dependencies: 'dependencies',
+                tags: 'tags', links: 'links',
+            };
+            const sets = [];
+            const vals = [];
+            for (const [camel, col] of Object.entries(fieldMap)) {
+                if (body[camel] !== undefined) {
+                    const val = body[camel];
+                    if (col === 'dependencies' || col === 'tags' || col === 'links') {
+                        sets.push(`${col} = ?`);
+                        vals.push(JSON.stringify(val));
+                    }
+                    else if (col === 'due_date' && val) {
+                        sets.push(`${col} = ?`);
+                        vals.push(new Date(val).toISOString());
+                    }
+                    else if (col === 'project_id' && (val === null || val === undefined)) {
+                        sets.push(`${col} = ?`);
+                        vals.push(null);
+                    }
+                    else {
+                        sets.push(`${col} = ?`);
+                        vals.push(val);
+                    }
+                }
+            }
+            if (sets.length > 0) {
+                sets.push('updated_at = ?');
+                vals.push(new Date().toISOString());
+                db.prepare(`UPDATE tasks SET ${sets.join(', ')} WHERE id = ?`).run(...vals, id);
+            }
+            const updated = db.prepare('SELECT * FROM tasks WHERE id = ?').get(id);
+            broadcast('task_updated', { entity: 'task', action: 'task_updated', payload: updated });
+            jsonResponse(res, 200, updated);
+            return;
+        }
+        // DELETE /api/tasks/:id
+        const taskDeleteMatch = req.url?.match(/^\/api\/tasks\/(\d+)$/);
+        if (taskDeleteMatch && req.method === 'DELETE') {
+            const db = getDb();
+            const id = Number(taskDeleteMatch[1]);
+            const task = db.prepare('SELECT * FROM tasks WHERE id = ?').get(id);
+            if (!task) {
+                jsonResponse(res, 404, { error: 'Task not found' });
+                return;
+            }
+            db.prepare('DELETE FROM tasks WHERE id = ?').run(id);
+            logActivity('task_deleted', task.title, { entityType: 'task', entityId: id });
+            broadcast('task_deleted', { entity: 'task', action: 'task_deleted', payload: { id } });
+            jsonResponse(res, 200, { deleted: true, id });
+            return;
+        }
+        // POST /api/tasks — create a task
+        if (req.url === '/api/tasks' && req.method === 'POST') {
+            const db = getDb();
+            const body = JSON.parse(await readBody(req));
+            const ts = new Date().toISOString();
+            const result = db.prepare(`INSERT INTO tasks (title, description, status, priority, project_id, dependencies, links, tags, due_date, estimated_time, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(body.title, body.description ?? null, body.status ?? 'not_started', body.priority ?? 'medium', body.projectId ?? null, JSON.stringify(body.dependencies ?? []), JSON.stringify(body.links ?? []), JSON.stringify(body.tags ?? []), body.dueDate ? new Date(body.dueDate).toISOString() : null, body.estimatedTime ?? null, ts, ts);
+            const task = db.prepare('SELECT * FROM tasks WHERE id = ?').get(result.lastInsertRowid);
+            logActivity('task_created', body.title, { entityType: 'task', entityId: result.lastInsertRowid });
+            broadcast('task_created', { entity: 'task', action: 'task_created', payload: task });
+            jsonResponse(res, 201, task);
+            return;
+        }
+        // POST /api/sessions — create a timer session
+        if (req.url === '/api/sessions' && req.method === 'POST') {
+            const db = getDb();
+            const body = JSON.parse(await readBody(req));
+            const ts = new Date().toISOString();
+            const result = db.prepare('INSERT INTO sessions (task_id, start, end) VALUES (?, ?, ?)').run(body.taskId, body.start ? new Date(body.start).toISOString() : ts, body.end ? new Date(body.end).toISOString() : null);
+            const session = db.prepare('SELECT * FROM sessions WHERE id = ?').get(result.lastInsertRowid);
+            broadcast('timer_started', { entity: 'timer', action: 'timer_started', payload: { task_id: body.taskId, session } });
+            jsonResponse(res, 201, session);
+            return;
+        }
+        // PATCH /api/sessions/:id — update session (close it)
+        const sessionPatchMatch = req.url?.match(/^\/api\/sessions\/(\d+)$/);
+        if (sessionPatchMatch && req.method === 'PATCH') {
+            const db = getDb();
+            const id = Number(sessionPatchMatch[1]);
+            const body = JSON.parse(await readBody(req));
+            if (body.end) {
+                db.prepare('UPDATE sessions SET end = ? WHERE id = ?').run(new Date(body.end).toISOString(), id);
+            }
+            const session = db.prepare('SELECT * FROM sessions WHERE id = ?').get(id);
+            jsonResponse(res, 200, session);
+            return;
+        }
+        // PATCH /api/projects/:id — partial update
+        const projectPatchMatch = req.url?.match(/^\/api\/projects\/(\d+)$/);
+        if (projectPatchMatch && req.method === 'PATCH') {
+            const db = getDb();
+            const id = Number(projectPatchMatch[1]);
+            const project = db.prepare('SELECT * FROM projects WHERE id = ?').get(id);
+            if (!project) {
+                jsonResponse(res, 404, { error: 'Project not found' });
+                return;
+            }
+            const body = JSON.parse(await readBody(req));
+            const fieldMap = {
+                name: 'name', color: 'color', type: 'type', description: 'description',
+            };
+            const sets = [];
+            const vals = [];
+            for (const [camel, col] of Object.entries(fieldMap)) {
+                if (body[camel] !== undefined) {
+                    sets.push(`${col} = ?`);
+                    vals.push(body[camel]);
+                }
+            }
+            if (sets.length > 0) {
+                sets.push('updated_at = ?');
+                vals.push(new Date().toISOString());
+                db.prepare(`UPDATE projects SET ${sets.join(', ')} WHERE id = ?`).run(...vals, id);
+            }
+            const updated = db.prepare('SELECT * FROM projects WHERE id = ?').get(id);
+            broadcast('project_updated', { entity: 'project', action: 'project_updated', payload: updated });
+            jsonResponse(res, 200, updated);
+            return;
+        }
+        // DELETE /api/projects/:id
+        const projectDeleteMatch = req.url?.match(/^\/api\/projects\/(\d+)$/);
+        if (projectDeleteMatch && req.method === 'DELETE') {
+            const db = getDb();
+            const id = Number(projectDeleteMatch[1]);
+            const project = db.prepare('SELECT * FROM projects WHERE id = ?').get(id);
+            if (!project) {
+                jsonResponse(res, 404, { error: 'Project not found' });
+                return;
+            }
+            db.prepare('DELETE FROM projects WHERE id = ?').run(id);
+            logActivity('project_deleted', project.name, { entityType: 'project', entityId: id });
+            broadcast('project_deleted', { entity: 'project', action: 'project_deleted', payload: { id } });
+            jsonResponse(res, 200, { deleted: true, id });
+            return;
+        }
+        // POST /api/broadcast — relay SSE events from other processes (e.g. MCP)
+        if (req.url === '/api/broadcast' && req.method === 'POST') {
+            const body = JSON.parse(await readBody(req));
+            if (body.event && body.data) {
+                broadcastLocal(body.event, body.data);
+            }
+            jsonResponse(res, 200, { relayed: true });
+            return;
+        }
+        res.writeHead(404);
+        res.end('Not Found');
+    });
+    server.on('error', (err) => {
+        if (err.code === 'EADDRINUSE') {
+            // Another MCP instance already owns this port — skip SSE, MCP tools still work
+            return;
+        }
+        // Unexpected error — still don't crash the MCP process
+    });
+    server.listen(PORT, '0.0.0.0', () => {
+        markSSEActive();
+    });
+}
+/** Broadcast directly to connected SSE clients in this process */
+function broadcastLocal(event, data) {
+    const message = `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
+    for (const client of clients) {
+        client.write(message);
+    }
+}
+/** Track whether this process owns the SSE server */
+let sseServerActive = false;
+export function markSSEActive() {
+    sseServerActive = true;
+}
+/**
+ * Broadcast an SSE event. If this process owns the SSE server, send directly.
+ * Otherwise, relay via HTTP to the process that does (sidecar on port 3456).
+ */
+export function broadcast(event, data) {
+    if (sseServerActive && clients.size > 0) {
+        broadcastLocal(event, data);
+    }
+    else {
+        // Relay to the SSE server owner via HTTP
+        const body = JSON.stringify({ event, data });
+        fetch(`http://localhost:${PORT}/api/broadcast`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body,
+        }).catch(() => {
+            // SSE server not running — silently skip
+        });
+    }
+}

package/dist/tools/activity.d.ts

@@ -0,0 +1,28 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function getActivityLog(params: {
+    limit?: number;
+    action?: string;
+    entity_type?: string;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare function clearActivityLog(): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare function logDebug(params: {
+    message: string;
+    task_id?: number;
+    detail?: string;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare function registerActivityTools(server: McpServer): void;

package/dist/tools/activity.js

@@ -0,0 +1,56 @@
+import { z } from 'zod';
+import { getDb } from '../db.js';
+import { successResponse, broadcastChange } from '../helpers.js';
+// ─── exported handler functions ───────────────────────────────────────
+export async function getActivityLog(params) {
+    const db = getDb();
+    const limit = params.limit ?? 50;
+    const conditions = [];
+    const values = [];
+    if (params.action) {
+        conditions.push('action = ?');
+        values.push(params.action);
+    }
+    if (params.entity_type) {
+        conditions.push('entity_type = ?');
+        values.push(params.entity_type);
+    }
+    let sql = 'SELECT * FROM activity_logs';
+    if (conditions.length > 0) {
+        sql += ' WHERE ' + conditions.join(' AND ');
+    }
+    sql += ' ORDER BY created_at DESC LIMIT ?';
+    values.push(limit);
+    const rows = db.prepare(sql).all(...values);
+    return successResponse(rows);
+}
+export async function clearActivityLog() {
+    const db = getDb();
+    const countRow = db.prepare('SELECT COUNT(*) AS count FROM activity_logs').get();
+    db.prepare('DELETE FROM activity_logs').run();
+    broadcastChange('activity', 'activity_cleared', {});
+    return successResponse({ deleted: countRow.count, message: 'Activity log cleared' });
+}
+export async function logDebug(params) {
+    const db = getDb();
+    const now = new Date().toISOString();
+    const result = db.prepare(`INSERT INTO activity_logs (action, title, detail, entity_type, entity_id, created_at)
+     VALUES (?, ?, ?, ?, ?, ?)`).run('debug_log', params.message, params.detail ?? null, params.task_id ? 'task' : null, params.task_id ?? null, now);
+    const entry = db.prepare('SELECT * FROM activity_logs WHERE id = ?').get(result.lastInsertRowid);
+    broadcastChange('activity', 'activity_logged', entry);
+    return successResponse({ id: result.lastInsertRowid, message: params.message });
+}
+// ─── MCP registration ─────────────────────────────────────────────────
+export function registerActivityTools(server) {
+    server.tool('get_activity_log', 'Retrieve recent activity log entries. Shows what has changed — task completions, timer events, status transitions. Filter by action or entity type.', {
+        limit: z.number().optional(),
+        action: z.string().optional(),
+        entity_type: z.string().optional(),
+    }, async (params) => getActivityLog(params));
+    server.tool('clear_activity_log', 'Delete all activity log entries. Use with caution — this is irreversible.', {}, async () => clearActivityLog());
+    server.tool('log_debug', 'Log a debug entry to the activity log. Use this while debugging to record what you are investigating, what you tried, what you found, and your reasoning. Optionally link to a task. These entries appear in the Activity Pulse in the UI.', {
+        message: z.string().describe('Short summary of what you are doing or found'),
+        detail: z.string().optional().describe('Longer explanation — stack traces, error messages, hypotheses, what you tried'),
+        task_id: z.number().optional().describe('Link this debug log to a specific task'),
+    }, async (params) => logDebug(params));
+}

package/dist/tools/agent.d.ts

@@ -0,0 +1,14 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function getAgentInstructions(): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare function clearData(): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare function registerAgentTools(server: McpServer): void;

package/dist/tools/agent.js

@@ -0,0 +1,85 @@
+import { getDb } from '../db.js';
+import { logActivity, successResponse, broadcastChange } from '../helpers.js';
+// ─── exported handler functions ───────────────────────────────────────
+export async function getAgentInstructions() {
+    const db = getDb();
+    // Gather live context to include in the instructions
+    const projectCount = db.prepare('SELECT COUNT(*) AS c FROM projects').get().c;
+    const taskCount = db.prepare('SELECT COUNT(*) AS c FROM tasks').get().c;
+    const inProgressCount = db.prepare("SELECT COUNT(*) AS c FROM tasks WHERE status = 'in_progress'").get().c;
+    const blockedCount = db.prepare("SELECT COUNT(*) AS c FROM tasks WHERE status = 'blocked'").get().c;
+    const unreadNotifs = db.prepare('SELECT COUNT(*) AS c FROM notifications WHERE read = 0').get().c;
+    const instructions = {
+        role: 'You are connected to TaskFlow, a local-first task and time tracking system. You have access to tools for managing projects, tasks, timers, analytics, activity logs, notifications, and settings.',
+        startup_checklist: [
+            'Call list_projects to see all projects and their task counts.',
+            'Identify which project is relevant to the current work. Use search_projects by name if unsure. If multiple projects match, ask the user to confirm which one before proceeding.',
+            'Call list_tasks with status "in_progress" to see what is actively being worked on.',
+            'Call list_tasks with status "blocked" to see what is stuck and might need your help.',
+            'Call list_notifications with unread_only=true to check for pending notifications.',
+        ],
+        current_state: {
+            projects: projectCount,
+            total_tasks: taskCount,
+            in_progress: inProgressCount,
+            blocked: blockedCount,
+            unread_notifications: unreadNotifs,
+        },
+        behavioral_rules: [
+            'At the start of a conversation, search for the current project by name using search_projects. Try multiple name variants if needed. If multiple projects match or you are unsure, ask the user to confirm which project to work on before creating or updating tasks. Always link new tasks to the confirmed project.',
+            'Before starting any coding work, check if a matching task exists in TaskFlow. If one exists, call start_timer on it to track time.',
+            'When you finish a piece of work, call stop_timer with the appropriate final_status: "done" if complete, "partial_done" if more work remains, "blocked" if you hit a blocker.',
+            'If you pause to wait for user input or switch context, call pause_timer on the active task.',
+            'If you encounter a blocker (missing dependency, unclear requirement, failing test you cannot fix), call stop_timer with final_status "blocked". This closes the active session and marks the task as blocked in one step. Update the task description to explain what is blocking it.',
+            'Before starting work on a task, check its dependencies array. If any dependency task is still "not_started" or "in_progress", set the task to "blocked" — do not start working on it until its dependencies are complete.',
+            'When the user asks "what should I work on?" or seems unsure what to do next, call list_tasks filtered by priority "critical" or "high" and status "not_started" to surface the most important unblocked work.',
+            'After completing a task, check if any blocked tasks had a dependency on it and might now be unblocked.',
+            'Periodically check list_notifications with unread_only=true and surface important ones to the user.',
+            'Before creating a new task, call list_tasks (or search_tasks) to check if a similar task already exists. Avoid creating duplicates — if a matching task exists, update it or start working on it instead of creating a new one.',
+            'When you finish work on a task, you MUST mark it as done. Call stop_timer with final_status "done" — this closes the session and sets the task to done in one step. Never leave a completed task in "in_progress" or "paused" status.',
+            'When you create new work items (files, features, fixes), create corresponding tasks in TaskFlow to keep the tracker in sync.',
+            'Proactively create tasks on the fly for any work you are doing — bug fixes, improvements, feature implementations, refactors. Create the task, start a timer, do the work, then stop the timer with the final status. Every meaningful unit of work should be tracked, even if the user did not explicitly ask you to create a task for it.',
+            'Use Markdown in description fields — headings, bullet lists, code blocks, bold/italic. Task and project descriptions render Markdown in the UI, so well-formatted descriptions are more readable for the user.',
+            'When debugging, use the log_debug tool to record your process — what you are investigating, what you tried, error messages, hypotheses, and findings. Link it to the relevant task with task_id. This creates a visible breadcrumb trail in the Activity Pulse that helps the user understand your reasoning.',
+        ],
+        task_workflow: {
+            description: 'The standard lifecycle of a task through the system',
+            flow: 'not_started → in_progress (start_timer) → paused (pause_timer) → in_progress (start_timer) → done/partial_done/blocked (stop_timer)',
+            valid_transitions: {
+                not_started: ['in_progress', 'blocked'],
+                in_progress: ['paused', 'blocked', 'partial_done', 'done'],
+                paused: ['in_progress', 'blocked', 'partial_done', 'done'],
+                blocked: ['not_started', 'in_progress'],
+                partial_done: ['in_progress', 'done'],
+                done: ['in_progress'],
+            },
+        },
+        tips: [
+            'Tasks have tags — use them to find related work (e.g. list_tasks with tag "bug" or "frontend").',
+            'Tasks can have dependencies — check the dependencies array to understand task ordering.',
+            'Use get_analytics for a high-level overview of time spent and task completion rates.',
+            'Use search_tasks to find tasks by keyword when you are not sure of the exact task ID.',
+            'Use search_projects to find a project by name. Try the repo name, directory name, or common abbreviations.',
+            'Read task descriptions carefully — they often contain implementation details, acceptance criteria, or context that will help you do better work.',
+            'Write task descriptions in Markdown: use ## headings for sections, - bullet lists for steps, ```code blocks``` for snippets, and **bold** for emphasis. The UI renders Markdown natively.',
+            'When creating tasks that depend on others, set dependencies and use the "blocked" status to indicate the blocking relationship. This shows up in the dependency graph.',
+        ],
+    };
+    return successResponse(instructions);
+}
+export async function clearData() {
+    const db = getDb();
+    db.exec('DELETE FROM sessions');
+    db.exec('DELETE FROM tasks');
+    db.exec('DELETE FROM projects');
+    db.exec('DELETE FROM notifications');
+    db.exec('DELETE FROM activity_logs');
+    logActivity('data_cleared', 'All data cleared', { entityType: 'system' });
+    broadcastChange('system', 'data_cleared', {});
+    return successResponse({ cleared: true, message: 'All tasks, projects, sessions, notifications, and activity logs deleted. Settings preserved.' });
+}
+// ─── MCP registration ─────────────────────────────────────────────────
+export function registerAgentTools(server) {
+    server.tool('get_agent_instructions', '**Call this at the start of every conversation.** Returns onboarding instructions, behavioral rules, and live project context for AI agents working with TaskFlow. This tool tells you how to proactively manage tasks, track time, and stay in sync with the project.', {}, async () => getAgentInstructions());
+    server.tool('clear_data', 'Delete ALL tasks, projects, sessions, notifications, and activity logs. Settings are preserved. Use with extreme caution — this is irreversible.', {}, async () => clearData());
+}

package/dist/tools/analytics.d.ts

@@ -0,0 +1,21 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function getAnalytics(params: {
+    start_date?: string;
+    end_date?: string;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare function getTimeline(params: {
+    start_date?: string;
+    end_date?: string;
+    group_by?: 'day' | 'week';
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare function registerAnalyticsTools(server: McpServer): void;

package/dist/tools/analytics.js

@@ -0,0 +1,108 @@
+import { z } from 'zod';
+import { getDb } from '../db.js';
+import { successResponse } from '../helpers.js';
+// ─── exported handler functions ───────────────────────────────────────
+export async function getAnalytics(params) {
+    const db = getDb();
+    const { start_date, end_date } = params;
+    // Build date filter for sessions
+    const sessionConditions = [];
+    const sessionValues = [];
+    if (start_date) {
+        sessionConditions.push('start >= ?');
+        sessionValues.push(start_date);
+    }
+    if (end_date) {
+        sessionConditions.push('start <= ?');
+        sessionValues.push(end_date);
+    }
+    const sessionWhere = sessionConditions.length > 0
+        ? `WHERE ${sessionConditions.join(' AND ')}`
+        : '';
+    // Total focused time (sum of all session durations in ms)
+    const durationFormula = `(julianday(COALESCE(end, datetime('now'))) - julianday(start)) * 86400000`;
+    const timeRow = db.prepare(`SELECT COALESCE(SUM(${durationFormula}), 0) AS total_focused_time FROM sessions ${sessionWhere}`).get(...sessionValues);
+    const total_focused_time = Math.round(timeRow.total_focused_time);
+    // Task counts by status
+    const taskRows = db.prepare('SELECT status, COUNT(*) AS count FROM tasks GROUP BY status').all();
+    const status_distribution = {};
+    let tasks_completed = 0;
+    let tasks_in_progress = 0;
+    let total_tasks = 0;
+    for (const row of taskRows) {
+        status_distribution[row.status] = row.count;
+        total_tasks += row.count;
+        if (row.status === 'done')
+            tasks_completed = row.count;
+        if (row.status === 'in_progress')
+            tasks_in_progress = row.count;
+    }
+    // Time per project (only tasks that belong to a project)
+    const projectTimeRows = db.prepare(`SELECT
+       t.project_id,
+       p.name AS project_name,
+       COALESCE(SUM(${durationFormula.replace(/start/g, 's.start').replace(/end/g, 's.end')}), 0) AS total_time
+     FROM sessions s
+     JOIN tasks t ON s.task_id = t.id
+     JOIN projects p ON t.project_id = p.id
+     ${sessionWhere.replace(/start/g, 's.start')}
+     GROUP BY t.project_id, p.name`).all(...sessionValues);
+    const time_per_project = projectTimeRows.map(row => ({
+        project_id: row.project_id,
+        project_name: row.project_name,
+        total_time: Math.round(row.total_time),
+    }));
+    return successResponse({
+        total_focused_time,
+        tasks_completed,
+        tasks_in_progress,
+        total_tasks,
+        status_distribution,
+        time_per_project,
+    });
+}
+export async function getTimeline(params) {
+    const db = getDb();
+    const { start_date, end_date, group_by = 'day' } = params;
+    const periodExpr = group_by === 'week'
+        ? `strftime('%Y-W%W', start)`
+        : `strftime('%Y-%m-%d', start)`;
+    const durationFormula = `(julianday(COALESCE(end, datetime('now'))) - julianday(start)) * 86400000`;
+    const conditions = [];
+    const values = [];
+    if (start_date) {
+        conditions.push('start >= ?');
+        values.push(start_date);
+    }
+    if (end_date) {
+        conditions.push('start <= ?');
+        values.push(end_date);
+    }
+    const where = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
+    const rows = db.prepare(`SELECT
+       ${periodExpr} AS period,
+       COALESCE(SUM(${durationFormula}), 0) AS total_time,
+       COUNT(*) AS session_count
+     FROM sessions
+     ${where}
+     GROUP BY period
+     ORDER BY period ASC`).all(...values);
+    const timeline = rows.map(row => ({
+        period: row.period,
+        total_time: Math.round(row.total_time),
+        session_count: row.session_count,
+    }));
+    return successResponse(timeline);
+}
+// ─── MCP registration ─────────────────────────────────────────────────
+export function registerAnalyticsTools(server) {
+    server.tool('get_analytics', 'Get a high-level analytics summary: total focused time, task completion rates, status distribution, and time per project. Useful for standup reports or understanding workload.', {
+        start_date: z.string().optional(),
+        end_date: z.string().optional(),
+    }, async (params) => getAnalytics(params));
+    server.tool('get_timeline', 'Get focused time grouped by day or week. Use for visualizing work patterns over time.', {
+        start_date: z.string().optional(),
+        end_date: z.string().optional(),
+        group_by: z.enum(['day', 'week']).optional(),
+    }, async (params) => getTimeline(params));
+}

package/dist/tools/notifications.d.ts

@@ -0,0 +1,31 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function listNotifications(params: {
+    limit?: number;
+    unread_only?: boolean;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare function markNotificationRead(params: {
+    id: number;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare function markAllNotificationsRead(): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare function clearNotifications(): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare function registerNotificationTools(server: McpServer): void;