@moxxy/plugin-mcp 0.26.0

package/src/admin/skill.ts

@@ -0,0 +1,83 @@
+import * as path from 'node:path';
+import { type Skill } from '@moxxy/sdk';
+import { writeFileAtomic } from '@moxxy/sdk/server';
+import type { McpServerConfig, McpToolDescriptor } from '../types.js';
+import type { AdminSkillRegistryLike } from './types.js';
+
+export interface WriteMcpUsageSkillOptions {
+  readonly skillRegistry: AdminSkillRegistryLike | null;
+  readonly userSkillsDir: string;
+}
+
+/**
+ * Compose a deterministic usage skill from the server's tool list.
+ * Cheaper and more reliable than a synthesize_skill model call — the
+ * descriptors already carry name + description, so the skill body just
+ * lays them out as a bulleted checklist. The user can edit the file
+ * later if they want a richer playbook.
+ */
+export function createMcpUsageSkillWriter(
+  opts: WriteMcpUsageSkillOptions,
+): (
+  server: McpServerConfig,
+  descriptors: ReadonlyArray<McpToolDescriptor>,
+) => Promise<{ path: string; skillName: string } | null> {
+  const { skillRegistry, userSkillsDir } = opts;
+  return async (server, descriptors) => {
+    const skillName = `${server.name}-mcp`;
+    if (skillRegistry?.byName(skillName)) {
+      // Already exists (likely from a previous attach) — leave it alone
+      // so user edits aren't clobbered.
+      return null;
+    }
+    const triggers = [server.name, `${server.name} mcp`, `use ${server.name}`];
+    const toolBullets = descriptors
+      .map((d) => {
+        const wrappedName = `mcp__${server.name}__${d.name}`;
+        return `- \`${wrappedName}\` — ${d.description ?? '(no description provided)'}`;
+      })
+      .join('\n');
+    const allowed = descriptors.map((d) => `mcp__${server.name}__${d.name}`);
+    const description = `Use the ${server.name} MCP server (${descriptors.length} tools).`.slice(0, 240);
+    const frontmatter =
+      `---\n` +
+      `name: ${skillName}\n` +
+      `description: ${description}\n` +
+      `triggers:\n${triggers.map((t) => `  - "${t}"`).join('\n')}\n` +
+      `allowed-tools:\n${allowed.map((a) => `  - ${a}`).join('\n')}\n` +
+      `---\n`;
+    const body =
+      `When the user wants to work with **${server.name}**, use the MCP tools below. Pick the tool that best matches the user's intent; chain multiple if needed.\n\n` +
+      `## Available tools\n\n${toolBullets}\n\n` +
+      `## Notes\n\n` +
+      `- Every tool above is namespaced \`mcp__${server.name}__*\`.\n` +
+      `- Auto-generated when the MCP server was registered. Edit this file by hand to refine the playbook.`;
+    const raw = `${frontmatter}\n${body}\n`;
+    const filePath = path.join(userSkillsDir, `${skillName}.md`);
+    // writeFileAtomic creates parent dirs and does a crash-safe tmp+rename.
+    await writeFileAtomic(filePath, raw);
+    if (skillRegistry) {
+      // Build a Skill object that mirrors what discoverSkills would
+      // produce so /skills, the system-prompt index, and load_skill all
+      // see it immediately.
+      const skillObject: Skill = {
+        id: `user/${skillName}` as Skill['id'],
+        path: filePath,
+        scope: 'user',
+        frontmatter: {
+          name: skillName,
+          description,
+          triggers,
+          'allowed-tools': allowed,
+        } as Skill['frontmatter'],
+        body,
+      };
+      try {
+        skillRegistry.register(skillObject);
+      } catch {
+        // already registered — fine
+      }
+    }
+    return { path: filePath, skillName };
+  };
+}

package/src/admin/tools/add.test.ts

