@moxxy/plugin-mcp 0.26.0

package/src/admin/tools/test.ts

@@ -0,0 +1,84 @@
+import { defineTool, type ToolDef } from '@moxxy/sdk';
+import { defaultClientFactory } from '../../client.js';
+import { MCP_CONNECT_TIMEOUT_MS, withTimeout } from '../../timeout.js';
+import { wrapMcpServerTools } from '../../wrap.js';
+import { addServerInput, validateAddServerInput } from '../schema.js';
+import { resolveServerSecrets, type McpSecretResolver } from '../secrets.js';
+
+export interface TestServerToolDeps {
+  /** Resolves `${vault:NAME}` placeholders in env/header values at connect time. */
+  readonly secretResolver?: McpSecretResolver | null;
+}
+
+export function buildTestServerTool(deps: TestServerToolDeps = {}): ToolDef {
+  return defineTool({
+    name: 'mcp_test_server',
+    description:
+      'Connect to an MCP server WITHOUT saving it to config. Returns the list of tools the ' +
+      'server exposes if the connection succeeds, or a connection-error message. Useful for ' +
+      'sanity-checking before calling mcp_add_server. Credentials (env/header values) must be ' +
+      'vault references, never plaintext: store the secret first via vault_set, then pass ' +
+      '"${vault:NAME}" — it is resolved at connect time.',
+    inputSchema: addServerInput,
+    // Mirrors mcp_add_server: a stdio server is an arbitrary local
+    // executable we spawn, so gate behind a prompt rather than running
+    // unknown commands silently.
+    permission: { action: 'prompt' },
+    // Honest capability surface modeled on the Bash tool: for kind="stdio"
+    // this spawns a child process the user named (subprocess + broad fs,
+    // since the command can touch anything it likes); for http/sse it
+    // makes an outbound connection to an arbitrary URL (net: any). Advisory
+    // until @moxxy/plugin-security is enabled, then enforced at call time.
+    isolation: {
+      required: 'inproc',
+      capabilities: {
+        subprocess: true,
+        fs: { read: ['$cwd/**', '/tmp/**'], write: ['$cwd/**', '/tmp/**'] },
+        net: { mode: 'any' },
+        env: ['PATH', 'HOME', 'USER', 'SHELL', 'LANG', 'LC_ALL', 'TERM'],
+        timeMs: 600_000,
+      },
+    },
+    handler: async (input) => {
+      const server = validateAddServerInput(input);
+      let client: Awaited<ReturnType<typeof defaultClientFactory>> | null = null;
+      try {
+        // Bound the connect + listTools handshake so a wedged / unreachable
+        // server surfaces as a readable connection error instead of hanging
+        // this tool call forever (defaultClientFactory + listTools take no
+        // AbortSignal). On timeout the inner `connect` may still resolve a
+        // client after we've rejected; the finally{} below closes whatever
+        // `client` we captured, so a late-opening handle isn't leaked.
+        client = await withTimeout(
+          defaultClientFactory(await resolveServerSecrets(server, deps.secretResolver ?? null)),
+          MCP_CONNECT_TIMEOUT_MS,
+          `MCP connect "${server.name}"`,
+        );
+        const wrapped = await withTimeout(
+          wrapMcpServerTools({ server, client }),
+          MCP_CONNECT_TIMEOUT_MS,
+          `MCP listTools "${server.name}"`,
+        );
+        return {
+          ok: true,
+          name: server.name,
+          tools: wrapped.map((t) => ({ name: t.name, description: t.description })),
+        };
+      } catch (err) {
+        return {
+          ok: false,
+          name: server.name,
+          error: err instanceof Error ? err.message : String(err),
+        };
+      } finally {
+        if (client) {
+          try {
+            await client.close();
+          } catch {
+            /* ignore */
+          }
+        }
+      }
+    },
+  });
+}

package/src/admin/types.ts

