@dalmasonto/taskflow-mcp 1.0.4 → 1.0.6

package/dist/index.js

@@ -31,8 +31,8 @@ function cleanupOrphanedSessions() {
     }
 }
 cleanupOrphanedSessions();
-// Always start the HTTP/SSE server
-startSSEServer();
+// Always start the HTTP/SSE server (probes for existing instances, finds fallback port)
+await startSSEServer();
 // Only start MCP stdio transport when not in http-only mode
 if (!httpOnly) {
     const { McpServer } = await import('@modelcontextprotocol/sdk/server/mcp.js');

package/dist/sse.d.ts

@@ -1,7 +1,9 @@
-export declare function startSSEServer(): void;
+export declare function startSSEServer(): Promise<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).
+ * Otherwise, relay via HTTP to the process that does.
  */
 export declare function broadcast(event: string, data: object): void;
+/** Returns the port the SSE server is actively using */
+export declare function getActivePort(): number;

package/dist/sse.js

@@ -1,6 +1,9 @@
 import { createServer } from 'http';
 import { getDb } from './db.js';
 import { logActivity } from './helpers.js';
+const SERVICE_ID = 'taskflow-mcp';
+const MAX_PORT_ATTEMPTS = 10;
+const PROBE_TIMEOUT_MS = 2000;
 const clients = new Set();
 function resolvePort() {
     // CLI arg takes priority: --port 4000
@@ -14,7 +17,27 @@ function resolvePort() {
     }
     return 3456;
 }
-const PORT = resolvePort();
+const PREFERRED_PORT = resolvePort();
+/** The port that is actually serving SSE — either ours or an existing instance's */
+let activePort = PREFERRED_PORT;
+/** Probe a port to check if a TaskFlow service is already running there */
+async function probeTaskFlow(port) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), PROBE_TIMEOUT_MS);
+    try {
+        const res = await fetch(`http://localhost:${port}/healthz`, { signal: controller.signal });
+        if (!res.ok)
+            return false;
+        const body = await res.json();
+        return body.service === SERVICE_ID;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
 function jsonResponse(res, status, data) {
     res.writeHead(status, { 'Content-Type': 'application/json' });
     res.end(JSON.stringify(data));
@@ -26,7 +49,7 @@ function readBody(req) {
         req.on('end', () => resolve(body));
     });
 }
