@fruition/fcp-mcp-server 1.4.0 → 1.5.0

package/README.md

@@ -4,7 +4,7 @@ MCP (Model Context Protocol) server that gives Claude Code direct access to the
 
 ## Features
 
-### Tools
+### FCP Launch Management Tools
 
 | Tool | Description |
 |------|-------------|
@@ -16,6 +16,19 @@ MCP (Model Context Protocol) server that gives Claude Code direct access to the
 | `fcp_add_progress_note` | Add progress notes to document work done |
 | `fcp_get_claude_md` | Generate CLAUDE.md content for a launch |
 
+### Unroo Task Management Tools
+
+| Tool | Description |
+|------|-------------|
+| `unroo_list_projects` | List all Unroo projects mapped to FCP clients |
+| `unroo_list_tasks` | Query tasks with filters (status, project, assignee) |
+| `unroo_create_task` | Create new tasks for discovered issues or follow-ups |
+| `unroo_update_task` | Update task status, hours logged, priority |
+| `unroo_get_my_tasks` | Get tasks assigned to current user |
+| `unroo_start_session` | Start work session for time tracking |
+| `unroo_end_session` | End work session and log time |
+| `unroo_create_follow_up` | Create follow-up task linked to a parent |
+
 ### Resources
 
 - `fcp://launches` - List of all launches

package/dist/index.js

@@ -37,8 +37,14 @@ import { execSync } from 'child_process';
 // Configuration
 const FCP_API_URL = process.env.FCP_API_URL || 'https://fcp.fru.io';
 const FCP_API_TOKEN = process.env.FCP_API_TOKEN || '';
+// Unroo API can be called directly (legacy) or proxied through FCP (recommended)
+// When UNROO_API_KEY is not set, Unroo calls go through FCP's proxy at /api/mcp/unroo/*
 const UNROO_API_URL = process.env.UNROO_API_URL || 'https://chat.frugpt.com';
 const UNROO_API_KEY = process.env.UNROO_API_KEY || '';
