@dalmasonto/taskflow-mcp 1.0.11 → 1.0.15

package/dist/tmux-bridge.js

@@ -1,4 +1,4 @@
-import { execSync } from 'child_process';
+import { execFileSync } from 'child_process';
 import { getDb } from './db.js';
 import { getActivePort } from './sse.js';
 import http from 'http';
@@ -9,11 +9,11 @@ function startSSEListener(options) {
     function connect() {
         const req = http.get(`http://localhost:${port}/events`, (res) => {
             let buffer = '';
+            let eventType = ''; // persists across chunks — SSE fields may split across TCP segments
             res.on('data', (chunk) => {
                 buffer += chunk.toString();
                 const lines = buffer.split('\n');
                 buffer = lines.pop() || '';
-                let eventType = '';
                 for (const line of lines) {
                     if (line.startsWith('event: ')) {
                         eventType = line.slice(7).trim();
@@ -26,6 +26,10 @@ function startSSEListener(options) {
                         catch { /* malformed JSON */ }
                         eventType = '';
                     }
+                    else if (line === '') {
+                        // SSE event delimiter — reset state for next event
+                        eventType = '';
+                    }
                 }
             });
             res.on('end', () => {
@@ -88,9 +92,14 @@ function injectAndMarkDelivered(id, text, tmuxPane) {
     const db = getDb();
     db.prepare('UPDATE agent_messages SET delivered = 1 WHERE id = ?').run(id);
     try {
-        execSync(`tmux send-keys -t ${tmuxPane} ${JSON.stringify(text)} Enter`, { stdio: 'ignore', timeout: 5000 });
-        // Long text triggers tmux bracketed paste — delay then send extra Enter to confirm
-        execSync(`sleep 1 && tmux send-keys -t ${tmuxPane} Enter`, { stdio: 'ignore', timeout: 5000 });
+        execFileSync('tmux', ['send-keys', '-t', tmuxPane, text, 'Enter'], { stdio: 'ignore', timeout: 5000 });
+        // Long text triggers tmux bracketed paste — async delay then extra Enter (non-blocking)
+        setTimeout(() => {
+            try {
+                execFileSync('tmux', ['send-keys', '-t', tmuxPane, 'Enter'], { stdio: 'ignore', timeout: 5000 });
+            }
+            catch { /* pane may have closed */ }
+        }, 1000);
         console.error(`[bridge] delivered message ${id} to tmux pane ${tmuxPane}`);
     }
     catch (err) {

package/dist/tools/activity.d.ts

@@ -15,6 +15,16 @@ export declare function clearActivityLog(): Promise<{
         text: string;
     }[];
 }>;
+export declare function compactActivityLog(params: {
+    preserve_recent?: number;
+    max_entries?: number;
+    dry_run?: boolean;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
 export declare function logDebug(params: {
     message: string;
     task_id?: number;

package/dist/tools/activity.js

@@ -31,6 +31,93 @@ export async function clearActivityLog() {
     broadcastChange('activity', 'activity_cleared', {});
     return successResponse({ deleted: countRow.count, message: 'Activity log cleared' });
 }
+// ─── compaction ──────────────────────────────────────────────────────
+const DEFAULT_PRESERVE_RECENT = 50;
+const DEFAULT_MAX_LOG_ENTRIES = 500;
+/** Actions that are always preserved in full (never compacted) */
+const MILESTONE_ACTIONS = new Set([
+    'task_created', 'task_completed', 'task_partial_done',
+    'project_created', 'project_deleted',
+    'agent_connected', 'agent_disconnected',
+]);
+export async function compactActivityLog(params) {
+    const db = getDb();
+    const preserveRecent = params.preserve_recent ?? DEFAULT_PRESERVE_RECENT;
+    const maxEntries = params.max_entries ?? DEFAULT_MAX_LOG_ENTRIES;
+    const totalCount = db.prepare('SELECT COUNT(*) AS count FROM activity_logs').get().count;
+    if (totalCount <= maxEntries) {
+        return successResponse({
+            compacted: false,
+            total_entries: totalCount,
+            message: `Log has ${totalCount} entries (threshold: ${maxEntries}) — no compaction needed.`,
+        });
+    }
+    // Get all entries sorted by date
+    const allEntries = db.prepare('SELECT * FROM activity_logs ORDER BY created_at ASC').all();
+    // Split into: entries to compact vs entries to preserve
+    const cutoffIndex = allEntries.length - preserveRecent;
+    const toCompact = allEntries.slice(0, cutoffIndex);
+    const toPreserve = allEntries.slice(cutoffIndex);
+    if (toCompact.length === 0) {
+        return successResponse({
+            compacted: false,
+            total_entries: totalCount,
+            message: 'All entries are within the preserve window — nothing to compact.',
+        });
+    }
+    // Generate summary of compacted entries
+    const actionCounts = {};
+    const milestones = [];
+    const timeRange = {
+        start: toCompact[0].created_at,
+        end: toCompact[toCompact.length - 1].created_at,
+    };
+    for (const entry of toCompact) {
+        actionCounts[entry.action] = (actionCounts[entry.action] || 0) + 1;
+        if (MILESTONE_ACTIONS.has(entry.action)) {
+            milestones.push(`[${entry.created_at.slice(0, 16)}] ${entry.action}: ${entry.title}`);
+        }
+    }
+    const summaryDetail = [
+        `## Compaction Summary`,
+        `**Period:** ${timeRange.start} → ${timeRange.end}`,
+        `**Entries compacted:** ${toCompact.length}`,
+        ``,
+        `### Action Counts`,
+        ...Object.entries(actionCounts)
+            .sort((a, b) => b[1] - a[1])
+            .map(([action, count]) => `- \`${action}\`: ${count}`),
+        ``,
+        `### Key Milestones`,
+        ...(milestones.length > 0
+            ? milestones.slice(-20).map(m => `- ${m}`)
+            : ['- (none)']),
+    ].join('\n');
+    if (params.dry_run) {
+        return successResponse({
+            compacted: false,
+            dry_run: true,
+            would_compact: toCompact.length,
+            would_preserve: toPreserve.length,
+            summary_preview: summaryDetail,
+        });
+    }
+    // Delete compacted entries and insert summary
+    const compactIds = toCompact.map(e => e.id);
+    const placeholders = compactIds.map(() => '?').join(',');
+    db.prepare(`DELETE FROM activity_logs WHERE id IN (${placeholders})`).run(...compactIds);
+    const now = new Date().toISOString();
+    db.prepare(`INSERT INTO activity_logs (action, title, detail, entity_type, entity_id, created_at)
+     VALUES (?, ?, ?, ?, ?, ?)`).run('compaction_summary', `Compacted ${toCompact.length} activity log entries (${timeRange.start.slice(0, 10)} → ${timeRange.end.slice(0, 10)})`, summaryDetail, null, null, now);
+    broadcastChange('activity', 'activity_compacted', { compacted: toCompact.length, preserved: toPreserve.length });
+    return successResponse({
+        compacted: true,
+        entries_removed: toCompact.length,
+        entries_preserved: toPreserve.length,
+        summary_inserted: true,
+        new_total: toPreserve.length + 1,
+    });
+}
 export async function logDebug(params) {
     const db = getDb();
     const now = new Date().toISOString();
@@ -49,12 +136,17 @@ export function registerActivityTools(server) {
         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());
+    }, { readOnlyHint: true }, async (params) => getActivityLog(params));
+    server.tool('clear_activity_log', 'Delete all activity log entries. Use with caution — this is irreversible.', {}, { destructiveHint: true }, async () => clearActivityLog());
     server.tool('log_debug', 'Log a debug entry to the activity log. Use this to record your work process — what you investigated, commands you ran, decisions you made, and findings. Entries appear in the Activity Pulse and on the project page. Link to a task (task_id) or project (project_id) for context.', {
         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, commands run, what you tried'),
         task_id: z.number().optional().describe('Link this debug log to a specific task'),
         project_id: z.number().optional().describe('Link this debug log to a project (used when no specific task applies)'),
-    }, async (params) => logDebug(params));
+    }, { readOnlyHint: false }, async (params) => logDebug(params));
+    server.tool('compact_activity_log', 'Compact old activity log entries into a summary. Keeps the most recent entries (default 50) and summarizes the rest. Use dry_run=true to preview what would be compacted. Runs automatically when log exceeds max_entries threshold.', {
+        preserve_recent: z.number().optional().describe('Number of recent entries to keep verbatim (default: 50)'),
+        max_entries: z.number().optional().describe('Only compact if log exceeds this count (default: 500)'),
+        dry_run: z.boolean().optional().describe('If true, show what would be compacted without doing it'),
+    }, { readOnlyHint: false }, async (params) => compactActivityLog(params));
 }

package/dist/tools/agent-inbox.js

@@ -15,7 +15,7 @@ export { myAgentName };
 export function registerAgentInboxTools(server) {
     server.tool('register_agent', 'Register this agent with a custom name. Optional — agents auto-register on startup using the project folder name. Call this only if you want a specific name.', {
         name: z.string().optional().describe('Custom agent name. If omitted, uses the project folder name.'),
-    }, async (params) => {
+    }, { readOnlyHint: false, idempotentHint: true }, async (params) => {
         myAgentName = doRegister({ customName: params.name });
         return successResponse({ name: myAgentName, message: `Registered as "${myAgentName}"` });
     });
@@ -24,7 +24,7 @@ export function registerAgentInboxTools(server) {
         question: z.string().describe('The question to ask the user'),
         context: z.string().optional().describe('Markdown context — proposals, trade-offs, code snippets shown before the question'),
         choices: z.array(z.string()).optional().describe('Optional quick-tap choices, e.g. ["Yes", "No", "Skip"]'),
-    }, async (params) => {
+    }, { readOnlyHint: false }, async (params) => {
         const db = getDb();
         const project = db.prepare('SELECT id FROM projects WHERE id = ?').get(params.project_id);
         if (!project)
@@ -46,7 +46,7 @@ export function registerAgentInboxTools(server) {
     });
     server.tool('check_response', 'Check if a previously posted question (via ask_user or ask_agent) has been answered. Returns the response if answered, or status "pending" if still waiting.', {
         message_id: z.number().describe('The message ID returned by ask_user or ask_agent'),
-    }, async (params) => {
+    }, { readOnlyHint: true }, async (params) => {
         const db = getDb();
         const message = db.prepare('SELECT * FROM agent_messages WHERE id = ?').get(params.message_id);
         if (!message)
@@ -68,7 +68,7 @@ export function registerAgentInboxTools(server) {
         recipient: z.string().describe('Name of the target agent (e.g. "backend", "task_flow:2")'),
         message: z.string().describe('The message to send'),
         context: z.string().optional().describe('Optional markdown context'),
-    }, async (params) => {
+    }, { readOnlyHint: false }, async (params) => {
         const db = getDb();
         const senderName = ensureRegistered();
         const recipient = getAgent(params.recipient);
@@ -88,7 +88,7 @@ export function registerAgentInboxTools(server) {
         context: z.string().optional().describe('Markdown context — background info, code snippets, proposals'),
         choices: z.array(z.string()).optional().describe('Optional quick-tap choices, e.g. ["Yes", "No", "Skip"]'),
         project_id: z.number().optional().describe('Optional project ID to attach the question to'),
-    }, async (params) => {
+    }, { readOnlyHint: false }, async (params) => {
         const db = getDb();
         const senderName = ensureRegistered();
         const recipient = getAgent(params.recipient);
@@ -112,7 +112,7 @@ export function registerAgentInboxTools(server) {
     server.tool('respond_to_message', 'Respond to a pending message addressed to this agent. Use check_messages to see incoming messages, then respond by message ID.', {
         message_id: z.number().describe('The message ID to respond to (from check_messages)'),
         response: z.string().describe('Your response text'),
-    }, async (params) => {
+    }, { readOnlyHint: false }, async (params) => {
         const db = getDb();
         const name = ensureRegistered();
         const message = db.prepare('SELECT * FROM agent_messages WHERE id = ?').get(params.message_id);
@@ -135,7 +135,7 @@ export function registerAgentInboxTools(server) {
             message: `Response sent to "${message.sender_name}".`,
         });
     });
-    server.tool('check_messages', 'Check for incoming messages from users or other agents addressed to this agent.', {}, async () => {
+    server.tool('check_messages', 'Check for incoming messages from users or other agents addressed to this agent.', {}, { readOnlyHint: true }, async () => {
         const db = getDb();
         const name = ensureRegistered();
         const messages = db.prepare(`SELECT * FROM agent_messages WHERE recipient_name = ? AND status = 'pending' ORDER BY created_at ASC`).all(name);
@@ -151,7 +151,7 @@ export function registerAgentInboxTools(server) {
     });
     server.tool('list_agents', 'List registered agents with their status, project path, and connection info.', {
         status: z.enum(['connected', 'disconnected']).optional().describe('Filter by status. Omit for all agents.'),
-    }, async (params) => {
+    }, { readOnlyHint: true }, async (params) => {
         const agents = listAgents(params.status);
         return successResponse(agents);
     });

package/dist/tools/agent.js

@@ -112,6 +112,6 @@ export async function clearData() {
 }
 // ─── 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());
+    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.', {}, { readOnlyHint: true }, 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.', {}, { destructiveHint: true }, async () => clearData());
 }

package/dist/tools/analytics.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import { getDb } from '../db.js';
-import { successResponse } from '../helpers.js';
+import { successResponse, errorResponse } from '../helpers.js';
 // ─── exported handler functions ───────────────────────────────────────
 export async function getAnalytics(params) {
     const db = getDb();
@@ -99,10 +99,93 @@ 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));
+    }, { readOnlyHint: true }, 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));
+    }, { readOnlyHint: true }, async (params) => getTimeline(params));
+    server.tool('get_tool_stats', 'Get tool execution statistics: call count, success rate, average duration per tool. Shows which tools are used most and which are slow or failing.', {
+        since: z.string().optional().describe('ISO date to filter from (e.g. "2026-04-01"). Defaults to all time.'),
+        tool_name: z.string().optional().describe('Filter to a specific tool name'),
+    }, { readOnlyHint: true }, async (params) => {
+        const db = getDb();
+        const conditions = [];
+        const values = [];
+        if (params.since) {
+            conditions.push('created_at >= ?');
+            values.push(params.since);
+        }
+        if (params.tool_name) {
+            conditions.push('tool_name = ?');
+            values.push(params.tool_name);
+        }
+        const where = conditions.length > 0 ? ` WHERE ${conditions.join(' AND ')}` : '';
+        const stats = db.prepare(`
+        SELECT
+          tool_name,
+          COUNT(*) as call_count,
+          SUM(CASE WHEN success = 1 THEN 1 ELSE 0 END) as success_count,
+          SUM(CASE WHEN success = 0 THEN 1 ELSE 0 END) as failure_count,
+          ROUND(AVG(duration_ms)) as avg_duration_ms,
+          MAX(duration_ms) as max_duration_ms,
+          MIN(created_at) as first_call,
+          MAX(created_at) as last_call
+        FROM tool_executions${where}
+        GROUP BY tool_name
+        ORDER BY call_count DESC
+      `).all(...values);
+        const total = db.prepare(`SELECT COUNT(*) as count FROM tool_executions${where}`).get(...values);
+        return successResponse({ total_executions: total.count, tools: stats });
+    });
+    server.tool('get_task_cost', 'Get per-task cost metrics: tool calls made during active timer sessions, total execution time, and tool breakdown. Useful for understanding which tasks consume the most resources.', {
+        task_id: z.number().optional().describe('Get cost for a specific task. Omit for all tasks.'),
+        project_id: z.number().optional().describe('Get cost for all tasks in a project'),
+    }, { readOnlyHint: true }, async (params) => {
+        const db = getDb();
+        if (params.task_id) {
+            // Cost for a single task — use subqueries to avoid cross-join inflation
+            const task = db.prepare('SELECT id, title, status FROM tasks WHERE id = ?').get(params.task_id);
+            if (!task)
+                return errorResponse(`Task ${params.task_id} not found`, 'NOT_FOUND');
+            const sessionTime = db.prepare('SELECT COALESCE(SUM(CASE WHEN end IS NOT NULL THEN (julianday(end) - julianday(start)) * 86400000 ELSE 0 END), 0) as total FROM sessions WHERE task_id = ?').get(params.task_id);
+            // Tool calls that occurred during any session for this task
+            const toolCalls = db.prepare(`
+          SELECT COUNT(*) as total, COALESCE(SUM(te.duration_ms), 0) as duration_ms,
+            SUM(CASE WHEN te.success = 0 THEN 1 ELSE 0 END) as failed
+          FROM tool_executions te
+          WHERE EXISTS (SELECT 1 FROM sessions s WHERE s.task_id = ? AND te.created_at >= s.start AND (s.end IS NULL OR te.created_at <= s.end))
+        `).get(params.task_id);
+            // Tool breakdown for this task
+            const tools = db.prepare(`
+          SELECT te.tool_name, COUNT(*) as call_count, ROUND(AVG(te.duration_ms)) as avg_ms
+          FROM tool_executions te
+          WHERE EXISTS (SELECT 1 FROM sessions s WHERE s.task_id = ? AND te.created_at >= s.start AND (s.end IS NULL OR te.created_at <= s.end))
+          GROUP BY te.tool_name
+          ORDER BY call_count DESC
+        `).all(params.task_id);
+            return successResponse({
+                task: { task_id: task.id, title: task.title, status: task.status, tool_calls: toolCalls.total, total_tool_duration_ms: toolCalls.duration_ms, failed_calls: toolCalls.failed, total_session_time_ms: sessionTime.total },
+                tool_breakdown: tools,
+            });
+        }
+        // All tasks (optionally filtered by project) — use subqueries to avoid cross-join
+        const projectFilter = params.project_id ? 'WHERE t.project_id = ?' : '';
+        const filterValues = params.project_id ? [params.project_id] : [];
+        const tasks = db.prepare(`
+        SELECT
+          t.id as task_id,
+          t.title,
+          t.status,
+          (SELECT COUNT(*) FROM tool_executions te WHERE EXISTS (SELECT 1 FROM sessions s WHERE s.task_id = t.id AND te.created_at >= s.start AND (s.end IS NULL OR te.created_at <= s.end))) as tool_calls,
+          (SELECT COALESCE(SUM(te.duration_ms), 0) FROM tool_executions te WHERE EXISTS (SELECT 1 FROM sessions s WHERE s.task_id = t.id AND te.created_at >= s.start AND (s.end IS NULL OR te.created_at <= s.end))) as total_tool_duration_ms,
+          (SELECT COALESCE(SUM(CASE WHEN end IS NOT NULL THEN (julianday(end) - julianday(start)) * 86400000 ELSE 0 END), 0) FROM sessions WHERE task_id = t.id) as total_session_time_ms
+        FROM tasks t
+        ${projectFilter}
+        HAVING tool_calls > 0
+        ORDER BY tool_calls DESC
+        LIMIT 30
+      `).all(...filterValues);
+        return successResponse({ tasks });
+    });
 }

package/dist/tools/checkpoint.d.ts

@@ -0,0 +1,27 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function createCheckpoint(params: {
+    task_id: number;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare function getCheckpoint(params: {
+    task_id: number;
+    latest?: boolean;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare function listCheckpoints(params: {
+    task_id: number;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+export declare function registerCheckpointTools(server: McpServer): void;

package/dist/tools/checkpoint.js

@@ -0,0 +1,105 @@
+import { z } from 'zod';
+import { readFileSync, writeFileSync, mkdirSync, readdirSync, unlinkSync } from 'fs';
+import { resolve } from 'path';
+import { homedir } from 'os';
+import { getDb } from '../db.js';
+import { successResponse, errorResponse } from '../helpers.js';
+const CHECKPOINTS_DIR = resolve(homedir(), '.taskflow/checkpoints');
+const MAX_CHECKPOINTS_PER_TASK = 10;
+function getTaskDir(taskId) {
+    const dir = resolve(CHECKPOINTS_DIR, String(taskId));
+    mkdirSync(dir, { recursive: true });
+    return dir;
+}
+export async function createCheckpoint(params) {
+    const db = getDb();
+    const task = db.prepare('SELECT * FROM tasks WHERE id = ?').get(params.task_id);
+    if (!task)
+        return errorResponse(`Task ${params.task_id} not found`, 'NOT_FOUND');
+    // Gather task state
+    const deps = db.prepare('SELECT dependency_id FROM task_dependencies WHERE task_id = ?').all(params.task_id);
+    const recentActivity = db.prepare('SELECT * FROM activity_logs WHERE entity_id = ? AND entity_type = ? ORDER BY created_at DESC LIMIT 20').all(params.task_id, 'task');
+    const activeSession = db.prepare('SELECT * FROM sessions WHERE task_id = ? AND end IS NULL').get(params.task_id);
+    const totalTime = db.prepare('SELECT SUM(CASE WHEN end IS NOT NULL THEN (julianday(end) - julianday(start)) * 86400000 ELSE 0 END) as total FROM sessions WHERE task_id = ?').get(params.task_id);
+    // Tool stats during this task's sessions
+    const toolStats = db.prepare(`
+    SELECT te.tool_name, COUNT(*) as calls, ROUND(AVG(te.duration_ms)) as avg_ms
+    FROM tool_executions te
+    JOIN sessions s ON s.task_id = ? AND te.created_at >= s.start AND (s.end IS NULL OR te.created_at <= s.end)
+    GROUP BY te.tool_name ORDER BY calls DESC LIMIT 10
+  `).all(params.task_id);
+    const checkpoint = {
+        task_id: params.task_id,
+        timestamp: new Date().toISOString(),
+        task,
+        dependencies: deps.map(d => d.dependency_id),
+        recent_activity: recentActivity,
+        active_session: activeSession,
+        total_time_ms: totalTime.total ?? 0,
+        tool_stats: toolStats,
+    };
+    // Write checkpoint file
+    const taskDir = getTaskDir(params.task_id);
+    const filename = `${checkpoint.timestamp.replace(/[:.]/g, '-')}.json`;
+    const filepath = resolve(taskDir, filename);
+    writeFileSync(filepath, JSON.stringify(checkpoint, null, 2), 'utf-8');
+    // Prune old checkpoints
+    const files = readdirSync(taskDir).filter(f => f.endsWith('.json')).sort();
+    while (files.length > MAX_CHECKPOINTS_PER_TASK) {
+        const oldest = files.shift();
+        try {
+            unlinkSync(resolve(taskDir, oldest));
+        }
+        catch { /* ignore */ }
+    }
+    return successResponse({
+        task_id: params.task_id,
+        checkpoint: filename,
+        path: filepath,
+        total_checkpoints: Math.min(files.length, MAX_CHECKPOINTS_PER_TASK),
+    });
+}
+export async function getCheckpoint(params) {
+    const taskDir = resolve(CHECKPOINTS_DIR, String(params.task_id));
+    let files;
+    try {
+        files = readdirSync(taskDir).filter(f => f.endsWith('.json')).sort();
+    }
+    catch {
+        return errorResponse(`No checkpoints found for task ${params.task_id}`, 'NOT_FOUND');
+    }
+    if (files.length === 0) {
+        return errorResponse(`No checkpoints found for task ${params.task_id}`, 'NOT_FOUND');
+    }
+    // Return latest by default
+    const file = files[files.length - 1];
+    const data = JSON.parse(readFileSync(resolve(taskDir, file), 'utf-8'));
+    return successResponse({
+        checkpoint: file,
+        data,
+        available_checkpoints: files.length,
+    });
+}
+export async function listCheckpoints(params) {
+    const taskDir = resolve(CHECKPOINTS_DIR, String(params.task_id));
+    let files;
+    try {
+        files = readdirSync(taskDir).filter(f => f.endsWith('.json')).sort();
+    }
+    catch {
+        return successResponse({ task_id: params.task_id, checkpoints: [] });
+    }
+    return successResponse({
+        task_id: params.task_id,
+        checkpoints: files.map(f => ({
+            filename: f,
+            timestamp: f.replace('.json', '').replace(/-/g, (m, offset) => offset <= 9 ? '-' : offset <= 15 ? ':' : '.'),
+        })),
+    });
+}
+// ─── MCP registration ─────────────────────────────────────────────────
+export function registerCheckpointTools(server) {
+    server.tool('create_checkpoint', 'Create a checkpoint snapshot of a task\'s current state. Captures: task data, dependencies, recent activity, active timer, tool stats. Useful before context switches or at key milestones.', { task_id: z.number().describe('The task ID to checkpoint') }, { readOnlyHint: false }, async (params) => createCheckpoint(params));
+    server.tool('get_checkpoint', 'Get the latest checkpoint for a task. Returns the full task snapshot — useful for resuming work after an interruption.', { task_id: z.number().describe('The task ID to get checkpoint for') }, { readOnlyHint: true }, async (params) => getCheckpoint(params));
+    server.tool('list_checkpoints', 'List all available checkpoints for a task.', { task_id: z.number().describe('The task ID to list checkpoints for') }, { readOnlyHint: true }, async (params) => listCheckpoints(params));
+}

package/dist/tools/notifications.js

@@ -52,8 +52,8 @@ export function registerNotificationTools(server) {
     server.tool('list_notifications', 'List notifications. Check with unread_only=true at conversation start to surface important updates for the user.', {
         limit: z.number().optional(),
         unread_only: z.boolean().optional(),
-    }, async (params) => listNotifications(params));
-    server.tool('mark_notification_read', 'Mark a notification as read after surfacing it to the user.', { id: z.number() }, async (params) => markNotificationRead(params));
-    server.tool('mark_all_notifications_read', 'Mark all unread notifications as read. Call after the user has been briefed on pending notifications.', {}, async () => markAllNotificationsRead());
-    server.tool('clear_notifications', 'Delete all notifications. Use with caution — this is irreversible.', {}, async () => clearNotifications());
+    }, { readOnlyHint: true }, async (params) => listNotifications(params));
+    server.tool('mark_notification_read', 'Mark a notification as read after surfacing it to the user.', { id: z.number() }, { readOnlyHint: false }, async (params) => markNotificationRead(params));
+    server.tool('mark_all_notifications_read', 'Mark all unread notifications as read. Call after the user has been briefed on pending notifications.', {}, { readOnlyHint: false }, async () => markAllNotificationsRead());
+    server.tool('clear_notifications', 'Delete all notifications. Use with caution — this is irreversible.', {}, { destructiveHint: true }, async () => clearNotifications());
 }

package/dist/tools/projects.js

@@ -97,16 +97,16 @@ export function registerProjectTools(server) {
         color: z.string().optional(),
         type: ProjectType.optional(),
         description: z.string().optional(),
-    }, async (params) => createProject(params));
-    server.tool('list_projects', 'List all projects with task count. Call this at conversation start to understand the workspace.', {}, async () => listProjects());
-    server.tool('get_project', 'Get a project by ID with all its tasks. Use this to understand the full scope of a project before starting work.', { id: z.number() }, async (params) => getProject(params));
+    }, { readOnlyHint: false }, async (params) => createProject(params));
+    server.tool('list_projects', 'List all projects with task count. Call this at conversation start to understand the workspace.', {}, { readOnlyHint: true }, async () => listProjects());
+    server.tool('get_project', 'Get a project by ID with all its tasks. Use this to understand the full scope of a project before starting work.', { id: z.number() }, { readOnlyHint: true }, async (params) => getProject(params));
     server.tool('update_project', 'Update project fields such as name, color, type, or description.', {
         id: z.number(),
         name: z.string().optional(),
         color: z.string().optional(),
         type: ProjectType.optional(),
         description: z.string().optional(),
-    }, async (params) => updateProject(params));
-    server.tool('delete_project', 'Delete a project by ID. Tasks under this project will be unlinked (project_id set to NULL), not deleted.', { id: z.number() }, async (params) => deleteProject(params));
-    server.tool('search_projects', 'Search projects by name or description. Use this to find projects related to your current work.', { query: z.string() }, async (params) => searchProjects(params));
+    }, { readOnlyHint: false }, async (params) => updateProject(params));
+    server.tool('delete_project', 'Delete a project by ID. Tasks under this project will be unlinked (project_id set to NULL), not deleted.', { id: z.number() }, { destructiveHint: true }, async (params) => deleteProject(params));
+    server.tool('search_projects', 'Search projects by name or description. Use this to find projects related to your current work.', { query: z.string() }, { readOnlyHint: true }, async (params) => searchProjects(params));
 }

package/dist/tools/settings.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { getDb } from '../db.js';
 import { logActivity, successResponse, broadcastChange } from '../helpers.js';
+import { getConfig, isServerConfigKey, writeConfigKey } from '../config.js';
 // ─── defaults ─────────────────────────────────────────────────────────
 const DEFAULT_SETTINGS = {
     timerBarDisplayMode: 'carousel',
@@ -23,6 +24,13 @@ const DEFAULT_SETTINGS = {
 };
 // ─── exported handler functions ───────────────────────────────────────
 export async function getSetting(params) {
+    // Server-level settings come from the config file
+    if (isServerConfigKey(params.key)) {
+        const config = getConfig();
+        const value = config[params.key] ?? null;
+        return successResponse({ key: params.key, value, source: 'config_file' });
+    }
+    // UI settings come from SQLite
     const db = getDb();
     const row = db
         .prepare('SELECT value FROM settings WHERE key = ?')
@@ -36,6 +44,19 @@ export async function getSetting(params) {
     return successResponse({ key: params.key, value: defaultValue });
 }
 export async function updateSetting(params) {
+    // Server-level settings write back to ~/.taskflow_config.json
+    if (isServerConfigKey(params.key)) {
+        writeConfigKey(params.key, params.value);
+        logActivity('settings_saved', params.key, { detail: `Server setting "${params.key}" updated in config file` });
+        broadcastChange('setting', 'settings_saved', { key: params.key, value: params.value });
+        return successResponse({
+            key: params.key,
+            value: params.value,
+            source: 'config_file',
+            note: 'Server setting saved to ~/.taskflow_config.json. Restart the MCP server for the change to take full effect.',
+        });
+    }
+    // UI settings go to SQLite
     const db = getDb();
     db.prepare('INSERT OR REPLACE INTO settings (key, value) VALUES (?, ?)').run(params.key, JSON.stringify(params.value));
     logActivity('settings_saved', params.key, { detail: `Setting "${params.key}" updated` });
@@ -44,9 +65,9 @@ export async function updateSetting(params) {
 }
 // ─── MCP registration ─────────────────────────────────────────────────
 export function registerSettingsTools(server) {
-    server.tool('get_setting', 'Get a setting value by key, returning the default if not set. Available keys: timerBarDisplayMode, notificationInterval, statusColors, operatorName, systemName, and more.', { key: z.string() }, async (params) => getSetting(params));
-    server.tool('update_setting', 'Update or create a setting value. Settings persist across sessions in the local SQLite database.', {
+    server.tool('get_setting', 'Get a setting value by key. Server settings (port, host, databasePath, logLevel, agentLivenessInterval, maxPortAttempts) come from ~/.taskflow_config.json. UI settings (timerBarDisplayMode, notificationInterval, statusColors, operatorName, systemName, etc.) come from SQLite.', { key: z.string() }, { readOnlyHint: true }, async (params) => getSetting(params));
+    server.tool('update_setting', 'Update a setting value. Server settings (port, host, databasePath, logLevel, agentLivenessInterval, maxPortAttempts) are written to ~/.taskflow_config.json and require a restart. UI settings are saved to the local SQLite database.', {
         key: z.string(),
         value: z.unknown(),
-    }, async (params) => updateSetting(params));
+    }, { readOnlyHint: false }, async (params) => updateSetting(params));
 }

package/dist/tools/tasks.d.ts

@@ -53,6 +53,8 @@ export declare function updateTask(params: {
     }>;
     due_date?: string;
     estimated_time?: number;
+    allowed_tools?: string[];
+    denied_tools?: string[];
 }): Promise<{
     content: {
         type: "text";