@@ -0,0 +1,193 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { McpServerConfig, McpToolDescriptor } from '../../types.js';
+import { readMcpConfig, writeMcpConfig } from '../config-io.js';
+import type { AddServerInput } from '../schema.js';
+import type { AdminToolRegistryLike } from '../types.js';
+import { buildAddServerTool, type AddServerToolDeps } from './add.js';
+
+const PING: McpToolDescriptor = { name: 'ping', description: 'pong', inputSchema: { type: 'object' } };
+
+const ctx = () => ({
+  sessionId: 's' as never,
+  turnId: 't' as never,
+  callId: 'c' as never,
+  cwd: '/tmp',
+  signal: new AbortController().signal,
+  log: { length: 0, at: () => undefined, slice: () => [], ofType: () => [], byTurn: () => [], toJSON: () => [] },
+  logger: { debug: () => {}, info: () => {}, warn: () => {}, error: () => {} },
+});
+
+const stdioInput = (over: Partial<AddServerInput> = {}): AddServerInput =>
+  ({ kind: 'stdio', name: 'demo', command: 'noop', autoSkill: true, ...over }) as AddServerInput;
+
+const fakeRegistry = (): AdminToolRegistryLike => ({
+  has: () => false,
+  register: () => {},
+  unregister: () => {},
+});
+
+describe('admin/tools/add (mcp_add_server)', () => {
+  let home: string;
+  const original = process.env.MOXXY_HOME;
+
+  beforeEach(async () => {
+    home = await mkdtemp(join(tmpdir(), 'moxxy-mcp-add-'));
+    process.env.MOXXY_HOME = home;
+  });
+
+  afterEach(async () => {
+    if (original === undefined) delete process.env.MOXXY_HOME;
+    else process.env.MOXXY_HOME = original;
+    await rm(home, { recursive: true, force: true });
+  });
+
+  const makeDeps = (over: Partial<AddServerToolDeps> = {}): {
+    deps: AddServerToolDeps;
+    attach: ReturnType<typeof vi.fn>;
+    detach: ReturnType<typeof vi.fn>;
+    writeSkill: ReturnType<typeof vi.fn>;
+  } => {
+    const attach = vi.fn(async (_server: McpServerConfig) => ({
+      toolNames: ['mcp__demo__ping'],
+      descriptors: [PING] as ReadonlyArray<McpToolDescriptor>,
+    }));
+    const detach = vi.fn(async (_name: string) => true);
+    const writeSkill = vi.fn(async (_s: McpServerConfig, _d: ReadonlyArray<McpToolDescriptor>) => ({
+      path: join(home, 'skills', 'demo-mcp.md'),
+      skillName: 'demo-mcp',
+    }));
+    const deps: AddServerToolDeps = {
+      registry: fakeRegistry(),
+      attachServer: attach as never,
+      detachServer: detach as never,
+      writeMcpUsageSkill: writeSkill as never,
+      ...over,
+    };
+    return { deps, attach, detach, writeSkill };
+  };
+
+  it('rejects a duplicate name before attaching anything', async () => {
+    await writeMcpConfig({ servers: [{ kind: 'stdio', name: 'demo', command: 'x' }] });
+    const { deps, attach } = makeDeps();
+    const tool = buildAddServerTool(deps);
+    await expect(tool.handler(stdioInput(), ctx())).rejects.toThrow(/already exists/);
+    // Must short-circuit before paying the connection cost.
+    expect(attach).not.toHaveBeenCalled();
+    // Catalog unchanged.
+    expect((await readMcpConfig()).servers).toHaveLength(1);
+  });
+
+  it('attaches + persists with cached descriptors + writes the usage skill on success', async () => {
+    const { deps, attach, writeSkill } = makeDeps();
+    const tool = buildAddServerTool(deps);
+    const res = (await tool.handler(stdioInput(), ctx())) as {
+      ok: boolean;
+      attached: boolean;
+      tools: string[];
+      skill: { skillName: string } | null;
+    };
+    expect(res.ok).toBe(true);
+    expect(res.attached).toBe(true);
+    expect(res.tools).toEqual(['mcp__demo__ping']);
+    expect(res.skill?.skillName).toBe('demo-mcp');
+    expect(attach).toHaveBeenCalledTimes(1);
+    expect(writeSkill).toHaveBeenCalledTimes(1);
+    // Persisted entry caches the discovered descriptors for lazy boot.
+    const cfg = await readMcpConfig();
+    expect(cfg.servers).toHaveLength(1);
+    expect(cfg.servers[0]).toMatchObject({ name: 'demo', command: 'noop', cachedTools: [PING] });
+  });
+
+  it('does NOT persist or write a skill when attach fails (no broken entry on disk)', async () => {
+    const attach = vi.fn(async () => {
+      throw new Error('connect failed');
+    });
+    const { deps, writeSkill } = makeDeps({ attachServer: attach as never });
+    const tool = buildAddServerTool(deps);
+    await expect(tool.handler(stdioInput(), ctx())).rejects.toThrow(/connect failed/);
+    expect(writeSkill).not.toHaveBeenCalled();
+    expect((await readMcpConfig()).servers).toEqual([]);
+  });
+
+  it('rolls back the live attach (detachServer) when the persist-time re-check loses a name race (u85-2)', async () => {
+    // attachServer succeeds (live tools registered), but a concurrent add for
+    // the same name lands between the initial read and the mutate, so the
+    // mutate's duplicate re-check throws. The registry must be rolled back.
+    const attach = vi.fn(async (_server: McpServerConfig) => {
+      // Simulate the racing add winning between read and mutate.
+      await writeMcpConfig({ servers: [{ kind: 'stdio', name: 'demo', command: 'other' }] });
+      return {
+        toolNames: ['mcp__demo__ping'],
+        descriptors: [PING] as ReadonlyArray<McpToolDescriptor>,
+      };
+    });
+    const { deps, detach, writeSkill } = makeDeps({ attachServer: attach as never });
+    const tool = buildAddServerTool(deps);
+    await expect(tool.handler(stdioInput(), ctx())).rejects.toThrow(/already exists/);
+    expect(attach).toHaveBeenCalledTimes(1);
+    // The orphaned registration + open client must be torn down.
+    expect(detach).toHaveBeenCalledWith('demo');
+    // No usage skill written, and the racing winner's entry is left intact
+    // (exactly one entry, command from the winner — not ours).
+    expect(writeSkill).not.toHaveBeenCalled();
+    const cfg = await readMcpConfig();
+    expect(cfg.servers).toHaveLength(1);
+    expect(cfg.servers[0]).toMatchObject({ name: 'demo', command: 'other' });
+  });
+
+  it('skips the usage skill when autoSkill is false', async () => {
+    const { deps, writeSkill } = makeDeps();
+    const tool = buildAddServerTool(deps);
+    const res = (await tool.handler(stdioInput({ autoSkill: false }), ctx())) as { skill: unknown };
+    expect(writeSkill).not.toHaveBeenCalled();
+    expect(res.skill).toBeNull();
+    // Server still attached + persisted.
+    expect((await readMcpConfig()).servers).toHaveLength(1);
+  });
+
+  it('reports skillError but still succeeds when skill writing throws', async () => {
+    const writeSkill = vi.fn(async () => {
+      throw new Error('disk full');
+    });
+    const { deps } = makeDeps({ writeMcpUsageSkill: writeSkill as never });
+    const tool = buildAddServerTool(deps);
+    const res = (await tool.handler(stdioInput(), ctx())) as {
+      ok: boolean;
+      skill: unknown;
+      skillError?: string;
+    };
+    expect(res.ok).toBe(true);
+    expect(res.skill).toBeNull();
+    expect(res.skillError).toMatch(/disk full/);
+    // Attach + persist still succeeded despite the skill failure.
+    expect((await readMcpConfig()).servers).toHaveLength(1);
+  });
+
+  it('reports attached:false (config-only) when no live registry is wired', async () => {
+    const { deps } = makeDeps({ registry: null });
+    const tool = buildAddServerTool(deps);
+    const res = (await tool.handler(stdioInput(), ctx())) as { attached: boolean; note: string };
+    expect(res.attached).toBe(false);
+    expect(res.note).toMatch(/Restart moxxy/);
+  });
+
+  it('persists an http server with its url + headers', async () => {
+    const { deps } = makeDeps();
+    const tool = buildAddServerTool(deps);
+    await tool.handler(
+      stdioInput({ kind: 'http', name: 'remote', command: undefined, url: 'https://r.test', headers: { a: 'b' } }),
+      ctx(),
+    );
+    const cfg = await readMcpConfig();
+    expect(cfg.servers[0]).toMatchObject({
+      kind: 'http',
+      name: 'remote',
+      url: 'https://r.test',
+      headers: { a: 'b' },
+      cachedTools: [PING],
+    });
+  });
+});

