feat(agent-core-v2): add the unified MCP management plane

.changeset/respect-mcp-management-readiness.md

@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code": patch
+---
+
+Respect workspace trust and configuration readiness when managing MCP servers.

packages/agent-core-v2/AGENTS.md

@@ -63,6 +63,10 @@ Business code must not `import 'node:fs'`, write SQL, hand-roll append-logs / at
 
 One accepted exception: `features/tower/protocol` manages the `.tower/` directory inside the *user's* repository (worktree slots, comms files, activity log) — workspace content, not engine state — and is a verbatim port of the v1 protocol whose semantics (atomic tmp+rename, real `git` CLI for worktrees/merges) are the feature. It keeps direct `node:fs` / `node:child_process` access; do not "modernize" it onto the Stores above without a dedicated migration.
 
+## MCP management plane
+
+The App scope owns the process-wide MCP management surface, split across three domains: `mcpConfig` (`src/app/mcpConfig/` — the `[mcp]` config section, the layered mcp.json loader with per-entry origins, `IMcpConfigStore` as the single write point for the user-level `mcp.json`, `IMcpOAuthStore` credential persistence, and `IMcpOAuthService`, the process-wide OAuth orchestrator with credential events, single-flight refresh, and proactive refresh timers), `mcpRegistry` (`IMcpRegistryService` — the unified read view over the file layers and plugin manifests with `source`/`origin`/`mutable`; runtime-name collisions keep both entries, and runtime resolution ranks an enabled plugin entry above the file layers), and `mcpManagement` (`IMcpManagementService` — guarded CRUD, connection-test probes, the locator-addressed inspection/auth-status surface, and locator-addressed OAuth begin/complete/cancel/reset with ambiguity rejection). The engine services are ungated; the edge exposure (kap-server routes, klient facade) gates on the `mcp_management` flag. On the Workspace side, `workspaceMcpConfig` merges the same sources (same plugin-over-file precedence), watches the files and plugin reloads, follows the store's `onDidWrite` for immediate management-plane reloads, and publishes fingerprint diffs that `workspaceMcp` applies to the handler-shared `McpConnectionManager` (tombstones for removals); `workspaceMcp` also subscribes the OAuth service's credential events to reconnect affected entries. Session overlays (`session/mcp`) keep caller-injected ephemeral servers session-local.
+
 ## Session index
 
 `ISessionIndex` (`src/app/sessionIndex/`, App scope) serves session list/resume reads over two paths: the authoritative directory scan (`sessionIndexSource`, always correct, linear) and the minidb-backed derived read model (`IQueryStore` at `<home>/cache/query-store`, keyset-paged, `O(log N + limit)`), gated by the `persistence_minidb_readmodel` flag (default ON; roll back via `KIMI_CODE_EXPERIMENTAL_PERSISTENCE_MINIDB_READMODEL=false` or the `[experimental]` config section). The read model has an explicit lifecycle — `uninitialized → preparing → ready/degraded` via `prepare()`/`status()`; reads while preparing answer from the authoritative store immediately and fold the `ISessionIndexMirror` queue in for read-your-writes; the first list shares one single-flight authoritative scan with the initial projection. The query-store is structural-only — text-index definitions are rejected at definition level, so session operations never touch the global full-text index (`<home>/search-index`, owned by kap-server's search surface).

packages/agent-core-v2/src/app/mcpConfig/configLoader.ts

@@ -0,0 +1,196 @@
+import { dirname, isAbsolute, join, normalize, resolve } from 'pathe';
+
+import { resolveKimiHome } from '#/app/bootstrap/bootstrap';
+import { findGitWorkTree } from '#/app/git/workTree';
+import { ErrorCodes, Error2 } from '#/errors';
+import { McpServerConfigSchema, type McpServerConfig } from '#/mcpCore/config-schema';
+import type { IHostFileSystem } from '#/os/interface/hostFileSystem';
+import { OsFsErrors, HostFsError } from '#/os/interface/hostFsErrors';
+
+export interface McpJsonPaths {
+  readonly user: string;
+  readonly projectRoot: string;
+  readonly project: string;
+}
+
+export interface ResolveMcpJsonPathsInput {
+  readonly fs: IHostFileSystem;
+  readonly cwd: string;
+  readonly homeDir?: string;
+}
+
+export async function resolveMcpJsonPaths(input: ResolveMcpJsonPathsInput): Promise<McpJsonPaths> {
+  const start = normalize(input.cwd);
+  const projectRoot = (await findGitWorkTree(input.fs, start))?.root ?? start;
+
+  return {
+    user: join(resolveKimiHome(input.homeDir), 'mcp.json'),
+    projectRoot: join(projectRoot, '.mcp.json'),
+    project: join(input.cwd, '.kimi-code', 'mcp.json'),
+  };
+}
+
+export interface LoadMcpServersInput {
+  readonly fs: IHostFileSystem;
+  readonly cwd: string;
+  readonly homeDir?: string;
+  readonly includeProject?: boolean;
+}
+
+export interface LoadMcpServersDetailedResult {
+  /** Later layers override earlier ones with the same key. */
+  readonly servers: Record<string, McpServerConfig>;
+  /** The file each effective entry was last defined in. */
+  readonly origins: Record<string, string>;
+}
+
+export async function loadMcpServers(
+  input: LoadMcpServersInput,
+): Promise<Record<string, McpServerConfig>> {
+  return (await loadMcpServersDetailed(input)).servers;
+}
+
+/**
+ * {@link loadMcpServers} plus the defining-file origin of every effective
+ * entry, for management surfaces that show where a server came from.
+ */
+export async function loadMcpServersDetailed(
+  input: LoadMcpServersInput,
+): Promise<LoadMcpServersDetailedResult> {
+  const paths = await resolveMcpJsonPaths(input);
+  if (input.includeProject === false) {
+    const user = await readMcpJson(input.fs, paths.user);
+    return { servers: user, origins: mapValuesToPath(user, paths.user) };
+  }
+  const layers: readonly [path: string, servers: Record<string, McpServerConfig>][] =
+    await Promise.all([
+      readMcpJson(input.fs, paths.user),
+      readMcpJson(input.fs, paths.projectRoot, { stdioCwdBase: dirname(paths.projectRoot) }),
+      readMcpJson(input.fs, paths.project),
+    ]).then(([user, projectRoot, project]) => [
+      [paths.user, user],
+      [paths.projectRoot, projectRoot],
+      [paths.project, project],
+    ]);
+  const servers: Record<string, McpServerConfig> = Object.create(null);
+  const origins: Record<string, string> = Object.create(null);
+  for (const [path, layer] of layers) {
+    for (const [name, config] of Object.entries(layer)) {
+      servers[name] = config;
+      origins[name] = path;
+    }
+  }
+  return { servers, origins };
+}
+
+interface ReadMcpJsonOptions {
+  readonly stdioCwdBase?: string;
+}
+
+async function readMcpJson(
+  fs: IHostFileSystem,
+  filePath: string,
+  options: ReadMcpJsonOptions = {},
+): Promise<Record<string, McpServerConfig>> {
+  let text: string;
+  try {
+    text = await fs.readText(filePath);
+  } catch (error: unknown) {
+    if (isFileNotFound(error)) return {};
+    throw new Error2(
+      ErrorCodes.CONFIG_INVALID,
+      `Failed to read ${filePath}: ${describeError(error)}`,
+      {
+        cause: error,
+      },
+    );
+  }
+
+  if (text.trim().length === 0) return {};
+
+  let data: unknown;
+  try {
+    data = JSON.parse(text);
+  } catch (error: unknown) {
+    throw new Error2(
+      ErrorCodes.CONFIG_INVALID,
+      `Invalid JSON in ${filePath}: ${describeError(error)}`,
+      {
+        cause: error,
+      },
+    );
+  }
+
+  try {
+    return normalizeMcpServers(parseMcpJsonServers(data), options);
+  } catch (error: unknown) {
+    throw new Error2(
+      ErrorCodes.CONFIG_INVALID,
+      `Invalid MCP server config in ${filePath}: ${describeError(error)}`,
+      {
+        cause: error,
+      },
+    );
+  }
+}
+
+function parseMcpJsonServers(data: unknown): Record<string, McpServerConfig> {
+  if (!isRecord(data)) {
+    throw new Error('expected a JSON object');
+  }
+  const raw = data['mcpServers'] ?? {};
+  if (!isRecord(raw)) {
+    throw new Error('"mcpServers" must be an object');
+  }
+  return Object.fromEntries(
+    Object.entries(raw).map(([name, value]) => [name, McpServerConfigSchema.parse(value)]),
+  );
+}
+
+function normalizeMcpServers(
+  servers: Record<string, McpServerConfig>,
+  options: ReadMcpJsonOptions,
+): Record<string, McpServerConfig> {
+  const stdioCwdBase = options.stdioCwdBase;
+  if (stdioCwdBase === undefined) return servers;
+
+  return Object.fromEntries(
+    Object.entries(servers).map(([name, config]) => [
+      name,
+      normalizeStdioCwd(config, stdioCwdBase),
+    ]),
+  );
+}
+
+function normalizeStdioCwd(config: McpServerConfig, cwdBase: string): McpServerConfig {
+  if (config.transport !== 'stdio') return config;
+  const cwd = config.cwd === undefined ? cwdBase : resolvePath(cwdBase, config.cwd);
+  return { ...config, cwd };
+}
+
+function mapValuesToPath(
+  servers: Record<string, McpServerConfig>,
+  path: string,
+): Record<string, string> {
+  const origins: Record<string, string> = Object.create(null);
+  for (const name of Object.keys(servers)) {
+    origins[name] = path;
+  }
+  return origins;
+}
+
+function resolvePath(base: string, value: string): string {
+  return isAbsolute(value) ? normalize(value) : resolve(base, value);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isFileNotFound(error: unknown): boolean {
+  return error instanceof HostFsError && error.code === OsFsErrors.codes.OS_FS_NOT_FOUND;
+}
+
+function describeError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}