@taskforcehq/taskforce 0.3.303 → 0.3.304

package/dist/mcp/canonicalAssetHelpers.d.ts

@@ -0,0 +1,70 @@
+import type { WorkspaceAssetEntry, WorkspaceAssetKind, WorkspaceAssetLinkRole, WorkspaceAssetScanStatus, WorkspaceAssetStore } from '../storage/workspaceAssetStore.js';
+import type { McpTaskAttachmentDescriptor, TaskAttachmentRecord } from './taskAttachmentTypes.js';
+export interface CanonicalAssetHelpersDeps {
+    activeWorkspaceId: string;
+    projectRoot: string;
+    basePath: string;
+    workspaceAssetStore: WorkspaceAssetStore | null;
+    objectStorageClient: {
+        getObject(storageKey: string): Promise<{
+            body: Buffer;
+        } | null>;
+    } | null;
+    sanitizeFilenameForPath: (filenameRaw: unknown, fallback?: string) => string;
+    sanitizeDisplayName: (valueRaw: unknown, fallback: string) => string;
+    toPosixPath: (filePath: string) => string;
+    inferMimeTypeFromPath: (filePath: string) => string;
+    inferAssetKind: (filePath: string, mimeType: string) => WorkspaceAssetKind;
+    buildCanonicalWorkspaceAssetRelativePath: (params: {
+        workspaceIdRaw: unknown;
+        kind: WorkspaceAssetKind;
+        filename: string;
+        now?: Date;
+    }) => {
+        relativePath: string;
+        assetId: string;
+    };
+}
+export declare function createCanonicalAssetHelpers(deps: CanonicalAssetHelpersDeps): {
+    normalizeAttachmentStorageKey: (pathValue: unknown, fsPathValue: unknown) => string | null;
+    buildSyntheticAttachmentId: (taskId: string, attachment: TaskAttachmentRecord) => string;
+    getAttachmentAssetRecord: (attachment: TaskAttachmentRecord) => WorkspaceAssetEntry | null;
+    buildAttachmentDownloadUrl: (attachment: McpTaskAttachmentDescriptor) => string;
+    buildDocumentDownloadUrl: (asset: WorkspaceAssetEntry) => string;
+    readCanonicalAttachmentBuffer: (taskId: string, attachment: McpTaskAttachmentDescriptor) => Promise<Buffer>;
+    readCanonicalDocumentBuffer: (asset: WorkspaceAssetEntry) => Promise<Buffer>;
+    toTaskAttachmentRecord: (attachment: string | TaskAttachmentRecord) => TaskAttachmentRecord;
+    resolveAttachmentLogicalFilename: (attachmentInput: string | TaskAttachmentRecord, assetOverride?: ReturnType<(attachment: TaskAttachmentRecord) => WorkspaceAssetEntry | null> | null) => string;
+    resolveCanonicalOverwriteTarget: (task: {
+        id: string;
+        attachments?: Array<string | TaskAttachmentRecord> | null;
+    }, filenameRaw: unknown, describeTaskAttachment: (taskId: string, attachmentInput: string | TaskAttachmentRecord) => McpTaskAttachmentDescriptor) => null | {
+        index: number;
+        attachment: TaskAttachmentRecord;
+        asset: NonNullable<ReturnType<(attachment: TaskAttachmentRecord) => WorkspaceAssetEntry | null>>;
+        descriptor: McpTaskAttachmentDescriptor;
+        relativePath: string;
+        absolutePath: string;
+        logicalFilename: string;
+    };
+    ensureCanonicalTaskAttachment: (relativePathRaw: string, taskIdRaw: string, captionRaw: string | undefined, timestampRaw: string | undefined, role: WorkspaceAssetLinkRole, options?: {
+        originalFilename?: string;
+        logicalName?: string;
+        assetId?: string;
+        documentId?: string | null;
+        createdAt?: string;
+        createdByUserId?: string | null;
+        scanStatus?: WorkspaceAssetScanStatus;
+        scanEngine?: string | null;
+        scanDetails?: string | null;
+    }) => WorkspaceAssetEntry | null;
+    buildCanonicalWorkspaceAssetRelativePath: (params: {
+        workspaceIdRaw: unknown;
+        kind: WorkspaceAssetKind;
+        filename: string;
+        now?: Date;
+    }) => {
+        relativePath: string;
+        assetId: string;
+    };
+};