package/src/admin/tools/add.ts

@@ -0,0 +1,118 @@
+import { defineTool, MoxxyError, type ToolDef } from '@moxxy/sdk';
+import type { McpServerConfig, McpToolDescriptor } from '../../types.js';
+import { mcpConfigPath, mutateMcpConfig, readMcpConfig } from '../config-io.js';
+import { addServerInput, validateAddServerInput } from '../schema.js';
+import type {
+  AdminToolRegistryLike,
+  McpStoredServer,
+} from '../types.js';
+
+export interface AddServerToolDeps {
+  readonly registry: AdminToolRegistryLike | null;
+  attachServer(server: McpServerConfig): Promise<{
+    toolNames: ReadonlyArray<string>;
+    descriptors: ReadonlyArray<McpToolDescriptor>;
+  }>;
+  /** Roll back a hot-attach (unregister its tools + close the client) when
+   *  persisting the new entry fails after `attachServer` already succeeded. */
+  detachServer(name: string): Promise<boolean>;
+  writeMcpUsageSkill(
+    server: McpServerConfig,
+    descriptors: ReadonlyArray<McpToolDescriptor>,
+  ): Promise<{ path: string; skillName: string } | null>;
+}
+
+export function buildAddServerTool(deps: AddServerToolDeps): ToolDef {
+  const { registry, attachServer, detachServer, writeMcpUsageSkill } = deps;
+  return defineTool({
+    name: 'mcp_add_server',
+    description:
+      'Register a new MCP server in ~/.moxxy/mcp.json. Pick "stdio" for local commands ' +
+      '(npm/uv packages, scripts); pick "http" or "sse" for remote HTTP servers. The new ' +
+      'server\'s tools become available after the next moxxy restart. Call mcp_test_server ' +
+      'first if you want to verify connectivity before persisting. NEVER pass API keys or ' +
+      'tokens in plaintext: store the secret in the vault first (vault_set), then reference ' +
+      'it as "${vault:NAME}" in the env/header value — the placeholder is what gets ' +
+      'persisted, and it is resolved only at connect time.',
+    inputSchema: addServerInput,
+    permission: { action: 'prompt' },
+    handler: async (input) => {
+      const server = validateAddServerInput(input);
+      const cfg = await readMcpConfig();
+      if (cfg.servers.some((s) => s.name === server.name)) {
+        throw new MoxxyError({
+          code: 'CONFIG_INVALID',
+          message:
+            `mcp_add_server: an MCP server named "${server.name}" already exists. ` +
+            `Use mcp_remove_server first, or pick a different name.`,
+        });
+      }
+      // Hot-attach: connect + register tools BEFORE persisting. If
+      // attach fails (bad URL, missing command, schema mismatch),
+      // we never write a broken entry to disk.
+      const { toolNames, descriptors } = await attachServer(server);
+      // Cache descriptors so next boot can register lazy stubs
+      // without paying the connection cost up-front.
+      const stored: McpStoredServer = { ...server, cachedTools: descriptors };
+      // Persist under the shared config mutex, re-reading the latest
+      // catalog so a concurrent add/remove can't clobber the file. The
+      // duplicate check is repeated against the fresh read to catch a race
+      // where two adds for the same name both passed the initial check.
+      try {
+        await mutateMcpConfig((current) => {
+          if (current.servers.some((s) => s.name === server.name)) {
+            throw new MoxxyError({
+              code: 'CONFIG_INVALID',
+              message:
+                `mcp_add_server: an MCP server named "${server.name}" already exists. ` +
+                `Use mcp_remove_server first, or pick a different name.`,
+            });
+          }
+          return { next: { servers: [...current.servers, stored] }, result: undefined };
+        });
+      } catch (err) {
+        // attachServer already registered the live tools + opened a client, but
+        // persistence failed (e.g. a concurrent add for the same name won the
+        // race, or the file write threw). Roll the live registry back so we
+        // don't strand callable tools with no config entry + a leaked client.
+        await detachServer(server.name).catch(() => undefined);
+        throw err;
+      }
+      // Auto-create the usage skill so /skills surfaces the new
+      // server alongside hand-authored skills. Best-effort — if
+      // skill writing fails, the MCP attach still succeeded.
+      let skillResult: { path: string; skillName: string } | null = null;
+      if (input.autoSkill !== false) {
+        try {
+          skillResult = await writeMcpUsageSkill(server, descriptors);
+        } catch (err) {
+          skillResult = null;
+          // surface but don't fail the whole tool call
+          return {
+            ok: true,
+            name: server.name,
+            path: mcpConfigPath(),
+            attached: registry !== null,
+            tools: toolNames,
+            skill: null,
+            skillError: err instanceof Error ? err.message : String(err),
+            note: 'Server attached + persisted; skill creation failed (see skillError).',
+          };
+        }
+      }
+      return {
+        ok: true,
+        name: server.name,
+        path: mcpConfigPath(),
+        attached: registry !== null,
+        tools: toolNames,
+        skill: skillResult,
+        note: registry
+          ? `Live in this session — ${toolNames.length} tool${toolNames.length === 1 ? '' : 's'} now callable.` +
+            (skillResult ? ` Usage skill written to ${skillResult.path}.` : '') +
+            ' Persisted; survives restart.'
+          : 'Saved to config. Restart moxxy to load the tools (no live registry was wired into the admin plugin).',
+      };
+    },
+  });
+}

