/**
 * 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';
    command?: string;
    args?: string[];
    env?: Record<string, string>;
    url?: string;
}
export interface InstalledMcpServer {
    name: string;
    path: string;
    config: McpYamlConfig;
    scope?: 'user' | 'project';
}
export interface McpCommandSpec {
    command: string;
    args: string[];
}
export interface McpTargetOperationResult {
    agentId: AgentId;
    version?: string;
    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';
    command?: string;
    args?: string[];
    env?: Record<string, string>;
    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;
}): {
    success: boolean;
    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;