-export function startSSEServer() {
+export async function startSSEServer() {
     const server = createServer(async (req, res) => {
         // CORS headers for all requests
         res.setHeader('Access-Control-Allow-Origin', '*');
@@ -37,6 +60,11 @@ export function startSSEServer() {
             res.end();
             return;
         }
+        // GET /healthz — identity probe so other instances can detect us
+        if (req.url === '/healthz' && req.method === 'GET') {
+            jsonResponse(res, 200, { service: SERVICE_ID, pid: process.pid });
+            return;
+        }
         if (req.url === '/events' && req.method === 'GET') {
             res.writeHead(200, {
                 'Content-Type': 'text/event-stream',
@@ -237,15 +265,49 @@ export function startSSEServer() {
         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;
+    // Try ports sequentially: probe occupied ports to see if they're ours
+    await new Promise((resolve) => {
+        let attempt = 0;
+        function tryPort(port) {
+            if (attempt >= MAX_PORT_ATTEMPTS) {
+                console.error(`[SSE] failed to bind after ${MAX_PORT_ATTEMPTS} attempts (ports ${PREFERRED_PORT}–${port - 1})`);
+                resolve();
+                return;
+            }
+            server.once('error', async (err) => {
+                if (err.code === 'EADDRINUSE') {
+                    const isTaskFlow = await probeTaskFlow(port);
+                    if (isTaskFlow) {
+                        // Another TaskFlow instance owns this port — connect to it instead
+                        activePort = port;
+                        console.log(`[SSE] port ${port} owned by another TaskFlow instance (pid probe) — using it`);
+                        resolve();
+                    }
+                    else {
+                        // Not ours — try next port
+                        console.log(`[SSE] port ${port} in use by non-TaskFlow service — trying ${port + 1}`);
+                        attempt++;
+                        tryPort(port + 1);
+                    }
+                }
+                else {
+                    console.error('[SSE] unexpected server error:', err.message);
+                    resolve();
+                }
+            });
+            server.listen(port, '0.0.0.0', () => {
+                activePort = port;
+                markSSEActive();
+                if (port !== PREFERRED_PORT) {
+                    console.log(`[SSE] listening on fallback port ${port} (preferred ${PREFERRED_PORT} was unavailable)`);
+                }
+                else {
+                    console.log(`[SSE] listening on port ${port}`);
+                }
+                resolve();
+            });
         }
-        // Unexpected error — still don't crash the MCP process
-    });
-    server.listen(PORT, '0.0.0.0', () => {
-        markSSEActive();
+        tryPort(PREFERRED_PORT);
     });
 }
 /** Broadcast directly to connected SSE clients in this process */
@@ -262,7 +324,7 @@ export function markSSEActive() {
 }
 /**
  * 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).
+ * Otherwise, relay via HTTP to the process that does.
  */
 export function broadcast(event, data) {
     if (sseServerActive && clients.size > 0) {
@@ -271,7 +333,7 @@ export function broadcast(event, data) {
     else {
         // Relay to the SSE server owner via HTTP
         const body = JSON.stringify({ event, data });
-        fetch(`http://localhost:${PORT}/api/broadcast`, {
+        fetch(`http://localhost:${activePort}/api/broadcast`, {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
             body,
@@ -280,3 +342,7 @@ export function broadcast(event, data) {
         });
     }
 }
+/** Returns the port the SSE server is actively using */
+export function getActivePort() {
+    return activePort;
+}

package/dist/tools/agent.js

@@ -25,16 +25,17 @@ export async function getAgentInstructions() {
         },
         rules: [
             // Task tracking
-            'Proactively create tasks for ALL substantial work (features, bugs, refactors). search_tasks first to avoid duplicates. Link tasks to the confirmed project.',
-            'Timer lifecycle: start_timer → work → stop_timer(final_status). Use "done"/"partial_done"/"blocked". pause_timer when waiting for input.',
-            'MUST stop_timer with "done" when work is complete. Never leave finished tasks in "in_progress" or "paused".',
+            'Proactively create tasks for ALL substantial work — features, bugs, refactors, AND debugging/investigation. Debugging is real work: create a task for it (e.g. "Debug: SSE connection dropping"), start a timer, and track it the same way you would a feature. search_tasks first to avoid duplicates. Link tasks to the confirmed project.',
+            'Timer lifecycle: start_timer → work → stop_timer(final_status). Use "done"/"partial_done"/"blocked". pause_timer when waiting for input. This applies equally to debugging tasks — start a timer before investigating, stop it when resolved or blocked.',
+            'MUST stop_timer with "done" when work is complete. Never leave finished tasks in "in_progress" or "paused". This includes debugging tasks — when the bug is fixed or the investigation concludes, stop the timer.',
             // Dependencies
             'Check task dependencies before starting. If any dep is incomplete, set task to "blocked".',
             'After completing a task, check if blocked tasks depending on it can be unblocked.',
             // Prioritization
             'When user is unsure what to work on: list_tasks priority="critical"/"high" status="not_started".',
             // Logging
-            'Use log_debug with task_id to record debugging steps, hypotheses, findings, decisions. Use Markdown formatting.',
+            'ALWAYS log your entire debugging process using log_debug with task_id. Log every stage: issue identification, hypothesis, files read/edited, commands run, errors encountered, fixes attempted, and resolution. This creates a visible trail in the Activity Pulse so users can follow your reasoning in real-time.',
+            'log_debug early and often — not just at the end. Log when you start investigating, when you find a clue, when you edit a file, and when the fix lands. Use Markdown: headings for stages, code blocks for errors/paths, bold for key findings.',
             // Formatting
             'Use Markdown in descriptions — headings, bullets, code blocks, bold. The UI renders it.',
         ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dalmasonto/taskflow-mcp",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "MCP server for TaskFlow — manage projects, tasks, timers, analytics via AI agents",
   "type": "module",
   "main": "dist/index.js",