package/src/admin/tools/list.ts

@@ -0,0 +1,19 @@
+import { defineTool, z, type ToolDef } from '@moxxy/sdk';
+import { readMcpConfig } from '../config-io.js';
+
+export function buildListServersTool(): ToolDef {
+  return defineTool({
+    name: 'mcp_list_servers',
+    description:
+      'List every MCP server currently registered in ~/.moxxy/mcp.json. Returns name + transport kind + connection details (command/url) for each.',
+    inputSchema: z.object({}),
+    handler: async () => {
+      const cfg = await readMcpConfig();
+      return cfg.servers.map((s) =>
+        s.kind === undefined || s.kind === 'stdio'
+          ? { name: s.name, kind: 'stdio' as const, command: (s as { command: string }).command }
+          : { name: s.name, kind: s.kind, url: (s as { url: string }).url },
+      );
+    },
+  });
+}

package/src/admin/tools/remove.test.ts

@@ -0,0 +1,74 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { readMcpConfig, writeMcpConfig } from '../config-io.js';
+import { buildRemoveServerTool } from './remove.js';
+
+const ctx = () => ({
+  sessionId: 's' as never,
+  turnId: 't' as never,
+  callId: 'c' as never,
+  cwd: '/tmp',
+  signal: new AbortController().signal,
+  log: { length: 0, at: () => undefined, slice: () => [], ofType: () => [], byTurn: () => [], toJSON: () => [] },
+  logger: { debug: () => {}, info: () => {}, warn: () => {}, error: () => {} },
+});
+
+describe('admin/tools/remove (mcp_remove_server)', () => {
+  let home: string;
+  const original = process.env.MOXXY_HOME;
+
+  beforeEach(async () => {
+    home = await mkdtemp(join(tmpdir(), 'moxxy-mcp-rm-'));
+    process.env.MOXXY_HOME = home;
+  });
+
+  afterEach(async () => {
+    if (original === undefined) delete process.env.MOXXY_HOME;
+    else process.env.MOXXY_HOME = original;
+    await rm(home, { recursive: true, force: true });
+  });
+
+  it('removes from config AND detaches from the live session', async () => {
+    await writeMcpConfig({
+      servers: [
+        { kind: 'stdio', name: 'demo', command: 'x' },
+        { kind: 'stdio', name: 'keep', command: 'y' },
+      ],
+    });
+    const detach = vi.fn(async () => true);
+    const tool = buildRemoveServerTool({ detachServer: detach });
+    const res = (await tool.handler({ name: 'demo' }, ctx())) as {
+      removed: boolean;
+      persistedChange: boolean;
+      detachedFromSession: boolean;
+    };
+    expect(res).toMatchObject({ removed: true, persistedChange: true, detachedFromSession: true });
+    expect(detach).toHaveBeenCalledWith('demo');
+    expect((await readMcpConfig()).servers.map((s) => s.name)).toEqual(['keep']);
+  });
+
+  it('reports removed:true when only the live session had it (config no-op)', async () => {
+    await writeMcpConfig({ servers: [] });
+    const detach = vi.fn(async () => true);
+    const tool = buildRemoveServerTool({ detachServer: detach });
+    const res = (await tool.handler({ name: 'ephemeral' }, ctx())) as {
+      removed: boolean;
+      persistedChange: boolean;
+      detachedFromSession: boolean;
+    };
+    expect(res).toMatchObject({ removed: true, persistedChange: false, detachedFromSession: true });
+  });
+
+  it('reports removed:false when nothing matched in config or session', async () => {
+    await writeMcpConfig({ servers: [{ kind: 'stdio', name: 'demo', command: 'x' }] });
+    const detach = vi.fn(async () => false);
+    const tool = buildRemoveServerTool({ detachServer: detach });
+    const res = (await tool.handler({ name: 'ghost' }, ctx())) as { removed: boolean; note: string };
+    expect(res.removed).toBe(false);
+    expect(res.note).toMatch(/No MCP server named "ghost"/);
+    // Existing entry untouched.
+    expect((await readMcpConfig()).servers.map((s) => s.name)).toEqual(['demo']);
+  });
+});

