@copado/agentia-cli 1.0.0 → 1.2.0

package/dist/lib/mcp/pipeline-automation-quality-tools.js

@@ -0,0 +1,452 @@
+import { z } from 'zod';
+import { fetchExtensionConfiguration, fetchExtensionConfigurations } from '../extension-configuration-ops.js';
+import { listPaginationZodFields, mcpPaginatedListPayload } from '../list-pagination.js';
+import { normalizeAutomationFilterCriteria, validateAutomationCreateControls, } from '../pipeline-automation-flags.js';
+import { activatePipelineAutomationRule, createPipelineAutomationRule, deactivatePipelineAutomationRule, deletePipelineAutomationRule, fetchPipelineAutomationRule, fetchPipelineAutomationRules, updatePipelineAutomationRule, } from '../pipeline-automation-ops.js';
+import { AUTOMATION_CRITERIA_LOGICS, AUTOMATION_CRITERIA_MODES, AUTOMATION_CRITERIA_OPERATORS, AUTOMATION_EXECUTION_TIMES, AUTOMATION_PROMOTION_TRIGGERS, AUTOMATION_SCOPES, AUTOMATION_SOURCE_ACTION_STATUSES, AUTOMATION_SOURCE_ACTIONS, } from '../pipeline-automation-types.js';
+import { assertSalesforceLifecycleId } from '../pipeline-lifecycle-id.js';
+import { buildPipelineQualityGateCreateArgsPayload, normalizeQualityGateFilterCriteria, } from '../pipeline-quality-gate-flags.js';
+import { activatePipelineQualityGate, createPipelineQualityGates, deactivatePipelineQualityGate, deletePipelineQualityGate, fetchPipelineQualityGate, fetchPipelineQualityGates, updatePipelineQualityGate, } from '../pipeline-quality-gate-ops.js';
+import { QUALITY_GATE_EXECUTION_SEQUENCES, QUALITY_GATE_FILTER_FIELDS, QUALITY_GATE_FILTER_OPERATORS, QUALITY_GATE_TESTS_FROM_VALUES, } from '../pipeline-quality-gate-types.js';
+import { safelyHandleTool } from './result.js';
+const automationFilterCriteriaSchema = z
+    .object({
+    conditions: z
+        .array(z.object({
+        field: z.string(),
+        operator: z.enum(AUTOMATION_CRITERIA_OPERATORS),
+        value: z.union([z.string(), z.number(), z.boolean()]),
+    }))
+        .optional(),
+    logic: z.enum(AUTOMATION_CRITERIA_LOGICS).optional(),
+    mode: z.enum(AUTOMATION_CRITERIA_MODES),
+    whereCondition: z.string().optional(),
+})
+    .describe('User-story filter. Builder: {mode:"builder",logic:"AND",conditions:[{field,operator,value}]}. Custom: {mode:"custom",whereCondition:"Name LIKE \'US-%\'"}.');
+const qualityGateFilterCriteriaSchema = z
+    .object({
+    conditions: z
+        .array(z.object({
+        field: z.enum(QUALITY_GATE_FILTER_FIELDS),
+        operator: z.enum(QUALITY_GATE_FILTER_OPERATORS),
+        value: z.string(),
+    }))
+        .min(1),
+    logic: z.string().optional(),
+})
+    .describe('Metadata-change filter. Example: {conditions:[{field:"Type",operator:"equals",value:"ApexClass"}],logic:"1"}. Fields: Name, Type, Directory.');
+function buildAutomationCreatePayload(args) {
+    const stageIds = args.stageIds ?? [];
+    const environmentIds = args.environmentIds ?? [];
+    validateAutomationCreateControls({
+        cronExpression: args.cronExpression,
+        customAutomationConnector: args.customAutomationConnector,
+        environmentIds,
+        environmentSyncSource: args.environmentSyncSource,
+        executionTime: args.executionTime,
+        promotionTrigger: args.promotionTrigger,
+        scope: args.scope,
+        sourceAction: args.sourceAction,
+        sourceActionStatus: args.sourceActionStatus,
+        stageIds,
+    });
+    const payload = {
+        environmentIds,
+        executionTime: args.executionTime,
+        name: args.name,
+        scope: args.scope,
+        stageIds,
+    };
+    if (args.description !== undefined)
+        payload.description = args.description;
+    if (args.cronExpression !== undefined)
+        payload.cronExpression = args.cronExpression;
+    if (args.callbackAction !== undefined)
+        payload.callbackAction = args.callbackAction;
+    if (args.promotionTrigger !== undefined)
+        payload.promotionTrigger = args.promotionTrigger;
+    if (args.environmentSyncSource !== undefined)
+        payload.environmentSyncSource = args.environmentSyncSource;
+    if (args.sourceAction !== undefined)
+        payload.sourceAction = args.sourceAction;
+    if (args.sourceActionStatus !== undefined)
+        payload.sourceActionStatus = args.sourceActionStatus;
+    if (args.customAutomationConnector !== undefined) {
+        payload.customAutomationConnector = args.customAutomationConnector;
+    }
+    if (args.filterCriteria !== undefined) {
+        payload.filterCriteria = normalizeAutomationFilterCriteria(args.filterCriteria);
+    }
+    return payload;
+}
+function buildAutomationUpdatePayload(args) {
+    const payload = {};
+    if (args.name !== undefined)
+        payload.name = args.name;
+    if (args.description !== undefined)
+        payload.description = args.description;
+    if (args.executionTime !== undefined)
+        payload.executionTime = args.executionTime;
+    if (args.cronExpression !== undefined)
+        payload.cronExpression = args.cronExpression;
+    if (args.callbackAction !== undefined)
+        payload.callbackAction = args.callbackAction;
+    if (args.stageIds !== undefined)
+        payload.stageIds = args.stageIds;
+    if (args.environmentIds !== undefined)
+        payload.environmentIds = args.environmentIds;
+    if (args.promotionTrigger !== undefined)
+        payload.promotionTrigger = args.promotionTrigger;
+    if (args.environmentSyncSource !== undefined)
+        payload.environmentSyncSource = args.environmentSyncSource;
+    if (args.sourceAction !== undefined)
+        payload.sourceAction = args.sourceAction;
+    if (args.sourceActionStatus !== undefined)
+        payload.sourceActionStatus = args.sourceActionStatus;
+    if (args.customAutomationConnector !== undefined) {
+        payload.customAutomationConnector = args.customAutomationConnector;
+    }
+    if (args.filterCriteria !== undefined) {
+        payload.filterCriteria = normalizeAutomationFilterCriteria(args.filterCriteria);
+    }
+    if (Object.keys(payload).length === 0) {
+        throw new Error('Must provide at least one field to update.');
+    }
+    return payload;
+}
+function buildQualityGateCreatePayload(args) {
+    return buildPipelineQualityGateCreateArgsPayload({
+        action: args.action,
+        entirePipeline: args.entirePipeline,
+        environmentIds: args.environmentIds,
+        executionSequence: args.executionSequence,
+        extensionConfigurationId: args.extensionConfigurationId,
+        filterCriteria: args.filterCriteria,
+        stageIds: args.stageIds,
+        testsFrom: args.testsFrom,
+        tool: args.tool,
+    });
+}
+function buildQualityGateUpdatePayload(args) {
+    const payload = {};
+    if (args.action !== undefined)
+        payload.action = args.action;
+    if (args.executionSequence !== undefined)
+        payload.executionSequence = args.executionSequence;
+    if (args.extensionConfigurationId !== undefined) {
+        payload.extensionConfigurationId = args.extensionConfigurationId;
+    }
+    if (args.testsFrom !== undefined)
+        payload.testsFrom = args.testsFrom;
+    if (args.entirePipeline !== undefined)
+        payload.entirePipeline = args.entirePipeline;
+    if (args.stageId !== undefined)
+        payload.stageId = args.stageId;
+    if (args.environmentId !== undefined)
+        payload.environmentId = args.environmentId;
+    if (payload.stageId !== undefined && payload.environmentId !== undefined) {
+        throw new Error('stageId and environmentId cannot both be set.');
+    }
+    if (payload.entirePipeline === true && (payload.stageId !== undefined || payload.environmentId !== undefined)) {
+        throw new Error('entirePipeline cannot be combined with stageId or environmentId.');
+    }
+    if (args.filterCriteria !== undefined) {
+        payload.filterCriteria = normalizeQualityGateFilterCriteria(args.filterCriteria);
+    }
+    if (Object.keys(payload).length === 0) {
+        throw new Error('Must provide at least one field to update.');
+    }
+    return payload;
+}
+async function automationList(args) {
+    return mcpPaginatedListPayload('automationRules', await fetchPipelineAutomationRules(args.pipelineId, {
+        active: args.active,
+        cursor: args.cursor,
+        executionTime: args.executionTime,
+        includeSystemGenerated: args.includeSystemGenerated,
+        name: args.name,
+        pageSize: args.pageSize,
+        sourceAction: args.sourceAction,
+    }));
+}
+async function automationGet(args) {
+    return {
+        automationRule: await fetchPipelineAutomationRule(args.pipelineId, args.id),
+    };
+}
+async function automationCreate(args) {
+    return {
+        automationRule: await createPipelineAutomationRule(args.pipelineId, buildAutomationCreatePayload(args)),
+    };
+}
+async function automationUpdate(args) {
+    return {
+        automationRule: await updatePipelineAutomationRule(args.pipelineId, args.id, buildAutomationUpdatePayload(args)),
+    };
+}
+async function automationDelete(args) {
+    await deletePipelineAutomationRule(args.pipelineId, args.id);
+    return { id: args.id, pipelineId: args.pipelineId };
+}
+async function automationActivate(args) {
+    const id = assertSalesforceLifecycleId(args.id, 'Automation rule ID');
+    await activatePipelineAutomationRule(args.pipelineId, id);
+    return { id, pipelineId: args.pipelineId };
+}
+async function automationDeactivate(args) {
+    const id = assertSalesforceLifecycleId(args.id, 'Automation rule ID');
+    await deactivatePipelineAutomationRule(args.pipelineId, id);
+    return { id, pipelineId: args.pipelineId };
+}
+async function qualityGateList(args) {
+    return mcpPaginatedListPayload('qualityGates', await fetchPipelineQualityGates(args.pipelineId, {
+        cursor: args.cursor,
+        name: args.name,
+        pageSize: args.pageSize,
+        tool: args.tool,
+    }));
+}
+async function qualityGateGet(args) {
+    return {
+        qualityGate: await fetchPipelineQualityGate(args.pipelineId, args.id),
+    };
+}
+async function qualityGateCreate(args) {
+    return {
+        qualityGates: await createPipelineQualityGates(args.pipelineId, buildQualityGateCreatePayload(args)),
+    };
+}
+async function qualityGateUpdate(args) {
+    return {
+        qualityGate: await updatePipelineQualityGate(args.pipelineId, args.id, buildQualityGateUpdatePayload(args)),
+    };
+}
+async function qualityGateDelete(args) {
+    await deletePipelineQualityGate(args.pipelineId, args.id);
+    return { id: args.id, pipelineId: args.pipelineId };
+}
+async function qualityGateActivate(args) {
+    const id = assertSalesforceLifecycleId(args.id, 'Quality gate ID');
+    await activatePipelineQualityGate(args.pipelineId, id);
+    return { id, pipelineId: args.pipelineId };
+}
+async function qualityGateDeactivate(args) {
+    const id = assertSalesforceLifecycleId(args.id, 'Quality gate ID');
+    await deactivatePipelineQualityGate(args.pipelineId, id);
+    return { id, pipelineId: args.pipelineId };
+}
+async function extensionConfigurationList(args = {}) {
+    return mcpPaginatedListPayload('extensionConfigurations', await fetchExtensionConfigurations({
+        active: args.active,
+        cursor: args.cursor,
+        name: args.name,
+        pageSize: args.pageSize,
+        testType: args.testType,
+        tool: args.tool,
+    }));
+}
+async function extensionConfigurationGet(args) {
+    return {
+        extensionConfiguration: await fetchExtensionConfiguration(args.id),
+    };
+}
+export const agentiaMcpPipelineAutomationQualityToolHandlers = {
+    extensionConfigurationGet,
+    extensionConfigurationList,
+    pipelineAutomationActivate: automationActivate,
+    pipelineAutomationCreate: automationCreate,
+    pipelineAutomationDeactivate: automationDeactivate,
+    pipelineAutomationDelete: automationDelete,
+    pipelineAutomationGet: automationGet,
+    pipelineAutomationList: automationList,
+    pipelineAutomationUpdate: automationUpdate,
+    pipelineQualityGateActivate: qualityGateActivate,
+    pipelineQualityGateCreate: qualityGateCreate,
+    pipelineQualityGateDeactivate: qualityGateDeactivate,
+    pipelineQualityGateDelete: qualityGateDelete,
+    pipelineQualityGateGet: qualityGateGet,
+    pipelineQualityGateList: qualityGateList,
+    pipelineQualityGateUpdate: qualityGateUpdate,
+};
+export function registerAgentiaMcpPipelineAutomationQualityTools(server) {
+    server.registerTool('agentia_pipeline_automation_list', {
+        description: 'List Copado pipeline automation rules via the CICD gateway.',
+        inputSchema: {
+            ...listPaginationZodFields,
+            active: z.boolean().optional().describe('Filter by active status.'),
+            executionTime: z.enum(AUTOMATION_EXECUTION_TIMES).optional().describe('Filter by execution time.'),
+            includeSystemGenerated: z.boolean().optional().describe('Include system-generated rules.'),
+            name: z.string().optional().describe('Filter by automation rule name.'),
+            pipelineId: z.string().describe('Pipeline ID or name.'),
+            sourceAction: z.enum(AUTOMATION_SOURCE_ACTIONS).optional().describe('Filter by source action.'),
+        },
+        title: 'Agentia Pipeline Automation List',
+    }, (args) => safelyHandleTool(() => automationList(args)));
+    server.registerTool('agentia_pipeline_automation_get', {
+        description: 'Get a Copado pipeline automation rule via the CICD gateway.',
+        inputSchema: {
+            id: z.string().describe('Automation rule ID or name.'),
+            pipelineId: z.string().describe('Pipeline ID or name.'),
+        },
+        title: 'Agentia Pipeline Automation Get',
+    }, (args) => safelyHandleTool(() => automationGet(args)));
+    server.registerTool('agentia_pipeline_automation_create', {
+        description: 'Create an inactive Copado pipeline automation rule via the CICD gateway.',
+        inputSchema: {
+            callbackAction: z.string().optional(),
+            cronExpression: z.string().optional(),
+            customAutomationConnector: z.string().optional(),
+            description: z.string().optional(),
+            environmentIds: z.array(z.string()).optional(),
+            environmentSyncSource: z.string().optional(),
+            executionTime: z.enum(AUTOMATION_EXECUTION_TIMES).describe('Execution time.'),
+            filterCriteria: automationFilterCriteriaSchema.optional(),
+            name: z.string().describe('Automation rule name.'),
+            pipelineId: z.string().describe('Pipeline ID or name.'),
+            promotionTrigger: z.enum(AUTOMATION_PROMOTION_TRIGGERS).optional(),
+            scope: z.enum(AUTOMATION_SCOPES).describe('Automation scope (immutable after create).'),
+            sourceAction: z.enum(AUTOMATION_SOURCE_ACTIONS).optional(),
+            sourceActionStatus: z.enum(AUTOMATION_SOURCE_ACTION_STATUSES).optional(),
+            stageIds: z.array(z.string()).optional(),
+        },
+        title: 'Agentia Pipeline Automation Create',
+    }, (args) => safelyHandleTool(() => automationCreate(args)));
+    server.registerTool('agentia_pipeline_automation_update', {
+        description: 'Update a Copado pipeline automation rule via the CICD gateway. Scope is immutable.',
+        inputSchema: {
+            callbackAction: z.string().optional(),
+            cronExpression: z.string().optional(),
+            customAutomationConnector: z.string().optional(),
+            description: z.string().optional(),
+            environmentIds: z.array(z.string()).optional(),
+            environmentSyncSource: z.string().optional(),
+            executionTime: z.enum(AUTOMATION_EXECUTION_TIMES).optional(),
+            filterCriteria: automationFilterCriteriaSchema.optional(),
+            id: z.string().describe('Automation rule ID or name.'),
+            name: z.string().optional(),
+            pipelineId: z.string().describe('Pipeline ID or name.'),
+            promotionTrigger: z.enum(AUTOMATION_PROMOTION_TRIGGERS).optional(),
+            sourceAction: z.enum(AUTOMATION_SOURCE_ACTIONS).optional(),
+            sourceActionStatus: z.enum(AUTOMATION_SOURCE_ACTION_STATUSES).optional(),
+            stageIds: z.array(z.string()).optional(),
+        },
+        title: 'Agentia Pipeline Automation Update',
+    }, (args) => safelyHandleTool(() => automationUpdate(args)));
+    server.registerTool('agentia_pipeline_automation_delete', {
+        description: 'Delete a Copado pipeline automation rule via the CICD gateway.',
+        inputSchema: {
+            id: z.string().describe('Automation rule ID or name.'),
+            pipelineId: z.string().describe('Pipeline ID or name.'),
+        },
+        title: 'Agentia Pipeline Automation Delete',
+    }, (args) => safelyHandleTool(() => automationDelete(args)));
+    server.registerTool('agentia_pipeline_automation_activate', {
+        description: 'Activate a Copado pipeline automation rule. Requires a Salesforce Id (not name).',
+        inputSchema: {
+            id: z.string().describe('Automation rule Salesforce ID.'),
+            pipelineId: z.string().describe('Pipeline ID or name.'),
+        },
+        title: 'Agentia Pipeline Automation Activate',
+    }, (args) => safelyHandleTool(() => automationActivate(args)));
+    server.registerTool('agentia_pipeline_automation_deactivate', {
+        description: 'Deactivate a Copado pipeline automation rule. Requires a Salesforce Id (not name).',
+        inputSchema: {
+            id: z.string().describe('Automation rule Salesforce ID.'),
+            pipelineId: z.string().describe('Pipeline ID or name.'),
+        },
+        title: 'Agentia Pipeline Automation Deactivate',
+    }, (args) => safelyHandleTool(() => automationDeactivate(args)));
+    server.registerTool('agentia_pipeline_quality_gate_list', {
+        description: 'List Copado pipeline quality gates via the CICD gateway.',
+        inputSchema: {
+            ...listPaginationZodFields,
+            name: z.string().optional().describe('Filter by quality gate name.'),
+            pipelineId: z.string().describe('Pipeline ID or name.'),
+            tool: z.string().optional().describe('Filter by tool.'),
+        },
+        title: 'Agentia Pipeline Quality Gate List',
+    }, (args) => safelyHandleTool(() => qualityGateList(args)));
+    server.registerTool('agentia_pipeline_quality_gate_get', {
+        description: 'Get a Copado pipeline quality gate via the CICD gateway.',
+        inputSchema: {
+            id: z.string().describe('Quality gate ID or name.'),
+            pipelineId: z.string().describe('Pipeline ID or name.'),
+        },
+        title: 'Agentia Pipeline Quality Gate Get',
+    }, (args) => safelyHandleTool(() => qualityGateGet(args)));
+    server.registerTool('agentia_pipeline_quality_gate_create', {
+        description: 'Create inactive Copado pipeline quality gates via the CICD gateway.',
+        inputSchema: {
+            action: z.string().describe('Pipeline action the gate runs for (for example Commit, Promotion, Deployment).'),
+            entirePipeline: z.boolean().optional().describe('Apply to the entire pipeline.'),
+            environmentIds: z.array(z.string()).optional(),
+            executionSequence: z.enum(QUALITY_GATE_EXECUTION_SEQUENCES).describe('Execution sequence.'),
+            extensionConfigurationId: z.string().describe('Active extension configuration ID.'),
+            filterCriteria: qualityGateFilterCriteriaSchema.optional(),
+            pipelineId: z.string().describe('Pipeline ID or name.'),
+            stageIds: z.array(z.string()).optional(),
+            testsFrom: z.enum(QUALITY_GATE_TESTS_FROM_VALUES).optional(),
+            tool: z.string().describe('Quality gate tool name.'),
+        },
+        title: 'Agentia Pipeline Quality Gate Create',
+    }, (args) => safelyHandleTool(() => qualityGateCreate(args)));
+    server.registerTool('agentia_pipeline_quality_gate_update', {
+        description: 'Update an inactive Copado pipeline quality gate via the CICD gateway.',
+        inputSchema: {
+            action: z.string().optional(),
+            entirePipeline: z.boolean().optional(),
+            environmentId: z.string().optional(),
+            executionSequence: z.enum(QUALITY_GATE_EXECUTION_SEQUENCES).optional(),
+            extensionConfigurationId: z.string().optional(),
+            filterCriteria: qualityGateFilterCriteriaSchema.optional(),
+            id: z.string().describe('Quality gate ID or name.'),
+            pipelineId: z.string().describe('Pipeline ID or name.'),
+            stageId: z.string().optional(),
+            testsFrom: z.enum(QUALITY_GATE_TESTS_FROM_VALUES).optional(),
+        },
+        title: 'Agentia Pipeline Quality Gate Update',
+    }, (args) => safelyHandleTool(() => qualityGateUpdate(args)));
+    server.registerTool('agentia_pipeline_quality_gate_delete', {
+        description: 'Delete an inactive Copado pipeline quality gate via the CICD gateway.',
+        inputSchema: {
+            id: z.string().describe('Quality gate ID or name.'),
+            pipelineId: z.string().describe('Pipeline ID or name.'),
+        },
+        title: 'Agentia Pipeline Quality Gate Delete',
+    }, (args) => safelyHandleTool(() => qualityGateDelete(args)));
+    server.registerTool('agentia_pipeline_quality_gate_activate', {
+        description: 'Activate a Copado pipeline quality gate. Requires a Salesforce Id (not name).',
+        inputSchema: {
+            id: z.string().describe('Quality gate Salesforce ID.'),
+            pipelineId: z.string().describe('Pipeline ID or name.'),
+        },
+        title: 'Agentia Pipeline Quality Gate Activate',
+    }, (args) => safelyHandleTool(() => qualityGateActivate(args)));
+    server.registerTool('agentia_pipeline_quality_gate_deactivate', {
+        description: 'Deactivate a Copado pipeline quality gate. Requires a Salesforce Id (not name).',
+        inputSchema: {
+            id: z.string().describe('Quality gate Salesforce ID.'),
+            pipelineId: z.string().describe('Pipeline ID or name.'),
+        },
+        title: 'Agentia Pipeline Quality Gate Deactivate',
+    }, (args) => safelyHandleTool(() => qualityGateDeactivate(args)));
+    server.registerTool('agentia_extension_configuration_list', {
+        description: 'List Copado extension configurations via the CICD gateway.',
+        inputSchema: {
+            ...listPaginationZodFields,
+            active: z.boolean().optional().describe('Filter by active status.'),
+            name: z.string().optional().describe('Filter by name.'),
+            testType: z.string().optional().describe('Filter by test type.'),
+            tool: z.string().optional().describe('Filter by extension tool.'),
+        },
+        title: 'Agentia Extension Configuration List',
+    }, (args) => safelyHandleTool(() => extensionConfigurationList(args || {})));
+    server.registerTool('agentia_extension_configuration_get', {
+        description: 'Get a Copado extension configuration via the CICD gateway.',
+        inputSchema: {
+            id: z.string().describe('Extension configuration ID or name.'),
+        },
+        title: 'Agentia Extension Configuration Get',
+    }, (args) => safelyHandleTool(() => extensionConfigurationGet(args)));
+}
+//# sourceMappingURL=pipeline-automation-quality-tools.js.map

