@beryl-so/cli 0.24.0 → 0.25.0

package/dist/adapters/mcp.js

@@ -6,6 +6,7 @@ import { loadConfig } from "../config.js";
 import { createContext } from "../context.js";
 import { CliError } from "../errors.js";
 import { ApiClient } from "../http.js";
+import { parseArgv } from "./cli.js";
 import { commands } from "../registry/index.js";
 import { cliVersion, warnIfStale } from "../version-check.js";
 export function toolName(spec) {
@@ -31,15 +32,103 @@ export function toolInputSchema(spec) {
             required.push(a.name);
     }
     for (const f of spec.flags ?? []) {
+        const withDefault = f.default !== undefined ? { default: f.default } : {};
         properties[f.name] =
             f.type === "strings"
-                ? { type: "array", items: { type: "string" }, description: f.description }
-                : { type: f.type, description: f.description, ...(f.enum ? { enum: f.enum } : {}) };
+                ? { type: "array", items: { type: "string" }, description: f.description, ...withDefault }
+                : {
+                    type: f.type,
+                    description: f.description,
+                    ...(f.enum ? { enum: f.enum } : {}),
+                    ...withDefault,
+                };
         if (f.required)
             required.push(f.name);
     }
     return { type: "object", properties, ...(required.length ? { required } : {}) };
 }
+function shellTokens(text) {
+    const tokens = [];
+    let current = "";
+    let quote = null;
+    let pending = false;
+    for (const ch of text) {
+        if (quote) {
+            if (ch === quote)
+                quote = null;
+            else
+                current += ch;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            pending = true;
+            continue;
+        }
+        if (/\s/.test(ch)) {
+            if (pending || current)
+                tokens.push(current);
+            current = "";
+            pending = false;
+            continue;
+        }
+        if (">|;#&".includes(ch))
+            return null;
+        current += ch;
+        pending = true;
+    }
+    if (quote)
+        return null;
+    if (pending || current)
+        tokens.push(current);
+    return tokens;
+}
+/** A CLI example translated to the JSON args the MCP tool takes, or null when it doesn't
+ *  translate cleanly (shell syntax, another command's example, nothing beyond defaults) —
+ *  agents must see tool args as JSON, never `--flag` syntax. */
+export function exampleArgs(spec, example) {
+    const prefix = `beryl ${spec.name}`;
+    if (example !== prefix && !example.startsWith(`${prefix} `))
+        return null;
+    const tokens = shellTokens(example.slice(prefix.length));
+    if (!tokens)
+        return null;
+    let parsed;
+    try {
+        parsed = parseArgv(spec, tokens);
+    }
+    catch {
+        return null;
+    }
+    if (parsed.help)
+        return null;
+    const byName = new Map((spec.flags ?? []).map((f) => [f.name, f]));
+    const out = {};
+    for (const [name, value] of Object.entries(parsed.input.args)) {
+        if (value === undefined || (Array.isArray(value) && value.length === 0))
+            continue;
+        out[name] = value;
+    }
+    for (const [name, value] of Object.entries(parsed.input.flags)) {
+        const f = byName.get(name);
+        // parseArgv fills declared defaults in; only what the example explicitly set teaches.
+        if (value === undefined || value === f?.default)
+            continue;
+        out[name] =
+            f?.type === "number" && typeof value === "string" && Number.isFinite(Number(value))
+                ? Number(value)
+                : value;
+    }
+    return Object.keys(out).length ? out : null;
+}
+export function toolDescription(spec) {
+    const base = spec.description ? `${spec.summary}. ${spec.description}` : spec.summary;
+    const lines = (spec.examples ?? [])
+        .map((e) => exampleArgs(spec, e))
+        .filter((a) => a !== null)
+        .map((a) => `Example: ${JSON.stringify(a)}`);
+    return lines.length ? `${base}\n${lines.join("\n")}` : base;
+}
 export function toolResult(result, lines) {
     const parts = [...lines];
     if (result.data !== undefined)
@@ -102,29 +191,36 @@ export function currentAuth(fallback) {
 export function __resetAuthCacheForTests() {
     authCache = undefined;
 }
+// The running version is stated up front because this server is long-lived and never
+// hot-reloads: a session can sit on a days-old build while `@latest` has moved, and
+// "that tool doesn't exist for me" is indistinguishable from a bug without it. Saying
+// it here means the model knows without spending a `version` tool call.
+export function mcpInstructions() {
+    const version = cliVersion();
+    return (`Beryl CLI v${version} (call the \`version\` tool for the API URL, Node ` +
+        "version, and whether this build is behind npm's latest). " +
+        "Beryl authors, runs, and heals end-to-end tests for any web app: tests are JSON " +
+        "action plans replayed in real cloud browsers, signing in as a durable test " +
+        "account whose mail arrives at the project's own mailbox — so signup/OTP/" +
+        "magic-link flows are self-contained, with no human login needed. " +
+        "The full authoring guide (plan shape, outcome assertions, email/OTP wiring, " +
+        "run-fix loop) ships as both the beryl-test skill and the `guide` tool — same " +
+        `content. If a beryl-test skill stating v${version} is already loaded, do not ` +
+        "call `guide`; if no beryl-test skill is available or it states another version, " +
+        "call `guide` before authoring your first test plan.");
+}
 export async function serveMcp(baseCtx) {
     // Fire-and-forget staleness warning: a stale MCP server silently exposes fewer
     // tools, and stderr is the one channel a stdio MCP server can safely log to.
     void warnIfStale(cliVersion(), (msg) => console.error(msg));
     const server = new Server({ name: "beryl", version: cliVersion() }, {
         capabilities: { tools: {} },
-        // The running version is stated up front because this server is long-lived and never
-        // hot-reloads: a session can sit on a days-old build while `@latest` has moved, and
-        // "that tool doesn't exist for me" is indistinguishable from a bug without it. Saying
-        // it here means the model knows without spending a `version` tool call.
-        instructions: `Beryl CLI v${cliVersion()} (call the \`version\` tool for the API URL, Node ` +
-            "version, and whether this build is behind npm's latest). " +
-            "Beryl authors, runs, and heals end-to-end tests for any web app: tests are JSON " +
-            "action plans replayed in real cloud browsers, signing in as a durable test " +
-            "account whose mail arrives at the project's own mailbox — so signup/OTP/" +
-            "magic-link flows are self-contained, with no human login needed. Before " +
-            "authoring your first test plan, call the `guide` tool — it returns the full " +
-            "authoring guide (plan shape, outcome assertions, email/OTP wiring, run-fix loop).",
+        instructions: mcpInstructions(),
     });
     server.setRequestHandler(ListToolsRequestSchema, () => ({
         tools: mcpTools().map((spec) => ({
             name: toolName(spec),
-            description: spec.description ? `${spec.summary}. ${spec.description}` : spec.summary,
+            description: toolDescription(spec),
             inputSchema: toolInputSchema(spec),
         })),
     }));