@moxxy/plugin-mcp 0.26.0

package/src/admin/config-io.ts

@@ -0,0 +1,112 @@
+import { promises as fs } from 'node:fs';
+import { createMutex } from '@moxxy/sdk';
+import { moxxyPath, writeFileAtomic } from '@moxxy/sdk/server';
+import { mcpStoredConfigRootSchema, mcpStoredServerSchema } from './config-schema.js';
+import type { McpStoredConfig, McpStoredServer } from './types.js';
+
+/**
+ * User-level MCP server catalog persisted at ~/.moxxy/mcp.json. Mutated
+ * by the admin tools; read at boot by @moxxy/cli setup to spin up
+ * connection plugins. JSON (not yaml) for trivial parse/write — these
+ * entries are programmatically managed, the user doesn't normally edit
+ * them by hand.
+ */
+export function mcpConfigPath(): string {
+  return moxxyPath('mcp.json');
+}
+
+/**
+ * Serializes the read-modify-write cycle of every config mutator so that
+ * concurrent mcp_add_server / mcp_remove_server (or enable/disable) calls
+ * can't interleave their read + write and clobber the file.
+ */
+const configMutex = createMutex();
+
+export async function readMcpConfig(): Promise<McpStoredConfig> {
+  try {
+    const raw = await fs.readFile(mcpConfigPath(), 'utf8');
+    const root = mcpStoredConfigRootSchema.safeParse(JSON.parse(raw));
+    if (!root.success) {
+      // The top-level shape is unusable (e.g. `servers` isn't an array) —
+      // treat as empty rather than crashing. The bad file is left in place
+      // so the user can inspect it.
+      return { servers: [] };
+    }
+    // Parse each entry independently and KEEP the valid ones. A single
+    // hand-edited bad row (e.g. a missing/empty `name`) must not strand every
+    // other configured server from boot/list/enable/remove — drop only the
+    // offending row. `.passthrough()` keeps each entry's opaque extras intact.
+    const servers: unknown[] = [];
+    for (const entry of root.data.servers) {
+      const parsed = mcpStoredServerSchema.safeParse(entry);
+      if (parsed.success) servers.push(parsed.data);
+    }
+    return { servers } as unknown as McpStoredConfig;
+  } catch {
+    // missing or malformed JSON — treat as empty
+  }
+  return { servers: [] };
+}
+
+export async function writeMcpConfig(cfg: McpStoredConfig): Promise<void> {
+  // Trailing newline preserved for editor-friendliness / clean diffs.
+  await writeFileAtomic(mcpConfigPath(), JSON.stringify(cfg, null, 2) + '\n');
+}
+
+/**
+ * Read-modify-write the catalog under the shared mutex. The mutator
+ * receives the freshly-read config and returns the next one; it is read
+ * and written as one critical section so concurrent admin mutators can't
+ * interleave and clobber each other. Returns whatever the mutator returns
+ * so callers can thread through derived values (e.g. the updated entry).
+ *
+ * Returning the same `cfg` object reference skips the write entirely — a
+ * no-op mutation (e.g. removing a name that isn't present) leaves the file
+ * untouched.
+ */
+export async function mutateMcpConfig<T>(
+  fn: (cfg: McpStoredConfig) => { next: McpStoredConfig; result: T } | Promise<{ next: McpStoredConfig; result: T }>,
+): Promise<T> {
+  return configMutex.run(async () => {
+    const cfg = await readMcpConfig();
+    const { next, result } = await fn(cfg);
+    if (next !== cfg) await writeMcpConfig(next);
+    return result;
+  });
+}
+
+/**
+ * Set a server's `disabled` flag in mcp.json. Used by both `moxxy mcp
+ * enable/disable` (CLI) and the `/mcp` slash command (TUI) — those
+ * paths bypass the model and write directly. Returns the updated entry,
+ * or null if no server with that name exists.
+ *
+ * Runtime detach (when disabling) and lazy re-attach (when enabling)
+ * are NOT performed here — callers in a live session need to call into
+ * the admin plugin's runtime API for that.
+ */
+export async function setServerDisabled(name: string, disabled: boolean): Promise<McpStoredServer | null> {
+  return mutateMcpConfig((cfg) => {
+    const idx = cfg.servers.findIndex((s) => s.name === name);
+    // Unknown name → same reference skips the write (mutateMcpConfig no-op).
+    if (idx < 0) return { next: cfg, result: null };
+    const updated: McpStoredServer = { ...cfg.servers[idx]!, disabled };
+    const nextServers = [...cfg.servers];
+    nextServers[idx] = updated;
+    return { next: { servers: nextServers }, result: updated };
+  });
+}
+
+/**
+ * Drop a server from the catalog by name. Returns true if anything was
+ * removed. Does NOT touch a live session's tool registry.
+ */
+export async function removeServerFromConfig(name: string): Promise<boolean> {
+  return mutateMcpConfig((cfg) => {
+    const before = cfg.servers.length;
+    const next = cfg.servers.filter((s) => s.name !== name);
+    // Nothing matched → same reference skips the write (mutateMcpConfig no-op).
+    if (next.length === before) return { next: cfg, result: false };
+    return { next: { servers: next }, result: true };
+  });
+}