package/src/admin/tools/remove.ts

@@ -0,0 +1,46 @@
+import { defineTool, z, type ToolDef } from '@moxxy/sdk';
+import { mutateMcpConfig } from '../config-io.js';
+import { serverNameSchema } from '../schema.js';
+
+export interface RemoveServerToolDeps {
+  detachServer(name: string): Promise<boolean>;
+}
+
+export function buildRemoveServerTool(deps: RemoveServerToolDeps): ToolDef {
+  const { detachServer } = deps;
+  return defineTool({
+    name: 'mcp_remove_server',
+    description:
+      'Remove an MCP server from ~/.moxxy/mcp.json and detach its tools from the live session. ' +
+      'The tools become uncallable immediately and the entry is gone on next restart.',
+    inputSchema: z.object({ name: serverNameSchema }),
+    permission: { action: 'prompt' },
+    handler: async ({ name }) => {
+      // Read-modify-write under the shared config mutex so a concurrent
+      // add/remove can't clobber the file.
+      const persisted = await mutateMcpConfig((cfg) => {
+        const filtered = cfg.servers.filter((s) => s.name !== name);
+        if (filtered.length === cfg.servers.length) {
+          // Nothing matched — return the same reference to skip the write.
+          return { next: cfg, result: false };
+        }
+        return { next: { servers: filtered }, result: true };
+      });
+      // Runtime detach runs OUTSIDE the config mutex (the live tool registry
+      // isn't guarded by it), so a concurrent same-name add could interleave
+      // between this persist and detach. Detach is best-effort and loosely
+      // coupled to the config — the entry is authoritative, the runtime map
+      // self-heals on the next attach/restart.
+      const detached = await detachServer(name);
+      if (!persisted && !detached) {
+        return { removed: false, name, note: `No MCP server named "${name}" was registered.` };
+      }
+      return {
+        removed: true,
+        name,
+        persistedChange: persisted,
+        detachedFromSession: detached,
+      };
+    },
+  });
+}