@@ -0,0 +1,112 @@
+import type { Skill, ToolDef } from '@moxxy/sdk';
+import type { McpClientLike, McpServerConfig, McpToolDescriptor } from '../types.js';
+import type { McpSecretResolver } from './secrets.js';
+
+/**
+ * Minimal skill-registry shape the admin plugin needs to auto-register
+ * a usage skill after `mcp_add_server`. Loose typing to keep this plugin
+ * free of an explicit @moxxy/core import.
+ */
+export interface AdminSkillRegistryLike {
+  register(skill: Skill): void;
+  byName(name: string): Skill | undefined;
+}
+
+/**
+ * Live runtime: live MCP clients keyed by server name plus the set of
+ * tool names each one registered into the session. Lets us close +
+ * unregister on `mcp_remove_server` and on shutdown without
+ * rediscovering anything. Module-scoped so the admin plugin and the
+ * shutdown hook share the same state; each Session that loads the
+ * plugin gets its own map via the closure in `buildMcpAdminPlugin`.
+ */
+export interface McpRuntimeHandle {
+  readonly client: McpClientLike;
+  readonly toolNames: ReadonlyArray<string>;
+}
+
+/**
+ * Tool-registry surface the admin plugin uses to hot-attach / detach
+ * MCP tools. Matches the `ToolRegistry` in @moxxy/core but typed loosely
+ * so we don't add an internal-dep on core from this plugin.
+ */
+export interface AdminToolRegistryLike {
+  has(name: string): boolean;
+  register(tool: ToolDef): void;
+  unregister(name: string): void;
+}
+
+/**
+ * On-disk catalog entry: connection config PLUS a cache of the tool
+ * descriptors the server last advertised, plus an enable/disable flag.
+ *
+ * Defined as an intersection (not `extends`) so the McpServerConfig
+ * discriminated union is preserved — `extends` would collapse it.
+ */
+export type McpStoredServer = McpServerConfig & {
+  readonly cachedTools?: ReadonlyArray<McpToolDescriptor>;
+  /** When true, the boot loader skips this entry — no lazy stubs are
+   *  registered and tools stay invisible. Lets the user keep the
+   *  connection config for later without paying for tool registration. */
+  readonly disabled?: boolean;
+};
+
+export interface McpStoredConfig {
+  readonly servers: ReadonlyArray<McpStoredServer>;
+}
+
+export interface BuildMcpAdminPluginOptions {
+  /**
+   * Live tool registry. When provided, `mcp_add_server` connects + wraps
+   * the server immediately and registers its tools into this registry —
+   * no restart needed. `mcp_remove_server` closes the client and
+   * unregisters. Pass `null` for pure-config behavior (write-only).
+   */
+  readonly toolRegistry: AdminToolRegistryLike | null;
+  /**
+   * Skill registry + skills dir. When provided, `mcp_add_server`
+   * auto-writes a deterministic usage skill (server-name + tool catalog)
+   * to disk and registers it so `/skills` and the system-prompt index
+   * surface the MCP server alongside hand-authored skills. The skill is
+   * generated from descriptors directly — no model call. Pass `null` to
+   * disable auto-skill creation.
+   */
+  readonly skillRegistry?: AdminSkillRegistryLike | null;
+  readonly userSkillsDir?: string;
+  /**
+   * Resolves `${vault:NAME}` placeholders in server env/header values at
+   * CONNECT time (every connect path: hot-attach, lazy attach, cache
+   * refresh, mcp_test_server). Wired from setup with the vault's
+   * `resolveString`; literal values pass through unchanged. The persisted
+   * catalog always keeps the placeholder form, never the plaintext.
+   */
+  readonly secretResolver?: McpSecretResolver | null;
+}
+
+/**
+ * Runtime control surface exposed alongside the admin Plugin. The TUI's
+ * /mcp slash command and the CLI's `moxxy mcp` subcommand use this to
+ * detach a server's live tools when disabling, or re-attach when
+ * enabling, without going through the model.
+ */
+export interface McpAdminApi {
+  /** Refresh + lazy-attach a server (used after enabling). */
+  enableAndAttach(name: string): Promise<{ toolNames: ReadonlyArray<string> } | null>;
+  /** Detach a server's live tools and close its client. */
+  detach(name: string): Promise<boolean>;
+  /**
+   * One-shot snapshot of every server configured in ~/.moxxy/mcp.json,
+   * joined with the runtime attach state. `enabled` reflects the persisted
+   * config (`disabled !== true`); `connected` is true when the server's
+   * tools are attached to the session (whether eagerly or via a lazy stub
+   * — both states make tools callable from a user's perspective). Used
+   * by the TUI status bar to show "mcp 2/3" style summaries.
+   */
+  listServers(): Promise<ReadonlyArray<McpServerStatus>>;
+}
+
+export interface McpServerStatus {
+  readonly name: string;
+  readonly enabled: boolean;
+  readonly connected: boolean;
+}

