@1mcp/agent 0.35.0-beta.3 → 0.35.0-beta.4

package/build/domains/admin/adminConfiguredServerService.js

@@ -1,7 +1,8 @@
 import { createHash } from 'node:crypto';
 import { mergeGlobalAndServerConfig } from '../../config/mcpConfigMerge.js';
 import { GLOBAL_TRANSPORT_CONFIG_KEYS, transportConfigSchema, } from '../../core/types/index.js';
-import { fingerprintConfiguredServerDefaults, fingerprintConfiguredServerSecretValue, fingerprintConfiguredServerTarget, isConfiguredServerTargetDisabled, } from '../../domains/config-change/configChange.js';
+import { fingerprintConfiguredServerConfigDocument, fingerprintConfiguredServerDefaults, fingerprintConfiguredServerSecretValue, fingerprintConfiguredServerTarget, isConfiguredServerTargetDisabled, } from '../../domains/config-change/configChange.js';
+import { createServerInstallationWorkflow, } from '../../domains/installation/serverInstallationWorkflow.js';
 import { z } from 'zod';
 const ENV_PLACEHOLDER_PATTERN = /\$\{[^}]+\}|\$[A-Za-z_][A-Za-z0-9_]*/u;
 const previewTransportConfigSchema = transportConfigSchema.extend({
@@ -12,6 +13,365 @@ const previewTransportConfigSchema = transportConfigSchema.extend({
     })
         .optional(),
 });
