@zgeoff/atc 2.37.0 → 2.38.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zgeoff/atc",
-  "version": "2.37.0",
+  "version": "2.38.0",
   "description": "Terminal control tower for coding-agent sessions",
   "homepage": "https://github.com/zgeoff/atc#readme",
   "bugs": "https://github.com/zgeoff/atc/issues",

package/src/agents/build-claude-config-seed.ts

@@ -4,10 +4,12 @@ import { CLAUDE_CONFIG_SEED_FILE } from './claude-config-seed-file';
  * The guest file that seeds a session's own Claude config folder with the
  * state the CLI reads from `.claude.json` to start without its first-run
  * onboarding, and with folder trust for `trustedRoot`, the exact root of a
- * verified clone, when one is given. It holds no account: the placeholder
+ * verified clone, when one is given. Trust also approves every MCP server
+ * the clone's own `.mcp.json` declares, so an unattended session never
+ * waits on the CLI's approval prompt. It holds no account: the placeholder
  * credential is what keeps the CLI from asking for a login. Without a
- * trusted root the CLI asks a person to trust the workspace on its first
- * start.
+ * trusted root the CLI asks a person to trust the workspace, and to approve
+ * the clone's MCP servers, on its first start.
  */
 export function buildClaudeConfigSeed(
   trustedRoot: string | null,
@@ -15,9 +17,10 @@ export function buildClaudeConfigSeed(
   const seed =
     trustedRoot === null
       ? ONBOARDED_CONFIG
-      : { ...ONBOARDED_CONFIG, projects: { [trustedRoot]: { hasTrustDialogAccepted: true } } };
+      : { ...ONBOARDED_CONFIG, projects: { [trustedRoot]: TRUSTED_PROJECT } };
 
   return { [CLAUDE_CONFIG_SEED_FILE]: JSON.stringify(seed, null, 2) };
 }
 
 const ONBOARDED_CONFIG = { hasCompletedOnboarding: true };
+const TRUSTED_PROJECT = { hasTrustDialogAccepted: true, enableAllProjectMcpServers: true };

package/src/agents/build-claude-mcp-config.ts

@@ -0,0 +1,27 @@
+import type { ClaudeMCPServer } from '../shared/collect-claude-auth';
+
+/**
+ * The MCP config file that gives a session each server over HTTP with the
+ * broker's placeholder as a bearer credential in the server's header, so
+ * impd's broker swaps in the credential it holds for the server's host and
+ * the session never holds it.
+ */
+export function buildClaudeMCPConfig(servers: readonly ClaudeMCPServer[]): {
+  readonly mcpServers: Readonly<Record<string, unknown>>;
+} {
+  return {
+    mcpServers: Object.fromEntries(
+      servers.map((server) => [
+        server.name,
+        {
+          type: 'http',
+          url: server.url,
+          headers: { [server.header]: `Bearer ${BROKER_PLACEHOLDER}` },
+        },
+      ]),
+    ),
+  };
+}
+
+// The value impd's broker replaces with the credential on the host's side.
+const BROKER_PLACEHOLDER = 'imp-broker-placeholder';

package/src/agents/claude-adapter.ts

@@ -32,6 +32,7 @@ import { buildArgsWithoutFlags } from './build-args-without-flags';
 import { buildATCBridgeFiles } from './build-atc-bridge-files';
 import { buildClaudeConfigSeed } from './build-claude-config-seed';
 import { buildClaudeGuestLaunch } from './build-claude-guest-launch';
+import { buildClaudeMCPConfig } from './build-claude-mcp-config';
 import { buildClaudeOverrideArgs } from './build-claude-override-args';
 import { buildHookSettings } from './build-hook-settings';
 import type { HookSettingsProfile } from './build-hook-settings';
@@ -232,7 +233,11 @@ export class ClaudeAdapter implements AgentAdapter {
   // config bundle, come from the host's own Claude config folder as it is
   // at this launch, staged under a key of this launch's own. A credential, endpoint, or provider variable in the
   // configured settings, or in the host's environment, would keep the CLI
-  // from sending the placeholder, so either refuses the start.
+  // from sending the placeholder, so either refuses the start. The entry's
+  // MCP servers reach the CLI through an MCP config file of the binding
+  // revision, each with the placeholder in its header. Their flag sits
+  // ahead of the settings flag, so the variadic flag never takes the
+  // prompt as one of its values.
   private planSubscriptionGuestSpawn(
     opts: SpawnOptions,
     dir: string,
@@ -247,6 +252,9 @@ export class ClaudeAdapter implements AgentAdapter {
     }
 
     const settingsPath = `auth-r${auth.revision}/settings.json`;
+    const mcpServers = this.entry.mcpServers ?? [];
+    const mcpPath = `auth-r${auth.revision}/mcp.json`;
+    const mcpArgs = mcpServers.length === 0 ? [] : ['--mcp-config', `${dir}/${mcpPath}`];
     const bundleKey = randomUUID();
 
     const launch = buildClaudeGuestLaunch(
@@ -256,7 +264,7 @@ export class ClaudeAdapter implements AgentAdapter {
         ...this.buildArgs(
           buildArgsWithoutFlags(this.entry.args, ['--permission-mode']),
           opts,
-          [],
+          mcpArgs,
           `${dir}/${settingsPath}`,
           `${dir}/atc-bridge`,
         ),
@@ -284,6 +292,9 @@ export class ClaudeAdapter implements AgentAdapter {
       args: launch.args,
       files: {
         [settingsPath]: JSON.stringify(settings, null, 2),
+        ...(mcpServers.length === 0
+          ? {}
+          : { [mcpPath]: JSON.stringify(buildClaudeMCPConfig(mcpServers), null, 2) }),
         ...buildClaudeConfigSeed(null),
         ...Object.fromEntries(
           Object.entries(bundle).map(([path, content]) => [
@@ -365,13 +376,13 @@ export class ClaudeAdapter implements AgentAdapter {
   private buildArgs(
     configured: readonly string[],
     opts: SpawnOptions,
-    modeArgs: readonly string[],
+    leadArgs: readonly string[],
     settings: string,
     pluginDir: string,
   ): string[] {
     return [
       ...buildClaudeOverrideArgs(configured, opts),
-      ...modeArgs,
+      ...leadArgs,
       '--settings',
       settings,
       '--plugin-dir',

package/src/build-migrated-config.ts

@@ -113,10 +113,22 @@ function renderAgentEntry(entry: AgentEntry): Record<string, unknown> {
   }
 
   if (entry.auth !== undefined) {
-    rendered['auth'] =
-      Object.keys(entry.auth.placeholderEnv).length > 0
-        ? { profiles: entry.auth.profiles, placeholderEnv: entry.auth.placeholderEnv }
-        : { profiles: entry.auth.profiles };
+    rendered['auth'] = {
+      profiles: entry.auth.profiles,
+      ...(Object.keys(entry.auth.placeholderEnv).length > 0
+        ? { placeholderEnv: entry.auth.placeholderEnv }
+        : {}),
+      ...(entry.mcpServers === undefined
+        ? {}
+        : {
+            mcpServers: Object.fromEntries(
+              entry.mcpServers.map((server) => [
+                server.name,
+                { url: server.url, profile: server.profile },
+              ]),
+            ),
+          }),
+    };
   }
 
   return rendered;

package/src/shared/collect-agents.ts

@@ -3,6 +3,7 @@ import { checkGatewayAuth } from './check-gateway-auth';
 import type { GatewayAuth } from './check-gateway-auth';
 import type { AuthProfile } from './collect-auth-profiles';
 import { collectClaudeAuth } from './collect-claude-auth';
+import type { ClaudeMCPServer } from './collect-claude-auth';
 import { isSubscriptionOverrideVariable } from './is-subscription-override-variable';
 import { isRecord } from './report';
 
@@ -16,7 +17,8 @@ type AgentKind = 'claude' | 'codex' | 'grok';
  * and arguments it starts with, and, for a Claude entry, the settings, the
  * environment, and the backend and credential it runs against. A Claude entry
  * with a `baseURL` is a gateway; without one it is stock Claude, whose
- * `auth` holds profiles alone, for the subscription sign-in.
+ * `auth` holds profiles alone, for the subscription sign-in, and whose
+ * `mcpServers` reach their hosts through those profiles.
  */
 export interface AgentEntry {
   readonly id: AgentID;
@@ -30,6 +32,7 @@ export interface AgentEntry {
   readonly baseURL?: string;
   readonly apiKeyHelper?: string;
   readonly auth?: GatewayAuth;
+  readonly mcpServers?: readonly ClaudeMCPServer[];
 }
 
 interface CollectedAgents {
@@ -43,7 +46,8 @@ interface CollectedAgents {
  * Reads the `agents` map into registry order. An entry that is not an object,
  * sets an unknown field or a field outside its kind, holds a wrong-typed
  * value, or fails an auth check is left out with every problem that refused
- * it, and the other entries load. A value that is not an object leaves the
+ * it, and the other entries load. An MCP server that breaks a rule is left
+ * out of its entry with an error, and the entry loads. A value that is not an object leaves the
  * registry empty.
  */
 export function collectAgents(
@@ -64,6 +68,7 @@ export function collectAgents(
       errors.push(...parsed.problems.map((problem) => `agents.${id}: ${problem}`));
     } else {
       agents.push(parsed.entry);
+      errors.push(...(parsed.warnings ?? []).map((warning) => `agents.${id}: ${warning}`));
     }
   }
 
@@ -86,7 +91,9 @@ const DEFAULT_LABELS: Readonly<Record<AgentKind, string>> = {
   grok: 'Grok',
 };
 
-type ParsedEntry = { readonly entry: AgentEntry } | { readonly problems: string[] };
+type ParsedEntry =
+  | { readonly entry: AgentEntry; readonly warnings?: readonly string[] }
+  | { readonly problems: string[] };
 
 function parseAgentEntry(
   id: string,
@@ -125,7 +132,9 @@ function parseAgentEntry(
     return claude;
   }
 
-  return { entry: { ...entry, ...claude } };
+  const { warnings, ...read } = claude;
+
+  return { entry: { ...entry, ...read }, ...(warnings === undefined ? {} : { warnings }) };
 }
 
 // The entry's kind, or the problem that refuses it. An absent kind is the id
@@ -251,6 +260,12 @@ function buildDefaultLabel(id: string, kind: AgentKind): string {
   return id === kind ? DEFAULT_LABELS[kind] : id;
 }
 
+interface ReadClaudeAuth {
+  readonly auth?: GatewayAuth;
+  readonly mcpServers?: readonly ClaudeMCPServer[];
+  readonly warnings?: readonly string[];
+}
+
 // The `auth` a Claude entry holds, or every problem with it. With a base URL
 // the entry is a gateway and its auth is the gateway's. Without one it is
 // stock Claude, whose auth is profiles alone and whose environment may not
@@ -259,7 +274,7 @@ function readClaudeAuth(
   entry: AgentEntry,
   raw: unknown,
   authProfiles: ReadonlyMap<string, AuthProfile>,
-): { readonly auth?: GatewayAuth } | { readonly problems: string[] } {
+): ReadClaudeAuth | { readonly problems: string[] } {
   if (entry.baseURL !== undefined) {
     if (raw === undefined) {
       return {};
@@ -288,13 +303,21 @@ function readClaudeAuth(
 
   const collected = collectClaudeAuth(raw, authProfiles, 'auth');
 
-  problems.push(...collected.errors, ...collectSubscriptionProblems(entry));
+  problems.push(...collectSubscriptionProblems(entry));
 
-  if (problems.length > 0 || collected.auth === null) {
+  if (collected.auth === null) {
+    return { problems: [...collected.errors, ...problems] };
+  }
+
+  if (problems.length > 0) {
     return { problems };
   }
 
-  return { auth: { profiles: collected.auth.profiles, placeholderEnv: {} } };
+  return {
+    auth: { profiles: collected.auth.profiles, placeholderEnv: {} },
+    ...(collected.auth.mcpServers.length === 0 ? {} : { mcpServers: collected.auth.mcpServers }),
+    warnings: collected.errors,
+  };
 }
 
 // What a stock entry with `auth` sets that would override the subscription

package/src/shared/collect-claude-auth.ts

@@ -2,14 +2,28 @@ import type { AuthProfile } from './collect-auth-profiles';
 import { isRecord } from './report';
 import { resolveAuthProfiles } from './resolve-auth-profiles';
 
+/**
+ * An MCP server a stock Claude session on a target that reaches impd's
+ * broker reaches over HTTP, with the header that one of the session's
+ * profiles sets for the server's host. The session sends a placeholder in
+ * that header, and impd swaps the credential in on the host's side.
+ */
+export interface ClaudeMCPServer {
+  readonly name: string;
+  readonly url: string;
+  readonly profile: string;
+  readonly header: string;
+}
+
 /**
  * The profiles a stock Claude session on a target that reaches impd's
  * broker signs in through: one of them sends the subscription's setup
  * token to the Anthropic API as a bearer authorization header, and the
- * rest bind beside it, such as a GitHub token.
+ * rest bind beside it, such as a GitHub token or an MCP server's key.
  */
 interface ClaudeAuth {
   readonly profiles: readonly string[];
+  readonly mcpServers: readonly ClaudeMCPServer[];
 }
 
 interface CollectedClaudeAuth {
@@ -23,7 +37,8 @@ interface CollectedClaudeAuth {
  * does not resolve, or whose profiles send no bearer authorization header
  * to the Anthropic API, is left out with every problem that refused it, so
  * stock Claude keeps the sign-in of the host it runs on rather than binding
- * a credential the CLI would never send.
+ * a credential the CLI would never send. An MCP server that breaks a rule
+ * is left out alone, with an error, and the sign-in stays.
  */
 export function collectClaudeAuth(
   raw: unknown,
@@ -48,7 +63,7 @@ export function collectClaudeAuth(
     };
   }
 
-  const extra = Object.keys(raw).find((key) => key !== 'profiles');
+  const extra = Object.keys(raw).find((key) => key !== 'profiles' && key !== 'mcpServers');
 
   if (extra !== undefined) {
     return {
@@ -79,8 +94,106 @@ export function collectClaudeAuth(
     };
   }
 
-  return { auth: { profiles: selected }, errors: [] };
+  const servers = collectMCPServers(raw['mcpServers'], field, selected, authProfiles);
+
+  return { auth: { profiles: selected, mcpServers: servers.servers }, errors: servers.errors };
 }
 
 // The one host Claude Code sends a subscription token to.
 const ANTHROPIC_API_HOST = 'api.anthropic.com';
+
+interface CollectedMCPServers {
+  readonly servers: readonly ClaudeMCPServer[];
+  readonly errors: readonly string[];
+}
+
+// Reads the `mcpServers` map, server names to the server's URL and the
+// selected profile that carries its credential.
+function collectMCPServers(
+  raw: unknown,
+  field: string,
+  selected: readonly string[],
+  authProfiles: ReadonlyMap<string, AuthProfile>,
+): CollectedMCPServers {
+  if (raw === undefined) {
+    return { servers: [], errors: [] };
+  }
+
+  if (!isRecord(raw) || Array.isArray(raw)) {
+    return { servers: [], errors: [`${field}.mcpServers must be an object of named servers`] };
+  }
+
+  const servers: ClaudeMCPServer[] = [];
+  const errors: string[] = [];
+
+  for (const [name, entry] of Object.entries(raw)) {
+    const parsed = parseMCPServer(name, entry, field, selected, authProfiles);
+
+    if (typeof parsed === 'string') {
+      errors.push(`${field}.mcpServers.${name}: ${parsed}`);
+    } else {
+      servers.push(parsed);
+    }
+  }
+
+  return { servers, errors };
+}
+
+// Claude Code's rule for an MCP server's name.
+const MCP_SERVER_NAME = /^[\w-]{1,64}$/u;
+
+// The server an entry holds, or the first rule it breaks. The header comes
+// from the profile, so the header the session sends and the one impd swaps
+// the credential into never differ.
+function parseMCPServer(
+  name: string,
+  entry: unknown,
+  field: string,
+  selected: readonly string[],
+  authProfiles: ReadonlyMap<string, AuthProfile>,
+): ClaudeMCPServer | string {
+  if (!MCP_SERVER_NAME.test(name)) {
+    return 'a server name must be letters, digits, underscores or hyphens';
+  }
+
+  if (!isRecord(entry) || Array.isArray(entry)) {
+    return 'a server must be an object with url and profile';
+  }
+
+  const extra = Object.keys(entry).find((key) => key !== 'url' && key !== 'profile');
+
+  if (extra !== undefined) {
+    return `${extra} cannot be set: atc fixes the transport and the placeholder header`;
+  }
+
+  const url = entry['url'];
+  const profileName = entry['profile'];
+
+  if (typeof profileName !== 'string' || !selected.includes(profileName)) {
+    return `profile must be one of ${field}.profiles`;
+  }
+
+  const profile = authProfiles.get(profileName);
+
+  if (profile?.kind !== 'custom') {
+    return 'profile must be a custom profile, which sets one header for one host';
+  }
+
+  const parsedURL = typeof url === 'string' && URL.canParse(url) ? new URL(url) : null;
+
+  if (
+    parsedURL === null ||
+    parsedURL.protocol !== 'https:' ||
+    parsedURL.port !== '' ||
+    parsedURL.username !== '' ||
+    parsedURL.password !== ''
+  ) {
+    return 'url must be an https URL with no port and no user info';
+  }
+
+  if (parsedURL.hostname !== profile.host) {
+    return `url must be on ${profile.host}, the host profile ${profileName} sends its credential to`;
+  }
+
+  return { name, url: parsedURL.href, profile: profileName, header: profile.header };
+}

package/src/shared/collect-legacy-agents.ts

@@ -51,6 +51,9 @@ export function collectLegacyAgents(
       ...(claudeAuth.auth === null
         ? {}
         : { auth: { profiles: claudeAuth.auth.profiles, placeholderEnv: {} } }),
+      ...(claudeAuth.auth === null || claudeAuth.auth.mcpServers.length === 0
+        ? {}
+        : { mcpServers: claudeAuth.auth.mcpServers }),
     },
     {
       id: 'grok',