raidcom-mcp 0.0.0-stage → 0.1.2

package/dist/config.js

@@ -0,0 +1,118 @@
+// Server settings, read once from the environment, and helpers for the bundled data files.
+import { existsSync, readFileSync } from "node:fs";
+import { createSecureContext } from "node:tls";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+/** Path of a file bundled with the server (spec/, package.json). */
+export const bundled = (...parts) => join(root, ...parts);
+/** Reads a JSON file, naming the file in the error if it cannot be parsed. */
+export function loadJson(path, what) {
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (e) {
+        throw new Error(`[raidcom-mcp] cannot read ${what} at ${path}: ${e.message}`);
+    }
+}
+/** Like loadJson, but returns `fallback` when the path is empty or the file does not exist. */
+export function loadOptionalJson(path, what, fallback) {
+    return path && existsSync(path) ? loadJson(path, what) : fallback;
+}
+export const VERSION = loadJson(bundled("package.json"), "package.json").version;
+export function loadServerConfig(env = process.env) {
+    return {
+        catalogPath: env.RAIDCOM_CATALOG || bundled("spec", "raidcom-catalog.json"),
+        limitsPath: env.RAIDCOM_LIMITS || bundled("spec", "limits.json"),
+        recipesPath: env.RAIDCOM_RECIPES || bundled("spec", "recipes.json"),
+        // An empty RAIDCOM_EXAMPLES turns the example questions off.
+        examplesPath: env.RAIDCOM_EXAMPLES ?? bundled("spec", "examples.json"),
+    };
+}
+const MIN_TOKEN_LENGTH = 32;
+/** RAIDCOM_HTTP_TRUST_PROXY: unset or false → 0, true → 1, or a number of proxies from 1 to 10. */
+function proxyHops(v) {
+    if (v === undefined || v === "" || v === "false" || v === "0")
+        return 0;
+    if (v === "true")
+        return 1;
+    if (/^\d+$/.test(v) && Number(v) >= 1 && Number(v) <= 10)
+        return Number(v);
+    throw new Error(`[raidcom-mcp] RAIDCOM_HTTP_TRUST_PROXY must be true, false or the number of proxies in front of the server (1 to 10), not "${v}"`);
+}
+const list = (v) => (v ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+/** True for addresses that only this machine can reach. */
+export function isLoopback(host) {
+    const h = host.replace(/^\[|\]$/g, "").toLowerCase();
+    return h === "localhost" || h === "::1" || /^127\.\d+\.\d+\.\d+$/.test(h);
+}
+/** Reads the TLS certificate and key, checking that they are valid PEM and belong together. */
+function loadTls(env) {
+    const certPath = env.RAIDCOM_HTTP_TLS_CERT;
+    const keyPath = env.RAIDCOM_HTTP_TLS_KEY;
+    if (!certPath && !keyPath)
+        return undefined;
+    if (!certPath || !keyPath)
+        throw new Error("[raidcom-mcp] Set both RAIDCOM_HTTP_TLS_CERT and RAIDCOM_HTTP_TLS_KEY to serve HTTPS, or neither");
+    const read = (path, what) => {
+        try {
+            return readFileSync(path);
+        }
+        catch (e) {
+            throw new Error(`[raidcom-mcp] cannot read the TLS ${what} at ${path}: ${e.message}`);
+        }
+    };
+    const tls = { cert: read(certPath, "certificate"), key: read(keyPath, "key") };
+    try {
+        createSecureContext(tls);
+    }
+    catch (e) {
+        throw new Error(`[raidcom-mcp] RAIDCOM_HTTP_TLS_CERT and RAIDCOM_HTTP_TLS_KEY are not a usable certificate and key: ${e.message}`);
+    }
+    return tls;
+}
+/**
+ * Reads the transport settings. The server only builds text, so it holds no secrets, but a public endpoint is
+ * still guarded: a bearer token (or an explicit RAIDCOM_HTTP_OPEN=true), TLS for any address other machines can
+ * reach, and a per-client rate limit.
+ */
+export function loadHttpConfig(env = process.env) {
+    const transport = (env.RAIDCOM_TRANSPORT || "stdio").toLowerCase();
+    if (transport === "stdio")
+        return undefined;
+    if (transport !== "http")
+        throw new Error(`[raidcom-mcp] RAIDCOM_TRANSPORT must be stdio or http, not "${env.RAIDCOM_TRANSPORT}"`);
+    const host = env.RAIDCOM_HTTP_HOST || "127.0.0.1";
+    const port = Number(env.RAIDCOM_HTTP_PORT ?? 8361);
+    if (!Number.isInteger(port) || port < 0 || port > 65535)
+        throw new Error(`[raidcom-mcp] RAIDCOM_HTTP_PORT must be a port number, not "${env.RAIDCOM_HTTP_PORT}"`);
+    const token = env.RAIDCOM_HTTP_TOKEN ?? "";
+    const open = env.RAIDCOM_HTTP_OPEN === "true";
+    if (token && token.length < MIN_TOKEN_LENGTH) {
+        throw new Error(`[raidcom-mcp] RAIDCOM_HTTP_TOKEN must be at least ${MIN_TOKEN_LENGTH} characters. Generate one with: openssl rand -hex 32`);
+    }
+    if (!token && !open) {
+        throw new Error(`[raidcom-mcp] RAIDCOM_TRANSPORT=http needs RAIDCOM_HTTP_TOKEN (clients send it as "Authorization: Bearer <token>"; generate one with: openssl rand -hex 32), ` +
+            `or RAIDCOM_HTTP_OPEN=true to serve anyone who can reach the port. The server only builds command text, so an open endpoint is a choice, not a risk to your arrays.`);
+    }
+    const tls = loadTls(env);
+    const behindTlsProxy = env.RAIDCOM_HTTP_BEHIND_TLS_PROXY === "true";
+    if (!isLoopback(host) && !tls && !behindTlsProxy) {
+        throw new Error(`[raidcom-mcp] RAIDCOM_HTTP_HOST=${host} would accept connections from other machines over plain HTTP. ` +
+            `Set RAIDCOM_HTTP_TLS_CERT and RAIDCOM_HTTP_TLS_KEY to serve HTTPS, or RAIDCOM_HTTP_BEHIND_TLS_PROXY=true if a proxy or load balancer ends TLS in front of this server.`);
+    }
+    const rate = Number(env.RAIDCOM_HTTP_RATE_LIMIT ?? 120);
+    if (!Number.isFinite(rate) || rate < 0)
+        throw new Error(`[raidcom-mcp] RAIDCOM_HTTP_RATE_LIMIT must be a number of requests per minute (0 for none), not "${env.RAIDCOM_HTTP_RATE_LIMIT}"`);
+    return {
+        host,
+        port,
+        token,
+        allowedHosts: list(env.RAIDCOM_HTTP_ALLOWED_HOSTS),
+        allowedOrigins: list(env.RAIDCOM_HTTP_ALLOWED_ORIGINS),
+        tls,
+        behindTlsProxy,
+        rateLimitPerMinute: Math.floor(rate),
+        trustProxy: proxyHops(env.RAIDCOM_HTTP_TRUST_PROXY),
+    };
+}

package/dist/http.js

@@ -0,0 +1,198 @@
+// Streamable HTTP transport (RAIDCOM_TRANSPORT=http), stateless: every POST to /mcp gets its own MCP server and
+// transport, which answer over an SSE stream and close with the response. The tools keep no per-client state, so
+// there are no sessions to track or expire, and any number of instances can sit behind a load balancer.
+//
+// The checks run before the MCP layer sees a request, in this order: path (and /healthz), Host and Origin (against
+// DNS rebinding and browser pages driving a local server), the rate limit, the bearer token, method, then body size.
+import { createServer as createHttpServer } from "node:http";
+import { createServer as createHttpsServer } from "node:https";
+import { createHash, timingSafeEqual } from "node:crypto";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { VERSION } from "./config.js";
+export const MCP_PATH = "/mcp";
+export const HEALTH_PATH = "/healthz";
+/** Largest request body accepted: tool arguments are small. */
+export const MAX_BODY_BYTES = 256 * 1024;
+/** Requests handled at once; more get 503. */
+export const MAX_CONCURRENT = 64;
+/** Requests one client address may have in progress at once, so a single client can't take every slot. */
+export const MAX_PER_CLIENT = 8;
+/** A client has this long to send its headers, and this long to send the whole request (ms). */
+export const HEADERS_TIMEOUT_MS = 10_000;
+export const REQUEST_TIMEOUT_MS = 15_000;
+/** Client addresses the rate limiter remembers at most. */
+const MAX_TRACKED = 10_000;
+const digest = (s) => createHash("sha256").update(s).digest();
+/** Compares the Authorization header with the token in constant time (hashed first, so length doesn't leak). */
+function authorized(header, token) {
+    const m = /^Bearer[ \t]+(\S+)\s*$/i.exec(header ?? "");
+    return !!m && timingSafeEqual(digest(m[1]), token);
+}
+/** The Host header values that name this server: loopback names for the port in use, plus any configured. */
+function hostNames(cfg, port) {
+    const names = ["localhost", "127.0.0.1", "[::1]"];
+    if (!names.includes(cfg.host) && cfg.host !== "0.0.0.0" && cfg.host !== "::")
+        names.push(cfg.host.includes(":") ? `[${cfg.host}]` : cfg.host);
+    return new Set([...names.map((n) => `${n}:${port}`), ...cfg.allowedHosts].map((h) => h.toLowerCase()));
+}
+function reject(res, status, message, headers = {}) {
+    res.writeHead(status, { "content-type": "application/json", ...headers });
+    res.end(JSON.stringify({ jsonrpc: "2.0", error: { code: -32000, message }, id: null }));
+}
+class TooLarge extends Error {
+}
+async function readJson(req) {
+    if (Number(req.headers["content-length"]) > MAX_BODY_BYTES)
+        throw new TooLarge();
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        size += chunk.length;
+        if (size > MAX_BODY_BYTES)
+            throw new TooLarge();
+        chunks.push(chunk);
+    }
+    return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+}
+/** Fixed-window request counter per client address. */
+export class RateLimiter {
+    perMinute;
+    now;
+    hits = new Map();
+    constructor(perMinute, now = Date.now) {
+        this.perMinute = perMinute;
+        this.now = now;
+    }
+    /** Number of client addresses currently remembered (for tests). */
+    get size() {
+        return this.hits.size;
+    }
+    /** True when the request is allowed. */
+    allow(key) {
+        if (this.perMinute <= 0)
+            return true;
+        const t = this.now();
+        if (this.hits.size >= MAX_TRACKED) {
+            for (const [k, v] of this.hits)
+                if (t - v.start >= 60_000)
+                    this.hits.delete(k);
+            // still full: forget the oldest windows (a Map iterates in insertion order), so memory stays bounded and the
+            // sweep above runs rarely
+            if (this.hits.size >= MAX_TRACKED)
+                for (const k of [...this.hits.keys()].slice(0, MAX_TRACKED / 2))
+                    this.hits.delete(k);
+        }
+        const h = this.hits.get(key);
+        if (!h || t - h.start >= 60_000) {
+            this.hits.set(key, { start: t, count: 1 });
+            return true;
+        }
+        return ++h.count <= this.perMinute;
+    }
+}
+/**
+ * The client's address. Each proxy appends the address it received the request from, so behind `hops` trusted
+ * proxies the client is the entry `hops` places from the right of X-Forwarded-For: the one the outermost trusted
+ * proxy added. Entries further left come from the client and can say anything. (Same rule as Express's
+ * `trust proxy` set to a number.)
+ */
+export function clientAddress(req, hops) {
+    if (hops > 0) {
+        const xff = req.headers["x-forwarded-for"];
+        const entries = (Array.isArray(xff) ? xff.join(",") : (xff ?? "")).split(",").map((s) => s.trim()).filter(Boolean);
+        if (entries.length)
+            return entries[Math.max(0, entries.length - hops)];
+    }
+    return req.socket.remoteAddress ?? "unknown";
+}
+/** Starts listening, over HTTPS when a certificate is set; resolves once the port is open, with the URL clients should use. */
+export async function startHttp(cfg, createServer) {
+    const token = cfg.token ? digest(cfg.token) : undefined;
+    const origins = new Set(cfg.allowedOrigins.map((o) => o.toLowerCase()));
+    const anyOrigin = origins.has("*");
+    let hosts = new Set();
+    const anyHost = cfg.allowedHosts.includes("*");
+    const limiter = new RateLimiter(cfg.rateLimitPerMinute);
+    let active = 0;
+    const perClient = new Map();
+    const refuse = (req, res, status, message, headers) => {
+        console.error(`[raidcom-mcp] refused ${req.method} ${req.url} from ${clientAddress(req, cfg.trustProxy)}: ${status} ${message}`);
+        reject(res, status, message, headers);
+    };
+    const handler = async (req, res) => {
+        const path = (req.url ?? "").split("?")[0];
+        if (path === HEALTH_PATH && (req.method === "GET" || req.method === "HEAD")) {
+            res.writeHead(200, { "content-type": "application/json", "cache-control": "no-store" });
+            // Behind proxies, the health check also shows the address the server takes as the caller's, so the number of
+            // proxies (RAIDCOM_HTTP_TRUST_PROXY) can be checked: it should be your own public address.
+            const body = { status: "ok", version: VERSION, ...(cfg.trustProxy ? { client: clientAddress(req, cfg.trustProxy) } : {}) };
+            return res.end(req.method === "HEAD" ? undefined : JSON.stringify(body));
+        }
+        if (path !== MCP_PATH)
+            return reject(res, 404, `Not found. The MCP endpoint is ${MCP_PATH}.`);
+        if (!anyHost && !hosts.has((req.headers.host ?? "").toLowerCase()))
+            return refuse(req, res, 403, "Host not allowed. Add it to RAIDCOM_HTTP_ALLOWED_HOSTS if this name should reach the server.");
+        const origin = req.headers.origin;
+        if (origin !== undefined && !anyOrigin && !origins.has(origin.toLowerCase()))
+            return refuse(req, res, 403, "Origin not allowed. Add it to RAIDCOM_HTTP_ALLOWED_ORIGINS if this page should reach the server.");
+        const client = clientAddress(req, cfg.trustProxy);
+        if (!limiter.allow(client))
+            return refuse(req, res, 429, "Too many requests. Try again in a minute.", { "retry-after": "60" });
+        if (token && !authorized(req.headers.authorization, token))
+            return refuse(req, res, 401, "Missing or wrong bearer token.", { "www-authenticate": 'Bearer realm="raidcom-mcp"' });
+        // Stateless: no standalone SSE stream (GET) and no session to end (DELETE).
+        if (req.method !== "POST")
+            return reject(res, 405, "Method not allowed. Send MCP requests with POST.", { allow: "POST" });
+        if (active >= MAX_CONCURRENT)
+            return reject(res, 503, "Too many requests in progress. Try again shortly.", { "retry-after": "1" });
+        const mine = perClient.get(client) ?? 0;
+        if (mine >= MAX_PER_CLIENT)
+            return refuse(req, res, 429, "Too many requests in progress from this address. Try again shortly.", { "retry-after": "1" });
+        active++;
+        perClient.set(client, mine + 1);
+        res.on("close", () => {
+            active--;
+            const n = (perClient.get(client) ?? 1) - 1;
+            if (n > 0)
+                perClient.set(client, n);
+            else
+                perClient.delete(client);
+        });
+        let body;
+        try {
+            body = await readJson(req);
+        }
+        catch (e) {
+            return e instanceof TooLarge
+                ? reject(res, 413, `Request body larger than ${MAX_BODY_BYTES} bytes.`, { connection: "close" })
+                : reject(res, 400, "Request body is not valid JSON.");
+        }
+        const server = createServer();
+        const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+        res.on("close", () => {
+            transport.close().catch(() => { });
+            server.close().catch(() => { });
+        });
+        try {
+            await server.connect(transport);
+            await transport.handleRequest(req, res, body);
+        }
+        catch (e) {
+            console.error(`[raidcom-mcp] error handling request: ${e.message}`);
+            if (!res.headersSent)
+                reject(res, 500, "Internal server error.");
+        }
+    };
+    // A client that sends its request slowly would otherwise hold a slot for Node's default of five minutes. The
+    // timeouts are checked every second rather than Node's default of every 30 seconds.
+    const timeouts = { headersTimeout: HEADERS_TIMEOUT_MS, requestTimeout: REQUEST_TIMEOUT_MS, connectionsCheckingInterval: 1_000 };
+    const http = cfg.tls ? createHttpsServer({ ...timeouts, cert: cfg.tls.cert, key: cfg.tls.key }, handler) : createHttpServer(timeouts, handler);
+    await new Promise((resolve, rej) => {
+        http.once("error", rej);
+        http.listen(cfg.port, cfg.host, () => resolve());
+    });
+    const port = http.address().port;
+    hosts = hostNames(cfg, port);
+    const shown = cfg.host.includes(":") ? `[${cfg.host}]` : cfg.host;
+    return { url: `${cfg.tls ? "https" : "http"}://${shown}:${port}${MCP_PATH}`, server: http };
+}