package/dist/lib/mcp/server.js

@@ -2,6 +2,8 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { createRequire } from 'node:module';
 import process from 'node:process';
+import { z } from 'zod';
+import { logVerboseDebug } from '../debug.js';
 import { migrateUserSettingsFromProjectConfig } from '../defaults-store.js';
 import { applyProjectRoot, hasExplicitProjectRoot } from '../project-root.js';
 import { runWithMcpRequestSignal } from './request-context.js';
@@ -10,15 +12,71 @@ import { withToolAnnotations } from './tool-annotations.js';
 import { registerAgentiaMcpTools } from './tools.js';
 const require = createRequire(import.meta.url);
 const packageJson = require('../../../package.json');
+/**
+ * SDK ListRootsResultSchema requires every uri to start with file://.
+ * Some clients send empty or non-file URIs; accept them here and filter below.
+ */
+const LenientListRootsResultSchema = z
+    .object({
+    roots: z.array(z.unknown()).optional().default([]),
+})
+    .passthrough();
+/** Keep only usable local file roots; empty / non-file:// entries are ignored. */
+export function collectMcpFileRootUris(roots) {
+    const uris = [];
+    for (const root of roots) {
+        if (root === null || typeof root !== 'object')
+            continue;
+        const { uri } = root;
+        if (typeof uri !== 'string')
+            continue;
+        const trimmed = uri.trim();
+        if (trimmed.startsWith('file://'))
+            uris.push(trimmed);
+    }
+    return uris;
+}
 export function createAgentiaMcpServer(lifecycleSignal, projectContextReady = Promise.resolve()) {
     const server = new McpServer({
         name: packageJson.name ?? 'agentia-cli',
         version: packageJson.version,
     });
+    installMcpClientCallDebugLogging(server.server);
     wrapMcpToolRegistration(server, lifecycleSignal, projectContextReady);
     registerAgentiaMcpTools(server);
     return server;
 }
