@fruition/fcp-mcp-server 1.18.0 → 1.19.0

package/bin/unroo-heartbeat.sh

@@ -57,12 +57,20 @@ if [ -f ".unroo" ]; then
   PROJECT_SLUG=$(grep -E "^project_slug=" .unroo 2>/dev/null | cut -d= -f2)
 fi
 
-# Get machine ID (for multi-machine tracking)
+# Get machine ID (for multi-machine tracking) — portable across Linux and macOS
 MACHINE_ID=""
 if [ -f /etc/machine-id ]; then
-  MACHINE_ID=$(cat /etc/machine-id | head -c 8)
-elif command -v hostid &> /dev/null; then
-  MACHINE_ID=$(hostid)
+  # Linux (systemd)
+  MACHINE_ID=$(head -c 8 /etc/machine-id 2>/dev/null)
+elif [ -r /var/lib/dbus/machine-id ]; then
+  # Linux (dbus, no systemd)
+  MACHINE_ID=$(head -c 8 /var/lib/dbus/machine-id 2>/dev/null)
+elif command -v ioreg >/dev/null 2>&1; then
+  # macOS — IOPlatformUUID is stable per machine
+  MACHINE_ID=$(ioreg -rd1 -c IOPlatformExpertDevice 2>/dev/null \
+    | awk -F'"' '/IOPlatformUUID/{print $4}' | head -c 8)
+elif command -v hostid >/dev/null 2>&1; then
+  MACHINE_ID=$(hostid 2>/dev/null)
 fi
 
 # Build JSON payload

package/dist/index.js

@@ -77,6 +77,148 @@ const UNROO_AVAILABLE = UNROO_API_KEY || (USE_FCP_UNROO_PROXY && FCP_API_TOKEN);
 // - Multiple processes on same machine (PID)
 // - Process restarts (timestamp)
 const INSTANCE_ID = `${process.env.HOSTNAME || 'local'}-${process.pid}-${Date.now()}`;
