@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/mcp-registry.js

@@ -1,52 +1,10 @@
-/**
- * Declarative MCP-target registry.
- *
- * Every MCP-capable agent gets ONE entry (`MCP_TARGETS`) describing where its
- * MCP config lives (version home, global user scope, project scope) and which
- * serialization format that file uses. Generic path resolution, config writing,
- * config parsing, and install now read this table instead of the four
- * independent `switch (agentId)` / `if (agentId === '...')` chains that used to
- * be copy-pasted across `lib/agents.ts`, `lib/mcp.ts`, and a since-deleted
- * `lib/resources/mcp.ts` (RUSH-2695) -- which had *different* membership sets, so
- * a harness could resolve a config path and then be silently skipped by the
- * writer, or be written to one file and read back from another.
- *
- * The membership set is pinned to `capableAgents('mcp')` by
- * `mcp-registry.test.ts`, so a newly added harness cannot start out "capable"
- * and quietly no-op: it must either declare a format here or declare, in
- * `format: null` + `unsupportedReason`, that agents-cli cannot write its config
- * yet. A `null` format still resolves paths (the reader and the staleness
- * detector need them); only the write path refuses, and it refuses loudly.
- *
- * Drift this table fixed, each verified against the harness's own docs or an
- * installed config dir:
- *
- *   - antigravity: MCP lives in the shared `~/.gemini/config/`, not the
- *     per-version `~/.gemini/antigravity-cli/` state dir (agy's bundled
- *     `agy-customizations/docs/mcp_servers.md`, and the file agy itself creates
- *     at `~/.gemini/config/mcp_config.json`) -- and its remote transport key is
- *     `serverUrl`, not `url`.
- *   - grok: MCP is `[mcp_servers.<name>]` inside `~/.grok/config.toml`
- *     (`~/.grok/docs/user-guide/07-mcp-servers.md`). The user-scope path said
- *     `.grok/mcp.json` and the parser read it as JSON, so nothing round-tripped.
- *   - kimi: the installer wrote `.kimi-code/mcp.json` while the path resolver
- *     answered `.kimi-code/settings.json`, so the staleness detector never saw
- *     what the writer had just written.
- */
 import * as os from 'os';
 import * as path from 'path';
-/** The user's real home — read at call time so a test's HOME override applies. */
 function realHome() {
     return process.env.HOME ?? os.homedir();
 }