+const configuredServerCreateSecretSchema = z
+    .object({
+    fieldPath: z.array(z.string()).min(2),
+    action: z.literal('replace'),
+    replacement: z.object({
+        kind: z.enum(['environmentReference', 'inlineSecret']),
+        value: z.string(),
+    }),
+})
+    .strict();
+const configuredServerCreateDraftSchema = z
+    .object({
+    name: z.string(),
+    enabled: z.boolean().optional(),
+    tags: z.array(z.string()).optional(),
+    transport: z
+        .object({
+        type: z.enum(['stdio', 'http', 'sse']),
+        command: z.string().optional(),
+        url: z.string().optional(),
+        args: z.array(z.string()).optional(),
+        cwd: z.string().optional(),
+        env: z.record(z.string(), z.string()).optional(),
+        headers: z.record(z.string(), z.string()).optional(),
+        timeout: z.number().optional(),
+        connectionTimeout: z.number().optional(),
+        requestTimeout: z.number().optional(),
+        restartOnExit: z.boolean().optional(),
+        maxRestarts: z.number().optional(),
+        restartDelay: z.number().optional(),
+    })
+        .strict(),
+    secrets: z.array(configuredServerCreateSecretSchema).optional(),
+})
+    .strict();
+const CONFIGURED_SERVER_CREATE_TRANSPORT_FIELD_KEYS = new Set([
+    'type',
+    'timeout',
+    'connectionTimeout',
+    'requestTimeout',
+    'url',
+    'headers',
+    'command',
+    'args',
+    'cwd',
+    'env',
+    'restartOnExit',
+    'maxRestarts',
+    'restartDelay',
+]);
+function normalizeConfiguredServerCreateDraft(value) {
+    const parsed = configuredServerCreateDraftSchema.safeParse(value);
+    if (!parsed.success) {
+        const record = value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+        const transport = record.transport && typeof record.transport === 'object' && !Array.isArray(record.transport)
+            ? record.transport
+            : {};
+        const transportType = transport.type === 'http' || transport.type === 'sse' ? transport.type : 'stdio';
+        return {
+            draft: {},
+            source: {
+                type: 'direct',
+                localName: typeof record.name === 'string' ? record.name : '',
+                transport: transportType,
+            },
+            validation: {
+                status: 'invalid',
+                errors: parsed.error.issues.map((issue) => ({
+                    fieldPath: issue.path.map(String),
+                    code: 'invalid_create_field',
+                    message: issue.message,
+                })),
+            },
+        };
+    }
+    const { transport } = parsed.data;
+    const draft = {
+        name: parsed.data.name,
+        enabled: parsed.data.enabled,
+        tags: parsed.data.tags,
+        transport: { ...transport },
+        secrets: parsed.data.secrets,
+    };
+    const secretContainer = transport.type === 'stdio' ? 'env' : 'headers';
+    const secretValues = configuredServerCreateSecretValues(draft, secretContainer);
+    const source = {
+        type: 'direct',
+        localName: parsed.data.name,
+        transport: transport.type,
+        enabled: parsed.data.enabled,
+        tags: parsed.data.tags,
+        command: transport.command,
+        url: transport.url,
+        args: transport.args,
+        cwd: transport.cwd,
+        env: mergeConfiguredServerCreateRecord(transport.env, secretContainer === 'env' ? secretValues : undefined),
+        headers: mergeConfiguredServerCreateRecord(transport.headers, secretContainer === 'headers' ? secretValues : undefined),
+        timeout: transport.timeout,
+        connectionTimeout: transport.connectionTimeout,
+        requestTimeout: transport.requestTimeout,
+        autoRestart: transport.restartOnExit,
+        maxRestarts: transport.maxRestarts,
+        restartDelay: transport.restartDelay,
+    };
+    return { draft, source, validation: { status: 'valid', errors: [] } };
+}
+function configuredServerCreateSecretValues(draft, container) {
+    const values = {};
+    for (const secret of draft.secrets ?? []) {
+        if (secret.fieldPath.length !== 2 || secret.fieldPath[0] !== container || !isValidFieldPath(secret.fieldPath)) {
+            continue;
+        }
+        if (!secret.replacement)
+            continue;
+        values[secret.fieldPath[1]] = replacementValue(secret.replacement);
+    }
+    return values;
+}
+function mergeConfiguredServerCreateRecord(base, additions) {
+    const merged = { ...base, ...additions };
+    return Object.keys(merged).length > 0 ? merged : undefined;
+}
+function createWorkflowValidation(workflow, config) {
+    const errors = [];
+    for (const [field, messages] of Object.entries(workflow.fieldErrors ?? {})) {
+        for (const message of messages) {
+            errors.push({
+                fieldPath: field === 'localName' ? ['name'] : ['transport', field],
+                code: 'invalid_create_field',
+                message,
+            });
+        }
+    }
+    if (workflow.status === 'exists' || workflow.status === 'template_conflict') {
+        errors.push({
+            fieldPath: ['name'],
+            code: workflow.status === 'template_conflict' ? 'template_name_conflict' : 'configured_server_name_conflict',
+            message: 'A configured server or Template Server definition already uses this name.',
+        });
+    }
+    if (config) {
+        const parsed = previewTransportConfigSchema.safeParse(config);
+        if (!parsed.success) {
+            for (const issue of parsed.error.issues) {
+                errors.push({
+                    fieldPath: ['transport', ...issue.path.map(String)],
+                    code: 'invalid_transport_config',
+                    message: issue.message,
+                });
+            }
+        }
+    }
+    return { status: errors.length === 0 ? 'valid' : 'invalid', errors };
+}
+function validateConfiguredServerCreateSecrets(draft) {
+    const errors = [];
+    const expectedContainer = draft.transport?.type === 'stdio' ? 'env' : 'headers';
+    for (const [index, secret] of (draft.secrets ?? []).entries()) {
+        const basePath = ['secrets', String(index)];
+        if (!isValidFieldPath(secret.fieldPath) ||
+            secret.fieldPath.length !== 2 ||
+            secret.fieldPath[0] !== expectedContainer) {
+            errors.push({
+                fieldPath: [...basePath, 'fieldPath'],
+                code: 'unsupported_secret_field',
+                message: `Secret replacement must target ${expectedContainer} for the selected transport.`,
+            });
+        }
+        if (!secret.replacement) {
+            errors.push({
+                fieldPath: [...basePath, 'replacement'],
+                code: 'missing_secret_replacement',
+                message: 'Create secret actions require a replacement.',
+            });
+            continue;
+        }
+        if (secret.replacement.kind === 'environmentReference' && !isEnvironmentReferenceInput(secret.replacement.value)) {
+            errors.push({
+                fieldPath: [...basePath, 'replacement', 'value'],
+                code: 'invalid_environment_reference',
+                message: 'Environment reference must be an environment variable name or substitution expression.',
+            });
+        }
+        if (secret.replacement.kind === 'inlineSecret' && secret.replacement.value.length === 0) {
+            errors.push({
+                fieldPath: [...basePath, 'replacement', 'value'],
+                code: 'empty_inline_secret',
+                message: 'Inline secret replacement cannot be empty.',
+            });
+        }
+    }
+    return { status: errors.length === 0 ? 'valid' : 'invalid', errors };
+}
+function createConfiguredServerCreateContract() {
+    const transportFields = TRANSPORT_FIELD_DEFINITIONS.filter((definition) => CONFIGURED_SERVER_CREATE_TRANSPORT_FIELD_KEYS.has(definition.key)).map((definition) => ({
+        fieldPath: ['transport', definition.key],
+        label: definition.label,
+        control: definition.control,
+        value: definition.defaultValue,
+        options: definition.key === 'type' ? ['stdio', 'http', 'sse'] : definition.options,
+        editable: true,
+        applicableTransportTypes: definition.applicableTransportTypes?.filter((type) => type !== 'streamableHttp'),
+    }));
+    return {
+        schemaVersion: 1,
+        capabilities: {
+            create: { supported: true },
+            forceReplacement: { supported: false },
+            rawJson: { supported: false },
+            preview: { supported: true },
+            apply: { supported: true },
+        },
+        secretPolicy: {
+            allowedActions: ['replace'],
+            environmentReference: {
+                recommended: true,
+                storesSecretMaterial: false,
+                guidance: 'Store an environment variable name or substitution expression instead of secret material.',
+            },
+            inlineReplacement: {
+                emphasis: 'secondary',
+                guidance: 'Inline secret material is stored in the Runtime Scope configuration.',
+            },
+        },
+        fieldGroups: [
+            {
+                id: 'identity',
+                label: 'Identity',
+                fields: [
+                    { fieldPath: ['name'], label: 'Server Name', control: 'text', editable: true },
+                    { fieldPath: ['enabled'], label: 'Enabled', control: 'switch', value: true, editable: true },
+                    { fieldPath: ['tags'], label: 'Tags', control: 'tag-list', value: [], editable: true },
+                ],
+            },
+            { id: 'transport', label: 'Transport', fields: transportFields },
+        ],
+    };
+}
+function createConfiguredServerCreateDiff(proposed, draft) {
+    const diff = [
+        { fieldPath: ['name'], oldValue: undefined, newValue: proposed.id, riskFlags: [] },
+        { fieldPath: ['enabled'], oldValue: undefined, newValue: proposed.enabled, riskFlags: ['connection_critical'] },
+        { fieldPath: ['tags'], oldValue: undefined, newValue: proposed.tags, riskFlags: [] },
+    ];
+    for (const [key, value] of Object.entries(proposed.transport)) {
+        diff.push({
+            fieldPath: ['transport', key],
+            oldValue: undefined,
+            newValue: value,
+            riskFlags: previewRiskFlags([key]),
+        });
+    }
+    for (const secret of draft.secrets ?? []) {
+        diff.push({
+            fieldPath: secret.fieldPath,
+            oldValue: undefined,
+            newValue: previewSecretNewValue(secret),
+            secretAction: 'replace',
+            riskFlags: ['connection_critical', 'secret'],
+        });
+    }
+    return diff;
+}
+function previewSecretNewValue(secret) {
+    const replacement = secret.replacement;
+    if (!replacement)
+        return { present: false, value: '[REDACTED]', secret: true };
+    if (replacement.kind === 'environmentReference') {
+        return {
+            kind: 'environmentReference',
+            value: normalizeEnvironmentReference(replacement.value),
+            storesSecretMaterial: false,
+        };
+    }
+    return { present: true, value: '[REDACTED]', secret: true };
+}
+function configuredServerCreatePreviewFingerprint(input) {
+    const redactedDraft = {
+        ...input.draft,
+        secrets: input.draft.secrets?.map((secret) => ({
+            fieldPath: secret.fieldPath,
+            action: secret.action,
+            replacement: secret.replacement ? fingerprintSecretReplacement(secret.replacement) : undefined,
+        })),
+    };
+    return `preview_${createHash('sha256')
+        .update(stableStringify({
+        schemaVersion: 1,
+        configFingerprint: input.configFingerprint,
+        draft: redactedDraft,
+        proposed: input.proposed,
+        diff: input.diff,
+        validation: input.validation,
+        connectivityCheck: connectivityFingerprintFacts(input.connectivityCheck),
+    }))
+        .digest('hex')}`;
+}
+function connectivityFingerprintFacts(connectivityCheck) {
+    if (connectivityCheck.status !== 'passed')
+        return connectivityCheck;
+    return { status: connectivityCheck.status, mode: connectivityCheck.mode };
+}
+function previewCreateConfigChange(targetName, workflowStatus, changed) {
+    const status = workflowStatus === 'template_conflict'
+        ? 'template_conflict'
+        : workflowStatus === 'exists'
+            ? 'destination_conflict'
+            : changed
+                ? 'changed'
+                : 'failed';
+    return {
+        status,
+        operation: 'create_static',
+        configPath: '[redacted]',
+        target: {
+            name: targetName,
+            ...(workflowStatus === 'template_conflict'
+                ? { source: 'mcpTemplates' }
+                : workflowStatus === 'exists'
+                    ? { source: 'mcpServers' }
+                    : {}),
+        },
+        changed,
+        backup: { created: false },
+        retentionCleanup: { attempted: false, deletedPaths: [], warnings: [] },
+        reload: { status: 'skipped' },
+        warnings: [],
+    };
+}
+function createDraftCandidateName(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return '';
+    const name = value.name;
+    return typeof name === 'string' ? name : '';
+}
+function sanitizeCreateConfirmationFacts(facts) {
+    if (!facts)
+        return undefined;
+    const allowed = [
+        'previewConfirmed',
+        'targetNameConfirmed',
+        'secretChangeConfirmed',
+        'connectionCriticalConfirmed',
+        'connectivityFailureOverrideConfirmed',
+    ];
+    const sanitized = Object.fromEntries(allowed.filter((key) => key in facts).map((key) => [key, facts[key]]));
+    return Object.keys(sanitized).length ? sanitized : undefined;
+}
+function assertSuccessfulConfiguredServerCreate(configChange) {
+    if (configChange.status === 'changed')
+        return;
+    if (configChange.status === 'source_conflict') {
+        throw new AdminConfiguredServerApplyError('configured_server_stale_preview');
+    }
+    if (configChange.status === 'destination_conflict' || configChange.status === 'template_conflict') {
+        throw new AdminConfiguredServerApplyError('configured_server_destination_conflict');
+    }
+    throw new AdminConfiguredServerApplyError('configured_server_create_failed');
+}
 export class AdminConfiguredServerNotFoundError extends Error {
     targetName;
     code = 'configured_server_not_found';
@@ -26,6 +386,88 @@ export class AdminConfiguredServerService {
     constructor(options) {
         this.options = options;
     }
+    async getConfiguredServerCreateContract(input) {
+        return this.options.operationService.executeReadOnly({
+            context: input.context,
+            operationName: 'getConfiguredServerCreateContract',
+            run: async () => createConfiguredServerCreateContract(),
+        });
+    }
+    async previewConfiguredServerCreate(input) {
+        return this.options.operationService.executeDryRun({
+            context: input.context,
+            operationName: 'previewConfiguredServerCreate',
+            run: async () => this.previewConfiguredServerCreateResult(input),
+        });
+    }
+    async applyConfiguredServerCreate(input) {
+        const candidateName = createDraftCandidateName(input.draft);
+        const context = {
+            ...input.context,
+            target: { type: 'configured_server', id: candidateName },
+            confirmationFacts: sanitizeCreateConfirmationFacts(input.context.confirmationFacts),
+        };
+        return this.options.operationService.executeMutation({
+            context,
+            operationName: 'applyConfiguredServerCreate',
+            prepare: async () => {
+                const document = this.options.readConfigDocument() ?? {};
+                const preview = await this.previewConfiguredServerCreateResult({ ...input, connectivityCheck: 'auto' }, true, document);
+                if (preview.previewFingerprint !== input.previewFingerprint) {
+                    throw new AdminConfiguredServerApplyError('configured_server_stale_preview');
+                }
+                if (preview.validation.status !== 'valid' || !preview.configChange.changed) {
+                    throw new AdminConfiguredServerApplyError('configured_server_create_invalid');
+                }
+                const prepared = await this.resolveConfiguredServerCreate(input.draft, document);
+                if (!prepared.config) {
+                    throw new AdminConfiguredServerApplyError('configured_server_create_invalid');
+                }
+                if (prepared.enabled &&
+                    !wouldUseLocalStdioTransport(prepared.config) &&
+                    preview.connectivityCheck.status !== 'passed' &&
+                    !(preview.connectivityCheck.status === 'skipped' && preview.connectivityCheck.reason === 'checker_unavailable') &&
+                    !(preview.connectivityCheck.status === 'failed' &&
+                        input.context.confirmationFacts?.connectivityFailureOverrideConfirmed === true)) {
+                    throw new AdminConfiguredServerApplyError('configured_server_connectivity_blocked');
+                }
+                const secretChange = prepared.draft.secrets?.length;
+                const configFingerprint = fingerprintConfiguredServerConfigDocument(document);
+                return {
+                    confirmationRequirements: [
+                        { code: 'previewConfirmed', expected: input.previewFingerprint },
+                        { code: 'targetNameConfirmed', expected: prepared.targetName },
+                        { code: 'connectionCriticalConfirmed', expected: true },
+                        ...(secretChange ? [{ code: 'secretChangeConfirmed', expected: true }] : []),
+                        ...(preview.connectivityCheck.status === 'failed'
+                            ? [{ code: 'connectivityFailureOverrideConfirmed', expected: true }]
+                            : []),
+                    ],
+                    run: async () => {
+                        let configChange;
+                        try {
+                            configChange = await this.options.configChangeService.createStaticConfiguredServerTarget({
+                                targetName: prepared.targetName,
+                                serverConfig: prepared.config,
+                                operation: 'install',
+                                backup: 'skip',
+                                expectedConfigFingerprint: configFingerprint,
+                            });
+                        }
+                        catch {
+                            throw new AdminConfiguredServerApplyError('configured_server_create_failed');
+                        }
+                        assertSuccessfulConfiguredServerCreate(configChange);
+                        return {
+                            targetName: prepared.targetName,
+                            previewFingerprint: preview.previewFingerprint,
+                            configChange,
+                        };
+                    },
+                };
+            },
+        });
+    }
     async listConfiguredServers(input) {
         return this.options.operationService.executeReadOnly({
             context: input.context,
@@ -280,6 +722,70 @@ export class AdminConfiguredServerService {
             serverConfig: input.serverConfig,
         });
     }
+    async previewConfiguredServerCreateResult(input, forceConnectivity = false, document = this.options.readConfigDocument() ?? {}) {
+        const prepared = await this.resolveConfiguredServerCreate(input.draft, document);
+        const proposedReadModel = prepared.config
+            ? createConfiguredServerReadModel(prepared.targetName, mergeGlobalAndServerConfig(document.serverDefaults, prepared.config))
+            : undefined;
+        const validation = prepared.validation;
+        const diff = proposedReadModel ? createConfiguredServerCreateDiff(proposedReadModel, prepared.draft) : [];
+        const changed = validation.status === 'valid' && prepared.workflow.status === 'preview';
+        const connectivityCheck = prepared.config
+            ? await this.previewConnectivityCheck({
+                targetName: prepared.targetName,
+                serverConfig: prepared.config,
+                enabled: prepared.enabled,
+                validationStatus: validation.status,
+                connectionCriticalChanged: true,
+                force: forceConnectivity || input.connectivityCheck === 'manual',
+                endpointChangedWithPreservedSecrets: false,
+            })
+            : { status: 'skipped', reason: 'validation_failed' };
+        const preview = {
+            targetName: prepared.targetName,
+            previewFingerprint: configuredServerCreatePreviewFingerprint({
+                configFingerprint: fingerprintConfiguredServerConfigDocument(document),
+                draft: prepared.draft,
+                proposed: proposedReadModel,
+                diff,
+                validation,
+                connectivityCheck,
+            }),
+            validation,
+            diff,
+            configChange: previewCreateConfigChange(prepared.targetName, prepared.workflow.status, changed),
+            connectivityCheck,
+            expectedReload: {
+                policy: 'observe_after_write',
+                possibleStatuses: ['observed', 'runtime_not_running', 'reload_disabled', 'failed'],
+            },
+        };
+        return preview;
+    }
+    async resolveConfiguredServerCreate(draftValue, document = this.options.readConfigDocument() ?? {}) {
+        const normalized = normalizeConfiguredServerCreateDraft(draftValue);
+        const workflow = createServerInstallationWorkflow({
+            findConfiguredTarget: (targetName) => {
+                if (document.mcpTemplates?.[targetName])
+                    return { name: targetName, source: 'mcpTemplates' };
+                if (document.mcpServers?.[targetName])
+                    return { name: targetName, source: 'mcpServers' };
+                return null;
+            },
+        });
+        const workflowResult = await workflow.run({ mode: 'preview', source: normalized.source });
+        const config = workflowResult.config;
+        const validation = mergeValidation(mergeValidation(normalized.validation, validateConfiguredServerCreateSecrets(normalized.draft)), createWorkflowValidation(workflowResult, config));
+        return {
+            draft: normalized.draft,
+            source: normalized.source,
+            targetName: normalized.source.localName,
+            enabled: normalized.source.enabled !== false,
+            workflow: workflowResult,
+            config,
+            validation,
+        };
+    }
 }
 function assertSuccessfulConfigChange(configChange) {
     if (configChange.reload.status === 'failed') {