+/**
+ * Log every server→client MCP request/notification when DEBUG=verbose.
+ * Covers roots/list and any future client calls made through the protocol.
+ */
+export function installMcpClientCallDebugLogging(protocol) {
+    const target = protocol;
+    const originalRequest = target.request.bind(target);
+    target.request = async (request, resultSchema, options) => {
+        logVerboseDebug('MCP client request', request);
+        try {
+            const result = await originalRequest(request, resultSchema, options);
+            logVerboseDebug('MCP client response', {
+                method: typeof request?.method === 'string' ? request.method : undefined,
+                result,
+            });
+            return result;
+        }
+        catch (error) {
+            logVerboseDebug('MCP client error', {
+                error: error instanceof Error ? error.message : String(error),
+                method: typeof request?.method === 'string' ? request.method : undefined,
+            });
+            throw error;
+        }
+    };
+    const originalNotification = target.notification.bind(target);
+    target.notification = async (notification, options) => {
+        logVerboseDebug('MCP client notification', notification);
+        await originalNotification(notification, options);
+    };
+}
 function combineSignals(requestSignal, lifecycleSignal) {
     if (requestSignal === undefined || lifecycleSignal === undefined) {
         return { dispose() { }, signal: requestSignal ?? lifecycleSignal };
@@ -61,8 +119,19 @@ function wrapMcpToolRegistration(server, lifecycleSignal, projectContextReady =
 function clientSupportsRoots(server) {
     return (server.server._clientCapabilities?.roots !== undefined);
 }
+async function listMcpFileRootUris(server) {
+    try {
+        const result = await server.server.request({ method: 'roots/list' }, LenientListRootsResultSchema);
+        return collectMcpFileRootUris(result.roots);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`[agentia-mcp] ignoring invalid MCP roots/list response: ${message}\n`);
+        return undefined;
+    }
+}
 async function applyMcpProjectRoot(server, includeMcpRoots) {
-    const rootUris = includeMcpRoots ? (await server.server.listRoots()).roots.map((root) => root.uri) : undefined;
+    const rootUris = includeMcpRoots ? await listMcpFileRootUris(server) : undefined;
     applyProjectRoot(undefined, rootUris);
     await migrateUserSettingsFromProjectConfig().catch(() => {
         // Best-effort; MCP tools still fall back to reading legacy project keys.

package/dist/lib/mcp/testing-live-tools.js

@@ -2,15 +2,22 @@ import { mkdtemp } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { z } from 'zod';
-import { controlTestingLive, executeTestingLive, getTestingLiveHistory, getTestingLiveReports, getTestingLiveStatus, inspectTestingLive, saveTestingLiveScreenshot, setTestingLiveOptions, startTestingLive, stopTestingLive, } from '../testing-live-operations.js';
+import { controlTestingLive, executeTestingLive, getTestingLiveHistory, getTestingLiveReports, getTestingLiveStatus, inspectTestingLive, parseTestingLiveScreen, saveTestingLiveScreenshot, setTestingLiveOptions, startTestingLive, stopTestingLive, } from '../testing-live-operations.js';
 import { TESTING_LIVE_LIBRARIES } from '../testing-live-types.js';
 import { safelyHandleTool } from './result.js';
 async function testingLiveStart(args) {
-    const screenValues = [args.screenWidth, args.screenHeight, args.screenDepth];
-    const supplied = screenValues.filter((value) => value !== undefined);
-    if (supplied.length > 0 && supplied.length !== 3) {
-        throw new Error('Provide screenWidth, screenHeight, and screenDepth together.');
+    const hasScreenParts = args.screenDepth !== undefined || args.screenHeight !== undefined || args.screenWidth !== undefined;
+    if (hasScreenParts && (args.screen !== undefined || args.viewport !== undefined)) {
+        throw new Error('Use either screen/viewport or screenWidth/screenHeight/screenDepth, not both.');
     }
+    let screenInput = args.screen;
+    if (hasScreenParts) {
+        if (args.screenDepth === undefined || args.screenHeight === undefined || args.screenWidth === undefined) {
+            throw new Error('Provide screenWidth, screenHeight, and screenDepth together.');
+        }
+        screenInput = { depth: args.screenDepth, height: args.screenHeight, width: args.screenWidth };
+    }
+    const screen = parseTestingLiveScreen(screenInput, args.viewport);
     return {
         result: await startTestingLive({
             description: args.description,
@@ -21,9 +28,7 @@ async function testingLiveStart(args) {
             noBrowser: args.noBrowser,
             pollIntervalMs: args.pollIntervalSeconds === undefined ? undefined : args.pollIntervalSeconds * 1000,
             projectId: args.project,
-            screen: supplied.length === 0
-                ? undefined
-                : { depth: args.screenDepth, height: args.screenHeight, width: args.screenWidth },
+            screen,
             section: args.section,
             sectionIndex: args.sectionIndex,
             sessionVersion: args.sessionVersion,
@@ -58,7 +63,9 @@ async function testingLiveExecute(args) {
     };
 }
 async function testingLiveControl(action, args) {
-    return { result: await controlTestingLive(action, { jobId: args.job, projectId: args.project, sessionId: args.sessionId }) };
+    return {
+        result: await controlTestingLive(action, { jobId: args.job, projectId: args.project, sessionId: args.sessionId }),
+    };
 }
 async function testingLiveInspect(args) {
     return {
@@ -100,7 +107,9 @@ async function testingLiveSetOptions(args) {
     };
 }
 async function testingLiveHistory(args) {
-    return { result: getTestingLiveHistory({ jobId: args.job, limit: args.limit, projectId: args.project, status: args.status }) };
+    return {
+        result: getTestingLiveHistory({ jobId: args.job, limit: args.limit, projectId: args.project, status: args.status }),
+    };
 }
 export const testingLiveMcpHandlers = {
     testingLiveContinue: (args) => testingLiveControl('continue', args),
@@ -116,7 +125,7 @@ export const testingLiveMcpHandlers = {
     testingLiveStop,
 };
 const liveSessionSchema = {
-    job: z.number().int().positive().optional().describe('Optional CRT job/test ID guard.'),
+    job: z.number().int().positive().optional().describe('Optional CRT job ID guard.'),
     project: z.number().int().positive().describe('CRT project ID.'),
     sessionId: z.number().int().positive().optional().describe('Optional active live session ID guard.'),
 };
@@ -135,12 +144,13 @@ export function registerTestingLiveMcpTools(server) {
         inputSchema: {
             description: z.string().max(500).optional(),
             japIme: z.boolean().optional(),
-            job: z.number().int().positive().describe('CRT job/test ID.'),
+            job: z.number().int().positive().describe('CRT job ID.'),
             library: z.enum(TESTING_LIVE_LIBRARIES).optional(),
             noBootstrap: z.boolean().optional(),
             noBrowser: z.boolean().optional(),
             pollIntervalSeconds: z.number().int().min(1).max(30).optional(),
             project: z.number().int().positive().describe('CRT project ID.'),
+            screen: z.string().max(100).optional(),
             screenDepth: z.number().int().min(8).max(32).optional(),
             screenHeight: z.number().int().min(240).max(4320).optional(),
             screenWidth: z.number().int().min(320).max(7680).optional(),
@@ -148,6 +158,7 @@ export function registerTestingLiveMcpTools(server) {
             sectionIndex: z.number().int().positive().optional(),
             sessionVersion: z.string().max(100).optional(),
             timeoutSeconds: z.number().int().min(1).max(600).optional(),
+            viewport: z.string().max(100).optional(),
         },
         title: 'Agentia Testing Live Start',
     }, (args) => safelyHandleTool(() => testingLiveStart(args)));
@@ -204,7 +215,7 @@ export function registerTestingLiveMcpTools(server) {
     server.registerTool('agentia_testing_live_history', {
         description: 'Read bounded sanitized local CRT live execution history.',
         inputSchema: {
-            job: z.number().int().positive().describe('CRT job/test ID.'),
+            job: z.number().int().positive().describe('CRT job ID.'),
             limit: z.number().int().min(1).max(500).optional(),
             project: z.number().int().positive().describe('CRT project ID.'),
             status: z.enum(['completed', 'failed', 'recorded']).optional(),