-/**
- * Single source of truth for every MCP-capable agent's config location and
- * format. Keys MUST equal `capableAgents('mcp')` -- pinned by
- * `mcp-registry.test.ts`.
- */
 export const MCP_TARGETS = {
     claude: {
-        // Claude reads user-scope MCP from ~/.claude.json, not .claude/settings.json.
         home: (h) => path.join(h, '.claude.json'),
         project: (cwd) => path.join(cwd, '.mcp.json'),
         format: 'claude-json',
@@ -64,7 +22,6 @@ export const MCP_TARGETS = {
         format: 'claude-json',
     },
     opencode: {
-        // OpenCode loads ~/.config/opencode/opencode.jsonc, not ~/.opencode/.
         home: (h) => path.join(h, '.config', 'opencode', 'opencode.jsonc'),
         project: (cwd) => path.join(cwd, 'opencode.jsonc'),
         format: 'opencode-jsonc',
@@ -75,20 +32,12 @@ export const MCP_TARGETS = {
         format: 'openclaw-json',
     },
     antigravity: {
-        // NOT version-isolated, and `home` is deliberately ignored. agy reads MCP
-        // from `~/.gemini/config/mcp_config.json` in the user's REAL home: only
-        // `~/.gemini/antigravity-cli` is symlinked into a version home, while
-        // `~/.gemini/config` is a plain directory agy opens directly. Writing under
-        // a version home therefore lands somewhere agy never reads -- the same
-        // reason `antigravityWorkflowsDir` (lib/workflows.ts) ignores versionHome,
-        // where it is strace-verified against a running agy.
         home: () => path.join(realHome(), '.gemini', 'config', 'mcp_config.json'),
         project: (cwd) => path.join(cwd, '.gemini', 'config', 'mcp_config.json'),
         format: 'antigravity-json',
         homeGlobal: true,
     },
     grok: {
-        // Grok's MCP servers are [mcp_servers.<name>] tables in config.toml.
         home: (h) => path.join(h, '.grok', 'config.toml'),
         project: (cwd) => path.join(cwd, '.grok', 'config.toml'),
         format: 'toml',
@@ -114,16 +63,10 @@ export const MCP_TARGETS = {
         format: 'muse-json',
     },
     warp: {
-        // Oz reads the Claude .mcp.json schema from ~/.warp/ and <root>/.warp/.
         home: (h) => path.join(h, '.warp', '.mcp.json'),
         project: (cwd) => path.join(cwd, '.warp', '.mcp.json'),
         format: 'claude-json',
     },
-    // ── paths known, write format not implemented ──────────────────────────────
-    // These four resolve paths (so `agents mcp list` and the staleness detector
-    // still work) but refuse the write instead of no-opping. Implementing one
-    // means verifying its schema against the installed harness, then setting
-    // `format` here -- nothing else changes.
     copilot: {
         home: (h) => path.join(h, '.copilot', 'mcp-config.json'),
         project: (cwd) => path.join(cwd, '.copilot', 'mcp-config.json'),
@@ -143,16 +86,9 @@ export const MCP_TARGETS = {
         unsupportedReason: 'Goose declares MCP servers as `extensions:` entries, not an mcp_servers map',
     },
 };
-/** The registry entry for `agent`, or undefined when it stores no MCP config. */
 export function mcpTarget(agent) {
     return MCP_TARGETS[agent];
 }
-/**
- * Why the write path refuses `agent`, or null when it can write.
- *
- * Two distinct refusals, both loud: the agent has no entry at all (not
- * MCP-capable, or a hard-deprecated id), or it has one with `format: null`.
- */
 export function mcpWriteUnsupportedReason(agent) {
     const target = MCP_TARGETS[agent];
     if (!target)

package/dist/lib/mcp.d.ts

@@ -1,16 +1,4 @@
-/**
- * MCP server management - reading from ~/.agents/mcp/ and applying to agent configs.
- *
- * MCP servers are stored as YAML files in ~/.agents/mcp/:
- *   ~/.agents/mcp/swarm.yaml
- *   ~/.agents/mcp/figma.yaml
- *
- * Each file defines a server that gets applied (merged) into agent configs during sync.
- */
 import type { AgentId } from './types.js';
-/**
- * MCP server config as stored in ~/.agents/mcp/*.yaml
- */
 export interface McpYamlConfig {
     name: string;
     transport: 'stdio' | 'http';
@@ -35,92 +23,31 @@ export interface McpTargetOperationResult {
     success: boolean;
     error?: string;
 }
-/**
- * Parse an MCP server config from a YAML file.
- */
 export declare function parseMcpServerConfig(filePath: string): McpYamlConfig | null;
-/**
- * Validate an MCP server name. Rejects names that could be misinterpreted as
- * command-line options or that contain characters unsafe for argv/identifier use.
- */
 export declare function validateMcpServerName(name: string): void;
-/** Path to the user-owned project-trust store (never inside a repo). */
 export declare function getMcpTrustStorePath(): string;
-/**
- * Whether the project that owns `projectAgentsDir` has been explicitly trusted
- * for MCP auto-apply. Untrusted by default (fail closed).
- */
 export declare function isProjectMcpTrusted(projectAgentsDir: string): boolean;
-/**
- * Record explicit trust for the project containing `cwd` so its project-scoped
- * MCP servers may be registered/spawned. Returns the trusted project root, or
- * null when `cwd` is not inside a project (no `.agents/` to trust).
- */
 export declare function trustProjectMcp(cwd?: string): string | null;
-/** Revoke MCP trust for the project containing `cwd`. Returns true if it was trusted. */
 export declare function untrustProjectMcp(cwd?: string): boolean;
-/**
- * List all MCP server configs from ~/.agents/mcp/.
- *
- * When `enforceProjectTrust` is set, project-scoped configs are included only
- * for a project the user has explicitly trusted (see `isProjectMcpTrusted`) —
- * this is the choke point that keeps an untrusted cloned repo's MCP servers out
- * of the register/spawn path. It ALSO fixes name-collision shadowing: an
- * untrusted project entry is dropped before dedup, so it can never mask a
- * same-named user entry. Display callers omit the flag to surface project
- * entries (command+args and all) regardless of trust.
- */
 export declare function listMcpServerConfigs(cwd?: string, options?: {
     enforceProjectTrust?: boolean;
 }): InstalledMcpServer[];
-/**
- * Parse one config during a directory SCAN. `validateMcpYamlConfig` returns null
- * for some malformed shapes but *throws* for others (`args` not a string array,
- * `command`/`env` of the wrong type), and a scan must not be all-or-nothing: a
- * single bad file under `<repo>/mcp/` took down the whole of
- * `agents inspect <repo>` with an unhandled stack trace. Skip the file and name
- * it, exactly as a null return is already skipped. Explicit single-file
- * operations call `parseMcpServerConfig` directly and still throw loudly.
- */
 export declare function parseMcpConfigForScan(filePath: string): McpYamlConfig | null;
-/**
- * Scan a repository for MCP server YAML configs.
- * Looks under <repoPath>/mcp/*.yaml — same on-disk layout as ~/.agents/mcp/.
- */
 export declare function discoverMcpConfigsFromRepo(repoPath: string): InstalledMcpServer[];
-/**
- * Install an MCP YAML config from a source file into ~/.agents/mcp/.
- * Re-serializes via writeMcpServerConfig so the on-disk filename is
- * deterministic (sanitized from the server name).
- */
 export declare function installMcpConfigCentrally(sourcePath: string): {
     success: boolean;
     error?: string;
     path?: string;
 };
-/**
- * Get MCP servers by name.
- * If names is provided, returns only those servers.
- * Otherwise returns all servers.
- */
 export declare function getMcpServersByName(names?: string[], options?: {
     cwd?: string;
     enforceProjectTrust?: boolean;
 }): InstalledMcpServer[];
-/**
- * Assemble the JSON payload Claude's `--mcp-config` flag expects from a set of
- * installed MCP servers: `{ "mcpServers": { "<name>": { command, args, env } | { url } } }`.
- * Pure — takes servers, returns a JSON string. The caller writes it to an
- * ephemeral file and passes the path to buildExecCommand.
- */
 export declare function buildWorkflowMcpConfig(servers: InstalledMcpServer[]): string;
 export declare function registerMcpCommandToTargets(targets: {
     directAgents: AgentId[];
     versionSelections: Map<AgentId, string[]>;
 }, name: string, commandSpec: McpCommandSpec, scope?: 'user' | 'project', transport?: string): Promise<McpTargetOperationResult[]>;
-/**
- * MCP server shaped for direct config-file serialization.
- */
 export interface WritableMcpServer {
     name: string;
     transport: 'stdio' | 'http' | 'sse';
@@ -130,37 +57,9 @@ export interface WritableMcpServer {
     url?: string;
     headers?: Record<string, string>;
 }
-/**
- * Serialize MCP servers into an agent-specific config file.
- *
- * The format comes from `MCP_TARGETS` (lib/mcp-registry.ts), so a harness whose
- * schema is not implemented **throws** here rather than falling through the
- * switch and returning as if it had written something. `installMcpServers`
- * catches that and reports it as an error, never as a silent success.
- *
- * `mode: 'overwrite'` replaces the whole MCP section (used for tool-managed
- * version-home configs). `mode: 'merge'` updates/adds the provided server
- * entries while preserving existing entries (used for project-level configs
- * that users may hand-edit or populate via agent CLI commands).
- *
- * An empty `servers` list is a no-op by default — most callers pass a
- * resolved-but-possibly-empty selection and an empty one means "nothing to
- * apply," not "clear whatever is there," so this must never wipe an existing
- * config out from under an unrelated caller. `options.allowEmpty` is the
- * explicit opt-in for a caller that owns the ENTIRE mcp section by
- * construction (it always knows the complete current desired server set,
- * including the empty set) and needs `overwrite` to actually clear it —
- * still only the mcp section: `readExistingConfig` above preserves every
- * other top-level key already, in both modes.
- */
 export declare function writeMcpConfig(agentId: AgentId, configPath: string, servers: WritableMcpServer[], mode?: 'overwrite' | 'merge', options?: {
     allowEmpty?: boolean;
 }): void;
-/**
- * Install MCP servers to an agent.
- * For Claude/Codex: uses CLI commands (claude mcp add, codex mcp add)
- * For others: edits config files directly
- */
 export declare function installMcpServers(agentId: AgentId, version: string, versionHome: string, mcpNames?: string[], options?: {
     cwd?: string;
 }): {
@@ -168,20 +67,6 @@ export declare function installMcpServers(agentId: AgentId, version: string, ver
     applied: string[];
     errors: string[];
 };
-/**
- * Write an MCP server config to ~/.agents/mcp/.
- */
 export declare function writeMcpServerConfig(config: McpYamlConfig): string;
-/**
- * True when MCP server `name` materialized in `agent`'s version home byte-matches
- * the resolved SOURCE definition `source` — the content-drift predicate `agents
- * doctor` uses. Parses the home's canonical MCP config for the harness (no
- * `claude mcp add` shell-out — the on-disk file is parseable) and structurally
- * compares command/args/env/url. Returns false when the server is absent from
- * the home (surfaced as `missing`/`extra` at the name level, not here).
- */
 export declare function mcpServerMatches(agent: AgentId, versionHome: string, name: string, source: McpYamlConfig): boolean;
-/**
- * Remove an MCP server config from ~/.agents/mcp/.
- */
 export declare function removeMcpServerConfig(name: string): boolean;