package/src/admin.ts

@@ -0,0 +1,25 @@
+/**
+ * Backward-compatibility façade. The real implementation lives in
+ * `./admin/` as cohesive sub-modules; this file just re-exports the
+ * symbols that consumers (and the package's own `src/index.ts`) import.
+ */
+export {
+  buildMcpAdminPlugin,
+  buildMcpAdminPluginWithApi,
+  mcpAdminPlugin,
+  mcpConfigPath,
+  readMcpConfig,
+  removeServerFromConfig,
+  setServerDisabled,
+  writeMcpConfig,
+  resolveServerSecrets,
+  type McpSecretResolver,
+  type AdminSkillRegistryLike,
+  type AdminToolRegistryLike,
+  type BuildMcpAdminPluginOptions,
+  type McpAdminApi,
+  type McpRuntimeHandle,
+  type McpServerStatus,
+  type McpStoredConfig,
+  type McpStoredServer,
+} from './admin/index.js';

package/src/client.ts

@@ -0,0 +1,120 @@
+/**
+ * Default MCP client factory + transport setup. Lives in its own module so
+ * both `index.ts` (the public surface) and `admin.ts` (the runtime
+ * admin/hot-attach tools) can pull `defaultClientFactory` without the two
+ * referencing each other — which is what would otherwise create the
+ * `admin.ts → index.ts → admin.ts` import cycle.
+ */
+
+import type {
+  McpCallResult,
+  McpClientLike,
+  McpContentBlock,
+  McpPluginOptions,
+  McpServerConfig,
+  McpToolDescriptor,
+} from './types.js';
+
+export async function defaultClientFactory(
+  server: McpServerConfig,
+  options: McpPluginOptions = { servers: [] },
+): Promise<McpClientLike> {
+  const { Client } = (await import('@modelcontextprotocol/sdk/client/index.js')) as {
+    Client: new (info: { name: string; version: string }, capabilities: { capabilities: Record<string, unknown> }) => McpClientUntyped;
+  };
+  // Type the SDK boundary ONCE here; the rest of the factory works against the
+  // typed `McpClientUntyped` so a signature change in the SDK surfaces as a
+  // compile error rather than being papered over by per-call casts.
+  const client: McpClientUntyped = new Client(
+    { name: options.clientName ?? 'moxxy', version: options.clientVersion ?? '0.0.0' },
+    { capabilities: {} },
+  );
+
+  const transport = await createTransport(server);
+  await client.connect(transport);
+
+  return {
+    async listTools() {
+      const result = await client.listTools();
+      return { tools: (result.tools ?? []).map(toToolDescriptor) };
+    },
+    async callTool(args) {
+      const result = await client.callTool(args);
+      const out: McpCallResult = {
+        content: result.content?.map(toContentBlock),
+        isError: result.isError,
+      };
+      return out;
+    },
+    async close() {
+      await client.close();
+    },
+  };
+}
+
+/** Narrow one SDK tool entry to our internal descriptor at the single boundary. */
+function toToolDescriptor(t: { name: string; description?: string; inputSchema: unknown }): McpToolDescriptor {
+  return t;
+}
+
+/** Narrow one SDK content block to our internal union at the single boundary. */
+function toContentBlock(block: { type: string } & Record<string, unknown>): McpContentBlock {
+  return block as McpContentBlock;
+}
+
+interface McpClientUntyped {
+  connect(transport: unknown): Promise<void>;
+  listTools(): Promise<{ tools?: Array<{ name: string; description?: string; inputSchema: unknown }> }>;
+  callTool(args: {
+    name: string;
+    arguments: unknown;
+  }): Promise<{ content?: Array<{ type: string } & Record<string, unknown>>; isError?: boolean }>;
+  close(): Promise<void>;
+}
+
+async function createTransport(server: McpServerConfig): Promise<unknown> {
+  const kind: 'stdio' | 'sse' | 'http' = server.kind ?? 'stdio';
+  if (kind === 'stdio') {
+    const stdioServer = server as { command: string; args?: ReadonlyArray<string>; env?: Record<string, string>; cwd?: string };
+    const { StdioClientTransport } = (await import('@modelcontextprotocol/sdk/client/stdio.js')) as {
+      StdioClientTransport: new (config: {
+        command: string;
+        args?: string[];
+        env?: Record<string, string>;
+        cwd?: string;
+        stderr?: 'inherit' | 'pipe' | 'ignore' | 'overlapped' | number;
+      }) => unknown;
+    };
+    // Set stderr to 'ignore' so spawned subprocesses (mcp-remote, etc.)
+    // don't dump their boot logs into the moxxy TUI. The SDK defaults
+    // to 'inherit' which clobbers the chat with proxy-status lines on
+    // every boot. Set MOXXY_MCP_STDERR=inherit to opt back in for
+    // debugging.
+    const stderrMode: 'inherit' | 'ignore' =
+      process.env.MOXXY_MCP_STDERR === 'inherit' ? 'inherit' : 'ignore';
+    return new StdioClientTransport({
+      command: stdioServer.command,
+      args: stdioServer.args ? [...stdioServer.args] : undefined,
+      env: stdioServer.env,
+      cwd: stdioServer.cwd,
+      stderr: stderrMode,
+    });
+  }
+  const httpish = server as { url: string; headers?: Record<string, string> };
+  if (kind === 'sse') {
+    const { SSEClientTransport } = (await import('@modelcontextprotocol/sdk/client/sse.js')) as {
+      SSEClientTransport: new (url: URL, opts?: { requestInit?: { headers?: Record<string, string> } }) => unknown;
+    };
+    return new SSEClientTransport(new URL(httpish.url), {
+      requestInit: httpish.headers ? { headers: httpish.headers } : undefined,
+    });
+  }
+  const { StreamableHTTPClientTransport } = (await import(
+    '@modelcontextprotocol/sdk/client/streamableHttp.js'
+  )) as {
+    StreamableHTTPClientTransport: new (url: URL, opts?: { requestInit?: { headers?: Record<string, string> } }) => unknown;
+  };
+  return new StreamableHTTPClientTransport(new URL(httpish.url), {
+    requestInit: httpish.headers ? { headers: httpish.headers } : undefined,
+  });
+}

