clyops-mcp 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,106 @@
-# Temporary Holding Version
+# clyops-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Give an AI agent a directory of [clyops](https://github.com/wankdanker/clyops) tools over the
+[Model Context Protocol](https://modelcontextprotocol.io). Every clyops tool becomes an MCP tool:
+its description and input schema come from its own `--help-json-schema`, so the agent sees the same
+options, types, choices and ranges the tool validates, and nothing needs to be written per tool.
+
+```sh
+npm install -g clyops-mcp
+```
+
+## Local agent (stdio)
+
+```sh
+claude mcp add mytool -- clyops-mcp --root ~/mytool/scripts
+```
+
+or in any client's MCP config:
+
+```json
+{ "mcpServers": { "mytool": { "command": "clyops-mcp", "args": ["--root", "/home/me/mytool/scripts"] } } }
+```
+
+```
+scripts/
+  .clyops             (description: My tools) → the server's instructions to the agent
+  check.sh            → tool "check"
+  media/
+    to-pcm.sh         → tool "media_to-pcm"
+```
+
+The directory is read like [clyops-dispatch](../dispatch) reads it, and `--root` may also be a
+dispatcher definition file. Only programs built on a clyops library are offered.
+
+A call's arguments are validated against the tool's schema before anything runs and mapped onto
+its command line ([spec §13](../../spec/SPEC.md#13-json-input-toargv)). The agent gets the tool's
+stdout back; when stdout is a JSON object it is also returned as structured content. A tool that
+fails comes back as an error with its exit status and stderr, so the agent can read the tool's own
+message and correct itself.
+
+- **Commands.** A program with commands (`tasks db migrate`) gives one MCP tool per command:
+  `tasks_db_migrate`.
+- **Effects.** A tool's declared effects become MCP annotations: `read-only` → `readOnlyHint`,
+  `destructive` → `destructiveHint`, `idempotent` → `idempotentHint`, `network` →
+  `openWorldHint`. Clients use them to decide when to ask before running a tool.
+- **stdin and stdout.** A tool that declares stdin takes it as one more argument, `stdin` (base64
+  for binary types). Declared binary stdout comes back as an `image` or `audio` content block, or
+  an embedded resource (a blob) for other types.
+- **Secrets.** Secret options are passed to the tool in its environment rather than on the command
+  line, and shown as `***` in logs.
+
+```
+clyops-mcp --root DIR [--name NAME] [--cwd DIR] [--timeout SECONDS] [--no-watch]
+           [--allow GLOB]... [--deny GLOB]... [--read-only] [--paths-within DIR]...
+           [--max-output BYTES] [--audit FILE]
+```
+
+The server watches the tools directory: when a tool is added, changed or removed it tells the
+agent (`notifications/tools/list_changed`), and clients that support it refresh their tool list
+without restarting the server. `--no-watch` reads the tools once at startup.
+
+Tools run in `--cwd` (default: where the server was started, which for most clients is the
+project the agent is working in), so relative paths resolve there. Options can also be set as
+`CLYOPS_MCP_<OPTION>` in the environment.
+
+## Security
+
+The agent can run any tool the server offers with any arguments its schema accepts. Offer only
+what it should be able to run:
+
+- `--allow media/*` / `--deny admin/**` (repeatable): globs over a tool's words, `*` within a word
+  and `**` across words. A tool must match an `--allow` pattern when there are any, and no
+  `--deny` pattern. `allow:` and `deny:` lines in the root `.clyops` file apply as well.
+- `--read-only`: offer only tools that declare the `read-only` effect.
+- `--paths-within DIR` (repeatable): path arguments (`path`, `file:*`, `dir:*`) must resolve inside
+  one of these directories, symlinks followed, before anything runs.
+- `--max-output BYTES` (default 16 MiB): keep at most this much of a tool's stdout and stderr.
+- `--audit FILE` (`-` for stderr): one JSON line per run with the tool, its command line (secrets
+  as `***`), exit status and duration.
+
+## Over HTTP
+
+[clyops-api](../api) serves the same tools over MCP's streamable HTTP transport at `/mcp`, next to
+its REST endpoints and behind the same API key:
+
+```sh
+clyops-api --root ~/mytool/scripts --api-key "$KEY"
+claude mcp add --transport http mytool http://127.0.0.1:8080/mcp --header "Authorization: Bearer $KEY"
+```
+
+Or mount it in your own Express app:
+
+```js
+import express from 'express';
+import { loadTools } from 'clyops-tools';
+import { mcpHttpHandler } from 'clyops-mcp';
+
+const { tree, tools } = await loadTools('./scripts');
+const app = express();
+app.use(express.json());
+app.post('/mcp', mcpHttpHandler({ name: tree.name, tools }));
+app.listen(8080);
+```
+
+`createMcpServer({name, tools, ...})` returns the SDK `Server` for any other transport. Each HTTP
+request is handled statelessly with its own server instance.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+// clyops-mcp --root DIR: a stdio MCP server for a directory of clyops tools.
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { Cli, warn } from 'clyops';
+import { auditLog, loadTools, watchTools } from 'clyops-tools';
+import { readFileSync } from 'node:fs';
+import { createMcpServer } from './server.js';
+const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+const cli = new Cli({ name: 'clyops-mcp' });
+cli.setDescription('Serve a directory of clyops tools to an AI agent over MCP (stdio): one MCP tool per clyops tool, with its input schema from the tool\'s --help-json-schema.');
+cli.setEpilog('Every option can also be set in the environment as CLYOPS_MCP_<OPTION>.\n\nExamples:\n  claude mcp add mytool -- clyops-mcp --root ~/mytool/scripts\n  { "mcpServers": { "mytool": { "command": "clyops-mcp", "args": ["--root", "/home/me/mytool/scripts"] } } }');
+cli.opt('CLYOPS_MCP_ROOT', 'root', 'r', '', 'Tools directory or dispatcher definition file', 'Tools', 'path');
+cli.opt('CLYOPS_MCP_NAME', 'name', 'n', 'optional', 'Server name (default: the directory name)', 'Tools');
+cli.opt('CLYOPS_MCP_CWD', 'cwd', '', 'optional', 'Working directory for the tools (default: the current one)', 'Tools', 'dir:exists');
+cli.opt('CLYOPS_MCP_TIMEOUT', 'timeout', 't', '0', 'Kill a tool after this many seconds (0: never)', 'Tools', 'int:0-');
+cli.opt('CLYOPS_MCP_WATCH', 'watch', 'w', 'true', 'Pick up added, changed and removed tools without a restart', 'Tools', 'bool');
+cli.optArray('CLYOPS_MCP_ALLOW', 'allow', 'a', 'Serve only tools matching this glob over their words (media/*, media/**)', 'Security');
+cli.optArray('CLYOPS_MCP_DENY', 'deny', 'D', 'Leave out tools matching this glob', 'Security');
+cli.opt('CLYOPS_MCP_READ_ONLY', 'read-only', '', 'flag', 'Serve only tools that declare the read-only effect', 'Security');
+cli.optArray('CLYOPS_MCP_PATHS_WITHIN', 'paths-within', '', 'Path arguments must resolve inside this directory', 'Security', 'dir:exists');
+cli.opt('CLYOPS_MCP_MAX_OUTPUT', 'max-output', '', '16777216', 'Keep at most this many bytes of a tool\'s stdout and stderr (0: all)', 'Security', 'int:0-');
+cli.opt('CLYOPS_MCP_AUDIT', 'audit', '', 'optional', 'Append a JSON line per run to this file (-: stderr)', 'Security', 'path');
+const args = cli.run();
+// stdout is the MCP channel; clyops logs to stderr.
+const onError = (cmd, err) => warn('%s%s', cmd ? `skipping ${cmd.words.join(' ')}: ` : '', err.message);
+const filter = { allow: args.CLYOPS_MCP_ALLOW, deny: args.CLYOPS_MCP_DENY, readOnly: args.CLYOPS_MCP_READ_ONLY };
+const opts = { name: args.CLYOPS_MCP_NAME ?? undefined, filter, onError };
+const within = args.CLYOPS_MCP_PATHS_WITHIN;
+const watcher = args.CLYOPS_MCP_WATCH
+    ? await watchTools(args.CLYOPS_MCP_ROOT, {
+        ...opts,
+        // The server reads mcp.tools on each request; tell the agent the list changed.
+        onChange: ({ tools }) => {
+            mcp.tools = tools;
+            void server.sendToolListChanged();
+        },
+    })
+    : undefined;
+const { tree, tools } = watcher ? watcher.current() : await loadTools(args.CLYOPS_MCP_ROOT, opts);
+const mcp = {
+    name: tree.name,
+    version,
+    instructions: tree.description || undefined,
+    tools,
+    cwd: args.CLYOPS_MCP_CWD ?? undefined,
+    timeoutMs: args.CLYOPS_MCP_TIMEOUT * 1000,
+    within: within.length ? within : undefined,
+    maxOutput: args.CLYOPS_MCP_MAX_OUTPUT,
+    audit: args.CLYOPS_MCP_AUDIT ? auditLog(args.CLYOPS_MCP_AUDIT) : undefined,
+};
+const server = createMcpServer(mcp);
+// The watcher would keep the process alive after the agent disconnects, and
+// the stdio transport doesn't close by itself when stdin ends.
+server.onclose = () => watcher?.close();
+process.stdin.on('end', () => void server.close());
+await server.connect(new StdioServerTransport());

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from './server.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+// clyops-mcp: a directory of clyops tools as MCP tools, over stdio or streamable HTTP.
+export * from './server.js';

package/dist/server.d.ts

@@ -0,0 +1,38 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { type AuditEntry, type Tool } from 'clyops-tools';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+export interface McpOptions {
+    /** Server name shown to clients (e.g. the tools directory's name). */
+    name: string;
+    version?: string;
+    /** Instructions for the agent, e.g. the tools directory's description. */
+    instructions?: string;
+    tools: Tool[];
+    /** Working directory tools run in (default: the server's). */
+    cwd?: string;
+    /** Kill a tool after this long (0: never). */
+    timeoutMs?: number;
+    /** Path-valued arguments must resolve inside these directories. */
+    within?: string[];
+    /** Keep at most this many bytes of a tool's stdout and stderr (0: all). */
+    maxOutput?: number;
+    /** Called after every run, for an audit log. */
+    audit?: (entry: Omit<AuditEntry, 'time'>) => void;
+}
+/** The MCP tool name for a clyops tool: its words joined by `_` (`media_to-pcm`). */
+export declare function toolName(tool: Tool): string;
+/**
+ * The SDK server for `opts`. It reads `opts.tools` on every request, so
+ * replacing it (then calling `server.sendToolListChanged()` on a connected
+ * server) updates the tools without a restart.
+ */
+export declare function createMcpServer(opts: McpOptions): Server;
+/**
+ * A request handler serving MCP over streamable HTTP, statelessly: each
+ * request gets its own server and transport. Mount it on POST (and GET/DELETE,
+ * which it answers with 405) at a path such as `/mcp`, after a JSON body parser.
+ * Pass a function to serve whatever it returns for each request (given the request, e.g. to serve per-caller tools).
+ */
+export declare function mcpHttpHandler<R extends IncomingMessage & {
+    body?: unknown;
+}>(opts: McpOptions | ((req: R) => McpOptions)): (req: R, res: ServerResponse) => Promise<void>;

package/dist/server.js

@@ -0,0 +1,146 @@
+// An MCP server over a directory of clyops tools: one MCP tool per clyops
+// tool, its input schema from the tool's --help-json-schema (spec section 13).
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { AjvJsonSchemaValidator } from '@modelcontextprotocol/sdk/validation/ajv';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { InputError, isTextType, runTool, tail, toJsonSchema } from 'clyops-tools';
+/** The MCP tool name for a clyops tool: its words joined by `_` (`media_to-pcm`). */
+export function toolName(tool) {
+    return tool.words.join('_').replace(/[^A-Za-z0-9_-]/g, '_').slice(0, 64);
+}
+/** A tool's declared binary stdout type, if any (spec section 1.3). */
+function binaryStdout(tool) {
+    const type = tool.schema.stdout?.contentType;
+    return type && !isTextType(type) ? type.split(';')[0].trim() : undefined;
+}
+/**
+ * What the agent reads back from a run: stdout (an image, audio or a blob for
+ * declared binary output), and on failure the exit status and stderr.
+ */
+function toResult(tool, result) {
+    const content = [];
+    const binary = binaryStdout(tool);
+    if (binary && result.stdoutBuffer?.length) {
+        const data = result.stdoutBuffer.toString('base64');
+        if (binary.startsWith('image/'))
+            content.push({ type: 'image', data, mimeType: binary });
+        else if (binary.startsWith('audio/'))
+            content.push({ type: 'audio', data, mimeType: binary });
+        else
+            content.push({ type: 'resource', resource: { uri: `clyops://${toolName(tool)}/stdout`, mimeType: binary, blob: data } });
+    }
+    if (result.stdout)
+        content.push({ type: 'text', text: result.stdout });
+    if (!result.ok) {
+        const why = result.timedOut ? 'timed out' : result.signal ? `was killed (${result.signal})` : `exited with status ${result.exitCode}`;
+        // All of stderr: a tool's error line often comes before its usage text.
+        content.push({ type: 'text', text: [`${tool.words.join(' ')} ${why}.`, ...tail(result.stderr, Infinity)].join('\n') });
+    }
+    if (!content.length)
+        content.push({ type: 'text', text: '(no output)' });
+    const json = result.json;
+    return {
+        content,
+        isError: !result.ok,
+        ...(json && typeof json === 'object' && !Array.isArray(json) ? { structuredContent: json } : {}),
+    };
+}
+// Each tool's input schema and compiled validator, built once per tool object.
+// A tool that declares stdin takes it as one more argument, `stdin`.
+const validator = new AjvJsonSchemaValidator();
+const prepared = new WeakMap();
+function prepare(tool) {
+    let entry = prepared.get(tool);
+    if (!entry) {
+        const inputSchema = toJsonSchema(tool.schema);
+        const stdin = tool.schema.stdin;
+        const properties = inputSchema.properties;
+        if (stdin && !('stdin' in properties)) {
+            const text = isTextType(stdin.contentType);
+            const what = [stdin.description, stdin.contentType && `(${stdin.contentType})`].filter(Boolean).join(' ');
+            properties.stdin = { type: 'string', description: `Standard input${what ? `: ${what}` : ''}${text ? '' : ', base64-encoded'}`, ...(text ? {} : { contentEncoding: 'base64' }) };
+        }
+        entry = { inputSchema, validate: validator.getValidator(inputSchema) };
+        prepared.set(tool, entry);
+    }
+    return entry;
+}
+/** MCP tool annotations from the tool's declared effects (spec section 1.3). */
+function annotations(tool) {
+    const effects = tool.schema.effects ?? [];
+    const out = {};
+    if (effects.includes('read-only'))
+        out.readOnlyHint = true;
+    if (effects.includes('destructive'))
+        out.destructiveHint = true;
+    if (effects.includes('idempotent'))
+        out.idempotentHint = true;
+    if (effects.includes('network'))
+        out.openWorldHint = true;
+    return Object.keys(out).length ? { annotations: out } : {};
+}
+/**
+ * The SDK server for `opts`. It reads `opts.tools` on every request, so
+ * replacing it (then calling `server.sendToolListChanged()` on a connected
+ * server) updates the tools without a restart.
+ */
+export function createMcpServer(opts) {
+    const server = new Server({ name: opts.name, version: opts.version ?? '0.0.0' }, { capabilities: { tools: { listChanged: true } }, instructions: opts.instructions });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: opts.tools.map((tool) => ({
+            name: toolName(tool),
+            title: tool.words.join(' '),
+            description: [tool.schema.description, tool.schema.epilog].filter(Boolean).join('\n\n'),
+            inputSchema: prepare(tool).inputSchema,
+            ...annotations(tool),
+        })),
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+        const tool = opts.tools.find((t) => toolName(t) === request.params.name);
+        if (!tool)
+            return { content: [{ type: 'text', text: `Unknown tool: ${request.params.name}` }], isError: true };
+        const checked = prepare(tool).validate(request.params.arguments ?? {});
+        if (!checked.valid)
+            return { content: [{ type: 'text', text: `Invalid arguments: ${checked.errorMessage}` }], isError: true };
+        const { stdin, ...input } = checked.data;
+        const declared = tool.schema.stdin;
+        const stdinData = declared && typeof stdin === 'string' ? (isTextType(declared.contentType) ? stdin : Buffer.from(stdin, 'base64')) : undefined;
+        let result;
+        try {
+            result = await runTool(tool, declared ? input : checked.data, {
+                cwd: opts.cwd, timeoutMs: opts.timeoutMs, signal: extra.signal, within: opts.within, maxOutput: opts.maxOutput,
+                stdin: stdinData, stdout: binaryStdout(tool) ? 'buffer' : 'text',
+            });
+        }
+        catch (err) {
+            if (err instanceof InputError)
+                return { content: [{ type: 'text', text: `Invalid arguments: ${err.message}` }], isError: true };
+            throw err;
+        }
+        opts.audit?.({
+            tool: tool.words.join(' '), command: result.command, exitCode: result.exitCode, signal: result.signal,
+            timedOut: result.timedOut, durationMs: result.durationMs, via: 'mcp',
+        });
+        return toResult(tool, result);
+    });
+    return server;
+}
+/**
+ * A request handler serving MCP over streamable HTTP, statelessly: each
+ * request gets its own server and transport. Mount it on POST (and GET/DELETE,
+ * which it answers with 405) at a path such as `/mcp`, after a JSON body parser.
+ * Pass a function to serve whatever it returns for each request (given the request, e.g. to serve per-caller tools).
+ */
+export function mcpHttpHandler(opts) {
+    return async (req, res) => {
+        const server = createMcpServer(typeof opts === 'function' ? opts(req) : opts);
+        const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+        res.on('close', () => {
+            void transport.close();
+            void server.close();
+        });
+        await server.connect(transport);
+        await transport.handleRequest(req, res, req.body);
+    };
+}

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "clyops-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Give an AI agent a directory of clyops tools over MCP (stdio or streamable HTTP), with each tool's input schema from its --help-json-schema.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wankdanker/clyops.git",
+    "directory": "apps/mcp"
+  },
+  "keywords": [
+    "clyops",
+    "mcp",
+    "model-context-protocol",
+    "agent",
+    "cli",
+    "tools"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "type": "module",
+  "bin": {
+    "clyops-mcp": "./dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json && chmod +x dist/cli.js",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test test/*.test.mjs",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "clyops": "0.2.0",
+    "clyops-tools": "0.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0",
+    "express": "^5.2.1"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+// clyops-mcp --root DIR: a stdio MCP server for a directory of clyops tools.
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { Cli, warn } from 'clyops';
+import { auditLog, loadTools, watchTools } from 'clyops-tools';
+import { readFileSync } from 'node:fs';
+import { createMcpServer } from './server.js';
+
+const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')) as { version: string };
+
+const cli = new Cli({ name: 'clyops-mcp' });
+cli.setDescription('Serve a directory of clyops tools to an AI agent over MCP (stdio): one MCP tool per clyops tool, with its input schema from the tool\'s --help-json-schema.');
+cli.setEpilog('Every option can also be set in the environment as CLYOPS_MCP_<OPTION>.\n\nExamples:\n  claude mcp add mytool -- clyops-mcp --root ~/mytool/scripts\n  { "mcpServers": { "mytool": { "command": "clyops-mcp", "args": ["--root", "/home/me/mytool/scripts"] } } }');
+cli.opt('CLYOPS_MCP_ROOT',    'root',    'r', '',         'Tools directory or dispatcher definition file', 'Tools', 'path');
+cli.opt('CLYOPS_MCP_NAME',    'name',    'n', 'optional', 'Server name (default: the directory name)',     'Tools');
+cli.opt('CLYOPS_MCP_CWD',     'cwd',     '',  'optional', 'Working directory for the tools (default: the current one)', 'Tools', 'dir:exists');
+cli.opt('CLYOPS_MCP_TIMEOUT', 'timeout', 't', '0',        'Kill a tool after this many seconds (0: never)', 'Tools', 'int:0-');
+cli.opt('CLYOPS_MCP_WATCH',   'watch',   'w', 'true',     'Pick up added, changed and removed tools without a restart', 'Tools', 'bool');
+cli.optArray('CLYOPS_MCP_ALLOW',        'allow',        'a',              'Serve only tools matching this glob over their words (media/*, media/**)', 'Security');
+cli.optArray('CLYOPS_MCP_DENY',         'deny',         'D',              'Leave out tools matching this glob', 'Security');
+cli.opt('CLYOPS_MCP_READ_ONLY',         'read-only',    '',  'flag',      'Serve only tools that declare the read-only effect', 'Security');
+cli.optArray('CLYOPS_MCP_PATHS_WITHIN', 'paths-within', '',               'Path arguments must resolve inside this directory', 'Security', 'dir:exists');
+cli.opt('CLYOPS_MCP_MAX_OUTPUT',        'max-output',   '',  '16777216',  'Keep at most this many bytes of a tool\'s stdout and stderr (0: all)', 'Security', 'int:0-');
+cli.opt('CLYOPS_MCP_AUDIT',             'audit',        '',  'optional',  'Append a JSON line per run to this file (-: stderr)', 'Security', 'path');
+const args = cli.run();
+
+// stdout is the MCP channel; clyops logs to stderr.
+const onError = (cmd: { words: string[] } | null, err: Error) => warn('%s%s', cmd ? `skipping ${cmd.words.join(' ')}: ` : '', err.message);
+const filter = { allow: args.CLYOPS_MCP_ALLOW as string[], deny: args.CLYOPS_MCP_DENY as string[], readOnly: args.CLYOPS_MCP_READ_ONLY as boolean };
+const opts = { name: (args.CLYOPS_MCP_NAME as string | null) ?? undefined, filter, onError };
+const within = args.CLYOPS_MCP_PATHS_WITHIN as string[];
+const watcher = args.CLYOPS_MCP_WATCH
+  ? await watchTools(args.CLYOPS_MCP_ROOT as string, {
+      ...opts,
+      // The server reads mcp.tools on each request; tell the agent the list changed.
+      onChange: ({ tools }) => {
+        mcp.tools = tools;
+        void server.sendToolListChanged();
+      },
+    })
+  : undefined;
+const { tree, tools } = watcher ? watcher.current() : await loadTools(args.CLYOPS_MCP_ROOT as string, opts);
+const mcp = {
+  name: tree.name,
+  version,
+  instructions: tree.description || undefined,
+  tools,
+  cwd: (args.CLYOPS_MCP_CWD as string | null) ?? undefined,
+  timeoutMs: (args.CLYOPS_MCP_TIMEOUT as number) * 1000,
+  within: within.length ? within : undefined,
+  maxOutput: args.CLYOPS_MCP_MAX_OUTPUT as number,
+  audit: args.CLYOPS_MCP_AUDIT ? auditLog(args.CLYOPS_MCP_AUDIT as string) : undefined,
+};
+const server = createMcpServer(mcp);
+// The watcher would keep the process alive after the agent disconnects, and
+// the stdio transport doesn't close by itself when stdin ends.
+server.onclose = () => watcher?.close();
+process.stdin.on('end', () => void server.close());
+await server.connect(new StdioServerTransport());

package/src/index.ts

@@ -0,0 +1,2 @@
+// clyops-mcp: a directory of clyops tools as MCP tools, over stdio or streamable HTTP.
+export * from './server.js';

package/src/server.ts

@@ -0,0 +1,164 @@
+// An MCP server over a directory of clyops tools: one MCP tool per clyops
+// tool, its input schema from the tool's --help-json-schema (spec section 13).
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { AjvJsonSchemaValidator } from '@modelcontextprotocol/sdk/validation/ajv';
+import type { JsonSchemaValidator } from '@modelcontextprotocol/sdk/validation/types.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, type CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { InputError, isTextType, runTool, tail, toJsonSchema, type AuditEntry, type JsonSchema, type Tool, type ToolResult } from 'clyops-tools';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+
+export interface McpOptions {
+  /** Server name shown to clients (e.g. the tools directory's name). */
+  name: string;
+  version?: string;
+  /** Instructions for the agent, e.g. the tools directory's description. */
+  instructions?: string;
+  tools: Tool[];
+  /** Working directory tools run in (default: the server's). */
+  cwd?: string;
+  /** Kill a tool after this long (0: never). */
+  timeoutMs?: number;
+  /** Path-valued arguments must resolve inside these directories. */
+  within?: string[];
+  /** Keep at most this many bytes of a tool's stdout and stderr (0: all). */
+  maxOutput?: number;
+  /** Called after every run, for an audit log. */
+  audit?: (entry: Omit<AuditEntry, 'time'>) => void;
+}
+
+/** The MCP tool name for a clyops tool: its words joined by `_` (`media_to-pcm`). */
+export function toolName(tool: Tool): string {
+  return tool.words.join('_').replace(/[^A-Za-z0-9_-]/g, '_').slice(0, 64);
+}
+
+/** A tool's declared binary stdout type, if any (spec section 1.3). */
+function binaryStdout(tool: Tool): string | undefined {
+  const type = tool.schema.stdout?.contentType;
+  return type && !isTextType(type) ? type.split(';')[0].trim() : undefined;
+}
+
+/**
+ * What the agent reads back from a run: stdout (an image, audio or a blob for
+ * declared binary output), and on failure the exit status and stderr.
+ */
+function toResult(tool: Tool, result: ToolResult): CallToolResult {
+  const content: CallToolResult['content'] = [];
+  const binary = binaryStdout(tool);
+  if (binary && result.stdoutBuffer?.length) {
+    const data = result.stdoutBuffer.toString('base64');
+    if (binary.startsWith('image/')) content.push({ type: 'image', data, mimeType: binary });
+    else if (binary.startsWith('audio/')) content.push({ type: 'audio', data, mimeType: binary });
+    else content.push({ type: 'resource', resource: { uri: `clyops://${toolName(tool)}/stdout`, mimeType: binary, blob: data } });
+  }
+  if (result.stdout) content.push({ type: 'text', text: result.stdout });
+  if (!result.ok) {
+    const why = result.timedOut ? 'timed out' : result.signal ? `was killed (${result.signal})` : `exited with status ${result.exitCode}`;
+    // All of stderr: a tool's error line often comes before its usage text.
+    content.push({ type: 'text', text: [`${tool.words.join(' ')} ${why}.`, ...tail(result.stderr, Infinity)].join('\n') });
+  }
+  if (!content.length) content.push({ type: 'text', text: '(no output)' });
+  const json = result.json;
+  return {
+    content,
+    isError: !result.ok,
+    ...(json && typeof json === 'object' && !Array.isArray(json) ? { structuredContent: json as Record<string, unknown> } : {}),
+  };
+}
+
+// Each tool's input schema and compiled validator, built once per tool object.
+// A tool that declares stdin takes it as one more argument, `stdin`.
+const validator = new AjvJsonSchemaValidator();
+const prepared = new WeakMap<Tool, { inputSchema: JsonSchema; validate: JsonSchemaValidator<Record<string, unknown>> }>();
+function prepare(tool: Tool) {
+  let entry = prepared.get(tool);
+  if (!entry) {
+    const inputSchema = toJsonSchema(tool.schema);
+    const stdin = tool.schema.stdin;
+    const properties = inputSchema.properties as Record<string, JsonSchema>;
+    if (stdin && !('stdin' in properties)) {
+      const text = isTextType(stdin.contentType);
+      const what = [stdin.description, stdin.contentType && `(${stdin.contentType})`].filter(Boolean).join(' ');
+      properties.stdin = { type: 'string', description: `Standard input${what ? `: ${what}` : ''}${text ? '' : ', base64-encoded'}`, ...(text ? {} : { contentEncoding: 'base64' }) };
+    }
+    entry = { inputSchema, validate: validator.getValidator<Record<string, unknown>>(inputSchema as never) };
+    prepared.set(tool, entry);
+  }
+  return entry;
+}
+
+/** MCP tool annotations from the tool's declared effects (spec section 1.3). */
+function annotations(tool: Tool) {
+  const effects = tool.schema.effects ?? [];
+  const out: Record<string, boolean> = {};
+  if (effects.includes('read-only')) out.readOnlyHint = true;
+  if (effects.includes('destructive')) out.destructiveHint = true;
+  if (effects.includes('idempotent')) out.idempotentHint = true;
+  if (effects.includes('network')) out.openWorldHint = true;
+  return Object.keys(out).length ? { annotations: out } : {};
+}
+
+/**
+ * The SDK server for `opts`. It reads `opts.tools` on every request, so
+ * replacing it (then calling `server.sendToolListChanged()` on a connected
+ * server) updates the tools without a restart.
+ */
+export function createMcpServer(opts: McpOptions): Server {
+  const server = new Server({ name: opts.name, version: opts.version ?? '0.0.0' }, { capabilities: { tools: { listChanged: true } }, instructions: opts.instructions });
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: opts.tools.map((tool) => ({
+      name: toolName(tool),
+      title: tool.words.join(' '),
+      description: [tool.schema.description, tool.schema.epilog].filter(Boolean).join('\n\n'),
+      inputSchema: prepare(tool).inputSchema as { type: 'object'; [key: string]: unknown },
+      ...annotations(tool),
+    })),
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+    const tool = opts.tools.find((t) => toolName(t) === request.params.name);
+    if (!tool) return { content: [{ type: 'text', text: `Unknown tool: ${request.params.name}` }], isError: true };
+    const checked = prepare(tool).validate(request.params.arguments ?? {});
+    if (!checked.valid) return { content: [{ type: 'text', text: `Invalid arguments: ${checked.errorMessage}` }], isError: true };
+    const { stdin, ...input } = checked.data;
+    const declared = tool.schema.stdin;
+    const stdinData = declared && typeof stdin === 'string' ? (isTextType(declared.contentType) ? stdin : Buffer.from(stdin, 'base64')) : undefined;
+    let result: ToolResult;
+    try {
+      result = await runTool(tool, declared ? input : checked.data, {
+        cwd: opts.cwd, timeoutMs: opts.timeoutMs, signal: extra.signal, within: opts.within, maxOutput: opts.maxOutput,
+        stdin: stdinData, stdout: binaryStdout(tool) ? 'buffer' : 'text',
+      });
+    } catch (err) {
+      if (err instanceof InputError) return { content: [{ type: 'text', text: `Invalid arguments: ${err.message}` }], isError: true };
+      throw err;
+    }
+    opts.audit?.({
+      tool: tool.words.join(' '), command: result.command, exitCode: result.exitCode, signal: result.signal,
+      timedOut: result.timedOut, durationMs: result.durationMs, via: 'mcp',
+    });
+    return toResult(tool, result);
+  });
+
+  return server;
+}
+
+/**
+ * A request handler serving MCP over streamable HTTP, statelessly: each
+ * request gets its own server and transport. Mount it on POST (and GET/DELETE,
+ * which it answers with 405) at a path such as `/mcp`, after a JSON body parser.
+ * Pass a function to serve whatever it returns for each request (given the request, e.g. to serve per-caller tools).
+ */
+export function mcpHttpHandler<R extends IncomingMessage & { body?: unknown }>(opts: McpOptions | ((req: R) => McpOptions)) {
+  return async (req: R, res: ServerResponse): Promise<void> => {
+    const server = createMcpServer(typeof opts === 'function' ? opts(req) : opts);
+    const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+    res.on('close', () => {
+      void transport.close();
+      void server.close();
+    });
+    await server.connect(transport);
+    await transport.handleRequest(req, res, req.body);
+  };
+}