package/src/admin/tools/test.test.ts

@@ -0,0 +1,123 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import type { McpClientLike, McpServerConfig } from '../../types.js';
+import type { AddServerInput } from '../schema.js';
+
+// mcp_test_server connects through `defaultClientFactory` (../../client.js).
+// Inject a fake so the test never spawns a real subprocess / opens a socket.
+const hoisted = vi.hoisted(() => ({
+  impl: null as ((server: McpServerConfig) => Promise<McpClientLike>) | null,
+}));
+
+vi.mock('../../client.js', () => ({
+  defaultClientFactory: async (server: McpServerConfig): Promise<McpClientLike> => {
+    if (!hoisted.impl) throw new Error('impl not set');
+    return hoisted.impl(server);
+  },
+}));
+
+const { buildTestServerTool } = await import('./test.js');
+
+const ctx = () => ({
+  sessionId: 's' as never,
+  turnId: 't' as never,
+  callId: 'c' as never,
+  cwd: '/tmp',
+  signal: new AbortController().signal,
+  log: { length: 0, at: () => undefined, slice: () => [], ofType: () => [], byTurn: () => [], toJSON: () => [] },
+  logger: { debug: () => {}, info: () => {}, warn: () => {}, error: () => {} },
+});
+
+const input = (over: Partial<AddServerInput> = {}): AddServerInput =>
+  ({ kind: 'stdio', name: 'demo', command: 'noop', autoSkill: true, ...over }) as AddServerInput;
+
+describe('admin/tools/test (mcp_test_server)', () => {
+  it('returns ok + the tool list when the connection succeeds, and closes the client', async () => {
+    let closed = 0;
+    hoisted.impl = async () => ({
+      listTools: async () => ({
+        tools: [{ name: 'ping', description: 'pong', inputSchema: { type: 'object' } }],
+      }),
+      callTool: async () => ({ content: [] }),
+      close: async () => {
+        closed++;
+      },
+    });
+    const tool = buildTestServerTool();
+    const res = (await tool.handler(input(), ctx())) as {
+      ok: boolean;
+      name: string;
+      tools: Array<{ name: string; description?: string }>;
+    };
+    expect(res.ok).toBe(true);
+    expect(res.name).toBe('demo');
+    expect(res.tools).toEqual([{ name: 'mcp__demo__ping', description: 'pong' }]);
+    expect(closed).toBe(1);
+  });
+
+  it('returns ok:false with the error message when the connection fails (no throw)', async () => {
+    hoisted.impl = async () => {
+      throw new Error('connect refused');
+    };
+    const tool = buildTestServerTool();
+    const res = (await tool.handler(input(), ctx())) as { ok: boolean; error: string };
+    expect(res.ok).toBe(false);
+    expect(res.error).toMatch(/connect refused/);
+  });
+
+  it('still closes the client when listTools throws after connecting', async () => {
+    let closed = 0;
+    hoisted.impl = async () => ({
+      listTools: async () => {
+        throw new Error('list boom');
+      },
+      callTool: async () => ({ content: [] }),
+      close: async () => {
+        closed++;
+      },
+    });
+    const tool = buildTestServerTool();
+    const res = (await tool.handler(input(), ctx())) as { ok: boolean; error: string };
+    expect(res.ok).toBe(false);
+    expect(res.error).toMatch(/list boom/);
+    expect(closed).toBe(1);
+  });
+
+  describe('bounded connect/discovery (no infinite hang)', () => {
+    afterEach(() => {
+      vi.useRealTimers();
+    });
+
+    it('returns ok:false with a timeout error when connect never resolves', async () => {
+      vi.useFakeTimers();
+      // A wedged / unreachable server must NOT hang the tool call forever —
+      // the bounded connect surfaces a readable timeout as a normal failure.
+      hoisted.impl = () => new Promise<McpClientLike>(() => {});
+      const tool = buildTestServerTool();
+      const promise = tool.handler(input(), ctx()) as Promise<{ ok: boolean; error: string }>;
+      await vi.advanceTimersByTimeAsync(30 * 1000);
+      const res = await promise;
+      expect(res.ok).toBe(false);
+      expect(res.error).toMatch(/timed out/);
+    });
+
+    it('returns ok:false with a timeout error when listTools never resolves, and closes the client', async () => {
+      vi.useFakeTimers();
+      let closed = 0;
+      hoisted.impl = async () => ({
+        listTools: () => new Promise<{ tools: never[] }>(() => {}),
+        callTool: async () => ({ content: [] }),
+        close: async () => {
+          closed++;
+        },
+      });
+      const tool = buildTestServerTool();
+      const promise = tool.handler(input(), ctx()) as Promise<{ ok: boolean; error: string }>;
+      await vi.advanceTimersByTimeAsync(30 * 1000);
+      const res = await promise;
+      expect(res.ok).toBe(false);
+      expect(res.error).toMatch(/timed out/);
+      // The finally{} must still close the connected-but-mute client.
+      expect(closed).toBe(1);
+    });
+  });
+});