package/src/discovery.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { ServiceRegistry } from '@moxxy/sdk';
+import { mcpAdminPlugin } from './index.js';
+
+/**
+ * The discovery-loadable default export resolves the tools + skills registries
+ * and the secret resolver from the service registry in onInit, and publishes its
+ * runtime api as the 'mcpAdmin' service (which Session.mcpAdmin exposes), instead
+ * of the host `{ toolRegistry, skillRegistry, secretResolver }` closure + stash.
+ */
+describe('mcpAdminPlugin (discovery-loadable)', () => {
+  it('exposes the mcp tools + an onInit hook', () => {
+    const names = mcpAdminPlugin.tools?.map((t) => t.name) ?? [];
+    expect(names).toContain('mcp_add_server');
+    expect(typeof mcpAdminPlugin.hooks?.onInit).toBe('function');
+  });
+
+  it('onInit resolves tools/skills/resolveSecrets and publishes mcpAdmin', async () => {
+    const reg = {
+      has: () => false,
+      register: () => {},
+      unregister: () => {},
+      byName: () => undefined,
+      list: () => [],
+    };
+    const get = vi.fn((name: string) =>
+      name === 'tools' || name === 'skills'
+        ? reg
+        : name === 'resolveSecrets'
+          ? async (v: string) => v
+          : undefined,
+    );
+    const register = vi.fn();
+    const services = { get, register, require: () => undefined, has: () => true } as unknown as ServiceRegistry;
+
+    // The inner onInit reads ~/.moxxy/mcp.json (absent on CI → caught + skipped);
+    // we only assert the service wiring here.
+    await mcpAdminPlugin.hooks!.onInit!({ services } as never);
+
+    expect(get).toHaveBeenCalledWith('tools');
+    expect(get).toHaveBeenCalledWith('skills');
+    expect(get).toHaveBeenCalledWith('resolveSecrets');
+    expect(register).toHaveBeenCalledWith('mcpAdmin', expect.anything());
+  });
+});

