@dalmasonto/taskflow-mcp 1.0.0

package/README.md

@@ -0,0 +1,184 @@
+# TaskFlow MCP Server
+
+A local-first task and time tracking system exposed as [MCP](https://modelcontextprotocol.io) tools. Any MCP-compatible AI agent can manage projects, tasks, timers, analytics, and notifications through this server.
+
+## Quickstart
+
+### 1. Install and build
+
+```bash
+cd mcp-server
+npm install
+npm run build
+```
+
+### 2. Configure your MCP client
+
+Add a `.mcp.json` file to your project root (or wherever your MCP client reads config):
+
+```json
+{
+  "mcpServers": {
+    "taskflow": {
+      "command": "node",
+      "args": ["/absolute/path/to/mcp-server/dist/index.js"]
+    }
+  }
+}
+```
+
+Replace the path with the absolute path to your built `dist/index.js`.
+
+### 3. Auto-allow permissions (Claude Code)
+
+By default, Claude Code will prompt you to approve each MCP tool call. To allow all TaskFlow tools without prompts, add this to `.claude/settings.local.json`:
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "mcp__taskflow__*"
+    ]
+  },
+  "enableAllProjectMcpServers": true
+}
+```
+
+The `mcp__taskflow__*` wildcard matches every tool exposed by this server.
+
+For other MCP clients (Cursor, Windsurf, etc.), check their docs for permission/auto-approve configuration.
+
+## Agent Integration Guide
+
+### How agents discover TaskFlow
+
+TaskFlow uses two layers to guide agent behavior:
+
+**Layer 1: Tool descriptions (passive discovery)**
+Every tool has a description that hints at when and why to use it. MCP clients surface these descriptions when the agent connects, so the agent learns the workflow organically. For example, `start_timer` says "Call this before beginning work on any task to track focused time."
+
+**Layer 2: `get_agent_instructions` tool (active onboarding)**
+This is the key tool. Its description says **"Call this at the start of every conversation."** When called, it returns:
+
+- A role description for the agent
+- A startup checklist (list projects, check in-progress tasks, check notifications)
+- Behavioral rules (when to start/stop timers, how to handle blockers, etc.)
+- Live context (current project count, in-progress tasks, blocked tasks, unread notifications)
+- The full task status workflow with valid transitions
+
+Any well-behaved agent will call this tool when it sees the description, without needing explicit user instructions.
+
+### Making it automatic (recommended)
+
+For the most reliable experience, add one line to your project's `CLAUDE.md` (or equivalent agent config):
+
+```markdown
+## MCP Integration
+At the start of each conversation, call the `get_agent_instructions` tool from the taskflow MCP server to understand your task management workflow.
+```
+
+This guarantees the agent calls the instruction tool on every conversation start. Without this, the agent will still likely discover the tool via its description, but the CLAUDE.md line makes it deterministic.
+
+### Example conversation flow
+
+Here's what a conversation looks like when the agent is properly connected:
+
+```
+Agent connects → sees get_agent_instructions in tool list → calls it
+  ↓
+Gets instructions + live context (3 projects, 2 tasks in progress, 1 blocked)
+  ↓
+Calls list_tasks(status="in_progress") → sees "Build dashboard page" is active
+  ↓
+User: "Let's work on the dashboard"
+  ↓
+Agent: calls get_task(id=5) → reads description for implementation details
+Agent: calls start_timer(task_id=5) → time tracking begins
+  ↓
+Agent implements the feature, referencing task description for acceptance criteria
+  ↓
+Agent: calls stop_timer(task_id=5, final_status="done")
+Agent: checks if any blocked tasks depended on task 5
+```
+
+### Strategies for proactive agent behavior
+
+The `get_agent_instructions` tool tells agents to:
+
+1. **Check tasks before coding** — before starting work, search for a matching task and start its timer
+2. **Track time automatically** — start_timer when beginning work, pause_timer on context switches, stop_timer when done
+3. **Surface blockers** — if stuck, update the task to "blocked" with context in the description
+4. **Suggest next work** — when the user asks "what should I work on?", surface high-priority unblocked tasks
+5. **Stay in sync** — create tasks for new work items to keep the tracker up to date
+6. **Read descriptions** — task descriptions contain implementation details and acceptance criteria
+
+## Available Tools
+
+### Agent
+| Tool | Description |
+|------|-------------|
+| `get_agent_instructions` | Returns onboarding instructions and live context for AI agents. **Call first.** |
+
+### Tasks
+| Tool | Description |
+|------|-------------|
+| `create_task` | Create a task with dependencies, tags, links, and time estimates |
+| `list_tasks` | List tasks with filters (status, project, priority, tag) |
+| `get_task` | Get a task by ID with time tracking info |
+| `update_task` | Update task fields |
+| `update_task_status` | Change status with transition validation |
+| `delete_task` | Delete a task by ID |
+| `bulk_create_tasks` | Create multiple tasks in a single transaction |
+| `search_tasks` | Full-text search by title or description |
+
+### Projects
+| Tool | Description |
+|------|-------------|
+| `create_project` | Create a project (active_project or project_idea) |
+| `list_projects` | List all projects with task counts |
+| `get_project` | Get a project with all its tasks |
+| `update_project` | Update project fields |
+| `delete_project` | Delete a project (tasks are unlinked, not deleted) |
+
+### Timer
+| Tool | Description |
+|------|-------------|
+| `start_timer` | Start a timer session (task transitions to in_progress) |
+| `pause_timer` | Pause the active session (task transitions to paused) |
+| `stop_timer` | Stop timer with final status (done/partial_done/blocked) |
+| `list_sessions` | List sessions with optional date range filter |
+
+### Analytics
+| Tool | Description |
+|------|-------------|
+| `get_analytics` | Summary: focused time, completion rates, status distribution, time per project |
+| `get_timeline` | Focused time grouped by day or week |
+
+### Activity
+| Tool | Description |
+|------|-------------|
+| `get_activity_log` | Recent activity: completions, timer events, status changes |
+| `clear_activity_log` | Delete all activity log entries |
+
+### Notifications
+| Tool | Description |
+|------|-------------|
+| `list_notifications` | List notifications (filter by unread) |
+| `mark_notification_read` | Mark a single notification as read |
+| `mark_all_notifications_read` | Mark all as read |
+| `clear_notifications` | Delete all notifications |
+
+### Settings
+| Tool | Description |
+|------|-------------|
+| `get_setting` | Get a setting by key (returns default if not set) |
+| `update_setting` | Update or create a setting |
+
+## Configuration
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `TASKFLOW_SSE_PORT` | `3456` | Port for the SSE broadcast server |
+| Database location | `~/.taskflow/taskflow.db` | SQLite database with WAL mode |
+
+The SSE server at `http://localhost:3456/events` broadcasts real-time changes to connected UI clients. The `/sync` endpoint returns a full data dump for initial sync.

