@moxxy/plugin-mcp 0.26.0

package/src/admin/runtime.ts

@@ -0,0 +1,244 @@
+import { MoxxyError } from '@moxxy/sdk';
+import type { McpClientLike, McpServerConfig, McpToolDescriptor } from '../types.js';
+import { defaultClientFactory } from '../client.js';
+import { MCP_CONNECT_TIMEOUT_MS, withTimeout } from '../timeout.js';
+import { wrapMcpServerToolsLazy } from '../wrap.js';
+import { mutateMcpConfig } from './config-io.js';
+import { resolveServerSecrets, type McpSecretResolver } from './secrets.js';
+import type {
+  AdminToolRegistryLike,
+  McpRuntimeHandle,
+  McpStoredServer,
+} from './types.js';
+
+export interface McpRuntime {
+  readonly runtimes: Map<string, McpRuntimeHandle>;
+  attachServer(server: McpServerConfig): Promise<{
+    toolNames: ReadonlyArray<string>;
+    descriptors: ReadonlyArray<McpToolDescriptor>;
+  }>;
+  attachServerLazy(server: McpStoredServer): { toolNames: ReadonlyArray<string> };
+  refreshServerCache(server: McpStoredServer): Promise<McpStoredServer>;
+  detachServer(name: string): Promise<boolean>;
+}
+
+export interface McpRuntimeOptions {
+  /**
+   * Resolves `${vault:NAME}` placeholders in env/header values at CONNECT
+   * time (see `secrets.ts`). The stored config — and everything persisted
+   * back to it — keeps the placeholder form.
+   */
+  readonly secretResolver?: McpSecretResolver | null;
+}
+
+export function createMcpRuntime(
+  registry: AdminToolRegistryLike | null,
+  options: McpRuntimeOptions = {},
+): McpRuntime {
+  const secretResolver = options.secretResolver ?? null;
+  /** Connect with secrets resolved; `server` itself stays placeholder-form. */
+  const connect = async (server: McpServerConfig): Promise<McpClientLike> =>
+    defaultClientFactory(await resolveServerSecrets(server, secretResolver));
+  // Track hot-attached runtimes keyed by server name. We need to know
+  // which tools each server contributed so `mcp_remove_server` can
+  // unregister them cleanly, and which client to close on shutdown.
+  const runtimes = new Map<string, McpRuntimeHandle>();
+
+  /**
+   * Eager attach used by `mcp_add_server`: connect, list tools, register
+   * them. Returns the discovered descriptors so the caller can cache
+   * them into mcp.json for lazy boots next time.
+   */
+  const attachServer: McpRuntime['attachServer'] = async (server) => {
+    // Bound the connect + listTools handshake. `mcp_add_server` and
+    // `enableAndAttach` drive this path at the model's request; a wedged
+    // server spawn (or a connected-but-mute endpoint that never answers
+    // listTools) would otherwise hang the tool call indefinitely — a
+    // permanent pending dot with no recovery short of killing moxxy. On
+    // timeout we reject AND close any client that opened, so a slow-to-spawn
+    // stdio child / socket can't leak after we've given up on it.
+    const client = await withTimeout(
+      connect(server),
+      MCP_CONNECT_TIMEOUT_MS,
+      `MCP connect "${server.name}"`,
+    );
+    let list: { tools: ReadonlyArray<McpToolDescriptor> };
+    try {
+      list = await withTimeout(
+        client.listTools(),
+        MCP_CONNECT_TIMEOUT_MS,
+        `MCP listTools "${server.name}"`,
+      );
+    } catch (err) {
+      await client.close().catch(() => {});
+      throw err;
+    }
+    const descriptors = list.tools;
+    // List ONCE and feed the descriptors into the lazy wrapper over the
+    // already-open client — wrapMcpServerTools would call listTools a second
+    // time, paying a redundant round-trip and risking descriptor/tool drift
+    // for servers whose tool list is non-deterministic between calls.
+    const wrapped = wrapMcpServerToolsLazy({
+      server,
+      descriptors,
+      getClient: () => Promise.resolve(client),
+    });
+    if (!registry) {
+      await client.close();
+      return { toolNames: wrapped.map((t) => t.name), descriptors };
+    }
+    const collisions = wrapped.filter((t) => registry.has(t.name)).map((t) => t.name);
+    if (collisions.length > 0) {
+      await client.close();
+      throw new MoxxyError({
+        code: 'CONFIG_INVALID',
+        message:
+          `mcp_add_server: tool name collision — already registered: ${collisions.join(', ')}. ` +
+          'Pick a different server name (the server name becomes a prefix on each tool).',
+      });
+    }
+    for (const tool of wrapped) registry.register(tool);
+    runtimes.set(server.name, { client, toolNames: wrapped.map((t) => t.name) });
+    return { toolNames: wrapped.map((t) => t.name), descriptors };
+  };
+
+  /**
+   * Lazy attach used at boot: register stub tools using cached
+   * descriptors WITHOUT connecting. The first call to any of these
+   * tools triggers a single shared connection via `getOrConnect`;
+   * subsequent calls reuse it. Failed connections reset so the next
+   * call can retry.
+   *
+   * When `cachedTools` is missing (catalog entry predates the cache
+   * feature or was edited by hand), the caller is responsible for
+   * refreshing the cache first via `refreshServerCache`.
+   */
+  const attachServerLazy: McpRuntime['attachServerLazy'] = (server) => {
+    if (!registry) return { toolNames: [] };
+    if (runtimes.has(server.name)) return { toolNames: runtimes.get(server.name)!.toolNames };
+    const descriptors = server.cachedTools ?? [];
+    if (descriptors.length === 0) {
+      return { toolNames: [] };
+    }
+
+    let connectPromise: Promise<McpClientLike> | null = null;
+    const getOrConnect = async (): Promise<McpClientLike> => {
+      if (!connectPromise) {
+        connectPromise = (async () => {
+          // Bound the first-call connect so a wedged transport can't hang the
+          // triggering tool call forever (the per-call timeout in wrap.ts only
+          // covers callTool, not this connect handshake).
+          const client = await withTimeout(
+            connect(server),
+            MCP_CONNECT_TIMEOUT_MS,
+            `MCP connect "${server.name}"`,
+          );
+          // Stash the live client on the runtime entry so shutdown can
+          // close it. The entry was created with a sentinel; replace it.
+          const runtime = runtimes.get(server.name);
+          if (runtime) {
+            runtimes.set(server.name, { client, toolNames: runtime.toolNames });
+            return client;
+          }
+          // detachServer ran while this connect was in flight: the runtime
+          // entry (and its shutdown close path) is gone. Close the freshly
+          // opened client here so its stdio child / socket isn't orphaned,
+          // and fail the call rather than handing back a leaked handle.
+          await client.close().catch(() => {});
+          throw new Error(`MCP server "${server.name}" detached during connect`);
+        })().catch((err) => {
+          // Reset so a future call can retry instead of being stuck on
+          // a rejected promise.
+          connectPromise = null;
+          throw err;
+        });
+      }
+      return connectPromise;
+    };
+
+    const wrapped = wrapMcpServerToolsLazy({ server, descriptors, getClient: getOrConnect });
+    const collisions = wrapped.filter((t) => registry.has(t.name)).map((t) => t.name);
+    if (collisions.length > 0) {
+      throw new MoxxyError({
+        code: 'CONFIG_INVALID',
+        message:
+          `lazy attach: tool name collision for "${server.name}": ${collisions.join(', ')}. ` +
+          'A different server (or a previously-attached version) already owns these names.',
+      });
+    }
+    for (const tool of wrapped) registry.register(tool);
+    // Sentinel client gets swapped for the real one inside getOrConnect.
+    // Until first call, close() is a no-op via the LazyClient sentinel.
+    const lazyClient: McpClientLike = {
+      listTools: async () => ({ tools: descriptors }),
+      callTool: async (args) => (await getOrConnect()).callTool(args),
+      close: async () => {
+        if (connectPromise) {
+          const client = await connectPromise.catch(() => null);
+          if (client) await client.close();
+        }
+      },
+    };
+    runtimes.set(server.name, { client: lazyClient, toolNames: wrapped.map((t) => t.name) });
+    return { toolNames: wrapped.map((t) => t.name) };
+  };
+
+  /**
+   * Connect to a server, list its tools, and write the descriptors back
+   * to mcp.json. Used to refresh stale or missing caches at boot. The
+   * connection is closed immediately — registration happens via the
+   * caller's subsequent `attachServerLazy` call.
+   */
+  const refreshServerCache: McpRuntime['refreshServerCache'] = async (server) => {
+    // Bound the connect handshake: a dead endpoint or a stdio child that
+    // spawns but never completes the MCP handshake would otherwise hang here,
+    // and at boot core awaits onInit serially — one stale entry would make
+    // moxxy unstartable. On timeout we reject (the onInit catch logs+skips it).
+    const client = await withTimeout(
+      connect(server),
+      MCP_CONNECT_TIMEOUT_MS,
+      `MCP connect "${server.name}"`,
+    );
+    try {
+      // Bound listTools too — a connected-but-unresponsive server can stall
+      // discovery just as badly as a dead connect.
+      const list = await withTimeout(
+        client.listTools(),
+        MCP_CONNECT_TIMEOUT_MS,
+        `MCP listTools "${server.name}"`,
+      );
+      const refreshed: McpStoredServer = { ...server, cachedTools: list.tools };
+      // Persist the refreshed cache so subsequent boots can lazy-attach
+      // without reconnecting. Read-modify-write under the shared config
+      // mutex so a concurrent add/remove can't clobber the file.
+      await mutateMcpConfig((cfg) => ({
+        next: { servers: cfg.servers.map((s) => (s.name === server.name ? refreshed : s)) },
+        result: undefined,
+      }));
+      return refreshed;
+    } finally {
+      try {
+        await client.close();
+      } catch {
+        /* ignore */
+      }
+    }
+  };
+
+  const detachServer: McpRuntime['detachServer'] = async (name) => {
+    const runtime = runtimes.get(name);
+    if (!runtime) return false;
+    runtimes.delete(name);
+    if (registry) {
+      for (const toolName of runtime.toolNames) registry.unregister(toolName);
+    }
+    try {
+      await runtime.client.close();
+    } catch {
+      // ignore — best-effort close
+    }
+    return true;
+  };
+
+  return { runtimes, attachServer, attachServerLazy, refreshServerCache, detachServer };
+}