package/src/index.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it } from 'vitest';
+import { createMcpPlugin } from './index.js';
+import type { McpClientLike } from './types.js';
+
+const fakeClient: McpClientLike = {
+  async listTools() {
+    return {
+      tools: [
+        { name: 'ping', description: 'returns pong', inputSchema: { type: 'object' } },
+      ],
+    };
+  },
+  async callTool({ name }) {
+    return { content: [{ type: 'text', text: `pong from ${name}` }] };
+  },
+  async close() {},
+};
+
+describe('createMcpPlugin', () => {
+  it('builds a Plugin whose tools wrap each MCP server', async () => {
+    const plugin = await createMcpPlugin({
+      servers: [{ name: 'demo', command: 'noop' }],
+      clientFactory: async () => fakeClient,
+    });
+    expect(plugin.name).toBe('@moxxy/plugin-mcp');
+    expect(plugin.tools).toHaveLength(1);
+    expect(plugin.tools![0]!.name).toBe('mcp__demo__ping');
+  });
+
+  it('aggregates tools across multiple servers', async () => {
+    const plugin = await createMcpPlugin({
+      servers: [
+        { name: 'a', command: 'noop' },
+        { name: 'b', command: 'noop' },
+      ],
+      clientFactory: async () => fakeClient,
+    });
+    expect(plugin.tools).toHaveLength(2);
+    expect(plugin.tools!.map((t) => t.name)).toEqual(['mcp__a__ping', 'mcp__b__ping']);
+  });
+
+  it('connects servers in parallel and bounds boot at the slowest, not the sum (u86-5)', async () => {
+    // Two servers whose listTools each take ~50ms. Serial boot would take
+    // ~100ms; parallel ~50ms. Assert well under the serial sum and that both
+    // tool sets land in server order.
+    const slowClient = (name: string): McpClientLike => ({
+      async listTools() {
+        await new Promise((r) => setTimeout(r, 50));
+        return { tools: [{ name: 'ping', description: 'p', inputSchema: { type: 'object' } }] };
+      },
+      async callTool() {
+        return { content: [{ type: 'text', text: `pong ${name}` }] };
+      },
+      async close() {},
+    });
+    const start = Date.now();
+    const plugin = await createMcpPlugin({
+      servers: [{ name: 'a', command: 'noop' }, { name: 'b', command: 'noop' }],
+      clientFactory: async (s) => slowClient(s.name),
+    });
+    const elapsed = Date.now() - start;
+    expect(plugin.tools!.map((t) => t.name)).toEqual(['mcp__a__ping', 'mcp__b__ping']);
+    expect(elapsed).toBeLessThan(90); // < the ~100ms serial sum
+  });
+
+  it('closes already-connected clients when a later server fails to connect', async () => {
+    const closed: string[] = [];
+    let n = 0;
+    const factory = async (server: { name: string }): Promise<McpClientLike> => {
+      n++;
+      if (n === 2) throw new Error('second server connect failed');
+      return { ...fakeClient, async close() { closed.push(server.name); } };
+    };
+    await expect(
+      createMcpPlugin({
+        servers: [{ name: 'a', command: 'noop' }, { name: 'b', command: 'noop' }],
+        clientFactory: factory,
+      }),
+    ).rejects.toThrow(/second server connect failed/);
+    // The first server's client must have been closed (not leaked), even though
+    // we never returned the plugin and so its onShutdown hook was never wired.
+    expect(closed).toEqual(['a']);
+  });
+
+  it('registers an onShutdown hook that closes all clients', async () => {
+    let closed = 0;
+    const c: McpClientLike = { ...fakeClient, async close() { closed++; } };
+    const plugin = await createMcpPlugin({
+      servers: [{ name: 'a', command: 'noop' }, { name: 'b', command: 'noop' }],
+      clientFactory: async () => c,
+    });
+    await plugin.hooks?.onShutdown?.({} as never);
+    expect(closed).toBe(2);
+  });
+});