package/dist/db.d.ts

@@ -0,0 +1,5 @@
+import Database from 'better-sqlite3';
+export declare function resolvePath(p: string): string;
+export declare function getDb(): Database.Database;
+export declare function initDb(path: string): Database.Database;
+export declare function closeDb(): void;

package/dist/db.js

@@ -0,0 +1,109 @@
+import Database from 'better-sqlite3';
+import { mkdirSync } from 'fs';
+import { dirname, resolve } from 'path';
+import { homedir } from 'os';
+const DEFAULT_DB_PATH = '~/.taskflow/taskflow.db';
+let db = null;
+// Expands ~/path to $HOME/path. Only handles ~/ prefix, not ~user/ paths.
+export function resolvePath(p) {
+    if (p.startsWith('~/') || p === '~') {
+        return resolve(homedir(), p.slice(2));
+    }
+    return resolve(p);
+}
+export function getDb() {
+    if (db)
+        return db;
+    return initDb(process.env.TASKFLOW_DB_PATH || DEFAULT_DB_PATH);
+}
+// For testing: initialize with a specific path (use ':memory:' for tests)
+export function initDb(path) {
+    if (db) {
+        db.close();
+        db = null;
+    }
+    const dbPath = path === ':memory:' ? ':memory:' : resolvePath(path);
+    if (path !== ':memory:')
+        mkdirSync(dirname(dbPath), { recursive: true });
+    db = new Database(dbPath);
+    db.pragma('journal_mode = WAL');
+    db.pragma('foreign_keys = ON');
+    db.pragma('busy_timeout = 5000');
+    initSchema(db);
+    return db;
+}
+function initSchema(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS projects (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      name TEXT NOT NULL,
+      color TEXT NOT NULL DEFAULT '#de8eff',
+      type TEXT NOT NULL DEFAULT 'active_project',
+      description TEXT,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS tasks (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      title TEXT NOT NULL,
+      description TEXT,
+      status TEXT NOT NULL DEFAULT 'not_started',
+      priority TEXT NOT NULL DEFAULT 'medium',
+      project_id INTEGER REFERENCES projects(id) ON DELETE SET NULL,
+      dependencies TEXT NOT NULL DEFAULT '[]',
+      links TEXT NOT NULL DEFAULT '[]',
+      tags TEXT NOT NULL DEFAULT '[]',
+      due_date TEXT,
+      estimated_time INTEGER,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS sessions (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      task_id INTEGER NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
+      start TEXT NOT NULL,
+      end TEXT
+    );
+
+    CREATE TABLE IF NOT EXISTS activity_logs (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      action TEXT NOT NULL,
+      title TEXT NOT NULL,
+      detail TEXT,
+      entity_type TEXT,
+      entity_id INTEGER,
+      created_at TEXT NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS notifications (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      title TEXT NOT NULL,
+      message TEXT NOT NULL,
+      type TEXT NOT NULL DEFAULT 'info',
+      read INTEGER NOT NULL DEFAULT 0,
+      created_at TEXT NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS settings (
+      key TEXT PRIMARY KEY,
+      value TEXT NOT NULL
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_tasks_status ON tasks(status);
+    CREATE INDEX IF NOT EXISTS idx_tasks_project_id ON tasks(project_id);
+    CREATE INDEX IF NOT EXISTS idx_tasks_priority ON tasks(priority);
+    CREATE INDEX IF NOT EXISTS idx_sessions_task_id ON sessions(task_id);
+    CREATE INDEX IF NOT EXISTS idx_activity_logs_created_at ON activity_logs(created_at);
+    CREATE INDEX IF NOT EXISTS idx_activity_logs_action ON activity_logs(action);
+    CREATE INDEX IF NOT EXISTS idx_notifications_read ON notifications(read);
+    CREATE INDEX IF NOT EXISTS idx_notifications_created_at ON notifications(created_at);
+  `);
+}
+export function closeDb() {
+    if (db) {
+        db.close();
+        db = null;
+    }
+}

package/dist/helpers.d.ts

@@ -0,0 +1,21 @@
+import type { ActivityAction, ErrorCode } from './types.js';
+export declare function logActivity(action: ActivityAction, title: string, options?: {
+    detail?: string;
+    entityType?: string;
+    entityId?: number;
+}): void;
+export declare function errorResponse(error: string, code: ErrorCode): {
+    isError: true;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+export declare function successResponse(data: unknown): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+export declare function now(): string;
+export declare function broadcastChange(entity: string, action: string, payload: unknown): void;

package/dist/helpers.js

@@ -0,0 +1,27 @@
+import { getDb } from './db.js';
+import { broadcast } from './sse.js';
+export function logActivity(action, title, options) {
+    const db = getDb();
+    const ts = new Date().toISOString();
+    const result = db.prepare(`INSERT INTO activity_logs (action, title, detail, entity_type, entity_id, created_at)
+     VALUES (?, ?, ?, ?, ?, ?)`).run(action, title, options?.detail ?? null, options?.entityType ?? null, options?.entityId ?? null, ts);
+    const entry = db.prepare('SELECT * FROM activity_logs WHERE id = ?').get(result.lastInsertRowid);
+    broadcast('activity_logged', { entity: 'activity', action: 'activity_logged', payload: entry });
+}
+export function errorResponse(error, code) {
+    return {
+        isError: true,
+        content: [{ type: 'text', text: JSON.stringify({ error, code }) }],
+    };
+}
+export function successResponse(data) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+    };
+}
+export function now() {
+    return new Date().toISOString();
+}
+export function broadcastChange(entity, action, payload) {
+    broadcast(action, { entity, action, payload });
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+import { startSSEServer } from './sse.js';
+import { getDb } from './db.js';
+import { broadcast } from './sse.js';
+const httpOnly = process.argv.includes('--http-only');
+// Close any orphaned sessions left from a previous crash
+// If the server died while sessions were active, they'll have no `end` timestamp
+function cleanupOrphanedSessions() {
+    const db = getDb();
+    const now = new Date().toISOString();
+    const orphaned = db.prepare('SELECT * FROM sessions WHERE end IS NULL').all();
+    if (orphaned.length === 0)
+        return;
+    db.prepare('UPDATE sessions SET end = ? WHERE end IS NULL').run(now);
+    // Set orphaned in_progress tasks back to paused
+    const taskIds = [...new Set(orphaned.map(s => s.task_id))];
+    for (const taskId of taskIds) {
+        const task = db.prepare('SELECT status FROM tasks WHERE id = ?').get(taskId);
+        if (task?.status === 'in_progress') {
+            db.prepare("UPDATE tasks SET status = 'paused', updated_at = ? WHERE id = ?").run(now, taskId);
+            broadcast('task_updated', { entity: 'task', action: 'task_status_changed', payload: db.prepare('SELECT * FROM tasks WHERE id = ?').get(taskId) });
+        }
+    }
+}
+cleanupOrphanedSessions();
+// Always start the HTTP/SSE server
+startSSEServer();
+// Only start MCP stdio transport when not in http-only mode
+if (!httpOnly) {
+    const { McpServer } = await import('@modelcontextprotocol/sdk/server/mcp.js');
+    const { StdioServerTransport } = await import('@modelcontextprotocol/sdk/server/stdio.js');
+    const { registerTaskTools } = await import('./tools/tasks.js');
+    const { registerProjectTools } = await import('./tools/projects.js');
+    const { registerTimerTools } = await import('./tools/timer.js');
+    const { registerAnalyticsTools } = await import('./tools/analytics.js');
+    const { registerActivityTools } = await import('./tools/activity.js');
+    const { registerNotificationTools } = await import('./tools/notifications.js');
+    const { registerSettingsTools } = await import('./tools/settings.js');
+    const { registerAgentTools } = await import('./tools/agent.js');
+    const server = new McpServer({
+        name: 'taskflow',
+        version: '1.0.0',
+    });
+    registerAgentTools(server);
+    registerTaskTools(server);
+    registerProjectTools(server);
+    registerTimerTools(server);
+    registerAnalyticsTools(server);
+    registerActivityTools(server);
+    registerNotificationTools(server);
+    registerSettingsTools(server);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}

package/dist/sse.d.ts

@@ -0,0 +1,7 @@
+export declare function startSSEServer(): void;
+export declare function markSSEActive(): void;
+/**
+ * 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 declare function broadcast(event: string, data: object): void;