package/src/admin/schema.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from 'vitest';
+import { MoxxyError } from '@moxxy/sdk';
+import { addServerInput, type AddServerInput, validateAddServerInput } from './schema.js';
+
+const input = (over: Partial<AddServerInput>): AddServerInput =>
+  ({ kind: 'stdio', name: 'demo', command: 'noop', autoSkill: true, ...over }) as AddServerInput;
+
+describe('validateAddServerInput', () => {
+  it('builds a stdio config and strips autoSkill', () => {
+    const cfg = validateAddServerInput(input({ command: 'npx', args: ['x'], autoSkill: true }));
+    expect(cfg).toEqual({ kind: 'stdio', name: 'demo', command: 'npx', args: ['x'] });
+    expect('autoSkill' in cfg).toBe(false);
+  });
+
+  it('builds an http config and strips autoSkill', () => {
+    const cfg = validateAddServerInput(
+      input({ kind: 'http', command: undefined, url: 'https://x.test', headers: { a: 'b' } }),
+    );
+    expect(cfg).toEqual({ kind: 'http', name: 'demo', url: 'https://x.test', headers: { a: 'b' } });
+    expect('autoSkill' in cfg).toBe(false);
+  });
+
+  it('throws CONFIG_INVALID when kind="stdio" omits command', () => {
+    let err: unknown;
+    try {
+      validateAddServerInput(input({ kind: 'stdio', command: undefined }));
+    } catch (e) {
+      err = e;
+    }
+    expect(err).toBeInstanceOf(MoxxyError);
+    expect((err as MoxxyError).code).toBe('CONFIG_INVALID');
+    expect((err as Error).message).toMatch(/requires a `command`/);
+  });
+
+  it('throws CONFIG_INVALID when kind="http" omits url', () => {
+    expect(() => validateAddServerInput(input({ kind: 'http', command: undefined }))).toThrow(
+      /requires a `url`/,
+    );
+  });
+
+  it('throws CONFIG_INVALID when kind="sse" omits url', () => {
+    let err: unknown;
+    try {
+      validateAddServerInput(input({ kind: 'sse', command: undefined }));
+    } catch (e) {
+      err = e;
+    }
+    expect((err as MoxxyError).code).toBe('CONFIG_INVALID');
+    expect((err as Error).message).toMatch(/kind="sse"/);
+  });
+});
+
+describe('addServerInput url scheme allow-list (SSRF surface)', () => {
+  const base = { kind: 'http' as const, name: 'remote' };
+
+  it('accepts http and https urls', () => {
+    expect(addServerInput.safeParse({ ...base, url: 'https://mcp.example.com' }).success).toBe(true);
+    expect(addServerInput.safeParse({ ...base, url: 'http://localhost:3000/mcp' }).success).toBe(true);
+  });
+
+  it.each([
+    'file:///etc/passwd',
+    'gopher://internal/',
+    'ws://mcp.example.com',
+    'ftp://host/x',
+  ])('rejects non-http(s) scheme %s', (url) => {
+    const parsed = addServerInput.safeParse({ ...base, url });
+    expect(parsed.success).toBe(false);
+  });
+});

