@copado/agentia-cli 1.0.0-beta.1 → 1.0.0-beta.4

package/dist/lib/mcp/server.js

@@ -3,18 +3,19 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { createRequire } from 'node:module';
 import process from 'node:process';
 import { migrateUserSettingsFromProjectConfig } from '../defaults-store.js';
-import { applyProjectRoot } from '../project-root.js';
+import { applyProjectRoot, hasExplicitProjectRoot } from '../project-root.js';
 import { runWithMcpRequestSignal } from './request-context.js';
 import { runWithMcpToolContext } from './result.js';
+import { withToolAnnotations } from './tool-annotations.js';
 import { registerAgentiaMcpTools } from './tools.js';
 const require = createRequire(import.meta.url);
 const packageJson = require('../../../package.json');
-export function createAgentiaMcpServer(lifecycleSignal) {
+export function createAgentiaMcpServer(lifecycleSignal, projectContextReady = Promise.resolve()) {
     const server = new McpServer({
         name: packageJson.name ?? 'agentia-cli',
         version: packageJson.version,
     });
-    wrapMcpToolRegistration(server, lifecycleSignal);
+    wrapMcpToolRegistration(server, lifecycleSignal, projectContextReady);
     registerAgentiaMcpTools(server);
     return server;
 }
@@ -41,13 +42,14 @@ function combineSignals(requestSignal, lifecycleSignal) {
         signal: controller.signal,
     };
 }