package/dist/mcp/canonicalAssetHelpers.js

@@ -0,0 +1,259 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { createHash, randomUUID } from 'node:crypto';
+export function createCanonicalAssetHelpers(deps) {
+    const normalizeAttachmentStorageKey = (pathValue, fsPathValue) => {
+        const fsPathRaw = String(fsPathValue || '').trim().replace(/\\/g, '/');
+        if (fsPathRaw) {
+            return fsPathRaw.replace(/^\.taskforce\//, '').trim() || null;
+        }
+        const pathRaw = String(pathValue || '').trim();
+        if (!pathRaw)
+            return null;
+        if (/^https?:\/\//i.test(pathRaw))
+            return pathRaw;
+        if (pathRaw.startsWith('/api/taskforce/context/')) {
+            return decodeURIComponent(pathRaw.slice('/api/taskforce/context/'.length)).trim() || null;
+        }
+        return null;
+    };
+    const buildSyntheticAttachmentId = (taskId, attachment) => {
+        const stableSource = [
+            taskId,
+            String(attachment.path || '').trim(),
+            String(attachment.fsPath || '').trim(),
+            String(attachment.caption || '').trim(),
+        ].join('::');
+        return `attachment-${createHash('sha256').update(stableSource).digest('hex').slice(0, 24)}`;
+    };
+    const getAttachmentAssetRecord = (attachment) => {
+        if (!deps.workspaceAssetStore)
+            return null;
+        const assetId = String(attachment.assetId || '').trim();
+        if (assetId) {
+            const byId = deps.workspaceAssetStore.get(assetId, deps.activeWorkspaceId);
+            if (byId && !byId.deletedAt)
+                return byId;
+        }
+        const storageKey = normalizeAttachmentStorageKey(attachment.path, attachment.fsPath);
+        if (!storageKey || /^https?:\/\//i.test(storageKey))
+            return null;
+        const byStorageKey = deps.workspaceAssetStore.getByStorageKey(storageKey, deps.activeWorkspaceId);
+        if (byStorageKey && !byStorageKey.deletedAt)
+            return byStorageKey;
+        return null;
+    };
+    const buildAttachmentDownloadUrl = (attachment) => {
+        if (attachment.source === 'external')
+            return attachment.path;
+        const safeName = encodeURIComponent(String(attachment.caption || attachment.displayName || attachment.originalFilename || path.basename(attachment.fsPath || attachment.path) || 'download').trim());
+        const joiner = attachment.path.includes('?') ? '&' : '?';
+        return `${attachment.path}${joiner}download=1&filename=${safeName}`;
+    };
+    const buildDocumentDownloadUrl = (asset) => {
+        const safeName = deps.sanitizeFilenameForPath(asset.originalFilename
+            || asset.logicalName
+            || path.basename(String(asset.storageKey || '').trim())
+            || 'document.txt', 'document.txt');
+        return `/api/taskforce/documents/${encodeURIComponent(String(asset.assetId || '').trim())}/content?download=1&filename=${encodeURIComponent(safeName)}`;
+    };
+    const describeAttachmentStorageContext = (attachment, storageKey) => {
+        const parts = [
+            `attachmentId=${attachment.attachmentId}`,
+            `assetId=${String(attachment.assetId || 'unknown')}`,
+            `storageKey=${storageKey || 'unknown'}`
+        ];
+        return parts.join(', ');
+    };
+    const readCanonicalAttachmentBuffer = async (taskId, attachment) => {
+        const assetId = String(attachment.assetId || '').trim();
+        const asset = assetId && deps.workspaceAssetStore
+            ? deps.workspaceAssetStore.get(assetId, deps.activeWorkspaceId)
+            : null;
+        if (!asset || asset.deletedAt) {
+            throw new Error(`Attachment ${attachment.attachmentId} not found on task ${taskId}`);
+        }
+        if (asset.scanStatus === 'infected') {
+            throw new Error('Attachment is quarantined');
+        }
+        if (asset.scanStatus === 'pending') {
+            throw new Error('Attachment scan pending');
+        }
+        if (asset.storageProvider === 'r2') {
+            const attachmentContext = describeAttachmentStorageContext(attachment, asset.storageKey);
+            if (!deps.objectStorageClient) {
+                throw new Error(`Attachment read failed from R2 because object storage is not configured in this MCP runtime (${attachmentContext})`);
+            }
+            let object;
+            try {
+                object = await deps.objectStorageClient.getObject(asset.storageKey);
+            }
+            catch (error) {
+                const message = error instanceof Error ? String(error.message || '').trim() : String(error || '').trim();
+                throw new Error(`Attachment read failed from R2 (${attachmentContext}): ${message || 'Unknown object storage error'}`);
+            }
+            if (!object) {
+                throw new Error(`Attachment ${attachment.attachmentId} not found on task ${taskId}`);
+            }
+            return object.body;
+        }
+        const resolvedPath = path.resolve(deps.basePath, asset.storageKey);
+        if (!resolvedPath.startsWith(path.resolve(deps.basePath))) {
+            throw new Error(`Attachment ${attachment.attachmentId} not found on task ${taskId}`);
+        }
+        if (!fs.existsSync(resolvedPath) || !fs.statSync(resolvedPath).isFile()) {
+            throw new Error(`Attachment ${attachment.attachmentId} not found on task ${taskId}`);
+        }
+        return fs.readFileSync(resolvedPath);
+    };
+    const readCanonicalDocumentBuffer = async (asset) => {
+        if (asset.deletedAt || asset.kind !== 'document') {
+            throw new Error(`Document ${asset.assetId} not found in workspace ${deps.activeWorkspaceId}.`);
+        }
+        if (asset.scanStatus === 'infected') {
+            throw new Error('Document is quarantined');
+        }
+        if (asset.scanStatus === 'pending') {
+            throw new Error('Document scan pending');
+        }
+        if (asset.storageProvider === 'r2') {
+            if (!deps.objectStorageClient) {
+                throw new Error(`Document read failed from R2 because object storage is not configured in this MCP runtime (assetId=${asset.assetId}, storageKey=${asset.storageKey || 'unknown'})`);
+            }
+            let object;
+            try {
+                object = await deps.objectStorageClient.getObject(asset.storageKey);
+            }
+            catch (error) {
+                const message = error instanceof Error ? String(error.message || '').trim() : String(error || '').trim();
+                throw new Error(`Document read failed from R2 (assetId=${asset.assetId}, storageKey=${asset.storageKey || 'unknown'}): ${message || 'Unknown object storage error'}`);
+            }
+            if (!object) {
+                throw new Error(`Document ${asset.assetId} not found in workspace ${deps.activeWorkspaceId}.`);
+            }
+            return object.body;
+        }
+        const resolvedPath = path.resolve(deps.basePath, asset.storageKey);
+        if (!resolvedPath.startsWith(path.resolve(deps.basePath))) {
+            throw new Error(`Document ${asset.assetId} not found in workspace ${deps.activeWorkspaceId}.`);
+        }
+        if (!fs.existsSync(resolvedPath) || !fs.statSync(resolvedPath).isFile()) {
+            throw new Error(`Document ${asset.assetId} not found in workspace ${deps.activeWorkspaceId}.`);
+        }
+        return fs.readFileSync(resolvedPath);
+    };
+    const toTaskAttachmentRecord = (attachment) => {
+        if (typeof attachment === 'string') {
+            return { path: attachment };
+        }
+        return attachment;
+    };
+    const resolveAttachmentLogicalFilename = (attachmentInput, assetOverride) => {
+        const attachment = toTaskAttachmentRecord(attachmentInput);
+        const asset = assetOverride ?? getAttachmentAssetRecord(attachment);
+        const candidate = String(attachment.originalFilename
+            || asset?.originalFilename
+            || attachment.displayName
+            || asset?.logicalName
+            || '').trim();
+        if (candidate) {
+            return deps.sanitizeFilenameForPath(candidate);
+        }
+        const storageKey = normalizeAttachmentStorageKey(attachment.path, attachment.fsPath);
+        return deps.sanitizeFilenameForPath(storageKey ? path.basename(storageKey) : '', 'attachment.txt');
+    };
+    const resolveCanonicalOverwriteTarget = (task, filenameRaw, describeTaskAttachment) => {
+        const requestedFilename = deps.sanitizeFilenameForPath(filenameRaw);
+        const existingAttachments = Array.isArray(task.attachments) ? task.attachments : [];
+        for (let index = 0; index < existingAttachments.length; index++) {
+            const attachment = toTaskAttachmentRecord(existingAttachments[index]);
+            const asset = getAttachmentAssetRecord(attachment);
+            if (!asset || asset.deletedAt || asset.storageProvider === 'external')
+                continue;
+            const descriptor = describeTaskAttachment(task.id, attachment);
+            if (descriptor.source !== 'canonical')
+                continue;
+            const logicalFilename = resolveAttachmentLogicalFilename(attachment, asset);
+            if (logicalFilename !== requestedFilename)
+                continue;
+            const relativePath = deps.toPosixPath(path.relative(deps.projectRoot, path.resolve(deps.basePath, asset.storageKey)));
+            return {
+                index,
+                attachment,
+                asset,
+                descriptor,
+                relativePath,
+                absolutePath: path.resolve(deps.basePath, asset.storageKey),
+                logicalFilename,
+            };
+        }
+        return null;
+    };
+    const ensureCanonicalTaskAttachment = (relativePathRaw, taskIdRaw, captionRaw, timestampRaw, role, options) => {
+        if (!deps.workspaceAssetStore)
+            return null;
+        const relativePath = String(relativePathRaw || '').trim();
+        const taskId = String(taskIdRaw || '').trim();
+        if (!relativePath || !taskId)
+            return null;
+        const absolutePath = path.resolve(deps.projectRoot, relativePath);
+        if (!fs.existsSync(absolutePath) || !fs.statSync(absolutePath).isFile())
+            return null;
+        const storageKey = relativePath.replace(/^\.taskforce\//, '').trim() || relativePath;
+        const buffer = fs.readFileSync(absolutePath);
+        const stats = fs.statSync(absolutePath);
+        const mimeType = deps.inferMimeTypeFromPath(relativePath);
+        const kind = deps.inferAssetKind(relativePath, mimeType);
+        const timestamp = String(timestampRaw || new Date().toISOString()).trim() || new Date().toISOString();
+        const existing = deps.workspaceAssetStore.getByStorageKey(storageKey, deps.activeWorkspaceId);
+        const originalFilename = deps.sanitizeFilenameForPath(options?.originalFilename || existing?.originalFilename || path.basename(relativePath));
+        const logicalName = deps.sanitizeDisplayName(options?.logicalName || existing?.logicalName || originalFilename, originalFilename);
+        const asset = deps.workspaceAssetStore.upsertAsset({
+            assetId: options?.assetId || existing?.assetId || `asset-${randomUUID().replace(/-/g, '')}`,
+            workspaceId: deps.activeWorkspaceId,
+            kind,
+            logicalName,
+            originalFilename,
+            mimeType,
+            storageProvider: 'local',
+            storageKey,
+            contentSha256: createHash('sha256').update(buffer).digest('hex'),
+            sizeBytes: stats.size,
+            documentId: kind === 'document' ? (options?.documentId || existing?.documentId || `doc-${randomUUID().replace(/-/g, '')}`) : null,
+            version: kind === 'document' ? Math.max(1, Number(existing?.version || 0) + 1) : null,
+            isLatest: true,
+            scanStatus: options?.scanStatus || existing?.scanStatus || 'clean',
+            scanEngine: options?.scanEngine !== undefined ? options.scanEngine : (existing?.scanEngine || null),
+            scanDetails: options?.scanDetails !== undefined ? options.scanDetails : (existing?.scanDetails || null),
+            createdByUserId: options?.createdByUserId !== undefined ? options.createdByUserId : (existing?.createdByUserId || null),
+            createdAt: options?.createdAt || existing?.createdAt || timestamp,
+            updatedAt: timestamp,
+            deletedAt: null,
+            purgeAfter: null
+        });
+        deps.workspaceAssetStore.upsertLink({
+            workspaceId: deps.activeWorkspaceId,
+            assetId: asset.assetId,
+            taskId,
+            role,
+            displayName: kind === 'document' ? null : (captionRaw || null),
+            updatedAt: timestamp,
+            deletedAt: null
+        });
+        return asset;
+    };
+    return {
+        normalizeAttachmentStorageKey,
+        buildSyntheticAttachmentId,
+        getAttachmentAssetRecord,
+        buildAttachmentDownloadUrl,
+        buildDocumentDownloadUrl,
+        readCanonicalAttachmentBuffer,
+        readCanonicalDocumentBuffer,
+        toTaskAttachmentRecord,
+        resolveAttachmentLogicalFilename,
+        resolveCanonicalOverwriteTarget,
+        ensureCanonicalTaskAttachment,
+        buildCanonicalWorkspaceAssetRelativePath: deps.buildCanonicalWorkspaceAssetRelativePath,
+    };
+}

package/dist/mcp/clientIntegrations.d.ts

@@ -1,5 +1,5 @@
 import { type AiProfileBootstrapConfig } from './aiProfileBootstrap.js';
-export type McpClientId = 'cursor' | 'cline' | 'vscode' | 'windsurf' | 'antigravity' | 'openclaw' | 'codex' | 'claude-code' | 'gemini-cli' | 'claude-desktop' | 'chatgpt-desktop';
+export type McpClientId = 'general' | 'cursor' | 'cline' | 'vscode' | 'windsurf' | 'antigravity' | 'openclaw' | 'codex' | 'claude-code' | 'gemini-cli' | 'claude-desktop' | 'chatgpt-desktop';
 export interface McpClientOption {
     id: McpClientId;
     label: string;
@@ -11,6 +11,16 @@ export interface BuildCloudMcpClientConfigInput extends AiProfileBootstrapConfig
     tokenValue: string;
     serverId: string;
 }
+export interface LocalMcpServerConfig {
+    command: string;
+    args: string[];
+    env?: Record<string, string>;
+}
+export interface BuildLocalMcpClientConfigInput {
+    clientId: McpClientId;
+    serverId: string;
+    serverConfig: LocalMcpServerConfig;
+}
 export interface CloudMcpClientIntegration {
     clientId: McpClientId;
     kind: 'json' | 'text';
@@ -25,3 +35,4 @@ export declare const MCP_CLIENT_OPTIONS: McpClientOption[];
 export declare function sanitizeMcpId(value: string, fallback: string): string;
 export declare function buildCloudMcpServerId(workspaceName?: string | null, projectName?: string | null): string;
 export declare function buildCloudMcpClientIntegration(input: BuildCloudMcpClientConfigInput): CloudMcpClientIntegration;
+export declare function buildLocalMcpClientIntegration(input: BuildLocalMcpClientConfigInput): CloudMcpClientIntegration;

package/dist/mcp/clientIntegrations.js

@@ -1,14 +1,15 @@
 import { buildAiProfileBootstrapHeaders } from './aiProfileBootstrap.js';
 export const MCP_CLIENT_OPTIONS = [
-    { id: 'cursor', label: 'Cursor' },
-    { id: 'cline', label: 'Cline' },
-    { id: 'vscode', label: 'VS Code / Copilot' },
-    { id: 'windsurf', label: 'Windsurf' },
+    { id: 'general', label: 'General' },
     { id: 'antigravity', label: 'Antigravity' },
-    { id: 'openclaw', label: 'OpenClaw' },
-    { id: 'codex', label: 'Codex' },
     { id: 'claude-code', label: 'Claude Code CLI' },
+    { id: 'cline', label: 'Cline' },
+    { id: 'codex', label: 'Codex' },
+    { id: 'cursor', label: 'Cursor' },
     { id: 'gemini-cli', label: 'Gemini CLI' },
+    { id: 'openclaw', label: 'OpenClaw' },
+    { id: 'vscode', label: 'VS Code / Copilot' },
+    { id: 'windsurf', label: 'Windsurf' },
 ];
 export function sanitizeMcpId(value, fallback) {
     const normalized = String(value || '')
@@ -43,6 +44,27 @@ function buildConfigurationInstruction(baseInstruction, options) {
         return baseInstruction;
     return buildAutomationBootstrapInstruction(`${baseInstruction} Use the generated config exactly as shown.`);
 }
+function buildLocalConfigurationInstruction(baseInstruction) {
+    return `${baseInstruction} Use the generated config exactly as shown. No token is required for local stdio MCP.`;
+}
+function formatTomlString(value) {
+    return JSON.stringify(value);
+}
+function formatTomlArray(values) {
+    return `[${values.map((value) => formatTomlString(value)).join(', ')}]`;
+}
+function buildTomlEnvAssignment(env) {
+    if (!env || Object.keys(env).length === 0)
+        return [];
+    return [
+        `env = { ${Object.entries(env).map(([key, value]) => `${key} = ${formatTomlString(value)}`).join(', ')} }`
+    ];
+}
+function shellEscapeArg(value) {
+    if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(value))
+        return value;
+    return `'${value.replace(/'/g, `'\"'\"'`)}'`;
+}
 export function buildCloudMcpClientIntegration(input) {
     const { clientId, endpoint, tokenValue, serverId } = input;
     const headers = buildCloudMcpHeaders(input);
@@ -52,6 +74,18 @@ export function buildCloudMcpClientIntegration(input) {
         .map(([key, value]) => ` --header "${key}: ${value}"`)
         .join('');
     switch (clientId) {
+        case 'general':
+            return {
+                clientId,
+                kind: 'json',
+                rootKey: 'mcpServers',
+                serverConfig: {
+                    url: endpoint,
+                    headers
+                },
+                instructionLabel: 'General MCP Configuration Instructions',
+                instructionText: buildConfigurationInstruction('Add this server to your MCP client using its standard remote HTTP configuration format.')
+            };
         case 'cursor':
             return {
                 clientId,
@@ -178,3 +212,124 @@ export function buildCloudMcpClientIntegration(input) {
         }
     }
 }
+export function buildLocalMcpClientIntegration(input) {
+    const { clientId, serverId, serverConfig } = input;
+    const baseStdioConfig = {
+        command: serverConfig.command,
+        args: serverConfig.args,
+        ...(serverConfig.env && Object.keys(serverConfig.env).length > 0 ? { env: serverConfig.env } : {})
+    };
+    const claudeEnvFlags = Object.entries(serverConfig.env || {})
+        .map(([key, value]) => ` --env ${shellEscapeArg(`${key}=${value}`)}`)
+        .join('');
+    const claudeArgs = [serverConfig.command, ...serverConfig.args].map((value) => shellEscapeArg(value)).join(' ');
+    switch (clientId) {
+        case 'general':
+            return {
+                clientId,
+                kind: 'json',
+                rootKey: 'mcpServers',
+                serverConfig: baseStdioConfig,
+                instructionLabel: 'General MCP Configuration Instructions',
+                instructionText: buildLocalConfigurationInstruction('Add this server to your MCP client using its standard local stdio configuration format.')
+            };
+        case 'cursor':
+            return {
+                clientId,
+                kind: 'json',
+                rootKey: 'mcpServers',
+                serverConfig: baseStdioConfig,
+                instructionLabel: 'Cursor Configuration Instructions',
+                instructionText: buildLocalConfigurationInstruction('Open Cursor settings, find MCP servers, and paste this local stdio config.')
+            };
+        case 'cline':
+            return {
+                clientId,
+                kind: 'json',
+                rootKey: 'mcpServers',
+                serverConfig: baseStdioConfig,
+                instructionLabel: 'Cline Configuration Instructions',
+                instructionText: buildLocalConfigurationInstruction('Open Cline MCP Servers and paste this local stdio server config.')
+            };
+        case 'vscode':
+            return {
+                clientId,
+                kind: 'json',
+                rootKey: 'servers',
+                serverConfig: {
+                    type: 'stdio',
+                    ...baseStdioConfig
+                },
+                instructionLabel: 'VS Code Configuration Instructions',
+                instructionText: buildLocalConfigurationInstruction('Open .vscode/mcp.json or MCP: Open User Configuration and add this server under the servers object.')
+            };
+        case 'windsurf':
+            return {
+                clientId,
+                kind: 'json',
+                rootKey: 'mcpServers',
+                serverConfig: baseStdioConfig,
+                instructionLabel: 'Windsurf Configuration Instructions',
+                instructionText: buildLocalConfigurationInstruction('Open Windsurf MCP settings and paste this local stdio config.')
+            };
+        case 'antigravity':
+            return {
+                clientId,
+                kind: 'json',
+                rootKey: 'mcpServers',
+                serverConfig: baseStdioConfig,
+                instructionLabel: 'Antigravity Configuration Instructions',
+                instructionText: buildLocalConfigurationInstruction('Open Antigravity MCP settings, view the raw config, and paste this local stdio configuration.')
+            };
+        case 'openclaw':
+            return {
+                clientId,
+                kind: 'json',
+                rootKey: 'servers',
+                wrapperKeys: ['mcp'],
+                serverConfig: {
+                    transport: 'stdio',
+                    ...baseStdioConfig
+                },
+                instructionLabel: 'OpenClaw Configuration Instructions',
+                instructionText: buildLocalConfigurationInstruction('Open ~/.openclaw/openclaw.json and add this local stdio server under mcp.servers.')
+            };
+        case 'codex':
+            return {
+                clientId,
+                kind: 'text',
+                renderedText: [
+                    `[mcp_servers.${serverId}]`,
+                    `command = ${formatTomlString(serverConfig.command)}`,
+                    `args = ${formatTomlArray(serverConfig.args)}`,
+                    ...buildTomlEnvAssignment(serverConfig.env)
+                ].join('\n'),
+                instructionLabel: 'Codex Configuration Instructions',
+                instructionText: buildLocalConfigurationInstruction('Open ~/.codex/config.toml and add this local MCP entry.')
+            };
+        case 'claude-code':
+            return {
+                clientId,
+                kind: 'text',
+                renderedText: `claude mcp add ${serverId}${claudeEnvFlags} -- ${claudeArgs}`,
+                instructionLabel: 'Claude Code Configuration Instructions',
+                instructionText: buildLocalConfigurationInstruction('Run this Claude Code command in your terminal to add the local Taskforce MCP server.')
+            };
+        case 'gemini-cli':
+            return {
+                clientId,
+                kind: 'json',
+                rootKey: 'mcpServers',
+                serverConfig: baseStdioConfig,
+                instructionLabel: 'Gemini CLI Configuration Instructions',
+                instructionText: buildLocalConfigurationInstruction('Open ~/.gemini/settings.json and add this local MCP server under mcpServers.')
+            };
+        case 'claude-desktop':
+        case 'chatgpt-desktop':
+            throw new Error(`Unsupported local MCP client: ${clientId}`);
+        default: {
+            const exhaustiveCheck = clientId;
+            throw new Error(`Unsupported local MCP client: ${exhaustiveCheck}`);
+        }
+    }
+}

package/dist/mcp/clientIntegrations.test.js

@@ -1,13 +1,40 @@
 import { describe, expect, it } from 'vitest';
-import { MCP_CLIENT_OPTIONS, buildCloudMcpClientIntegration, buildCloudMcpServerId, } from './clientIntegrations';
+import { MCP_CLIENT_OPTIONS, buildCloudMcpClientIntegration, buildLocalMcpClientIntegration, buildCloudMcpServerId, } from './clientIntegrations';
 describe('clientIntegrations', () => {
     it('builds a readable cloud MCP server id from workspace name', () => {
         expect(buildCloudMcpServerId('Workspace Alpha', null)).toBe('taskforce-workspace-alpha');
         expect(buildCloudMcpServerId('A Workspace Name That Is Way Too Long For Comfort', null)).toBe('taskforce-a-workspace-name-that-is');
     });
-    it('keeps enabled connector clients available in the selector', () => {
-        expect(MCP_CLIENT_OPTIONS.map((option) => option.id)).toEqual(expect.arrayContaining(['openclaw', 'codex', 'gemini-cli']));
-        expect(MCP_CLIENT_OPTIONS.map((option) => option.id)).not.toEqual(expect.arrayContaining(['chatgpt-desktop', 'claude-desktop']));
+    it('keeps enabled connector clients available in the selector in the intended order', () => {
+        expect(MCP_CLIENT_OPTIONS.map((option) => option.id)).toEqual([
+            'general',
+            'antigravity',
+            'claude-code',
+            'cline',
+            'codex',
+            'cursor',
+            'gemini-cli',
+            'openclaw',
+            'vscode',
+            'windsurf'
+        ]);
+    });
+    it('builds generic cloud MCP config for the General option', () => {
+        const integration = buildCloudMcpClientIntegration({
+            clientId: 'general',
+            endpoint: 'https://performance-app.taskforcehq.ai/mcp',
+            tokenValue: '<<GENERATE_TOKEN>>',
+            serverId: 'taskforce-workspace-alpha',
+        });
+        expect(integration.kind).toBe('json');
+        expect(integration.rootKey).toBe('mcpServers');
+        expect(integration.instructionLabel).toBe('General MCP Configuration Instructions');
+        expect(integration.serverConfig).toEqual({
+            url: 'https://performance-app.taskforcehq.ai/mcp',
+            headers: {
+                Authorization: 'Bearer <<GENERATE_TOKEN>>'
+            }
+        });
     });
     it('builds JSON config for VS Code using the servers root', () => {
         const integration = buildCloudMcpClientIntegration({
@@ -133,4 +160,49 @@ describe('clientIntegrations', () => {
         expect(integration.kind).toBe('text');
         expect(integration.renderedText).toBe('gemini mcp add taskforce-workspace-alpha https://performance-app.taskforcehq.ai/mcp --transport http --header "Authorization: Bearer <<GENERATE_TOKEN>>"');
     });
+    it('builds local Codex config without token headers', () => {
+        const integration = buildLocalMcpClientIntegration({
+            clientId: 'codex',
+            serverId: 'taskforce-workspace-alpha',
+            serverConfig: {
+                command: 'taskforce',
+                args: ['mcp', '/Users/rossburke/projects/taskforce'],
+                env: {
+                    TASKFORCE_TENANT_ID: 'tenant-alpha',
+                    TASKFORCE_WORKSPACE_ID: 'workspace-alpha'
+                }
+            }
+        });
+        expect(integration.kind).toBe('text');
+        expect(integration.renderedText).toContain('[mcp_servers.taskforce-workspace-alpha]');
+        expect(integration.renderedText).toContain('command = "taskforce"');
+        expect(integration.renderedText).toContain('args = ["mcp", "/Users/rossburke/projects/taskforce"]');
+        expect(integration.renderedText).toContain('TASKFORCE_TENANT_ID = "tenant-alpha"');
+        expect(integration.renderedText).not.toContain('Authorization');
+    });
+    it('builds local VS Code config with stdio transport', () => {
+        const integration = buildLocalMcpClientIntegration({
+            clientId: 'vscode',
+            serverId: 'taskforce-workspace-alpha',
+            serverConfig: {
+                command: 'taskforce',
+                args: ['mcp', '/Users/rossburke/projects/taskforce'],
+                env: {
+                    TASKFORCE_TENANT_ID: 'tenant-alpha',
+                    TASKFORCE_WORKSPACE_ID: 'workspace-alpha'
+                }
+            }
+        });
+        expect(integration.kind).toBe('json');
+        expect(integration.rootKey).toBe('servers');
+        expect(integration.serverConfig).toEqual({
+            type: 'stdio',
+            command: 'taskforce',
+            args: ['mcp', '/Users/rossburke/projects/taskforce'],
+            env: {
+                TASKFORCE_TENANT_ID: 'tenant-alpha',
+                TASKFORCE_WORKSPACE_ID: 'workspace-alpha'
+            }
+        });
+    });
 });