package/src/index.ts

@@ -0,0 +1,101 @@
+import { definePlugin, type Plugin } from '@moxxy/sdk';
+import type { McpClientLike, McpPluginOptions, McpServerConfig } from './types.js';
+import { defaultClientFactory } from './client.js';
+import { MCP_CONNECT_TIMEOUT_MS, withTimeout } from './timeout.js';
+import { wrapMcpServerTools } from './wrap.js';
+
+export type {
+  McpClientLike,
+  McpContentBlock,
+  McpPluginOptions,
+  McpServerConfig,
+  McpToolDescriptor,
+  SseServerConfig,
+  StdioServerConfig,
+  StreamableHttpServerConfig,
+} from './types.js';
+export { wrapMcpServerTools } from './wrap.js';
+export { defaultToolNamePrefix } from './types.js';
+export { defaultClientFactory } from './client.js';
+export {
+  buildMcpAdminPlugin,
+  buildMcpAdminPluginWithApi,
+  mcpAdminPlugin,
+  mcpConfigPath,
+  readMcpConfig,
+  removeServerFromConfig,
+  setServerDisabled,
+  writeMcpConfig,
+  resolveServerSecrets,
+  type McpSecretResolver,
+  type McpAdminApi,
+  type McpServerStatus,
+  type McpStoredConfig,
+  type McpStoredServer,
+} from './admin.js';
+
+export interface CreateMcpPluginOptions extends McpPluginOptions {
+  /**
+   * Inject a custom client factory. Used by tests; production code uses the
+   * default factory that imports `@modelcontextprotocol/sdk`.
+   */
+  readonly clientFactory?: (server: McpServerConfig, options: McpPluginOptions) => Promise<McpClientLike>;
+}
+
+export async function createMcpPlugin(opts: CreateMcpPluginOptions): Promise<Plugin> {
+  const factory = opts.clientFactory ?? defaultClientFactory;
+  // Connect + list each server in PARALLEL: serial boot paid the sum of every
+  // server's spawn/handshake/listTools round-trip, so N servers serialized N
+  // latencies. allSettled bounds boot at the slowest server, not the sum,
+  // while still letting us close every successfully-opened client if any leg
+  // fails (the onShutdown hook is only wired once we RETURN the plugin).
+  const opened: McpClientLike[] = [];
+  const results = await Promise.allSettled(
+    opts.servers.map(async (server) => {
+      // Bound the connect handshake so a single wedged server spawn surfaces
+      // as a rejected leg rather than stalling boot until the transport's own
+      // (possibly absent) timeout fires. The leg's client, if it opened before
+      // the timeout, is still tracked in `opened` and closed in the failure
+      // cleanup below.
+      const client = await withTimeout(
+        factory(server, opts),
+        MCP_CONNECT_TIMEOUT_MS,
+        `MCP connect "${server.name}"`,
+      );
+      // Record the client the instant it opens, before listTools — so even a
+      // listTools failure can't leak its child process / socket.
+      opened.push(client);
+      return withTimeout(
+        wrapMcpServerTools({ server, client, toolNamePrefix: opts.toolNamePrefix }),
+        MCP_CONNECT_TIMEOUT_MS,
+        `MCP listTools "${server.name}"`,
+      );
+    }),
+  );
+
+  const failure = results.find((r) => r.status === 'rejected');
+  if (failure) {
+    await Promise.allSettled(opened.map((c) => c.close()));
+    throw (failure as PromiseRejectedResult).reason;
+  }
+
+  // Flatten in server order (map preserves index → deterministic tool order).
+  const tools = results.flatMap((r) => (r as PromiseFulfilledResult<Awaited<ReturnType<typeof wrapMcpServerTools>>>).value);
+  const clients = opened;
+
+  return definePlugin({
+    name: '@moxxy/plugin-mcp',
+    version: '0.0.0',
+    tools,
+    hooks: {
+      onShutdown: async () => {
+        await Promise.allSettled(clients.map((c) => c.close()));
+      },
+    },
+  });
+}
+
+
+
+// Discovery entry: `createPluginLoader` requires a default Plugin export.
+export { mcpAdminPlugin as default } from './admin.js';