-function wrapMcpToolRegistration(server, lifecycleSignal) {
+function wrapMcpToolRegistration(server, lifecycleSignal, projectContextReady = Promise.resolve()) {
     const registerTool = server.registerTool.bind(server);
-    server.registerTool = ((name, config, handler) => registerTool(name, config, (...args) => {
+    server.registerTool = ((name, config, handler) => registerTool(name, withToolAnnotations(name, config), (...args) => {
         const extra = args.at(-1);
         const { dispose, signal } = combineSignals(extra?.signal, lifecycleSignal);
         return runWithMcpRequestSignal(signal, async () => {
             try {
+                await projectContextReady;
                 return await runWithMcpToolContext(name, async () => handler(...args));
             }
             finally {
@@ -56,13 +58,38 @@ function wrapMcpToolRegistration(server, lifecycleSignal) {
         });
     }));
 }
-export async function startAgentiaMcpServer(transport = new StdioServerTransport()) {
-    applyProjectRoot();
+function clientSupportsRoots(server) {
+    return (server.server._clientCapabilities?.roots !== undefined);
+}
+async function applyMcpProjectRoot(server, includeMcpRoots) {
+    const rootUris = includeMcpRoots ? (await server.server.listRoots()).roots.map((root) => root.uri) : undefined;
+    applyProjectRoot(undefined, rootUris);
     await migrateUserSettingsFromProjectConfig().catch(() => {
         // Best-effort; MCP tools still fall back to reading legacy project keys.
     });
+}
+export async function startAgentiaMcpServer(transport = new StdioServerTransport()) {
     const lifecycle = new AbortController();
-    const server = createAgentiaMcpServer(lifecycle.signal);
+    let resolveProjectContext;
+    let rejectProjectContext;
+    const projectContextReady = new Promise((resolve, reject) => {
+        resolveProjectContext = resolve;
+        rejectProjectContext = reject;
+    });
+    projectContextReady.catch((error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`[agentia-mcp] project context error: ${message}\n`);
+    });
+    const server = createAgentiaMcpServer(lifecycle.signal, projectContextReady);
+    if (hasExplicitProjectRoot()) {
+        await applyMcpProjectRoot(server, false);
+        resolveProjectContext();
+    }
+    else {
+        server.server.oninitialized = () => {
+            applyMcpProjectRoot(server, clientSupportsRoots(server)).then(resolveProjectContext, rejectProjectContext);
+        };
+    }
     let closing = false;
     const close = async () => {
         if (closing)

package/dist/lib/mcp/tool-annotations.js

@@ -0,0 +1,268 @@
+/**
+ * Standard MCP tool annotations for every Agentia MCP tool.
+ *
+ * Annotations are hints for MCP clients (auto-approve, confirmation prompts); they are not
+ * enforcement. Gateway authorization still applies. Only a few tools enforce their own `confirm` flag.
+ *
+ * Every tool is classified here explicitly. `test/lib/mcp/tool-annotations.test.ts` fails when a
+ * registered tool is missing from the table, so new tools must be classified when they are added.
+ */
+/** MCP spec: destructive means the tool may overwrite or remove existing state, not only add. */
+const CLASS_ANNOTATIONS = {
+    // Runs or triggers something with side effects; repeating it repeats the effect.
+    action: { destructiveHint: true, idempotentHint: false, readOnlyHint: false },
+    // Read-only but not repeatable (model output varies).
+    ask: { destructiveHint: false, idempotentHint: false, readOnlyHint: true },
+    // Purely additive; repeating it creates another record.
+    create: { destructiveHint: false, idempotentHint: false, readOnlyHint: false },
+    // Removes or resets state; repeating it has no further effect.
+    delete: { destructiveHint: true, idempotentHint: true, readOnlyHint: false },
+    read: { destructiveHint: false, idempotentHint: true, readOnlyHint: true },
+    // Overwrites existing state with the same result when repeated.
+    update: { destructiveHint: true, idempotentHint: true, readOnlyHint: false },
+};
+/** Triggers side effects (commit, promote, run, kill, ...). */
+const ACTION_TOOLS = [
+    'agentia_cloud_commit',
+    'agentia_cloud_promote',
+    'agentia_data_sync_apply',
+    'agentia_function_run',
+    'agentia_function_run_local',
+    'agentia_job_kill',
+    'agentia_job_pause',
+    'agentia_job_resume',
+    'agentia_job_run',
+    'agentia_metadata_refresh_deleted',
+    'agentia_metadata_refresh_run',
+    'agentia_promotion_run',
+    'agentia_testing_build_abort',
+    'agentia_testing_build_run',
+    'agentia_testing_job_run',
+    'agentia_testing_live_continue',
+    'agentia_testing_live_execute',
+    'agentia_testing_live_interrupt',
+    'agentia_testing_live_stop',
+    'agentia_testing_run',
+    'agentia_work_commit',
+    'agentia_work_done',
+    'agentia_work_publish',
+    'agentia_work_push',
+    'agentia_work_submit',
+    'agentia_work_test',
+    'agentia_work_test_apex',
+];
+/** Read-only, non-repeatable model calls. */
+const ASK_TOOLS = [
+    'agentia_ai_ask',
+];
+/** Additive writes. */
+const CREATE_TOOLS = [
+    'agentia_credential_create',
+    'agentia_data_commit_create',
+    'agentia_data_filter_add',
+    'agentia_data_formula_create',
+    'agentia_data_template_convert_old',
+    'agentia_data_template_create',
+    'agentia_environment_create',
+    'agentia_pipeline_connection_create',
+    'agentia_pipeline_create',
+    'agentia_pipeline_stage_connection_create',
+    'agentia_project_create',
+    'agentia_repository_create',
+    'agentia_stage_create',
+    'agentia_testing_create',
+    'agentia_testing_data_table_create',
+    'agentia_testing_job_create',
+    'agentia_testing_job_download',
+    'agentia_testing_live_start',
+    'agentia_testing_project_create',
+    'agentia_testing_robot_create',
+    'agentia_testing_user_parameter_create',
+    'agentia_testing_variable_create',
+    'agentia_work_create',
+    'agentia_work_deployment_step_create',
+];
+/** Removes or resets state. */
+const DELETE_TOOLS = [
+    'agentia_data_filter_delete',
+    'agentia_data_template_delete',
+    'agentia_function_delete',
+    'agentia_pipeline_connection_delete',
+    'agentia_pipeline_stage_connection_delete',
+    'agentia_project_delete',
+    'agentia_repository_delete',
+    'agentia_repository_reset',
+    'agentia_stage_delete',
+    'agentia_testing_data_table_delete',
+    'agentia_testing_job_delete',
+    'agentia_testing_job_schedule_remove',
+    'agentia_testing_project_delete',
+    'agentia_testing_robot_delete',
+    'agentia_testing_user_parameter_delete',
+    'agentia_testing_variable_delete',
+    'agentia_work_delete',
+    'agentia_work_deployment_step_delete',
+];
+/** Read-only lookups. */
+const READ_TOOLS = [
+    'agentia_auth_get',
+    'agentia_credential_list',
+    'agentia_data_commit_list',
+    'agentia_data_dataset_file_content',
+    'agentia_data_dataset_file_list',
+    'agentia_data_filter_list',
+    'agentia_data_formula_list',
+    'agentia_data_records_match',
+    'agentia_data_records_search',
+    'agentia_data_sobject_fields',
+    'agentia_data_sobject_relationships',
+    'agentia_data_sync_preview_updates',
+    'agentia_data_template_get',
+    'agentia_data_template_get_detail',
+    'agentia_data_template_list',
+    'agentia_environment_auth_status',
+    'agentia_environment_get',
+    'agentia_environment_list',
+    'agentia_function_defaults',
+    'agentia_function_get',
+    'agentia_function_list',
+    'agentia_function_result_get',
+    'agentia_function_result_log_get',
+    'agentia_health_check',
+    'agentia_job_get',
+    'agentia_job_list',
+    'agentia_job_log_get',
+    'agentia_job_result_file_get',
+    'agentia_job_result_file_list',
+    'agentia_metadata_content_compare',
+    'agentia_metadata_content_get',
+    'agentia_metadata_dependency_list',
+    'agentia_metadata_index_compare',
+    'agentia_metadata_list',
+    'agentia_metadata_refresh_status',
+    'agentia_navigation_resolve',
+    'agentia_pipeline_connection_list',
+    'agentia_pipeline_get',
+    'agentia_pipeline_list',
+    'agentia_pipeline_stage_connection_list',
+    'agentia_project_default_get',
+    'agentia_project_get',
+    'agentia_project_list',
+    'agentia_promotion_conflict_get',
+    'agentia_promotion_conflict_list',
+    'agentia_promotion_get',
+    'agentia_promotion_list',
+    'agentia_repository_get',
+    'agentia_repository_list',
+    'agentia_repository_validate',
+    'agentia_stage_get',
+    'agentia_stage_list',
+    'agentia_testing_build_get',
+    'agentia_testing_build_latest',
+    'agentia_testing_build_list',
+    'agentia_testing_build_logs',
+    'agentia_testing_build_search',
+    'agentia_testing_data_table_get',
+    'agentia_testing_data_table_list',
+    'agentia_testing_job_files',
+    'agentia_testing_job_get',
+    'agentia_testing_job_list',
+    'agentia_testing_job_refs',
+    'agentia_testing_job_schedule_get',
+    'agentia_testing_live_history',
+    'agentia_testing_live_inspect',
+    'agentia_testing_live_reports',
+    'agentia_testing_live_screenshot',
+    'agentia_testing_live_status',
+    'agentia_testing_logs',
+    'agentia_testing_project_get',
+    'agentia_testing_project_list',
+    'agentia_testing_project_permission_get',
+    'agentia_testing_project_permission_list',
+    'agentia_testing_robot_get',
+    'agentia_testing_robot_list',
+    'agentia_testing_status',
+    'agentia_testing_user_parameter_get',
+    'agentia_testing_user_parameter_list',
+    'agentia_testing_variable_get',
+    'agentia_testing_variable_list',
+    'agentia_user_get',
+    'agentia_work_deployment_step_list',
+    'agentia_work_deployment_step_salesforce_flows',
+    'agentia_work_deployment_step_types',
+    'agentia_work_get',
+    'agentia_work_list',
+    'agentia_work_status',
+];
+/** Overwrites existing state. */
+const UPDATE_TOOLS = [
+    'agentia_auth_set',
+    'agentia_credential_update',
+    'agentia_data_filter_update',
+    'agentia_data_formula_update',
+    'agentia_data_template_save_detail',
+    'agentia_environment_update',
+    'agentia_function_upsert',
+    'agentia_pipeline_connection_update',
+    'agentia_pipeline_stage_connection_update',
+    'agentia_pipeline_update',
+    'agentia_project_default_set',
+    'agentia_project_default_unset',
+    'agentia_project_update',
+    'agentia_promotion_conflict_resolve',
+    'agentia_promotion_conflict_unresolve',
+    'agentia_promotion_job_step_update',
+    'agentia_repository_update',
+    'agentia_repository_auth_https',
+    'agentia_repository_auth_ssh',
+    'agentia_stage_update',
+    'agentia_testing_data_table_update',
+    'agentia_testing_job_schedule_set',
+    'agentia_testing_job_update',
+    'agentia_testing_job_upload',
+    'agentia_testing_live_set_options',
+    'agentia_testing_project_permission_set',
+    'agentia_testing_project_permission_update',
+    'agentia_testing_project_update',
+    'agentia_testing_robot_update',
+    'agentia_testing_update',
+    'agentia_testing_user_parameter_update',
+    'agentia_testing_variable_update',
+    'agentia_work_deployment_step_reorder',
+    'agentia_work_deployment_step_update',
+    'agentia_work_set',
+    'agentia_work_update',
+];
+/** Tools that only touch local state (keychain/config), not the gateway or Salesforce. */
+const LOCAL_ONLY_TOOLS = new Set([
+    'agentia_auth_get',
+    'agentia_project_default_get',
+    'agentia_project_default_set',
+    'agentia_project_default_unset',
+]);
+const TOOL_CLASSES = new Map([
+    ...ACTION_TOOLS.map((name) => [name, 'action']),
+    ...ASK_TOOLS.map((name) => [name, 'ask']),
+    ...CREATE_TOOLS.map((name) => [name, 'create']),
+    ...DELETE_TOOLS.map((name) => [name, 'delete']),
+    ...READ_TOOLS.map((name) => [name, 'read']),
+    ...UPDATE_TOOLS.map((name) => [name, 'update']),
+]);
+export function listClassifiedToolNames() {
+    return [...TOOL_CLASSES.keys()];
+}
+export function getToolAnnotations(toolName) {
+    const toolClass = TOOL_CLASSES.get(toolName);
+    if (toolClass === undefined)
+        return undefined;
+    return { ...CLASS_ANNOTATIONS[toolClass], openWorldHint: !LOCAL_ONLY_TOOLS.has(toolName) };
+}
+/** Returns the tool config with default annotations; annotations already set on the tool win. */
+export function withToolAnnotations(toolName, config) {
+    const defaults = getToolAnnotations(toolName);
+    if (defaults === undefined || typeof config !== 'object' || config === null)
+        return config;
+    const existing = config.annotations;
+    return { ...config, annotations: { ...defaults, ...existing } };
+}
+//# sourceMappingURL=tool-annotations.js.map

package/dist/lib/mcp/tools.js

@@ -37,7 +37,7 @@ import { buildPromotionManualTaskUpdatePayload, PROMOTION_MANUAL_TASK_STATUSES,
 import { performPromotionResume, performPromotionRun, PROMOTION_OPERATIONS, PROMOTION_RUN_DEFAULT_TIMEOUT_SECONDS, } from '../promotion-run.js';
 import { normalizePromotionDetail, normalizePromotionsListPage, promotionEndpoint, promotionListEndpoint, } from '../promotion-types.js';
 import { REPOSITORY_STRING_VALIDATION_KEYS, validateNonEmptyStringFields as validateRepositoryNonEmptyStringFields, } from '../repository-flags.js';
-import { normalizeRepositoriesListPage, normalizeRepository, normalizeRepositoryValidateResult, repositoriesEndpoint, REPOSITORY_AUTH_TYPES, REPOSITORY_PROVIDERS, REPOSITORY_SOURCE_FORMATS, repositoryEndpoint, repositoryResetEndpoint, repositoryValidateEndpoint, withRequiredRepositoryFields, } from '../repository-types.js';
+import { normalizeRepositoriesListPage, normalizeRepository, normalizeRepositoryValidateResult, repositoriesEndpoint, REPOSITORY_PROVIDERS, REPOSITORY_SOURCE_FORMATS, repositoryEndpoint, repositoryHttpsAuthEndpoint, repositoryResetEndpoint, repositorySshAuthEndpoint, repositoryValidateEndpoint, } from '../repository-types.js';
 import { buildStageMutationPayload, validateStagePayload } from '../stage-flags.js';
 import { normalizePipelineStageConnection, normalizeStage, normalizeStagesListPage, pipelineStageConnectionEndpoint, pipelineStageConnectionsEndpoint, STAGE_META_STAGE_SUGGESTIONS, stageEndpoint, stagesEndpoint, } from '../stage-types.js';
 import { getUserContext } from '../user-context.js';
@@ -47,6 +47,7 @@ import { workStatusEndpoint } from '../work-types.js';
 import { agentiaMcpAiToolHandlers, registerAgentiaMcpAiTools } from './ai-tools.js';
 import { agentiaMcpDataToolHandlers, registerAgentiaMcpDataTools } from './data-tools.js';
 import { agentiaMcpDeploymentStepToolHandlers, registerAgentiaMcpDeploymentStepTools } from './deployment-step-tools.js';
+import { agentiaMcpHealthCheckToolHandlers, registerAgentiaMcpHealthCheckTools } from './health-check-tools.js';
 import { safelyHandleTool, wrapMcpToolHandlers } from './result.js';
 import { agentiaMcpTestingToolHandlers, registerAgentiaMcpTestingTools } from './testing-tools.js';
 import { agentiaMcpWorkToolHandlers, registerAgentiaMcpWorkTools } from './work-tools.js';
@@ -560,17 +561,12 @@ async function repositoryUpdate(args) {
     if (Object.keys(explicitPayload).length === 0) {
         throw new Error('Must provide at least one field to update.');
     }
-    const currentResponse = await CicdGateway.call({
-        endpoint: repositoryEndpoint(id),
-        method: 'GET',
-    });
-    const payload = withRequiredRepositoryFields(explicitPayload, normalizeRepository(currentResponse));
-    const validationError = validateRepositoryPayload(payload);
+    const validationError = validateRepositoryMutationPayload(explicitPayload);
     if (validationError !== undefined) {
         throw new Error(validationError);
     }
     const response = await CicdGateway.call({
-        body: payload,
+        body: explicitPayload,
         endpoint: repositoryEndpoint(id),
         headers: {
             'Content-Type': 'application/json',
@@ -579,6 +575,26 @@ async function repositoryUpdate(args) {
     });
     return { repository: normalizeRepository(response) };
 }
+async function repositoryAuthHttps(args) {
+    const { id, overwrite, ...payload } = args;
+    await CicdGateway.call({
+        body: payload,
+        endpoint: repositoryHttpsAuthEndpoint(assertRequired(id, 'id'), overwrite === true),
+        headers: { 'Content-Type': 'application/json' },
+        method: 'PUT',
+    });
+    return { id };
+}
+async function repositoryAuthSsh(args) {
+    const { id, overwrite, ...payload } = args;
+    const response = await CicdGateway.call({
+        body: payload,
+        endpoint: repositorySshAuthEndpoint(assertRequired(id, 'id'), overwrite === true),
+        headers: { 'Content-Type': 'application/json' },
+        method: 'POST',
+    });
+    return { id, publicKey: response.publicKey };
+}
 async function repositoryDelete(args) {
     const id = assertRequired(args.id, 'id');
     await CicdGateway.call({
@@ -764,6 +780,9 @@ function validateRepositoryPayload(payload) {
     }
     return undefined;
 }
+function validateRepositoryMutationPayload(payload) {
+    return validateRepositoryNonEmptyStringFields(payload, REPOSITORY_STRING_VALIDATION_KEYS);
+}
 async function userGet(args = {}) {
     const user = await CicdGateway.call({
         endpoint: userEndpoint(resolveUserId(args.id)),
@@ -1206,6 +1225,7 @@ export const agentiaMcpToolHandlers = wrapMcpToolHandlers({
     ...agentiaMcpAiToolHandlers,
     ...agentiaMcpDataToolHandlers,
     ...agentiaMcpDeploymentStepToolHandlers,
+    ...agentiaMcpHealthCheckToolHandlers,
     authGet,
     authSet,
     credentialCreate,
@@ -1332,18 +1352,14 @@ const pipelineConnectionMutationSchema = {
 };
 const repositoryMutationSchema = {
     allowFunctionsGitCache: z.boolean().optional().describe('Allow Functions Git cache for this repository.'),
-    authType: z.enum(REPOSITORY_AUTH_TYPES).optional().describe('Repository authentication type.'),
     branchBaseUrl: z.string().nullable().optional().describe('Base URL for repository branch links.'),
     commitBaseUrl: z.string().nullable().optional().describe('Base URL for repository commit links.'),
-    extraHeaders: z.string().nullable().optional().describe('Additional authentication headers.'),
     isCopadoTunnelEnabled: z.boolean().optional().describe('Enable Copado tunnel for this repository.'),
-    password: z.string().nullable().optional().describe('Repository password or token. Sensitive input.'),
     provider: z.enum(REPOSITORY_PROVIDERS).optional().describe('Git repository provider.'),
     pullRequestBaseUrl: z.string().nullable().optional().describe('Base URL for repository pull request links.'),
     sourceFormat: z.enum(REPOSITORY_SOURCE_FORMATS).optional().describe('Git repository source format.'),
     tagBaseUrl: z.string().nullable().optional().describe('Base URL for repository tag links.'),
     uri: z.string().nullable().optional().describe('Repository clone URI.'),
-    username: z.string().nullable().optional().describe('Repository username.'),
 };
 const promotionListSchema = {
     createdById: z.string().optional().describe('Filter by creator ID.'),
@@ -1366,6 +1382,7 @@ export function registerAgentiaMcpTools(server) {
     registerAgentiaMcpAiTools(server);
     registerAgentiaMcpDataTools(server);
     registerAgentiaMcpDeploymentStepTools(server);
+    registerAgentiaMcpHealthCheckTools(server);
     registerAgentiaMcpTestingTools(server);
     server.registerTool('agentia_environment_list', {
         description: 'List Copado environments via the CICD gateway.',
@@ -1952,6 +1969,35 @@ export function registerAgentiaMcpTools(server) {
         },
         title: 'Agentia Repository Update',
     }, (args) => safelyHandleTool(() => repositoryUpdate(args)));
+    server.registerTool('agentia_repository_auth_https', {
+        description: 'Configure HTTPS repository authentication. The password and optional headers are sensitive and are redacted from responses.',
+        inputSchema: {
+            branchBaseUrl: z.string(),
+            commitBaseUrl: z.string(),
+            extraHeaders: z.string().optional().describe('Sensitive optional authentication headers.'),
+            id: z.string().describe('Copado Git repository ID.'),
+            overwrite: z.boolean().optional().describe('Explicitly replace an existing validated credential.'),
+            password: z.string().describe('Sensitive HTTPS password or personal access token.'),
+            pullRequestBaseUrl: z.string(),
+            tagBaseUrl: z.string(),
+            uri: z.string(),
+            username: z.string(),
+        },
+        title: 'Agentia Repository HTTPS Authentication',
+    }, (args) => safelyHandleTool(() => repositoryAuthHttps(args)));
+    server.registerTool('agentia_repository_auth_ssh', {
+        description: 'Configure SSH repository authentication and return the generated public key.',
+        inputSchema: {
+            branchBaseUrl: z.string(),
+            commitBaseUrl: z.string(),
+            id: z.string().describe('Copado Git repository ID.'),
+            overwrite: z.boolean().optional().describe('Explicitly replace an existing SSH key.'),
+            pullRequestBaseUrl: z.string(),
+            tagBaseUrl: z.string(),
+            uri: z.string(),
+        },
+        title: 'Agentia Repository SSH Authentication',
+    }, (args) => safelyHandleTool(() => repositoryAuthSsh(args)));
     server.registerTool('agentia_repository_delete', {
         description: 'Delete a Copado Git repository by ID via the CICD gateway.',
         inputSchema: { id: z.string().describe('Copado Git repository ID.') },