package/src/admin/schema.ts

@@ -0,0 +1,110 @@
+import { MoxxyError, z } from '@moxxy/sdk';
+import type { McpServerConfig } from '../types.js';
+
+export const serverNameSchema = z
+  .string()
+  .min(1)
+  .max(60)
+  .regex(/^[a-z0-9][a-z0-9-]*$/, 'name must be slug-like (lowercase letters, digits, hyphens)');
+
+// Flat schema (no discriminated union) so OpenAI's function-calling
+// validator accepts it. OpenAI rejects top-level oneOf/anyOf with
+// "object schema missing properties"; the model now sees a single
+// object with `kind` + every transport-specific field optional, plus
+// a runtime guard in the handler that enforces the per-kind required
+// set with a readable error.
+export const addServerInput = z.object({
+  kind: z.enum(['stdio', 'http', 'sse']).describe(
+    'Transport kind. "stdio" runs a local executable; "http" and "sse" connect to a remote URL.',
+  ),
+  name: serverNameSchema,
+  // stdio-only fields
+  command: z
+    .string()
+    .min(1)
+    .optional()
+    .describe('Required when kind="stdio". Executable to spawn (e.g. "npx", "uv", "python").'),
+  args: z
+    .array(z.string())
+    .optional()
+    .describe('Optional when kind="stdio". CLI arguments for the executable.'),
+  env: z
+    .record(z.string())
+    .optional()
+    .describe(
+      'Optional when kind="stdio". Environment variables for the spawned process. ' +
+        'Secrets MUST be vault references ("${vault:NAME}", stored via vault_set first), ' +
+        'never plaintext — placeholders are resolved at connect time only.',
+    ),
+  cwd: z
+    .string()
+    .optional()
+    .describe('Optional when kind="stdio". Working directory for the spawned process.'),
+  // http/sse-only fields
+  url: z
+    .string()
+    .url()
+    // Restrict to http(s): a bare .url() accepts file:, gopher:, ws:, etc.,
+    // turning a model-proposed MCP endpoint into an SSRF/file-read surface
+    // (e.g. file:///etc/passwd, http://169.254.169.254 metadata). The human
+    // permission prompt still gates the add/test, but reject obviously-wrong
+    // schemes before any connection is attempted.
+    .regex(/^https?:\/\//i, 'url must use the http:// or https:// scheme')
+    .optional()
+    .describe('Required when kind="http" or "sse". Server URL (http/https only).'),
+  headers: z
+    .record(z.string())
+    .optional()
+    .describe(
+      'Optional when kind="http" or "sse". HTTP headers (auth, etc). Secrets MUST be ' +
+        'vault references ("${vault:NAME}", stored via vault_set first), never plaintext — ' +
+        'placeholders are resolved at connect time only.',
+    ),
+  autoSkill: z
+    .boolean()
+    .optional()
+    .default(true)
+    .describe(
+      'When true (default), auto-write a deterministic usage skill ' +
+        '<server-name>-mcp.md into ~/.moxxy/skills/ documenting the ' +
+        'tools the server exposes. Pass false if the user explicitly ' +
+        'asked for no skill.',
+    ),
+});
+
+export type AddServerInput = z.infer<typeof addServerInput>;
+
+export function validateAddServerInput(input: AddServerInput): McpServerConfig {
+  // autoSkill is consumed by the handler, not by the connection factory —
+  // strip it before constructing the McpServerConfig.
+  void input.autoSkill;
+  if (input.kind === 'stdio') {
+    if (!input.command) {
+      throw new MoxxyError({
+        code: 'CONFIG_INVALID',
+        message: 'mcp_add_server: kind="stdio" requires a `command` field (e.g. "npx", "uv", "python").',
+      });
+    }
+    const out: McpServerConfig = {
+      kind: 'stdio',
+      name: input.name,
+      command: input.command,
+      ...(input.args ? { args: input.args } : {}),
+      ...(input.env ? { env: input.env } : {}),
+      ...(input.cwd ? { cwd: input.cwd } : {}),
+    };
+    return out;
+  }
+  if (!input.url) {
+    throw new MoxxyError({
+      code: 'CONFIG_INVALID',
+      message: `mcp_add_server: kind="${input.kind}" requires a \`url\` field (the remote MCP endpoint).`,
+    });
+  }
+  return {
+    kind: input.kind,
+    name: input.name,
+    url: input.url,
+    ...(input.headers ? { headers: input.headers } : {}),
+  };
+}

package/src/admin/secrets.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { McpServerConfig } from '../types.js';
+import { resolveServerSecrets } from './secrets.js';
+
+const resolver = vi.fn(async (value: string) =>
+  value.replace(/\$\{vault:([A-Za-z0-9_.-]+)\}/g, (_m, name: string) => `sekret-${name}`),
+);
+
+describe('resolveServerSecrets', () => {
+  it('resolves placeholders in stdio env values', async () => {
+    const server: McpServerConfig = {
+      kind: 'stdio',
+      name: 'demo',
+      command: 'npx',
+      env: { API_KEY: '${vault:k}', HOME: '/home/u' },
+    };
+    const out = (await resolveServerSecrets(server, resolver)) as Extract<McpServerConfig, { command: string }>;
+    expect(out.env).toEqual({ API_KEY: 'sekret-k', HOME: '/home/u' });
+    // Original untouched — that object is what gets persisted.
+    expect(server.env).toEqual({ API_KEY: '${vault:k}', HOME: '/home/u' });
+  });
+
+  it('resolves placeholders in http/sse header values', async () => {
+    const server: McpServerConfig = {
+      kind: 'sse',
+      name: 'demo',
+      url: 'https://mcp.example.com/sse',
+      headers: { authorization: 'Bearer ${vault:tok}' },
+    };
+    const out = (await resolveServerSecrets(server, resolver)) as Extract<McpServerConfig, { url: string }>;
+    expect(out.headers).toEqual({ authorization: 'Bearer sekret-tok' });
+  });
+
+  it('returns the same object when nothing resolves (literal passthrough)', async () => {
+    const server: McpServerConfig = {
+      kind: 'stdio',
+      name: 'demo',
+      command: 'npx',
+      env: { PLAIN: 'literal-value' },
+    };
+    expect(await resolveServerSecrets(server, resolver)).toBe(server);
+  });
+
+  it('is the identity without a resolver (back-compat for plaintext configs)', async () => {
+    const server: McpServerConfig = {
+      kind: 'http',
+      name: 'demo',
+      url: 'https://mcp.example.com',
+      headers: { authorization: 'Bearer plaintext' },
+    };
+    expect(await resolveServerSecrets(server, null)).toBe(server);
+    expect(await resolveServerSecrets(server, undefined)).toBe(server);
+  });
+
+  it('treats a missing kind as stdio', async () => {
+    const server = { name: 'demo', command: 'npx', env: { K: '${vault:x}' } } as McpServerConfig;
+    const out = (await resolveServerSecrets(server, resolver)) as Extract<McpServerConfig, { command: string }>;
+    expect(out.env).toEqual({ K: 'sekret-x' });
+  });
+});

package/src/admin/secrets.ts

@@ -0,0 +1,55 @@
+import type { McpServerConfig } from '../types.js';
+
+/**
+ * Connect-time secret resolution for MCP server credentials.
+ *
+ * Server entries in ~/.moxxy/mcp.json (and the `mcp_add_server` /
+ * `mcp_test_server` tool args) may carry `${vault:NAME}` placeholders in
+ * `env` values (stdio) and `headers` values (http/sse). The PLACEHOLDER is
+ * what gets persisted; the plaintext secret only ever materializes in the
+ * resolved copy handed to the transport at connect time — never in the
+ * model's context, never on disk.
+ *
+ * plugin-mcp deliberately has no vault dependency: setup wires a resolver
+ * (the CLI passes the vault's `resolveString`). A resolver MUST pass literal
+ * values through unchanged so pre-placeholder configs keep working.
+ */
+export type McpSecretResolver = (value: string) => Promise<string>;
+
+/**
+ * Return a copy of `server` with every `env` / `headers` value passed
+ * through `resolver`. With no resolver (or nothing to resolve) the original
+ * object is returned untouched — callers rely on that to persist the
+ * placeholder form, not the resolved one.
+ */
+export async function resolveServerSecrets(
+  server: McpServerConfig,
+  resolver: McpSecretResolver | null | undefined,
+): Promise<McpServerConfig> {
+  if (!resolver) return server;
+  const kind = server.kind ?? 'stdio';
+  if (kind === 'http' || kind === 'sse') {
+    const httpish = server as Extract<McpServerConfig, { url: string }>;
+    if (!httpish.headers) return server;
+    const headers = await resolveRecord(httpish.headers, resolver);
+    return headers === httpish.headers ? server : { ...httpish, headers };
+  }
+  const stdio = server as Extract<McpServerConfig, { command: string }>;
+  if (!stdio.env) return server;
+  const env = await resolveRecord(stdio.env, resolver);
+  return env === stdio.env ? server : { ...stdio, env };
+}
+
+async function resolveRecord(
+  rec: Record<string, string>,
+  resolver: McpSecretResolver,
+): Promise<Record<string, string>> {
+  let changed = false;
+  const out: Record<string, string> = {};
+  for (const [key, value] of Object.entries(rec)) {
+    const resolved = await resolver(value);
+    if (resolved !== value) changed = true;
+    out[key] = resolved;
+  }
+  return changed ? out : rec;
+}

package/src/admin/skill.test.ts

@@ -0,0 +1,143 @@
+import { readFile } from 'node:fs/promises';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { Skill } from '@moxxy/sdk';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import type { McpServerConfig, McpToolDescriptor } from '../types.js';
+import { createMcpUsageSkillWriter } from './skill.js';
+import type { AdminSkillRegistryLike } from './types.js';
+
+// Minimal block-scalar / sequence frontmatter parser — independent of the
+// unit under test — so "well-formed YAML" is actually parsed and checked,
+// not just regexed. Mirrors @moxxy/core's hand-rolled skill frontmatter
+// reader (key: scalar, plus `key:` followed by `  - item` sequences).
+function parseFrontmatter(raw: string): { fm: Record<string, unknown>; body: string } {
+  expect(raw.startsWith('---\n')).toBe(true);
+  const rest = raw.slice(4);
+  const end = rest.indexOf('\n---\n');
+  expect(end).toBeGreaterThan(-1);
+  const fmText = rest.slice(0, end);
+  const body = rest.slice(end + 5).replace(/^\n/, '');
+  const fm: Record<string, unknown> = {};
+  const lines = fmText.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!;
+    if (!line.trim()) continue;
+    const m = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line);
+    if (!m) throw new Error(`unparseable frontmatter line: ${JSON.stringify(line)}`);
+    const [, key, val] = m;
+    if (val) {
+      fm[key!] = val;
+    } else {
+      const items: string[] = [];
+      while (i + 1 < lines.length && /^\s+-\s/.test(lines[i + 1]!)) {
+        i++;
+        items.push(lines[i]!.replace(/^\s+-\s*/, '').replace(/^"(.*)"$/, '$1'));
+      }
+      fm[key!] = items;
+    }
+  }
+  return { fm, body };
+}
+
+const DESCRIPTORS: ReadonlyArray<McpToolDescriptor> = [
+  { name: 'fetch', description: 'Fetch a URL', inputSchema: { type: 'object' } },
+  { name: 'shell', description: undefined, inputSchema: { type: 'object' } },
+];
+
+const server: McpServerConfig = { kind: 'stdio', name: 'acme', command: 'noop' };
+
+const fakeRegistry = (): AdminSkillRegistryLike & { registered: Skill[] } => {
+  const registered: Skill[] = [];
+  return {
+    registered,
+    register: (s) => registered.push(s),
+    byName: (n) => registered.find((s) => s.frontmatter.name === n),
+  };
+};
+
+describe('admin/skill (createMcpUsageSkillWriter)', () => {
+  let dir: string;
+
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'moxxy-mcp-skill-'));
+  });
+
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it('writes a well-formed-YAML frontmatter file with the expected fields + body', async () => {
+    const registry = fakeRegistry();
+    const write = createMcpUsageSkillWriter({ skillRegistry: registry, userSkillsDir: dir });
+    const result = await write(server, DESCRIPTORS);
+    expect(result).not.toBeNull();
+    expect(result!.skillName).toBe('acme-mcp');
+    expect(result!.path).toBe(join(dir, 'acme-mcp.md'));
+
+    const raw = await readFile(result!.path, 'utf8');
+    const { fm, body } = parseFrontmatter(raw);
+    expect(fm.name).toBe('acme-mcp');
+    expect(fm.description).toBe('Use the acme MCP server (2 tools).');
+    expect(fm.triggers).toEqual(['acme', 'acme mcp', 'use acme']);
+    expect(fm['allowed-tools']).toEqual(['mcp__acme__fetch', 'mcp__acme__shell']);
+
+    // Body documents each tool, namespacing it, and handles the missing
+    // description gracefully.
+    expect(body).toContain('mcp__acme__fetch` — Fetch a URL');
+    expect(body).toContain('mcp__acme__shell` — (no description provided)');
+    expect(body).toContain('## Available tools');
+  });
+
+  it('registers a Skill object mirroring the discovered file', async () => {
+    const registry = fakeRegistry();
+    const write = createMcpUsageSkillWriter({ skillRegistry: registry, userSkillsDir: dir });
+    await write(server, DESCRIPTORS);
+    expect(registry.registered).toHaveLength(1);
+    const skill = registry.registered[0]!;
+    expect(skill.id).toBe('user/acme-mcp');
+    expect(skill.scope).toBe('user');
+    expect(skill.path).toBe(join(dir, 'acme-mcp.md'));
+    expect(skill.frontmatter.name).toBe('acme-mcp');
+    expect(skill.frontmatter['allowed-tools']).toEqual(['mcp__acme__fetch', 'mcp__acme__shell']);
+    expect(skill.body).toContain('## Available tools');
+  });
+
+  it('is a no-op (returns null, no re-register) when a skill of that name already exists', async () => {
+    const registry = fakeRegistry();
+    const write = createMcpUsageSkillWriter({ skillRegistry: registry, userSkillsDir: dir });
+    await write(server, DESCRIPTORS);
+    expect(registry.registered).toHaveLength(1);
+    // A second attach for the same server must not clobber user edits.
+    const second = await write(server, DESCRIPTORS);
+    expect(second).toBeNull();
+    expect(registry.registered).toHaveLength(1);
+  });
+
+  it('still writes the file (and returns a result) with no skill registry', async () => {
+    const write = createMcpUsageSkillWriter({ skillRegistry: null, userSkillsDir: dir });
+    const result = await write(server, DESCRIPTORS);
+    expect(result).not.toBeNull();
+    const raw = await readFile(result!.path, 'utf8');
+    expect(raw).toContain('name: acme-mcp');
+  });
+
+  it('reflects the tool count and lists every tool in allowed-tools + body', async () => {
+    const many: ReadonlyArray<McpToolDescriptor> = Array.from({ length: 5 }, (_, i) => ({
+      name: `t${i}`,
+      description: `does ${i}`,
+      inputSchema: { type: 'object' },
+    }));
+    const write = createMcpUsageSkillWriter({ skillRegistry: null, userSkillsDir: dir });
+    const result = await write(server, many);
+    const raw = await readFile(result!.path, 'utf8');
+    const { fm, body } = parseFrontmatter(raw);
+    expect(fm.description).toBe('Use the acme MCP server (5 tools).');
+    expect((fm['allowed-tools'] as string[])).toHaveLength(5);
+    expect((fm['allowed-tools'] as string[])[4]).toBe('mcp__acme__t4');
+    expect(body).toContain('mcp__acme__t4` — does 4');
+    // The description's defensive 240-char cap holds for normal inputs.
+    expect((fm.description as string).length).toBeLessThanOrEqual(240);
+  });
+});