+const ROLE_HIERARCHY = [
+    'super_admin',
+    'admin',
+    'billing_admin',
+    'operator',
+    'viewer',
+    'none',
+];
+const TOOL_PERMISSIONS = {
+    // --- super_admin only: destructive, irreversible, or move raw prod data ---
+    fcp_create_site: 'super_admin',
+    fcp_delete_site: 'super_admin',
+    fcp_delete_launch: 'super_admin',
+    fcp_clone_to_staging: 'super_admin',
+    fcp_clone_confirm: 'super_admin',
+    fcp_shield_remove_domain: 'super_admin',
+    fcp_backup_delete_pairing: 'super_admin',
+    fcp_filesync_cancel_sync: 'super_admin',
+    // --- admin+: mutating ops with real-world side effects ---
+    fcp_create_launch: 'admin',
+    fcp_update_launch: 'admin',
+    fcp_update_site: 'admin',
+    fcp_delete_checklist_item: 'admin',
+    fcp_shield_add_domain: 'admin',
+    fcp_shield_update_domain: 'admin',
+    fcp_backup_enable: 'admin',
+    fcp_backup_trigger: 'admin',
+    fcp_backup_check_trigger: 'admin',
+    fcp_backup_update_pairing: 'admin',
+    fcp_backup_download: 'admin',
+    fcp_backup_download_prepared: 'admin',
+    fcp_kinsta_backup_download: 'admin',
+    fcp_filesync_start_sync: 'admin',
+    fcp_filesync_get_confirmation: 'admin',
+    fcp_trigger_nuclei_scan: 'admin',
+    fcp_scan_security_headers: 'admin',
+    // --- operator+: routine writes (checklists, progress notes, Unroo tasks) ---
+    fcp_add_checklist_item: 'operator',
+    fcp_update_checklist_item: 'operator',
+    fcp_validate_checklist_item: 'operator',
+    fcp_add_progress_note: 'operator',
+    unroo_create_task: 'operator',
+    unroo_update_task: 'operator',
+    unroo_add_comment: 'operator',
+    unroo_create_follow_up: 'operator',
+    unroo_log_future_work: 'operator',
+    unroo_convert_to_backlog: 'operator',
+    unroo_start_session: 'operator',
+    unroo_end_session: 'operator',
+    // --- viewer (read-only) — explicit for clarity; any unmapped tool also defaults here ---
+    fcp_list_launches: 'viewer',
+    fcp_get_launch: 'viewer',
+    fcp_get_legacy_access: 'viewer',
+    fcp_get_checklist: 'viewer',
+    fcp_get_claude_md: 'viewer',
+    fcp_get_success_factors: 'viewer',
+    fcp_get_unroo_section: 'viewer',
+    fcp_filesync_list_configs: 'viewer',
+    fcp_filesync_get_config: 'viewer',
+    fcp_filesync_get_job_status: 'viewer',
+    fcp_get_nuclei_results: 'viewer',
+    fcp_get_security_headers_results: 'viewer',
+    fcp_list_sites: 'viewer',
+    fcp_search_sites: 'viewer',
+    fcp_get_site: 'viewer',
+    fcp_get_local_setup_guide: 'viewer',
+    fcp_shield_list_domains: 'viewer',
+    fcp_shield_get_domain: 'viewer',
+    fcp_shield_get_metrics: 'viewer',
+    fcp_backup_list_sites: 'viewer',
+    fcp_backup_get_config: 'viewer',
+    fcp_backup_list_eligible: 'viewer',
+    fcp_backup_list_backups: 'viewer',
+    fcp_backup_get_status: 'viewer',
+    fcp_backup_sanitize_status: 'viewer',
+    fcp_backup_list_pairings: 'viewer',
+    fcp_kinsta_backup_list_sites: 'viewer',
+    fcp_kinsta_backup_list: 'viewer',
+    fcp_clone_status: 'viewer',
+    fcp_clone_list: 'viewer',
+    fcp_get_dev_environment_info: 'viewer',
+    unroo_list_projects: 'viewer',
+    unroo_list_tasks: 'viewer',
+    unroo_get_task: 'viewer',
+    unroo_list_comments: 'viewer',
+    unroo_get_my_tasks: 'viewer',
+    unroo_get_parking_lot: 'viewer',
+    unroo_get_backlog: 'viewer',
+};
+// Resolved role for the current API key. Cached only on successful lookup so
+// transient FCP outages don't pin us to 'none' for the rest of the session.
+let cachedUserRole;
+async function fetchUserRole() {
+    if (cachedUserRole !== undefined)
+        return cachedUserRole;
+    // dev_bypass is the local-dev token; treat as super_admin to avoid
+    // gating local development against role lookup.
+    if (FCP_API_TOKEN === 'dev_bypass') {
+        cachedUserRole = 'super_admin';
+        return cachedUserRole;
+    }
+    if (!FCP_API_TOKEN) {
+        return 'none';
+    }
+    try {
+        const res = await fetch(`${FCP_API_URL}/api/mcp/me`, {
+            headers: { 'X-API-Key': FCP_API_TOKEN },
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (!res.ok) {
+            console.error(`[MCP Server] Role lookup failed: HTTP ${res.status}`);
+            return 'none';
+        }
+        const data = await res.json();
+        const role = data?.role ?? 'none';
+        cachedUserRole = role;
+        console.error(`[MCP Server] Resolved user role: ${role} (${data?.email ?? 'unknown'})`);
+        return role;
+    }
+    catch (err) {
+        console.error('[MCP Server] Role lookup error:', err);
+        return 'none';
+    }
+}
+function isRoleAtLeast(actual, required) {
+    if (actual === 'none')
+        return required === 'none';
+    const a = ROLE_HIERARCHY.indexOf(actual);
+    const r = ROLE_HIERARCHY.indexOf(required);
+    if (a === -1 || r === -1)
+        return false;
+    return a <= r;
+}
+async function enforceToolPermission(toolName) {
+    const required = TOOL_PERMISSIONS[toolName] ?? 'viewer';
+    const actual = await fetchUserRole();
+    if (!isRoleAtLeast(actual, required)) {
+        throw new Error(`Permission denied: tool '${toolName}' requires ${required} role; ` +
+            `your role is '${actual}'. Contact a super_admin (Brad, Mattox, or Andrea) ` +
+            `if you need access.`);
+    }
+}
 let currentProject = null;
 /**
  * Detect the current git remote URL
@@ -2805,6 +2947,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     // Track tool call for session management
     await sessionTracker.trackToolCall(name, `Called ${name}`);
     try {
+        // Role-based access control: gate destructive / sensitive tools by RBAC role
+        // resolved from /api/auth/me. Throws on insufficient privilege; the catch
+        // block below converts the error into the standard MCP error response.
+        await enforceToolPermission(name);
         switch (name) {
             case 'fcp_list_launches': {
                 const result = await client.listLaunches(args);
@@ -4049,10 +4195,15 @@ async function main() {
     // Sync ~/.claude/skills with the shared Unroo KG (non-blocking, opt-in).
     // First run on a fresh workstation is dry-run only; user opts in via
     // `fcp-mcp-server sync-skills --enable`.
+    // Passing the FCP key lets skills-sync route through FCP's Unroo proxy when
+    // no personal UNROO_API_KEY is set — so the single `claude mcp add` key
+    // covers skill sync too.
     runBackgroundSync({
         unrooApiKey: process.env.UNROO_API_KEY ?? "",
         userEmail: FCP_USER_EMAIL,
         unrooApiUrl: process.env.UNROO_API_URL,
+        fcpApiUrl: FCP_API_URL,
+        fcpApiToken: FCP_API_TOKEN,
     });
     // Handle graceful shutdown — idempotent, safe to call from any signal/event
     let shuttingDown = false;

package/dist/skills-sync-cli.js

@@ -47,10 +47,15 @@ Options:
   --enable        Persist the one-time opt-in flag and run a real sync
   --help, -h      Show this help
 
-Environment:
-  UNROO_API_KEY   Required. Same key the FCP MCP server uses.
-  FCP_USER_EMAIL  Required. Your Fruition team email; gates access to the KG.
-  UNROO_API_URL   Override (default https://app.unroo.io).
+Environment (proxy mode — default, recommended):
+  FCP_API_TOKEN   FCP API key. With this set and no UNROO_API_KEY, sync routes
+                  through FCP's Unroo proxy — no personal Unroo key needed.
+  FCP_API_URL     FCP base URL (default https://fcp.fru.io).
+
+Environment (direct mode — optional, legacy):
+  UNROO_API_KEY   Personal Unroo key. If set, sync talks to Unroo directly.
+  FCP_USER_EMAIL  Your Fruition team email; required for direct-mode attribution.
+  UNROO_API_URL   Unroo base URL override (default https://app.unroo.io).
 
 State file: ${defaultStateFile(defaultSkillsDir())}
 `.trim();
@@ -95,6 +100,9 @@ export async function runSkillsCli(argv) {
         unrooApiKey: process.env.UNROO_API_KEY ?? '',
         userEmail: process.env.FCP_USER_EMAIL ?? '',
         unrooApiUrl: process.env.UNROO_API_URL,
+        // FCP key enables proxy mode when no personal UNROO_API_KEY is set.
+        fcpApiUrl: process.env.FCP_API_URL,
+        fcpApiToken: process.env.FCP_API_TOKEN,
         // --enable forces a real run; otherwise let lib decide based on opt-in flag
         dryRun: args.enable ? false : args.dryRun,
     };

package/dist/skills-sync.d.ts

@@ -51,6 +51,8 @@ export interface SyncOptions {
     stateFile?: string;
     unrooApiUrl?: string;
     unrooApiKey?: string;
+    fcpApiUrl?: string;
+    fcpApiToken?: string;
     userEmail?: string;
     dryRun?: boolean;
     log?: (msg: string) => void;

package/dist/skills-sync.js

@@ -31,8 +31,18 @@ import { createHash } from 'crypto';
 // ---------------------------------------------------------------------------
 const STATE_VERSION = 1;
 const DEFAULT_UNROO_URL = 'https://app.unroo.io';
+const DEFAULT_FCP_URL = 'https://fcp.fru.io';
+// Direct mode: skills-sync talks straight to Unroo's knowledge-graph endpoints
+// with a personal UNROO_API_KEY.
 const SEARCH_PATH = '/api/external/fcp/knowledge/search';
 const CAPTURE_PATH = '/api/external/fcp/knowledge/capture-skill';
+// Proxy mode: skills-sync talks to FCP, which forwards to the same Unroo
+// endpoints using FCP's own service key. This lets a single FCP API key (the
+// one from `claude mcp add`) cover skill sync — no personal Unroo key to
+// obtain, export, or rotate. Mirrors USE_FCP_UNROO_PROXY in the MCP server.
+// See app/api/mcp/unroo/[...path]/route.ts.
+const PROXY_SEARCH_PATH = '/api/mcp/unroo/knowledge/search';
+const PROXY_CAPTURE_PATH = '/api/mcp/unroo/knowledge/capture-skill';
 // Refuse to upload bodies containing strings that look like a baked-in secret.
 // We capture the leading "label" and the candidate "value" separately so we
 // can reject obvious placeholder shapes (env-var names, template variables,
@@ -294,21 +304,20 @@ export function detectSecret(body) {
 export function hashBody(body) {
     return createHash('sha256').update(body, 'utf-8').digest('hex');
 }
-async function postCapture(baseUrl, apiKey, email, payload, fetchImpl) {
-    const res = await fetchImpl(`${baseUrl}${CAPTURE_PATH}`, {
+async function postCapture(ctx, payload) {
+    const res = await ctx.fetchImpl(ctx.captureUrl, {
         method: 'POST',
         headers: {
             'Content-Type': 'application/json',
             Accept: 'application/json',
-            'X-API-Key': apiKey,
-            'X-FCP-User-Email': email,
+            ...ctx.authHeaders,
         },
         body: JSON.stringify(payload),
     });
     const body = await res.text();
     return { ok: res.ok, status: res.status, body };
 }
-async function getSearch(baseUrl, apiKey, email, fetchImpl) {
+async function getSearch(ctx) {
     const all = [];
     let cursor = null;
     // Defensive cap: 50 pages × 100 = 5000 skills, far more than the team will
@@ -317,11 +326,10 @@ async function getSearch(baseUrl, apiKey, email, fetchImpl) {
         const qs = new URLSearchParams({ node_type: 'skill', limit: '100' });
         if (cursor)
             qs.set('cursor', cursor);
-        const res = await fetchImpl(`${baseUrl}${SEARCH_PATH}?${qs.toString()}`, {
+        const res = await ctx.fetchImpl(`${ctx.searchUrl}?${qs.toString()}`, {
             headers: {
                 Accept: 'application/json',
-                'X-API-Key': apiKey,
-                'X-FCP-User-Email': email,
+                ...ctx.authHeaders,
             },
         });
         if (!res.ok) {
@@ -384,7 +392,7 @@ async function pushOnce(ctx, state, result) {
             continue;
         }
         try {
-            const res = await postCapture(ctx.baseUrl, ctx.apiKey, ctx.email, payload, ctx.fetchImpl);
+            const res = await postCapture(ctx, payload);
             if (!res.ok) {
                 ctx.log(`[skills-sync] push ${skill.slug} failed (HTTP ${res.status}): ${res.body.slice(0, 200)}`);
                 continue;
@@ -403,7 +411,7 @@ async function pushOnce(ctx, state, result) {
 async function pullOnce(ctx, state, result) {
     let remoteSkills;
     try {
-        remoteSkills = await getSearch(ctx.baseUrl, ctx.apiKey, ctx.email, ctx.fetchImpl);
+        remoteSkills = await getSearch(ctx);
     }
     catch (err) {
         ctx.log(`[skills-sync] pull failed: ${err.message}`);
@@ -475,18 +483,80 @@ async function pullOnce(ctx, state, result) {
         result.pulled.push(slug);
     }
 }
-// ---------------------------------------------------------------------------
-// Public entrypoints
-// ---------------------------------------------------------------------------
-function makeCtx(opts, dryRunOverride) {
+/**
+ * Decide how skills-sync reaches the knowledge graph.
+ *
+ * Direct mode: a personal UNROO_API_KEY talks straight to Unroo. Used when the
+ * caller explicitly supplies an Unroo key (legacy / power-user setup).
+ *
+ * Proxy mode: the FCP API key talks to FCP, which forwards to the same Unroo
+ * endpoints with its own service key. This is the default — it means a
+ * developer only needs the one FCP key from `claude mcp add`, with no second
+ * key to obtain, export, or rotate. Mirrors USE_FCP_UNROO_PROXY in index.ts.
+ */
+function resolveTransport(opts) {
+    const email = opts.userEmail ?? '';
+    const unrooKey = opts.unrooApiKey ?? '';
+    const fcpToken = opts.fcpApiToken ?? '';
+    // Direct mode wins when a personal Unroo key is explicitly provided.
+    if (unrooKey) {
+        if (!email) {
+            return {
+                configured: false,
+                reason: 'UNROO_API_KEY is set but FCP_USER_EMAIL is not — cannot attribute sync',
+                mode: 'direct', searchUrl: '', captureUrl: '', authHeaders: {},
+            };
+        }
+        const base = opts.unrooApiUrl ?? DEFAULT_UNROO_URL;
+        return {
+            configured: true,
+            mode: 'direct',
+            searchUrl: `${base}${SEARCH_PATH}`,
+            captureUrl: `${base}${CAPTURE_PATH}`,
+            authHeaders: { 'X-API-Key': unrooKey, 'X-FCP-User-Email': email },
+        };
+    }
+    // Proxy mode: the FCP key carries the sync.
+    if (fcpToken) {
+        if (fcpToken === 'dev_bypass') {
+            return {
+                configured: false,
+                reason: 'FCP_API_TOKEN=dev_bypass (local dev) — skill sync skipped',
+                mode: 'proxy', searchUrl: '', captureUrl: '', authHeaders: {},
+            };
+        }
+        const base = opts.fcpApiUrl ?? DEFAULT_FCP_URL;
+        // The FCP proxy reads X-Acting-User-Email for attribution; it honors the
+        // override only when it matches the key owner (or an Auth0 session),
+        // otherwise it falls back to the key owner — itself a real Fruition user,
+        // so the knowledge graph's Fruition-org gate passes either way.
+        const authHeaders = { 'X-API-Key': fcpToken };
+        if (email)
+            authHeaders['X-Acting-User-Email'] = email;
+        return {
+            configured: true,
+            mode: 'proxy',
+            searchUrl: `${base}${PROXY_SEARCH_PATH}`,
+            captureUrl: `${base}${PROXY_CAPTURE_PATH}`,
+            authHeaders,
+        };
+    }
+    return {
+        configured: false,
+        reason: 'neither UNROO_API_KEY nor FCP_API_TOKEN is set — cannot reach the knowledge graph',
+        mode: 'proxy', searchUrl: '', captureUrl: '', authHeaders: {},
+    };
+}
+function makeCtx(opts, dryRunOverride, transport) {
     const skillsDir = opts.skillsDir ?? defaultSkillsDir();
     const stateFile = opts.stateFile ?? defaultStateFile(skillsDir);
     return {
         skillsDir,
         stateFile,
-        baseUrl: opts.unrooApiUrl ?? DEFAULT_UNROO_URL,
-        apiKey: opts.unrooApiKey ?? '',
-        email: opts.userEmail ?? '',
+        mode: transport.mode,
+        searchUrl: transport.searchUrl,
+        captureUrl: transport.captureUrl,
+        authHeaders: transport.authHeaders,
         fetchImpl: opts.fetchImpl ?? fetch,
         log: opts.log ?? ((m) => console.error(m)),
         dryRun: dryRunOverride,
@@ -509,12 +579,13 @@ export async function pushSkills(opts = {}) {
     // Fresh workstation -> force dry-run unless explicitly opted in OR caller
     // passed dryRun:false meaning "I know what I'm doing".
     const dryRun = opts.dryRun !== undefined ? opts.dryRun : state.optedIn !== true;
-    const ctx = makeCtx(opts, dryRun);
+    const transport = resolveTransport(opts);
+    const ctx = makeCtx(opts, dryRun, transport);
     const result = emptyResult(dryRun);
-    if (!ctx.apiKey || !ctx.email) {
-        ctx.log('[skills-sync] skipping push: UNROO_API_KEY or FCP_USER_EMAIL not set');
+    if (!transport.configured) {
+        ctx.log(`[skills-sync] skipping push: ${transport.reason}`);
         result.ok = false;
-        result.reason = 'missing auth';
+        result.reason = transport.reason ?? 'transport not configured';
         return result;
     }
     await pushOnce(ctx, state, result);
@@ -525,12 +596,13 @@ export async function pushSkills(opts = {}) {
 export async function pullSkills(opts = {}) {
     const state = loadState(opts.stateFile ?? defaultStateFile(opts.skillsDir ?? defaultSkillsDir()));
     const dryRun = opts.dryRun !== undefined ? opts.dryRun : state.optedIn !== true;
-    const ctx = makeCtx(opts, dryRun);
+    const transport = resolveTransport(opts);
+    const ctx = makeCtx(opts, dryRun, transport);
     const result = emptyResult(dryRun);
-    if (!ctx.apiKey || !ctx.email) {
-        ctx.log('[skills-sync] skipping pull: UNROO_API_KEY or FCP_USER_EMAIL not set');
+    if (!transport.configured) {
+        ctx.log(`[skills-sync] skipping pull: ${transport.reason}`);
         result.ok = false;
-        result.reason = 'missing auth';
+        result.reason = transport.reason ?? 'transport not configured';
         return result;
     }
     await pullOnce(ctx, state, result);
@@ -541,12 +613,13 @@ export async function pullSkills(opts = {}) {
 export async function syncSkills(opts = {}) {
     const state = loadState(opts.stateFile ?? defaultStateFile(opts.skillsDir ?? defaultSkillsDir()));
     const dryRun = opts.dryRun !== undefined ? opts.dryRun : state.optedIn !== true;
-    const ctx = makeCtx(opts, dryRun);
+    const transport = resolveTransport(opts);
+    const ctx = makeCtx(opts, dryRun, transport);
     const result = emptyResult(dryRun);
-    if (!ctx.apiKey || !ctx.email) {
-        ctx.log('[skills-sync] skipping sync: UNROO_API_KEY or FCP_USER_EMAIL not set');
+    if (!transport.configured) {
+        ctx.log(`[skills-sync] skipping sync: ${transport.reason}`);
         result.ok = false;
-        result.reason = 'missing auth';
+        result.reason = transport.reason ?? 'transport not configured';
         return result;
     }
     // Pull first so a brand-new workstation gets the team library before

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fruition/fcp-mcp-server",
-  "version": "1.18.0",
+  "version": "1.19.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",
@@ -39,7 +39,7 @@
     "@modelcontextprotocol/sdk": "^1.0.0"
   },
   "devDependencies": {
-    "@types/node": "^20.0.0",
+    "@types/node": "^25.6.2",
     "tsx": "^4.7.0",
     "typescript": "^5.3.0"
   }