package/src/admin/config-schema.ts

@@ -0,0 +1,39 @@
+import { z } from '@moxxy/sdk';
+import type { McpStoredConfig } from './types.js';
+
+/**
+ * Runtime shape guard for ~/.moxxy/mcp.json. Intentionally permissive:
+ * the catalog is programmatically managed and carries fields the admin
+ * tools care about (`name`, transport config) plus opaque extras
+ * (`cachedTools`, future flags) that must survive a read/write round-trip
+ * untouched — hence `.passthrough()` on each entry and on the root. We
+ * validate the structural invariant the loader relies on (a non-empty
+ * `name`) per entry.
+ */
+export const mcpStoredServerSchema = z
+  .object({
+    name: z.string().min(1),
+  })
+  .passthrough();
+
+/**
+ * Top-level guard only: `servers` must be an array. Each element is parsed
+ * INDIVIDUALLY by `readMcpConfig` against `mcpStoredServerSchema` so one bad
+ * row drops alone instead of stranding the whole catalog. Element type is
+ * `unknown` here on purpose — per-entry validation happens at read time.
+ */
+export const mcpStoredConfigRootSchema = z
+  .object({
+    servers: z.array(z.unknown()),
+  })
+  .passthrough();
+
+export const mcpStoredConfigSchema = z
+  .object({
+    servers: z.array(mcpStoredServerSchema),
+  })
+  .passthrough()
+  // The structural guard above is looser than the McpStoredConfig type
+  // (server transport fields are validated lazily at connect time), so
+  // re-assert the nominal type on the parsed output.
+  .transform((value) => value as unknown as McpStoredConfig);

package/src/admin/index.ts