package/dist/index.js

@@ -0,0 +1,307 @@
+#!/usr/bin/env node
+// MCP server that builds and checks Hitachi raidcom commands.
+//
+// Build-only by design: it validates structured requests against a catalogue generated from the Command Control
+// Interface Command Reference and returns command text. It never connects to a storage system and has no tool that
+// runs anything, so it can be hosted anywhere.
+import { readFileSync } from "node:fs";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, GetPromptRequestSchema, ListPromptsRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { Catalog, commandName, isDestructive, isReadOnly } from "./catalog.js";
+import { build } from "./builder.js";
+import { parseCommandLine } from "./cmdline.js";
+import { CommandIndex } from "./search.js";
+import { buildRecipe, buildScript } from "./recipes.js";
+import { VERSION, bundled, loadHttpConfig, loadJson, loadOptionalJson, loadServerConfig } from "./config.js";
+import { tools } from "./tools.js";
+/** Startup steps that read files: a bad file stops the server with one clear line instead of a stack trace. */
+function orExit(load) {
+    try {
+        return load();
+    }
+    catch (e) {
+        const msg = e.message;
+        console.error(msg.startsWith("[raidcom-mcp]") ? msg : `[raidcom-mcp] cannot start: ${msg}`);
+        process.exit(1);
+    }
+}
+const cfg = loadServerConfig();
+const httpCfg = orExit(() => loadHttpConfig());
+const catalog = orExit(() => new Catalog(cfg.catalogPath, cfg.limitsPath));
+const questions = orExit(() => loadOptionalJson(cfg.examplesPath, "example questions", {}));
+const index = new CommandIndex(catalog.commands.values(), questions);
+const recipes = orExit(() => loadJson(cfg.recipesPath, "recipes").recipes);
+const notes = {
+    conventions: orExit(() => readFileSync(bundled("spec", "notes", "conventions.md"), "utf8")),
+    horcm: orExit(() => readFileSync(bundled("spec", "notes", "horcm-setup.md"), "utf8")),
+};
+// ---------- helpers ----------
+function text(t, isError = false) {
+    return { content: [{ type: "text", text: t }], ...(isError ? { isError: true } : {}) };
+}
+const json = (v, isError = false) => text(JSON.stringify(v), isError);
+const str = (v) => (typeof v === "string" ? v : typeof v === "number" ? String(v) : "");
+const int = (v, fallback) => (typeof v === "number" || (typeof v === "string" && v.trim() !== "")) && Number.isFinite(Number(v)) ? Math.trunc(Number(v)) : fallback;
+const obj = (v) => (v && typeof v === "object" && !Array.isArray(v) ? v : {});
+const access = (c) => (isReadOnly(c) ? "read-only" : isDestructive(c) ? "changes the array (destructive)" : "changes the array");
+function section(title, items) {
+    return items.length ? `\n${title}:\n${items.map((i) => `- ${i}`).join("\n")}` : "";
+}
+function formatBuild(r) {
+    if (!r.ok)
+        return `Not built.${section("Errors", r.errors)}${section("Warnings", r.warnings)}`;
+    const kind = r.readOnly ? "read-only" : r.destructive ? "changes the array, destructive" : "changes the array";
+    return `${r.command}\n\n(${kind}${r.async ? ", asynchronous" : ""}; form: ${r.form?.title ? r.form.title.replace(/:$/, "") : r.form?.usage ?? "n/a"})${section("Warnings", r.warnings)}${section("Notes", r.notes)}`;
+}
+// ---------- tool handlers ----------
+function listCommands(args) {
+    const query = str(args.query).trim();
+    const action = str(args.action).trim().toLowerCase();
+    const object = str(args.object).trim().toLowerCase();
+    const row = (c) => `${commandName(c)} [${access(c)}${c.async ? ", async" : ""}]: ${c.summary}`;
+    if (!query && !action && !object) {
+        const byObject = new Map();
+        for (const c of catalog.commands.values())
+            byObject.set(c.object, [...(byObject.get(c.object) ?? []), c.action]);
+        const lines = [...byObject.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([o, a]) => `- ${o}: ${a.sort().join(", ")}`);
+        return text(`${catalog.commands.size} raidcom commands (action object). Pass query, action or object to list them.\n\n${lines.join("\n")}`);
+    }
+    if (!query) {
+        const found = [...catalog.commands.values()].filter((c) => (!action || c.action === action) && (!object || c.object === object));
+        if (!found.length)
+            return text("No commands match. Call with no arguments to see the objects and their actions.");
+        return text(`${found.length} command(s):\n${found.map((c) => `- ${row(c)}`).join("\n")}`);
+    }
+    const limit = Math.min(Math.max(int(args.limit, 10) || 10, 1), 40);
+    const r = index.search(query, { limit, action: action || undefined, object: object || undefined });
+    if (!r.hits.length)
+        return text("No commands matched. Try other words, or call with no arguments to see the objects.");
+    const advice = {
+        high: "Use the top result. Describe it if you need its options.",
+        medium: "The top result is likely right. Check its description before building.",
+        low: "Results are ambiguous. Describe the top 2 or 3 and choose by their descriptions, or search again with the object name (ldev, lun, host_grp, pool, ...).",
+    }[r.confidence];
+    return text(`Confidence: ${r.confidence.toUpperCase()}: ${r.reason}.\n${advice}\n\n${r.hits.map((h, i) => `${i + 1}. ${row(h.command)}`).join("\n")}`);
+}
+function describeCommand(args) {
+    const cmd = catalog.find(str(args.command));
+    if (!cmd)
+        return text(`Unknown raidcom command "${str(args.command)}". Closest: ${catalog.suggest(str(args.command)).join(", ")}. Use raidcom_list_commands to search.`, true);
+    const only = str(args.option);
+    const options = Object.entries(cmd.flags)
+        .filter(([f]) => !only || f === (only.startsWith("-") ? only : `-${only}`))
+        .map(([flag, shape]) => ({
+        option: flag,
+        usage: cmd.options[flag]?.usage,
+        values: shape.max === 0 ? "none (a switch)" : `${shape.min === shape.max ? shape.min : `${shape.min}${shape.max === null ? " or more" : ` to ${shape.max}`}`}${shape.placeholders?.length ? `: ${shape.placeholders.map((p) => `<${p}>`).join(" ")}` : ""}`,
+        ...(shape.enum ? { only: shape.enum } : shape.literals?.length ? { alsoAccepts: shape.literals } : {}),
+        ...(cmd.options[flag]?.hints ? { values_listed_in_manual: cmd.options[flag].hints } : {}),
+        description: cmd.options[flag]?.summary,
+        ...(cmd.flags[flag] && cmd.flags[flag].derived ? { note: "described in the text of another option, not in the syntax line" } : {}),
+    }));
+    if (only && !options.length)
+        return text(`raidcom ${commandName(cmd)} has no option "${only}". Options: ${Object.keys(cmd.flags).join(", ") || "none"}.`, true);
+    return json({
+        command: `raidcom ${commandName(cmd)}`,
+        summary: cmd.summary,
+        access: access(cmd),
+        asynchronous: cmd.async,
+        supported_storage_systems: cmd.supported.length ? cmd.supported : "see the Command Reference",
+        syntax_forms: cmd.forms.map((f) => ({ ...(f.title ? { when: f.title } : {}), usage: f.usage })),
+        options,
+        examples: cmd.examples.slice(0, 8).map((e) => ({ ...(e.text ? { what: e.text } : {}), command: e.command })),
+        reading_the_syntax: "[x] optional, {a | b} choose one, <x> a value you supply, ... one or more values.",
+    });
+}
+function buildCommand(args) {
+    const r = build(catalog, {
+        command: str(args.command),
+        options: obj(args.options),
+        model: str(args.model) || undefined,
+        global: obj(args.global),
+        strict: args.strict === false ? false : undefined,
+    });
+    return text(formatBuild(r), !r.ok);
+}
+function checkCommand(args) {
+    const parsed = parseCommandLine(catalog, str(args.command_line));
+    if (!parsed.request)
+        return text(`Not checked.${section("Errors", parsed.errors)}${section("Warnings", parsed.warnings)}`, true);
+    const r = build(catalog, { ...parsed.request, model: str(args.model) || undefined, strict: args.strict === false ? false : undefined });
+    const cmd = catalog.find(parsed.request.command);
+    const explained = Object.keys(parsed.request.options ?? {}).map((raw) => {
+        const flag = Object.keys(cmd.flags).find((f) => f.toLowerCase() === raw.toLowerCase());
+        return flag ? `${flag}: ${cmd.options[flag]?.summary || "(no description in the manual)"}` : `${raw}: not an option of raidcom ${commandName(cmd)}`;
+    });
+    const errors = [...parsed.errors, ...r.errors];
+    const warnings = [...parsed.warnings, ...r.warnings];
+    const head = r.ok && !parsed.errors.length ? `${r.command}\n\nValid. raidcom ${commandName(cmd)}: ${cmd.summary} (${access(cmd)}${cmd.async ? ", asynchronous" : ""})` : `Problems found with raidcom ${commandName(cmd)}.`;
+    return text(`${head}${section("Options", explained)}${section("Errors", errors)}${section("Warnings", warnings)}${r.ok ? section("Notes", r.notes) : ""}`, errors.length > 0);
+}
+function formatScript(r, what) {
+    if (!r.ok)
+        return text(`No script built.${section("Errors", r.errors)}${section("Warnings", r.warnings)}`, true);
+    const changing = r.commands.filter((c) => !c.readOnly).length;
+    const destructive = r.commands.filter((c) => c.destructive).length;
+    return text(`\`\`\`bash\n${r.script}\`\`\`\n\n${what}: ${r.commands.length} command(s), ${r.commands.length - changing} read-only, ${changing} changing${destructive ? `, ${destructive} destructive` : ""}.${section("Warnings", r.warnings)}${section("Notes", r.notes)}`);
+}
+function buildScriptTool(args) {
+    const steps = Array.isArray(args.steps) ? args.steps : [];
+    if (!steps.length)
+        return text("steps must be a non-empty array of {command, options, foreach?, zip?}.", true);
+    const r = buildScript(catalog, {
+        steps: steps.map((s) => ({ ...obj(s), command: str(obj(s).command), options: obj(obj(s).options), title: obj(s).title ? str(obj(s).title) : undefined })),
+        model: str(args.model) || undefined,
+        global: obj(args.global),
+        strict: args.strict === false ? false : undefined,
+        login: args.login === true,
+        lock_resource: args.lock_resource === true,
+        description: args.description ? str(args.description) : undefined,
+    });
+    return formatScript(r, "Script");
+}
+function listRecipes(args) {
+    const id = str(args.recipe).trim();
+    if (id) {
+        const r = Object.hasOwn(recipes, id) ? recipes[id] : undefined;
+        if (!r)
+            return text(`Unknown recipe "${id}". Recipes: ${Object.keys(recipes).join(", ")}.`, true);
+        return json({ recipe: id, title: r.title, summary: r.summary, params: r.params, steps: r.steps.map((s) => ({ title: s.title, command: s.command, options: s.options, ...(s.foreach ? { foreach: s.foreach } : {}), ...(s.zip ? { zip: s.zip } : {}), ...(s.when ? { only_when_given: s.when } : {}) })), notes: r.notes });
+    }
+    const query = str(args.query).toLowerCase().trim();
+    let entries = Object.entries(recipes);
+    if (query) {
+        const w = query.split(/[^a-z0-9]+/).filter((x) => x.length > 1);
+        entries = entries
+            .map(([k, r]) => ({ k, r, s: w.filter((x) => `${k} ${r.title} ${r.summary} ${r.keywords.join(" ")}`.toLowerCase().includes(x)).length }))
+            .filter((x) => x.s > 0)
+            .sort((a, b) => b.s - a.s)
+            .map((x) => [x.k, x.r]);
+        if (!entries.length)
+            return text(`No recipe matched. Recipes: ${Object.keys(recipes).join(", ")}.`);
+    }
+    return text(entries.map(([k, r]) => `- ${k}: ${r.title}. ${r.summary}`).join("\n"));
+}
+function buildRecipeTool(args) {
+    const id = str(args.recipe).trim();
+    const recipe = Object.hasOwn(recipes, id) ? recipes[id] : undefined;
+    if (!recipe)
+        return text(`Unknown recipe "${id}". Recipes: ${Object.keys(recipes).join(", ")}.`, true);
+    const r = buildRecipe(catalog, id, recipe, obj(args.params), {
+        model: str(args.model) || undefined,
+        global: obj(args.global),
+        strict: args.strict === false ? false : undefined,
+        login: args.login === true,
+        lock_resource: args.lock_resource === true,
+    });
+    return formatScript(r, recipe.title);
+}
+function modelLimits(args) {
+    const want = str(args.model).trim();
+    if (!want)
+        return json({ models: [...catalog.models.entries()].map(([id, m]) => ({ id, label: m.label, aliases: m.aliases })) });
+    const m = catalog.model(want);
+    if (!m)
+        return text(`Unknown model "${want}". Models: ${[...catalog.models.keys()].join(", ")}.`, true);
+    const l = m.limits;
+    return json({
+        model: m.id,
+        label: l.label,
+        serial_number: `${l.serial[0]} to ${l.serial[1]}`,
+        ldev_id: `${l.ldev[0]} to ${l.ldev[1]}`,
+        pool_id: `${l.pool[0]} to ${l.pool[1]}`,
+        lun: `${l.lun[0]} to ${l.lun[1]}`,
+        port_columns: l.portColumns.split("").join(", "),
+        port_letters: l.portLetters.split("").join(", "),
+        ...(l.portColumnsLimited ? { port_note: `columns ${l.portColumnsLimited.cols.split("").join(", ")} only have ports ${l.portColumnsLimited.letters.split("").join(", ")}` } : {}),
+        host_group_id: "0 to 254",
+        source: "Valid parameter ranges in the appendices of the CCI Command Reference",
+    });
+}
+async function callTool(req) {
+    const { name } = req.params;
+    const args = obj(req.params.arguments);
+    try {
+        switch (name) {
+            case "raidcom_list_commands": return listCommands(args);
+            case "raidcom_describe_command": return describeCommand(args);
+            case "raidcom_build_command": return buildCommand(args);
+            case "raidcom_check_command": return checkCommand(args);
+            case "raidcom_build_script": return buildScriptTool(args);
+            case "raidcom_list_recipes": return listRecipes(args);
+            case "raidcom_build_recipe": return buildRecipeTool(args);
+            case "raidcom_model_limits": return modelLimits(args);
+            default: return text(`Unknown tool ${name}`, true);
+        }
+    }
+    catch (e) {
+        return text(`Error: ${e.message}`, true);
+    }
+}
+// ---------- resources and prompts ----------
+const resources = [
+    { uri: "raidcom://notes/conventions", name: "raidcom conventions", description: "Login, instances, serial numbers, asynchronous commands, resource locking.", mimeType: "text/markdown" },
+    { uri: "raidcom://notes/horcm-setup", name: "Minimal HORCM configuration", description: "What the host that runs raidcom needs.", mimeType: "text/markdown" },
+    { uri: "raidcom://catalog/commands", name: "Command list", description: "Every raidcom command in the catalogue with its one-line summary.", mimeType: "text/markdown" },
+];
+function readResource(uri) {
+    if (uri === "raidcom://notes/conventions")
+        return notes.conventions;
+    if (uri === "raidcom://notes/horcm-setup")
+        return notes.horcm;
+    if (uri === "raidcom://catalog/commands") {
+        return `# raidcom commands\n\nFrom ${catalog.source} (generated ${catalog.generated}).\n\n` + [...catalog.commands.values()].map((c) => `- \`raidcom ${commandName(c)}\` [${access(c)}]: ${c.summary}`).join("\n") + "\n";
+    }
+    return undefined;
+}
+const GUIDANCE = "You build raidcom commands for Hitachi VSP storage with the raidcom_* tools. The server only builds text; it never runs anything.\n" +
+    "1. If you do not know the command, raidcom_list_commands with the user's words. 2. If unsure of its options, raidcom_describe_command. " +
+    "3. Build with raidcom_build_command (one command) or raidcom_build_script / raidcom_build_recipe (several; use foreach or ranges instead of repeating calls). " +
+    "4. Pass `model` when the user names one so IDs and ports are range-checked. 5. If a result has errors, fix the arguments and build again. " +
+    "6. Show the user the command or script, say which commands change the array, and remind them to review it and to run changing commands under raidcom lock resource, ideally first with -checkmode precheck. " +
+    "Never invent options: only use ones raidcom_describe_command lists. Ask the user for values you do not have (pool, LDEV IDs, ports, WWNs) instead of guessing them.";
+const prompts = [
+    { name: "build-raidcom-commands", description: "Turn a storage task into validated raidcom commands.", arguments: [{ name: "task", description: "What you want to do, e.g. \"present 4 x 100 GB volumes from pool 0 to host esx01 on CL1-A and CL2-A\"", required: true }, { name: "model", description: "Storage model, e.g. vsp-one-b28", required: false }] },
+    { name: "explain-raidcom-command", description: "Explain and check an existing raidcom command line.", arguments: [{ name: "command_line", description: "The raidcom command", required: true }] },
+];
+function getPrompt(name, args = {}) {
+    if (name === "build-raidcom-commands") {
+        return { description: prompts[0].description, messages: [{ role: "user", content: { type: "text", text: `${GUIDANCE}\n\nTask: ${args.task ?? ""}${args.model ? `\nStorage model: ${args.model}` : ""}\n\nBuild the commands for this task with the raidcom tools. List anything you still need from me before building.` } }] };
+    }
+    if (name === "explain-raidcom-command") {
+        return { description: prompts[1].description, messages: [{ role: "user", content: { type: "text", text: `Check this raidcom command with raidcom_check_command, then explain in plain words what it does, what it changes, and anything risky about it:\n\n${args.command_line ?? ""}` } }] };
+    }
+    throw new Error(`Unknown prompt ${name}`);
+}
+/** An MCP server with the tools. stdio uses one for the whole process; HTTP makes one per request. */
+function createServer() {
+    const server = new Server({ name: "raidcom-mcp", version: VERSION }, { capabilities: { tools: {}, resources: {}, prompts: {} }, instructions: GUIDANCE });
+    const toolList = tools();
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: toolList }));
+    server.setRequestHandler(CallToolRequestSchema, callTool);
+    server.setRequestHandler(ListResourcesRequestSchema, async () => ({ resources }));
+    server.setRequestHandler(ReadResourceRequestSchema, async (req) => {
+        const body = readResource(req.params.uri);
+        if (body === undefined)
+            throw new Error(`Unknown resource ${req.params.uri}`);
+        return { contents: [{ uri: req.params.uri, mimeType: "text/markdown", text: body }] };
+    });
+    server.setRequestHandler(ListPromptsRequestSchema, async () => ({ prompts }));
+    server.setRequestHandler(GetPromptRequestSchema, async (req) => getPrompt(req.params.name, req.params.arguments));
+    return server;
+}
+let listening = "";
+if (httpCfg) {
+    // Imported only here, so the stdio server never loads the HTTP stack.
+    const { startHttp } = await import("./http.js");
+    const { url } = await startHttp(httpCfg, createServer).catch((e) => {
+        console.error(`[raidcom-mcp] cannot listen on ${httpCfg.host}:${httpCfg.port}: ${e.message}`);
+        process.exit(1);
+    });
+    listening = `, listening on ${url}${httpCfg.token ? "" : " (no token: open endpoint)"}`;
+}
+else {
+    await createServer().connect(new StdioServerTransport());
+}
+console.error(`[raidcom-mcp] ready: ${catalog.commands.size} commands, ${Object.keys(recipes).length} recipes, build-only${listening}`);