+// If no Unroo key, use FCP as proxy (unified key setup)
+const USE_FCP_UNROO_PROXY = !UNROO_API_KEY;
+// Helper to check if Unroo functionality is available (either mode)
+const UNROO_AVAILABLE = UNROO_API_KEY || (USE_FCP_UNROO_PROXY && FCP_API_TOKEN);
 let currentProject = null;
 /**
  * Detect the current git remote URL
@@ -119,11 +125,12 @@ async function initializeProjectDetection() {
 class FCPClient {
     baseUrl;
     token;
+    defaultTimeout = 15000; // 15 seconds
     constructor(baseUrl, token) {
         this.baseUrl = baseUrl;
         this.token = token;
     }
-    async fetch(path, options = {}) {
+    async fetch(path, options = {}, timeoutMs) {
         const url = `${this.baseUrl}${path}`;
         const headers = {
             'Content-Type': 'application/json',
@@ -142,6 +149,7 @@ class FCPClient {
         const response = await fetch(url, {
             ...options,
             headers,
+            signal: AbortSignal.timeout(timeoutMs || this.defaultTimeout),
         });
         if (!response.ok) {
             const error = await response.text();
@@ -182,27 +190,61 @@ class FCPClient {
     }
 }
 // Unroo API Client
+// Supports two modes:
+// 1. Direct: Uses UNROO_API_KEY to call Unroo directly (legacy)
+// 2. Proxy: Routes through FCP at /api/mcp/unroo/* using FCP_API_TOKEN (recommended)
 class UnrooClient {
     baseUrl;
     apiKey;
-    constructor(baseUrl, apiKey) {
+    useProxy;
+    fcpUrl;
+    fcpToken;
+    defaultTimeout = 15000; // 15 seconds
+    constructor(baseUrl, apiKey, useProxy = false, fcpUrl = '', fcpToken = '') {
         this.baseUrl = baseUrl;
         this.apiKey = apiKey;
+        this.useProxy = useProxy;
+        this.fcpUrl = fcpUrl;
+        this.fcpToken = fcpToken;
+        if (this.useProxy) {
+            console.error('[UnrooClient] Using FCP proxy mode (unified key)');
+        }
+        else {
+            console.error('[UnrooClient] Using direct Unroo API mode');
+        }
     }
-    async fetch(path, options = {}) {
-        const url = `${this.baseUrl}${path}`;
+    async fetch(path, options = {}, timeoutMs) {
+        let url;
         const headers = {
             'Content-Type': 'application/json',
-            'X-API-Key': this.apiKey,
             ...(options.headers || {}),
         };
+        if (this.useProxy) {
+            // Route through FCP proxy: /api/external/fcp/X -> /api/mcp/unroo/X
+            const proxyPath = path.replace('/api/external/fcp/', '/api/mcp/unroo/');
+            url = `${this.fcpUrl}${proxyPath}`;
+            // Use FCP API token
+            if (this.fcpToken && this.fcpToken !== 'dev_bypass') {
+                headers['X-API-Key'] = this.fcpToken;
+            }
+            else if (this.fcpToken === 'dev_bypass') {
+                headers['X-Dev-Bypass'] = 'true';
+            }
+        }
+        else {
+            // Direct Unroo API call
+            url = `${this.baseUrl}${path}`;
+            headers['X-API-Key'] = this.apiKey;
+        }
         const response = await fetch(url, {
             ...options,
             headers,
+            signal: AbortSignal.timeout(timeoutMs || this.defaultTimeout),
         });
         if (!response.ok) {
             const error = await response.text();
-            throw new Error(`Unroo API error (${response.status}): ${error}`);
+            const source = this.useProxy ? 'FCP Proxy' : 'Unroo API';
+            throw new Error(`${source} error (${response.status}): ${error}`);
         }
         return response.json();
     }
@@ -270,6 +312,51 @@ class UnrooClient {
             }),
         });
     }
+    // ============================================================================
+    // Parking Lot / Backlog APIs
+    // ============================================================================
+    async logFutureWork(input) {
+        return this.fetch('/api/external/fcp/future-work', {
+            method: 'POST',
+            body: JSON.stringify(input),
+        });
+    }
+    async getFutureWork(filters) {
+        const params = new URLSearchParams();
+        if (filters.project_key)
+            params.set('project_key', filters.project_key);
+        if (filters.account_id)
+            params.set('account_id', filters.account_id);
+        if (filters.status)
+            params.set('status', filters.status);
+        if (filters.destination)
+            params.set('destination', filters.destination);
+        if (filters.limit)
+            params.set('limit', filters.limit.toString());
+        if (filters.offset)
+            params.set('offset', filters.offset.toString());
+        const query = params.toString();
+        return this.fetch(`/api/external/fcp/future-work${query ? `?${query}` : ''}`);
+    }
+    async updateFutureWork(id, updates) {
+        return this.fetch(`/api/external/fcp/future-work/${encodeURIComponent(id)}`, {
+            method: 'PUT',
+            body: JSON.stringify(updates),
+        });
+    }
+    async getBacklog(filters) {
+        const params = new URLSearchParams();
+        if (filters.project_key)
+            params.set('project_key', filters.project_key);
+        if (filters.priority)
+            params.set('priority', filters.priority);
+        if (filters.limit)
+            params.set('limit', filters.limit.toString());
+        if (filters.offset)
+            params.set('offset', filters.offset.toString());
+        const query = params.toString();
+        return this.fetch(`/api/external/fcp/backlog${query ? `?${query}` : ''}`);
+    }
 }
 // ============================================================================
 // Auto Session Tracking
@@ -282,6 +369,8 @@ class SessionTracker {
     activities = [];
     heartbeatInterval = null;
     currentTaskId = null;
+    consecutiveHeartbeatFailures = 0;
+    static MAX_HEARTBEAT_FAILURES = 3;
     constructor(unrooClient) {
         this.unrooClient = unrooClient;
     }
@@ -300,7 +389,8 @@ class SessionTracker {
             this.activities = this.activities.slice(-50);
         }
         // Auto-start session on first tool call
-        if (!this.sessionActive && UNROO_API_KEY) {
+        // Session tracking works with either direct Unroo key OR FCP proxy mode
+        if (!this.sessionActive && UNROO_AVAILABLE) {
             await this.startSession();
         }
         // Send heartbeat every 30 tool calls or every 5 minutes
@@ -320,7 +410,7 @@ class SessionTracker {
      * Start a new session
      */
     async startSession() {
-        if (!UNROO_API_KEY) {
+        if (!UNROO_AVAILABLE) {
             return;
         }
         try {
@@ -340,7 +430,12 @@ class SessionTracker {
             this.lastHeartbeat = new Date();
             // Set up periodic heartbeat (every 5 minutes)
             this.heartbeatInterval = setInterval(() => {
-                this.sendHeartbeat().catch(() => { });
+                this.sendHeartbeat().catch((err) => {
+                    this.consecutiveHeartbeatFailures++;
+                    if (this.consecutiveHeartbeatFailures >= SessionTracker.MAX_HEARTBEAT_FAILURES) {
+                        console.error(`[SessionTracker] Heartbeat failed ${this.consecutiveHeartbeatFailures}x - session tracking may not work`);
+                    }
+                });
             }, 5 * 60 * 1000);
             if (currentProject) {
                 console.error(`[SessionTracker] Session started for project: ${currentProject.domain}`);
@@ -357,7 +452,7 @@ class SessionTracker {
      * Send a heartbeat to keep session alive
      */
     async sendHeartbeat() {
-        if (!this.sessionActive || !UNROO_API_KEY) {
+        if (!this.sessionActive || !UNROO_AVAILABLE) {
             return;
         }
         try {
@@ -367,17 +462,20 @@ class SessionTracker {
             });
             this.lastHeartbeat = new Date();
             this.toolCallCount = 0;
+            this.consecutiveHeartbeatFailures = 0; // Reset on success
             console.error('[SessionTracker] Heartbeat sent');
         }
         catch (error) {
-            console.error('[SessionTracker] Failed to send heartbeat:', error);
+            this.consecutiveHeartbeatFailures++;
+            console.error(`[SessionTracker] Failed to send heartbeat (attempt ${this.consecutiveHeartbeatFailures}):`, error);
+            throw error; // Re-throw for interval handler
         }
     }
     /**
      * End the current session and log activity summary to task
      */
     async endSession() {
-        if (!this.sessionActive || !UNROO_API_KEY) {
+        if (!this.sessionActive || !UNROO_AVAILABLE) {
             return;
         }
         if (this.heartbeatInterval) {
@@ -441,7 +539,7 @@ const server = new Server({
     },
 });
 const client = new FCPClient(FCP_API_URL, FCP_API_TOKEN);
-const unrooClient = new UnrooClient(UNROO_API_URL, UNROO_API_KEY);
+const unrooClient = new UnrooClient(UNROO_API_URL, UNROO_API_KEY, USE_FCP_UNROO_PROXY, FCP_API_URL, FCP_API_TOKEN);
 const sessionTracker = new SessionTracker(unrooClient);
 // Tool definitions
 const TOOLS = [
@@ -789,6 +887,126 @@ const TOOLS = [
             required: ['parent_task_id', 'title'],
         },
     },
+    // Parking Lot / Backlog Tools
+    {
+        name: 'unroo_log_future_work',
+        description: 'Log future work items to parking lot or backlog. Use when you discover work that should be done later - bugs, tech debt, features, documentation needs, etc.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                title: {
+                    type: 'string',
+                    description: 'Title of the future work item (required)',
+                },
+                project_key: {
+                    type: 'string',
+                    description: 'JIRA project key or FCP-SITE-{id} (required)',
+                },
+                description: {
+                    type: 'string',
+                    description: 'Detailed description of the work needed',
+                },
+                priority: {
+                    type: 'string',
+                    enum: ['Urgent', 'High', 'Medium', 'Low'],
+                    description: 'Priority level (default: Medium)',
+                },
+                task_type: {
+                    type: 'string',
+                    enum: ['bug', 'tech_debt', 'feature', 'documentation', 'security', 'performance'],
+                    description: 'Type of work item',
+                },
+                estimated_hours: {
+                    type: 'number',
+                    description: 'Estimated hours to complete',
+                },
+                launch_id: {
+                    type: 'number',
+                    description: 'FCP launch ID if related to a launch',
+                },
+                checklist_item_id: {
+                    type: 'number',
+                    description: 'FCP checklist item ID if discovered during checklist work',
+                },
+                notes: {
+                    type: 'string',
+                    description: 'Additional notes or context',
+                },
+                destination: {
+                    type: 'string',
+                    enum: ['parking_lot', 'backlog'],
+                    description: 'Where to put the item: parking_lot (needs review) or backlog (ready for sprint). Default: parking_lot',
+                },
+            },
+            required: ['title', 'project_key'],
+        },
+    },
+    {
+        name: 'unroo_get_parking_lot',
+        description: 'Get items from the parking lot - discovered work that needs review before being added to backlog.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_key: {
+                    type: 'string',
+                    description: 'Filter by JIRA project key or FCP-SITE-{id}',
+                },
+                status: {
+                    type: 'string',
+                    description: 'Filter by status: pending, approved, rejected, converted (default: pending)',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Maximum number of items to return (default: 100)',
+                },
+            },
+        },
+    },
+    {
+        name: 'unroo_get_backlog',
+        description: 'Get backlog items - tasks ready to be scheduled into sprints.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_key: {
+                    type: 'string',
+                    description: 'Filter by JIRA project key or FCP-SITE-{id}',
+                },
+                priority: {
+                    type: 'string',
+                    enum: ['Urgent', 'High', 'Medium', 'Low'],
+                    description: 'Filter by priority',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Maximum number of items to return (default: 100)',
+                },
+            },
+        },
+    },
+    {
+        name: 'unroo_convert_to_backlog',
+        description: 'Convert a parking lot item to backlog. Use after reviewing a discovered item and deciding it should be done.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: {
+                    type: 'string',
+                    description: 'The ID of the parking lot item to convert (required)',
+                },
+                priority: {
+                    type: 'string',
+                    enum: ['Urgent', 'High', 'Medium', 'Low'],
+                    description: 'Priority for the backlog item (optional, keeps original if not specified)',
+                },
+                notes: {
+                    type: 'string',
+                    description: 'Notes about the conversion decision',
+                },
+            },
+            required: ['id'],
+        },
+    },
 ];
 // Register tool handlers
 server.setRequestHandler(ListToolsRequestSchema, async () => {
@@ -1079,6 +1297,89 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     ],
                 };
             }
