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.

.changeset/sdk-mcp-management-cwd.md

@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code-sdk": patch
+---
+
+Add an optional cwd parameter to global MCP management and authorization methods for project-layer-aware operations. MCP auth-status reads preserve implicit OAuth detection by default; pass verify: false for stored-credential-only classification or verify: true to verify every candidate.

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; a project layer joins the view only when the queried cwd itself is trusted, matching what the workspace runtime would load), and `mcpManagement` (`IMcpManagementService` — guarded CRUD (a mutable user-level entry stays writable past a read-only collision), connection-test probes, the locator-addressed inspection/auth-status surface, and locator-addressed OAuth begin/complete/cancel/reset with ambiguity rejection plus an idle timeout that cancels abandoned flows). The engine services and the edge exposure (kap-server routes, klient facade) are ungated. 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/_base/event.ts

@@ -112,6 +112,24 @@ export type IWaitUntilData<T> = Omit<T, 'waitUntil' | 'signal'>;
 export class AsyncEmitter<T extends IWaitUntil> extends Emitter<T> {
   private _asyncDeliveryQueue?: LinkedList<[(event: T) => void, IWaitUntilData<T>]>;
 
+  async fireAsyncConcurrent(data: IWaitUntilData<T>, signal: AbortSignal): Promise<void> {
+    if (this.isDisposed || this._listeners === undefined || signal.aborted) {
+      return;
+    }
+    const snapshot = Array.from(this._listeners);
+    await Promise.all(
+      snapshot.map((entry) =>
+        this.deliverAsync(
+          (event) => {
+            entry.listener.call(entry.thisArg, event);
+          },
+          data,
+          signal,
+        ),
+      ),
+    );
+  }
+
   async fireAsync(data: IWaitUntilData<T>, signal: AbortSignal): Promise<void> {
     if (this.isDisposed || this._listeners === undefined) {
       return;
@@ -129,32 +147,37 @@ export class AsyncEmitter<T extends IWaitUntil> extends Emitter<T> {
 
     while (this._asyncDeliveryQueue.size > 0 && !signal.aborted) {
       const [deliver, eventData] = this._asyncDeliveryQueue.shift()!;
-      const thenables: Promise<unknown>[] = [];
-
-      const event = {
-        ...eventData,
-        signal,
-        waitUntil: (p: Promise<unknown>): void => {
-          if (Object.isFrozen(thenables)) {
-            throw new Error('waitUntil can NOT be called asynchronously');
-          }
-          thenables.push(p);
-        },
-      } as T;
-
-      try {
-        deliver(event);
-      } catch (error) {
-        onUnexpectedError(error);
-        continue;
-      }
+      await this.deliverAsync(deliver, eventData, signal);
+    }
+  }
 
-      void Object.freeze(thenables);
-      const settled = await Promise.allSettled(thenables);
-      for (const result of settled) {
-        if (result.status === 'rejected') {
-          onUnexpectedError(result.reason);
+  private async deliverAsync(
+    deliver: (event: T) => void,
+    data: IWaitUntilData<T>,
+    signal: AbortSignal,
+  ): Promise<void> {
+    const thenables: Promise<unknown>[] = [];
+    const event = {
+      ...data,
+      signal,
+      waitUntil: (p: Promise<unknown>): void => {
+        if (Object.isFrozen(thenables)) {
+          throw new Error('waitUntil can NOT be called asynchronously');
         }
+        thenables.push(p);
+      },
+    } as T;
+    try {
+      deliver(event);
+    } catch (error) {
+      onUnexpectedError(error);
+      return;
+    }
+    void Object.freeze(thenables);
+    const settled = await Promise.allSettled(thenables);
+    for (const result of settled) {
+      if (result.status === 'rejected') {
+        onUnexpectedError(result.reason);
       }
     }
   }

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

@@ -0,0 +1,197 @@
+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');
+  }
+  if (!('mcpServers' in data)) return {};
+  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);
+}