@@ -0,0 +1,225 @@
+import { definePlugin, type LifecycleHooks, type Plugin } from '@moxxy/sdk';
+import { moxxyPath } from '@moxxy/sdk/server';
+import type { McpSecretResolver } from './secrets.js';
+import { readMcpConfig } from './config-io.js';
+import { createMcpRuntime } from './runtime.js';
+import { createMcpUsageSkillWriter } from './skill.js';
+import { buildAddServerTool } from './tools/add.js';
+import { buildListServersTool } from './tools/list.js';
+import { buildRemoveServerTool } from './tools/remove.js';
+import { buildTestServerTool } from './tools/test.js';
+import type {
+  AdminSkillRegistryLike,
+  AdminToolRegistryLike,
+  BuildMcpAdminPluginOptions,
+  McpAdminApi,
+  McpStoredConfig,
+  McpStoredServer,
+} from './types.js';
+
+export type {
+  AdminSkillRegistryLike,
+  AdminToolRegistryLike,
+  BuildMcpAdminPluginOptions,
+  McpAdminApi,
+  McpRuntimeHandle,
+  McpServerStatus,
+  McpStoredConfig,
+  McpStoredServer,
+} from './types.js';
+export {
+  mcpConfigPath,
+  readMcpConfig,
+  removeServerFromConfig,
+  setServerDisabled,
+  writeMcpConfig,
+} from './config-io.js';
+export { resolveServerSecrets, type McpSecretResolver } from './secrets.js';
+
+export function buildMcpAdminPluginWithApi(
+  opts: BuildMcpAdminPluginOptions = { toolRegistry: null },
+): { plugin: Plugin; api: McpAdminApi } {
+  return buildMcpAdminPluginInternal(opts);
+}
+
+export function buildMcpAdminPlugin(opts: BuildMcpAdminPluginOptions = { toolRegistry: null }): Plugin {
+  return buildMcpAdminPluginInternal(opts).plugin;
+}
+
+function lazyRegistryProxy<T extends object>(get: () => T | null, label: string): T {
+  return new Proxy({} as T, {
+    get(_target, prop) {
+      const resolved = get();
+      if (!resolved) {
+        throw new Error(`@moxxy/plugin-mcp: the "${label}" service is unavailable — the host must publish it`);
+      }
+      const value = (resolved as unknown as Record<string | symbol, unknown>)[prop];
+      return typeof value === 'function'
+        ? (value as (...args: unknown[]) => unknown).bind(resolved)
+        : value;
+    },
+  });
+}
+
+/**
+ * Discovery-loadable default export. Resolves the tool + skill registries and
+ * the secret resolver from the inter-plugin service registry in `onInit` (the
+ * host publishes `'tools'`/`'skills'`; the vault plugin publishes `'resolveSecrets'`),
+ * then publishes its runtime control api as the `'mcpAdmin'` service — which
+ * core's `Session.mcpAdmin` getter exposes to the runner + desktop. Lazy
+ * `Proxy`s defer every registry call to the resolved instance, so the tools +
+ * the boot-time lazy-stub registration run unchanged once `onInit` has wired it.
+ */
+export const mcpAdminPlugin: Plugin = (() => {
+  let resolvedTools: AdminToolRegistryLike | null = null;
+  let resolvedSkills: AdminSkillRegistryLike | null = null;
+  let resolvedSecrets: McpSecretResolver | null = null;
+
+  const lazyTools = lazyRegistryProxy<AdminToolRegistryLike>(() => resolvedTools, 'tools');
+  const lazySkills = lazyRegistryProxy<AdminSkillRegistryLike>(() => resolvedSkills, 'skills');
+  const secretResolver: McpSecretResolver = (value) =>
+    resolvedSecrets ? resolvedSecrets(value) : Promise.resolve(value);
+
+  const { plugin, api } = buildMcpAdminPluginWithApi({
+    toolRegistry: lazyTools,
+    skillRegistry: lazySkills,
+    secretResolver,
+  });
+  const innerOnInit = plugin.hooks?.onInit;
+
+  const hooks: LifecycleHooks = {
+    ...plugin.hooks,
+    onInit: async (ctx) => {
+      resolvedTools = ctx.services.get<AdminToolRegistryLike>('tools') ?? null;
+      resolvedSkills = ctx.services.get<AdminSkillRegistryLike>('skills') ?? null;
+      resolvedSecrets = ctx.services.get<McpSecretResolver>('resolveSecrets') ?? null;
+      ctx.services.register('mcpAdmin', api);
+      // Now the registry is resolved → register lazy stubs for saved servers.
+      await innerOnInit?.(ctx);
+    },
+  };
+
+  return definePlugin({ ...plugin, hooks });
+})();
+
+/**
+ * Build the MCP admin plugin: tools that let the agent register and
+ * manage MCP servers at runtime. When wired to a live tool registry,
+ * adds hot-attach so newly-registered servers are callable in the same
+ * session without a restart.
+ */
+function buildMcpAdminPluginInternal(
+  opts: BuildMcpAdminPluginOptions,
+): { plugin: Plugin; api: McpAdminApi } {
+  const registry = opts.toolRegistry;
+  const skillRegistry = opts.skillRegistry ?? null;
+  const userSkillsDir = opts.userSkillsDir ?? moxxyPath('skills');
+  const secretResolver = opts.secretResolver ?? null;
+
+  const runtime = createMcpRuntime(registry, { secretResolver });
+  const writeMcpUsageSkill = createMcpUsageSkillWriter({ skillRegistry, userSkillsDir });
+
+  const api: McpAdminApi = {
+    enableAndAttach: async (name) => {
+      const cfg = await readMcpConfig();
+      const found = cfg.servers.find((s) => s.name === name);
+      if (!found) return null;
+      let entry: McpStoredServer = found;
+      if (!entry.cachedTools || entry.cachedTools.length === 0) {
+        entry = await runtime.refreshServerCache(entry);
+      }
+      return runtime.attachServerLazy(entry);
+    },
+    detach: runtime.detachServer,
+    listServers: async () => {
+      const cfg = await readMcpConfig();
+      return cfg.servers.map((s) => ({
+        name: s.name,
+        enabled: s.disabled !== true,
+        connected: runtime.runtimes.has(s.name),
+      }));
+    },
+  };
+
+  const plugin = definePlugin({
+    name: '@moxxy/plugin-mcp',
+    version: '0.0.0',
+    tools: [
+      buildListServersTool(),
+      buildAddServerTool({
+        registry,
+        attachServer: runtime.attachServer,
+        detachServer: runtime.detachServer,
+        writeMcpUsageSkill,
+      }),
+      buildRemoveServerTool({ detachServer: runtime.detachServer }),
+      buildTestServerTool({ secretResolver }),
+    ],
+    hooks: {
+      // On session init, register lazy stubs for every saved MCP server.
+      // Servers WITH a tool-descriptor cache register stubs instantly
+      // (no connection). Servers WITHOUT a cache (entry predates the
+      // cache feature, edited by hand, etc.) auto-refresh — we connect
+      // once, list tools, write the cache back to mcp.json, then
+      // register lazy stubs. The connection is closed after listing;
+      // subsequent tool calls reconnect via the lazy path.
+      onInit: async (ctx) => {
+        if (!registry) return;
+        const log = (ctx as { logger?: { warn: (msg: string, meta?: unknown) => void } }).logger;
+        let cfg: McpStoredConfig;
+        try {
+          cfg = await readMcpConfig();
+        } catch {
+          return;
+        }
+        // Refresh every uncached server's catalog in PARALLEL: each
+        // refreshServerCache now carries its own bounded connect/listTools
+        // timeout, so allSettled bounds boot at the slowest server instead of
+        // the SUM of every server's handshake latency. (Serially awaiting one
+        // dead endpoint after another compounded the wedge.) Cached servers
+        // need no connection and resolve immediately.
+        const active = cfg.servers.filter((s) => !s.disabled);
+        const resolved = await Promise.all(
+          active.map(async (server): Promise<McpStoredServer | null> => {
+            if (server.cachedTools && server.cachedTools.length > 0) return server;
+            try {
+              return await runtime.refreshServerCache(server);
+            } catch (err) {
+              log?.warn?.(`mcp: failed to refresh cache for "${server.name}"`, {
+                err: err instanceof Error ? err.message : String(err),
+              });
+              return null;
+            }
+          }),
+        );
+        // Attach serially in config order so tool registration order stays
+        // deterministic (the refresh ran concurrently, but attach is cheap and
+        // synchronous — no connection — so this adds no boot latency).
+        for (const entry of resolved) {
+          if (!entry) continue;
+          try {
+            runtime.attachServerLazy(entry);
+          } catch (err) {
+            log?.warn?.(`mcp: failed to attach lazy stubs for "${entry.name}"`, {
+              err: err instanceof Error ? err.message : String(err),
+            });
+          }
+        }
+      },
+      // Close every attached MCP client (lazy or eager) on session
+      // shutdown so stdio child processes don't get orphaned and HTTP
+      // sockets don't leak.
+      onShutdown: async () => {
+        for (const [, runtime_] of runtime.runtimes) {
+          try {
+            await runtime_.client.close();
+          } catch {
+            /* ignore */
+          }
+        }
+        runtime.runtimes.clear();
+      },
+    },
+  });
+  return { plugin, api };
+}