@fruition/fcp-mcp-server 1.18.0 → 1.20.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,151 @@ 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_update_client_profile: '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_list_clients: 'viewer',
+    fcp_get_client: '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
@@ -372,6 +517,35 @@ class FCPClient {
     async getLocalSetupGuide(siteId) {
         return this.fetch(`/api/sites/${siteId}/local-setup`);
     }
+    // WebOps Client Directory
+    async listClients(filters) {
+        const params = new URLSearchParams();
+        if (filters?.q)
+            params.set('q', filters.q);
+        if (filters?.webops_lead)
+            params.set('webops_lead', filters.webops_lead);
+        if (filters?.contract_type)
+            params.set('contract_type', filters.contract_type);
+        if (filters?.tier)
+            params.set('tier', filters.tier);
+        if (filters?.marketing !== undefined)
+            params.set('marketing', String(filters.marketing));
+        if (filters?.status)
+            params.set('status', filters.status);
+        if (filters?.limit)
+            params.set('limit', String(filters.limit));
+        const qs = params.toString();
+        return this.fetch(`/api/clients${qs ? `?${qs}` : ''}`);
+    }
+    async getClient(accountId) {
+        return this.fetch(`/api/clients/${accountId}/profile`);
+    }
+    async updateClientProfile(accountId, updates) {
+        return this.fetch(`/api/clients/${accountId}/profile`, {
+            method: 'PUT',
+            body: JSON.stringify(updates),
+        });
+    }
     // Shield Domain Management
     async shieldListDomains(filters) {
         const params = new URLSearchParams();
@@ -2313,6 +2487,89 @@ const TOOLS = [
             required: ['website_id'],
         },
     },
+    // WebOps Client Directory
+    {
+        name: 'fcp_list_clients',
+        description: 'List client accounts from the WebOps Client Directory with their WebOps profile (lead, sponsor, contract type, service tier, site count). Use to answer "who manages X", "list all retainer clients", "which clients does Janine lead".',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                q: { type: 'string', description: 'Search by client/account name (substring match)' },
+                webops_lead: { type: 'string', description: 'Filter by WebOps lead (e.g. "Janine", "Mike")' },
+                contract_type: {
+                    type: 'string',
+                    description: 'Filter by contract type: tm, block, tm_or_block, retainer, pro_bono, other',
+                },
+                tier: {
+                    type: 'string',
+                    description: 'Filter by account service tier: standard, frucare, ada, redteam',
+                },
+                marketing: {
+                    type: 'boolean',
+                    description: 'Filter to marketing clients only (true) or non-marketing (false)',
+                },
+                status: {
+                    type: 'string',
+                    description: 'Profile status: active (default), deactivated, or all',
+                },
+                limit: { type: 'number', description: 'Max rows to return (default 300)' },
+            },
+        },
+    },
+    {
+        name: 'fcp_get_client',
+        description: "Get the full WebOps profile for one client account: relationship/commercial data, primary contacts, and all of the account's websites with detected analytics (GA4/GTM/Clarity/Bugherd).",
+        inputSchema: {
+            type: 'object',
+            properties: {
+                account_id: { type: 'number', description: 'The account ID (required)' },
+            },
+            required: ['account_id'],
+        },
+    },
+    {
+        name: 'fcp_update_client_profile',
+        description: "Update business/relationship fields on a client's WebOps profile. Technical facts (CMS, hosting, FruCare) are NOT editable here -- FCP detects/owns those. Only provided fields change.",
+        inputSchema: {
+            type: 'object',
+            properties: {
+                account_id: { type: 'number', description: 'The account ID to update (required)' },
+                webops_lead: { type: 'string', description: 'Canonical WebOps lead' },
+                relationship_sponsor: { type: 'string', description: 'Relationship sponsor' },
+                contract_type: {
+                    type: 'string',
+                    description: 'tm, block, tm_or_block, retainer, pro_bono, none, other',
+                },
+                contract_rate: { type: 'string', description: 'Freeform rate (e.g. "$155/hour")' },
+                contract_notes: { type: 'string', description: 'Contract notes' },
+                is_marketing_client: { type: 'boolean', description: 'Whether this is a marketing client' },
+                comms_platform: {
+                    type: 'string',
+                    description: 'Client collaboration platform (Google / MS Teams)',
+                },
+                client_time_zone: { type: 'string', description: 'Client time zone' },
+                meeting_cadence: { type: 'string', description: 'Meeting cadence' },
+                meeting_attendees: { type: 'string', description: 'Meeting attendees' },
+                last_client_contact: { type: 'string', description: 'Last contact note' },
+                looker_studio_url: { type: 'string', description: 'Looker Studio report URL' },
+                shared_drive_url: { type: 'string', description: 'Shared drive URL' },
+                client_assets_url: { type: 'string', description: 'Client assets URL' },
+                unroo_board_url: { type: 'string', description: 'Unroo board URL' },
+                client_goals: { type: 'string', description: 'Client goals & focus areas' },
+                what_you_need_to_know: {
+                    type: 'string',
+                    description: 'Key things to know about this client',
+                },
+                general_notes: { type: 'string', description: 'General notes' },
+                status: { type: 'string', description: 'active or deactivated' },
+                mark_reviewed: {
+                    type: 'boolean',
+                    description: 'Set true to stamp last_reviewed_at = now (confirms the profile is accurate)',
+                },
+            },
+            required: ['account_id'],
+        },
+    },
     // Fruition Shield - Shared WAF Gateway
     {
         name: 'fcp_shield_list_domains',
@@ -2805,6 +3062,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);
@@ -3107,6 +3368,28 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     ],
                 };
             }
+            // WebOps Client Directory Handlers
+            case 'fcp_list_clients': {
+                const filters = args;
+                const result = await client.listClients(filters);
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            case 'fcp_get_client': {
+                const { account_id } = args;
+                const result = await client.getClient(account_id);
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            case 'fcp_update_client_profile': {
+                const { account_id, ...updates } = args;
+                const result = await client.updateClientProfile(account_id, updates);
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                };
+            }
             // Launch CRUD Handlers
             case 'fcp_create_launch': {
                 const { name, platform, launch_type, target_launch_date, ...rest } = args;
@@ -4049,10 +4332,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.20.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"
   }