@taskforcehq/taskforce 0.3.303 → 0.3.305

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'
+            }
+        });
+    });
 });

package/dist/mcp/collaborationRegistrar.d.ts

@@ -0,0 +1,2 @@
+import type { DomainToolExecutor, RegisterMcpTool } from './toolCatalog.js';
+export declare function registerCollaborationTools(registerTool: RegisterMcpTool, executeTool: DomainToolExecutor): void;

package/dist/mcp/collaborationRegistrar.js

@@ -0,0 +1,71 @@
+import { AI_PROFILE_SURFACE_TYPES } from '../shared/aiProfileSurfaceType.js';
+import { bindDomainTool } from './toolCatalog.js';
+function stringProperty(description) {
+    return { type: 'string', description };
+}
+export function registerCollaborationTools(registerTool, executeTool) {
+    const register = (name, buildDescriptor) => {
+        registerTool({
+            name,
+            buildDescriptor: (context) => {
+                const descriptor = buildDescriptor(context);
+                return {
+                    name,
+                    description: descriptor.description,
+                    inputSchema: {
+                        type: 'object',
+                        properties: descriptor.inputSchema.properties,
+                        ...(descriptor.inputSchema.required ? { required: descriptor.inputSchema.required } : {}),
+                    },
+                };
+            },
+            handler: bindDomainTool(executeTool, name),
+        });
+    };
+    register('list_assignees', (context) => ({
+        description: context.describeTool('List eligible assignees for the active workspace. Returns human workspace members and AI profiles that can own tasks. Use this before create_task, update_task, assign_task, or bulk_assign_tasks when you need a valid assignee ID.'),
+        inputSchema: { properties: {} },
+    }));
+    register('get_current_profile', (context) => ({
+        description: context.describeTool('Inspect the effective AI profile for this session. Use this when an agent needs to know its current profile id before filtering for tasks assigned to itself. If no profile is currently bound, this tool explains how to bootstrap with resolve_profile. You may also pass profileToken to inspect a stateless AI profile without mutating session state. The response includes the profileToken so automations can persist it after first bootstrap.'),
+        inputSchema: {
+            properties: {
+                profileToken: stringProperty('Optional AI profile token to inspect when no profile is currently bound in session state.'),
+            },
+        },
+    }));
+    register('resolve_profile', (context) => ({
+        description: context.describeTool('Resolve or create the current AI collaborator profile for this workspace. On first bootstrap, omit profileToken and Taskforce will create a named AI profile, issue a stable profileToken, and return the profile id to use in assignee, createdBy, and comment author fields on later calls. When a valid profileToken is provided, Taskforce resolves the existing profile and updates any supplied presentation fields such as name, icon, color, description, role, provider, model, and surfaceType. Update semantics: omitted optional fields leave existing stored values unchanged. For description, role, provider, and model, empty strings are ignored rather than clearing. For surfaceType, null or an empty string clears the stored value; valid enum values replace it.'),
+        inputSchema: {
+            properties: {
+                name: stringProperty('Display name for the AI collaborator.'),
+                icon: stringProperty('Optional icon name or emoji saved with the AI profile. Omit to leave unchanged when profileToken is provided.'),
+                color: stringProperty('Optional profile color saved with the AI profile. Omit to leave unchanged when profileToken is provided.'),
+                description: stringProperty('Optional short description stored on the AI profile. Omit to leave unchanged when profileToken is provided.'),
+                role: stringProperty('Optional role label stored on the AI profile. Omit to leave unchanged when profileToken is provided.'),
+                provider: stringProperty('Optional provider name stored as secondary diagnostic metadata on the AI profile. Omit to leave unchanged when profileToken is provided.'),
+                model: stringProperty('Optional model name stored as secondary diagnostic metadata on the AI profile. Omit to leave unchanged when profileToken is provided.'),
+                surfaceType: {
+                    anyOf: [
+                        { type: 'string', enum: [...AI_PROFILE_SURFACE_TYPES] },
+                        { type: 'null' },
+                    ],
+                    description: 'Optional self-declared AI surface type. Use agent for a persistent named AI collaborator in Taskforce, coding_tool for the coding surface or terminal tool itself, chat_app for a conversational app identity, ide for an IDE-native copilot identity, and other only when none of those fit. If you are unsure and you are registering a named collaborator such as a teammate-style AI persona, choose agent. Omit to leave unchanged; pass null or an empty string to clear.',
+                },
+                profileToken: stringProperty('Previously issued Taskforce profile token. When provided, Taskforce resolves the existing profile instead of creating a new one, and applies any supplied presentation field updates to that profile.'),
+            },
+            required: ['name'],
+        },
+    }));
+    register('add_comment', (context) => ({
+        description: context.describeTool('Add a comment to a task. Use this for agent progress notes, handoff summaries, decision logs, and audit trails. Comments are visible in the task timeline.'),
+        inputSchema: {
+            properties: {
+                id: stringProperty('Task ID or task reference such as T-123.'),
+                text: stringProperty('Comment text.'),
+                author: stringProperty('Comment author identity. Use your AI profile id from resolve_profile, or use user for human-authored comments.'),
+            },
+            required: ['id', 'text', 'author'],
+        },
+    }));
+}

package/dist/mcp/documentAssetRegistrar.d.ts

@@ -0,0 +1,2 @@
+import type { DomainToolExecutor, RegisterMcpTool } from './toolCatalog.js';
+export declare function registerDocumentAssetTools(registerTool: RegisterMcpTool, executeTool: DomainToolExecutor): void;