+            // Parking Lot / Backlog Handlers
+            case 'unroo_log_future_work': {
+                const input = args;
+                const result = await unrooClient.logFutureWork({
+                    ...input,
+                    discovered_by: 'claude-code-mcp',
+                });
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: true,
+                                message: result.message,
+                                id: result.id,
+                                destination: result.destination,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'unroo_get_parking_lot': {
+                const { project_key, status, limit } = args;
+                const result = await unrooClient.getFutureWork({
+                    project_key,
+                    status: status || 'pending',
+                    destination: 'parking_lot',
+                    limit: limit || 100,
+                });
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: true,
+                                total: result.items.length,
+                                stats: result.stats,
+                                items: result.items,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'unroo_get_backlog': {
+                const { project_key, priority, limit } = args;
+                const result = await unrooClient.getBacklog({
+                    project_key,
+                    priority,
+                    limit: limit || 100,
+                });
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: true,
+                                total: result.total,
+                                items: result.items,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'unroo_convert_to_backlog': {
+                const { id, priority, notes } = args;
+                const result = await unrooClient.updateFutureWork(id, {
+                    convert_to_backlog: true,
+                    priority,
+                    notes,
+                });
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: true,
+                                message: `Parking lot item ${id} converted to backlog`,
+                                item: result.item,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
             default:
                 throw new Error(`Unknown tool: ${name}`);
         }
@@ -1192,6 +1493,13 @@ async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
     console.error(`FCP MCP Server v${MCP_SERVER_VERSION} running on stdio`);
+    console.error(`  FCP API: ${FCP_API_URL}`);
+    if (USE_FCP_UNROO_PROXY) {
+        console.error('  Unroo: via FCP proxy (unified key mode)');
+    }
+    else {
+        console.error(`  Unroo: direct (${UNROO_API_URL})`);
+    }
     // Auto-detect project from git remote (non-blocking)
     initializeProjectDetection();
     // Check for updates (non-blocking)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fruition/fcp-mcp-server",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "MCP Server for FCP Launch Coordination System - enables Claude Code to interact with FCP launches and track development time",
   "main": "dist/index.js",
   "type": "module",