package/src/timeout.ts

@@ -0,0 +1,37 @@
+/**
+ * Bounded connect/discovery timeout shared by every boot-time path that
+ * opens a connection and lists tools. The per-call timeout in `wrap.ts`
+ * (MCP_CALL_TIMEOUT_MS) only guards tool *invocations* — it does nothing
+ * for the connect()+listTools() handshake performed at session boot
+ * (refreshServerCache, eager createMcpPlugin) or on first lazy call. Without
+ * a cap, a single unreachable HTTP/SSE endpoint or a stdio child that spawns
+ * but never answers listTools blocks session boot forever (core awaits
+ * onInit serially), so one stale entry in mcp.json can make moxxy unstartable.
+ *
+ * 30s is generous for a real handshake (npx cold-start, slow proxy auth) but
+ * bounds the worst case to a skipped server rather than a wedged boot.
+ */
+export const MCP_CONNECT_TIMEOUT_MS = 30 * 1000;
+
+/**
+ * Race `work` against a hard timeout. On timeout the returned promise
+ * rejects; `work` itself is not cancellable here (the MCP SDK connect/list
+ * calls take no AbortSignal), so the caller is responsible for closing any
+ * handle that escapes after the reject. The timer is always cleared so it
+ * never keeps the event loop alive.
+ */
+export async function withTimeout<T>(
+  work: Promise<T>,
+  ms: number,
+  label: string,
+): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<never>((_resolve, reject) => {
+    timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms);
+  });
+  try {
+    return await Promise.race([work, timeout]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}

package/src/types.ts

@@ -0,0 +1,57 @@
+export interface StdioServerConfig {
+  readonly kind?: 'stdio';
+  readonly name: string;
+  readonly command: string;
+  readonly args?: ReadonlyArray<string>;
+  readonly env?: Record<string, string>;
+  readonly cwd?: string;
+}
+
+export interface SseServerConfig {
+  readonly kind: 'sse';
+  readonly name: string;
+  readonly url: string;
+  readonly headers?: Record<string, string>;
+}
+
+export interface StreamableHttpServerConfig {
+  readonly kind: 'http';
+  readonly name: string;
+  readonly url: string;
+  readonly headers?: Record<string, string>;
+}
+
+export type McpServerConfig = StdioServerConfig | SseServerConfig | StreamableHttpServerConfig;
+
+export interface McpPluginOptions {
+  readonly servers: ReadonlyArray<McpServerConfig>;
+  readonly clientName?: string;
+  readonly clientVersion?: string;
+  readonly toolNamePrefix?: (serverName: string, toolName: string) => string;
+}
+
+export interface McpClientLike {
+  listTools(): Promise<{ tools: ReadonlyArray<McpToolDescriptor> }>;
+  callTool(args: { name: string; arguments: unknown }): Promise<McpCallResult>;
+  close(): Promise<void>;
+}
+
+export interface McpToolDescriptor {
+  readonly name: string;
+  readonly description?: string;
+  readonly inputSchema: unknown;
+}
+
+export interface McpCallResult {
+  readonly content?: ReadonlyArray<McpContentBlock>;
+  readonly isError?: boolean;
+}
+
+export type McpContentBlock =
+  | { readonly type: 'text'; readonly text: string }
+  | { readonly type: 'image'; readonly data: string; readonly mimeType: string }
+  | { readonly type: 'resource'; readonly resource: unknown };
+
+export function defaultToolNamePrefix(serverName: string, toolName: string): string {
+  return `mcp__${serverName}__${toolName}`;
+}