@ai-ecoverse/mcpcat 0.15.9 → 0.17.0

package/README.md

@@ -24,6 +24,16 @@ npm install -g @ai-ecoverse/mcpcat
 
 mcpcat runs natively on macOS, Linux and Windows (Node ≥ 24), and inside Sliccy Seven as a kernel program, with the same flags, the same output and the same config file in both places. Orphan-free shutdown of stdio server trees in the kernel needs slicc-kernel ≥ 1.74.0; on older kernels only the direct child is signalled. A SIGKILLed mcpcat runs no handler. On slicc-kernel ≥ 1.88.0, mcpcat spawns stdio servers and served commands with a parent death signal (like Linux `PR_SET_PDEATHSIG`), so the kernel SIGKILLs each server's process group when mcpcat dies. On older kernels, and on the host, where there is no portable equivalent, servers that exit on stdin EOF (most MCP servers) still stop, but servers that ignore it keep running.
 
+## Releases: certified = latest
+
+Every change that alters what mcpcat ships is certified before it reaches `main`. A pull request that touches `src/`, the build, the dependencies or the release workflows gets mcpcat's cert-review on a pack of its head, and again in the merge queue on the exact tree that lands on `main`; a FAIL blocks the merge. Docs-, test- and CI-only changes skip it as "not behaviour". Each merge to `main` is then released to npm as `latest` in one step by semantic-release, with provenance, so `npm install @ai-ecoverse/mcpcat` and the installer always get certified code. The verdict line is a comment on the pull request and the `cert-review` commit status. It reads `certified …`, `cert-ci: FAIL …` when the reviewer or a check in code found a defect (status `failure`), or `cert-ci: INCOMPLETE …` when the review couldn't decide: the review job didn't succeed or was skipped, no verdict could be read, or the artifact or the runner's own `gh` was missing (status `error`). A fork's change to shipped behaviour also reads INCOMPLETE, since it gets no review. INCOMPLETE never certifies; re-run the failed jobs. A run that ends without `record` posting its status (a crashed plan, record or verdict job) still posts one on the head: `error` with its INCOMPLETE line, `failure` for a FAIL, or `pending` while the coordinator approval is missing. So the required `cert-review` check never waits forever, and a label change reuses only a `success` or `failure` verdict, never an INCOMPLETE one. The reviewer's verdict can add defects but never clear one found in code: `record` re-reads the suites' evidence (`stage.json`, `suites.json`), uploaded before the reviewer runs and bound by the artifact id and digest the review job output. A suite or security row that failed on the host or a pinned kernel, a changed test that fails on the head, an import in the kernel bundle or an unexplained rebuild difference is a FAIL. Missing suites, kernels or rows are INCOMPLETE. The NEGATIVE runs each changed test on the base's code: the subject's tests, helpers and fixtures with the base's `dist`, `scripts/` and `.github/workflows/`, all from the base sha, so a test of the cert tooling runs against main's tooling. The record names both shas. A changed test that also passes on the base is named in the line as `gaps: no-negative <file>`. Every artifact a later job reads (the tarball, the verdict, the suites' evidence) is downloaded by the artifact id its producer output, after `bind.mjs` checks the artifact's name, run and digest against that producer's outputs. Any other artifact from this attempt of the run under `mcpcat-tarball-`, `mcpcat-npm-tarball-` or `cert-review-` makes the line INCOMPLETE. An earlier attempt's leftovers, created before this attempt started, are never read.
+
+After each release, `cert-verify.yml` (on the Release run's success, or dispatched from `main` with a `version`) checks again that npm serves the SLSA subject built by `release.yml` on `main` from the tag, and that every pull request merged since the previous tag carries a green `cert-review` status on its head. Its hosted, write-only `notes` job then puts one line into the GitHub release notes, between `<!-- cert-verify -->` markers: `certified @ai-ecoverse/mcpcat@<version> sha256=<sha> (…; pr-certified since v<prev>: …)`, or `verified …` when some pull request lacks a green cert-review. A re-run with the same bytes leaves the notes as they are. Notes that already name another sha for the version, or npm bytes that don't verify, are a supply-chain alert: nothing is written and an issue is filed. Checks that couldn't run read `cert-ci: INCOMPLETE` and write nothing.
+
+Silence never passes: every gate in the workflows prints a verdict line, and its caller requires that line, not just an exit code. These are `all-green: PASS|FAIL …`, the cert job's `cert: kernel <v> — N kernel tests passed`, shipped.mjs's `behaviour:`/`not behaviour:`, release verify's `verified …`, and the installer tests' `All installer tests passed.`. A gate that exits 0 without its line fails.
+
+A pull request or merge group that touches the certification itself (the `cert-review` and `ci` workflows, `scripts/cert-review/` and `rows.json`, `scripts/cert.mjs`, `scripts/kernel-test-files.mjs`, and the cert-row, cert-gate, cert-review, cert-runner, cert-self-guard, cert-verify and cert-verdicts tests) fails `cert-review` with "needs coordinator review" until the label `cert-review-approved` is applied after its head arrived. The check is the shared [cert self-guard](https://github.com/ai-ecoverse/slicc-shared-web/tree/f342d7cf558c817ce517bbbbc4cc46df6eac2f97/.github/actions/cert-self-guard), pinned to a full sha in `cert-review.yml`. Only the lane coordinator applies the label, after reading the diff; workers never add or remove it. Any push removes it, so every new head needs a fresh approval; a label change re-runs the checks but reuses the recorded cert-review verdict of an unchanged head. To re-check an approval, run the label event, not the earlier push. The label is procedural: every agent acts as one admin account, so the permission check cannot tell a coordinator from a worker, and a deliberate rewrite of the workflow is not stopped. The `kernel-cert-*` pins in `package.json` are not guarded, because the guard matches whole files and guarding `package.json` would hold every Renovate bump for approval.
+
 ## Quick start
 
 ```sh
@@ -32,6 +42,10 @@ mcpcat weather get-forecast --lat 51.5 --lon -0.12
 mcpcat serve --http 8808 ./scripts/jira.jsh
 ```
 
+## Agent skill
+
+The package ships an [Agent Skill](https://agentskills.io/specification) that teaches an agent mcpcat in one file: `dist/skills/mcpcat/SKILL.md`, built from [`src/skill/SKILL.txt`](src/skill/SKILL.txt) (the repo keeps no Markdown besides README.md and AGENTS.md). It covers targets, listing and calling tools, `mcp.json`, exit codes, and the secrets rule: `${NAME}` placeholders in single quotes, never a value in a command, a file or the conversation, and never a token in `mcp.json`. `mcpcat help --skill` prints the copy that matches the installed version. `package.json` declares it as a pi package skill (`"pi": { "skills": ["dist/skills"] }`). In seven, bios links it into `/usr/share/skills` for the certified catalog install. It is shipped behaviour under `src/`, so a change to it gets a cert review.
+
 ## License
 
 Apache-2.0

package/dist/host/mcpcat.mjs

@@ -9113,6 +9113,12 @@ async function connect(platform2, options) {
   }
 }
 
+// src/render/sanitize.ts
+var CONTROL_RE = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g;
+function sanitizeTerminal(text) {
+  return text.replace(CONTROL_RE, (c) => `\\x${c.charCodeAt(0).toString(16).padStart(2, "0")}`);
+}
+
 // src/client/elicit.ts
 function readLine(platform2) {
   return new Promise((resolve, reject) => {
@@ -9164,7 +9170,7 @@ async function promptForSchema(platform2, schema) {
     const desc = prop.description ? ` - ${prop.description}` : "";
     const def = prop.default !== void 0 ? ` [${String(prop.default)}]` : "";
     const choices = prop.enum ? ` (${prop.enum.join("|")})` : "";
-    await platform2.write(2, `${key}${req}${desc}${choices}${def}: `);
+    await platform2.write(2, sanitizeTerminal(`${key}${req}${desc}${choices}${def}: `));
     const line = await readLine(platform2);
     const value = line.trim();
     if (value === "" && prop.default !== void 0) {
@@ -9186,8 +9192,8 @@ function parseInputRequest(result) {
 async function handleElicitation(platform2, inputRequest, isTty, respondData) {
   if (inputRequest.url) {
     if (isTty) {
-      await platform2.write(2, `Open this URL to continue: ${inputRequest.url}
-`);
+      await platform2.write(2, sanitizeTerminal(`Open this URL to continue: ${inputRequest.url}
+`));
       await platform2.write(2, "Press Enter when done...");
       await readLine(platform2);
       return { answers: {} };
@@ -9202,8 +9208,8 @@ async function handleElicitation(platform2, inputRequest, isTty, respondData) {
   }
   const schema = inputRequest.schema ?? { type: "object", properties: {} };
   if (inputRequest.message) {
-    await platform2.write(2, `${inputRequest.message}
-`);
+    await platform2.write(2, sanitizeTerminal(`${inputRequest.message}
+`));
   }
   const answers = await promptForSchema(platform2, schema);
   return { answers };
@@ -9724,8 +9730,11 @@ async function formatOutput(platform2, result, json) {
 `);
     }
     if (!result.ok) {
-      await platform2.write(2, `mcpcat: script failed: ${result.error.message}
-`);
+      await platform2.write(
+        2,
+        sanitizeTerminal(`mcpcat: script failed: ${result.error.message}
+`)
+      );
     }
   }
   const isTimeout = !result.ok && result.error && result.error.kind === "timeout";
@@ -11187,8 +11196,8 @@ async function renderCallResult(platform2, result, options) {
   }
   const text = renderCallResultText(result, options);
   if (result.isError) {
-    await platform2.write(2, r(`${text || "(tool reported error)"}
-`));
+    await platform2.write(2, sanitizeTerminal(r(`${text || "(tool reported error)"}
+`)));
     return 1;
   }
   if (text) {
@@ -11239,17 +11248,17 @@ function sanitizeName(raw) {
   const cleaned = raw.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
   return cleaned || "cli";
 }
-function cliPrefix(help, filePath, explicit) {
+function cliPrefix(help2, filePath, explicit) {
   if (explicit) return sanitizeName(explicit);
-  const fromUsage = usageProgramName(help);
+  const fromUsage = usageProgramName(help2);
   if (fromUsage) return sanitizeName(fromUsage);
   const base = filePath.split("/").pop() ?? filePath;
   return sanitizeName(base.replace(/\.jsh$/i, ""));
 }
-function parseHelp(help) {
-  const block = commandsFromBlock(help);
-  const program = usageProgramName(help);
-  const commands = mergeCommandLists(block.commands, usageCommands(help, program));
+function parseHelp(help2) {
+  const block = commandsFromBlock(help2);
+  const program = usageProgramName(help2);
+  const commands = mergeCommandLists(block.commands, usageCommands(help2, program));
   return {
     ...program ? { program } : {},
     commands: applyScopedFlags(commands, block.scoped),
@@ -11393,12 +11402,12 @@ function encodeFlag(flag, value) {
   }
   return { argv: [`--${flag.name}`, String(value)] };
 }
-function commandsFromBlock(help) {
+function commandsFromBlock(help2) {
   let section = "none";
   const commands = [];
   const globalFlags = [];
   const scoped = [];
-  for (const rawLine of help.split("\n")) {
+  for (const rawLine of help2.split("\n")) {
     const line = rawLine.replace(/\t/g, "  ");
     const header = classifyHeader(line);
     if (header) {
@@ -11446,8 +11455,8 @@ function parseCommandLine(line) {
     flags: spec.flags
   };
 }
-function usageProgramName(help) {
-  for (const raw of help.split("\n")) {
+function usageProgramName(help2) {
+  for (const raw of help2.split("\n")) {
     if (!/^[\s>*]*usage:/i.test(raw)) continue;
     const tokens = tokenize2(raw);
     const name = tokens[0];
@@ -11455,9 +11464,9 @@ function usageProgramName(help) {
   }
   return void 0;
 }
-function usageCommands(help, program) {
+function usageCommands(help2, program) {
   const commands = [];
-  for (const raw of help.split("\n")) {
+  for (const raw of help2.split("\n")) {
     const command = usageCommand(raw, program);
     if (command) commands.push(command);
   }
@@ -13296,8 +13305,8 @@ async function runWebMcpServe(platform2, options, version, resolvedBearer, gener
       return 3;
     }
     if (!resolved.tab) {
-      await platform2.write(2, `mcpcat serve --webmcp: ${resolved.error}
-`);
+      await platform2.write(2, sanitizeTerminal(`mcpcat serve --webmcp: ${resolved.error}
+`));
       return 3;
     }
     tab = resolved.tab;
@@ -14300,8 +14309,8 @@ ${url.href}
       await platform2.write(2, "mcpcat: sign-in cancelled\n");
       return 1;
     }
-    await platform2.write(2, `mcpcat: login failed: ${err.message}
-`);
+    await platform2.write(2, sanitizeTerminal(`mcpcat: login failed: ${err.message}
+`));
     return 4;
   }
 }
@@ -14934,8 +14943,8 @@ async function runAdd(platform2, args2, probe) {
   if (!flags.noProbe && probe) {
     const reason = await probe(name, config, platform2);
     if (reason) {
-      await platform2.write(2, `mcpcat add: probe failed: ${reason}
-`);
+      await platform2.write(2, sanitizeTerminal(`mcpcat add: probe failed: ${reason}
+`));
       return 3;
     }
   }
@@ -15316,7 +15325,7 @@ function redact(text, secrets) {
 function createVerboseLogger(platform2, enabled) {
   const secrets = /* @__PURE__ */ new Set();
   function write(line) {
-    const safe = redact(line, secrets);
+    const safe = sanitizeTerminal(redact(line, secrets));
     platform2.write(2, `${safe}
 `).catch(() => {
     });
@@ -15444,6 +15453,7 @@ Server and code verbs:
   discover <url>             Find MCP servers at a URL
   inbox [--json]             List discovery candidates
   help [verb]                Show help
+  help --skill               Print the agent skill (SKILL.md) for this version
 
 Options:
   --json                     JSON output
@@ -16135,8 +16145,11 @@ async function connectTargets(platform2, names, config, parsed, version) {
       const info = await conn.info();
       targets.push({ name, conn, instructions: info.instructions });
     } catch (err) {
-      await platform2.write(2, `mcpcat: connection to ${name} failed: ${err.message}
-`);
+      await platform2.write(
+        2,
+        sanitizeTerminal(`mcpcat: connection to ${name} failed: ${err.message}
+`)
+      );
     }
   }
   return {
@@ -16290,6 +16303,19 @@ async function run(platform2, version, args2) {
     throw err;
   }
 }
+async function help(platform2, version, args2) {
+  if (args2[0] !== "help" || !args2.includes("--skill")) {
+    await platform2.write(1, helpText(version));
+    return 0;
+  }
+  const skill = true ? "---\nname: mcpcat\ndescription: Call Model Context Protocol (MCP) servers from the shell with mcpcat, a curl for MCP. List and call tools, read resources and prompts, keep servers in mcp.json, and send secrets as ${VAR} placeholders that the vault fills in, never as values. Use when a task needs a tool from an MCP server over HTTP or a stdio command.\n---\n\n# mcpcat\n\n`mcpcat` talks to MCP servers over Streamable HTTP or stdio, one shell command per request. Options go before the target.\n\n## Targets\n\n- A URL: `https://example.com/mcp`.\n- A stdio command: `stdio:<command> [args\u2026]`, as one argument (`'stdio:my-server --flag'`).\n- A name from `mcp.json`, the same `~/.pi/agent/mcp.json` the agent reads.\n\n## Discover and call\n\n```bash\nmcpcat info https://example.com/mcp\nmcpcat tools https://example.com/mcp\nmcpcat describe https://example.com/mcp search\nmcpcat call https://example.com/mcp search --q oauth --limit 5\nmcpcat call docs search -d '{\"q\":\"oauth\",\"limit\":5}'\nmcpcat --json call docs search --q oauth\nmcpcat grep issue\n```\n\n- Tool arguments are `--name value` flags, coerced to the schema's types, or one JSON object with `-d` (`-d @file`, `-d @-` for stdin).\n- `describe` prints a tool's schema and help; `--schema` prints the raw JSON Schema, `--ts` TypeScript declarations.\n- `--json` prints deterministic JSON for scripts; human output otherwise. `-m <s>` sets the timeout (default 60 s).\n- `code -e '<js>'` runs a short script over configured servers (`tools.mcp__<server>__<tool>(args)`), with `-s <server>` to pick servers.\n\n## Configure servers\n\n```bash\nmcpcat add docs https://example.com/mcp\nmcpcat add docs https://example.com/mcp -H 'Authorization: Bearer ${DOCS_TOKEN}'\nmcpcat list\nmcpcat rm docs\nmcpcat import ~/.cursor/mcp.json\nmcpcat login docs\n```\n\n`login` runs the OAuth sign-in for a server that needs one; `logout` removes its tokens.\n\n## Secrets: never values, always placeholders\n\n- **Never print, echo, log or paste a secret's value**, not in a command, a file, a message or your answer. The value must never reach the conversation.\n- **Use `${NAME}` placeholders in single quotes**: `-H 'Authorization: Bearer ${GH_TOKEN}'`. mcpcat expands them itself, so the value stays out of argv. In seven, `NAME` holds the vault's placeholder, and the vault fills in the value where a secret rule allows that host.\n- **Never put a token into `mcp.json`.** Write `${NAME}` there too; `mcpcat add` refuses a literal `Bearer \u2026` value.\n- `-v` traces show expanded headers as `[REDACTED]`. Don't try to work around redaction.\n- If a request needs a secret that isn't there, ask the user to add it to the vault; don't ask them to paste it.\n\n## Exit codes\n\n| Code | Meaning |\n|---|---|\n| 0 | Success |\n| 1 | The tool reported an error (`isError`), or `grep` found nothing |\n| 2 | Usage: bad flags, unknown tool, invalid arguments or config |\n| 3 | Connection, transport or protocol failure |\n| 4 | Authentication required or failed: run the `mcpcat login` the message names |\n| 5 | JSON-RPC error from the server |\n| 6 | The server asked for input and there is no terminal |\n| 124 | Timeout |\n| 130 | Interrupted |\n\n## In seven\n\n- Host servers on the user's machine are `http://host.slicc.internal:<port>`, through a linked slicc CLI.\n- Stdio servers must be kernel commands; `npx` needs the optional Node.js package.\n- The agent's own MCP tools come from `mcp.json`; `mcpcat add` is how to add a server to it.\n" : void 0;
+  if (!skill) {
+    await platform2.write(2, "mcpcat help: this build has no skill\n");
+    return EXIT_USAGE;
+  }
+  await platform2.write(1, skill);
+  return 0;
+}
 async function runInner(platform2, version, args2) {
   if (args2.includes("--version") || args2.includes("-V")) {
     await platform2.write(1, `${version}
@@ -16297,8 +16323,7 @@ async function runInner(platform2, version, args2) {
     return 0;
   }
   if (args2.includes("--help") || args2.includes("-h") || args2[0] === "help") {
-    await platform2.write(1, helpText(version));
-    return 0;
+    return help(platform2, version, args2);
   }
   if (args2.length === 0) {
     await platform2.write(1, helpText(version));
@@ -16555,8 +16580,8 @@ async function runClientVerb(platform2, version, parsed) {
     if (!showProgress) return;
     const pct = total ? ` ${Math.round(progress / total * 100)}%` : "";
     const msg = message ? ` ${message}` : "";
-    platform2.write(2, `* progress:${pct}${msg}
-`).catch(() => {
+    platform2.write(2, sanitizeTerminal(`* progress:${pct}${msg}
+`)).catch(() => {
     });
   };
   const config = await MergedConfigSource.load(platform2);
@@ -16684,13 +16709,13 @@ async function closeAndKillStdio(conn) {
 }
 async function writeErr(p, json, kind, msg) {
   if (json) await renderErrorJson(p, kind, msg);
-  else await p.write(2, `mcpcat: ${msg}
-`);
+  else await p.write(2, sanitizeTerminal(`mcpcat: ${msg}
+`));
 }
 async function writeErrRedacted(p, json, kind, msg, redact2) {
   if (json) await renderErrorJson(p, kind, msg, void 0, void 0, redact2);
-  else await p.write(2, `mcpcat: ${redact2(msg)}
-`);
+  else await p.write(2, sanitizeTerminal(`mcpcat: ${redact2(msg)}
+`));
 }
 function collectConfigSecrets(headers, env) {
   if (!headers) return [];
@@ -16963,5 +16988,5 @@ try {
   });
 } catch {
 }
-var code = await run(platform, "0.15.9", args);
+var code = await run(platform, "0.17.0", args);
 process.exit(code);

package/dist/kernel/mcpcat.mjs

@@ -8734,6 +8734,12 @@ async function connect(platform2, options) {
   }
 }
 
+// src/render/sanitize.ts
+var CONTROL_RE = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g;
+function sanitizeTerminal(text) {
+  return text.replace(CONTROL_RE, (c) => `\\x${c.charCodeAt(0).toString(16).padStart(2, "0")}`);
+}
+
 // src/client/elicit.ts
 function readLine(platform2) {
   return new Promise((resolve2, reject) => {
@@ -8785,7 +8791,7 @@ async function promptForSchema(platform2, schema) {
     const desc = prop.description ? ` - ${prop.description}` : "";
     const def = prop.default !== void 0 ? ` [${String(prop.default)}]` : "";
     const choices = prop.enum ? ` (${prop.enum.join("|")})` : "";
-    await platform2.write(2, `${key}${req}${desc}${choices}${def}: `);
+    await platform2.write(2, sanitizeTerminal(`${key}${req}${desc}${choices}${def}: `));
     const line = await readLine(platform2);
     const value = line.trim();
     if (value === "" && prop.default !== void 0) {
@@ -8807,8 +8813,8 @@ function parseInputRequest(result) {
 async function handleElicitation(platform2, inputRequest, isTty, respondData) {
   if (inputRequest.url) {
     if (isTty) {
-      await platform2.write(2, `Open this URL to continue: ${inputRequest.url}
-`);
+      await platform2.write(2, sanitizeTerminal(`Open this URL to continue: ${inputRequest.url}
+`));
       await platform2.write(2, "Press Enter when done...");
       await readLine(platform2);
       return { answers: {} };
@@ -8823,8 +8829,8 @@ async function handleElicitation(platform2, inputRequest, isTty, respondData) {
   }
   const schema = inputRequest.schema ?? { type: "object", properties: {} };
   if (inputRequest.message) {
-    await platform2.write(2, `${inputRequest.message}
-`);
+    await platform2.write(2, sanitizeTerminal(`${inputRequest.message}
+`));
   }
   const answers = await promptForSchema(platform2, schema);
   return { answers };
@@ -9345,8 +9351,11 @@ async function formatOutput(platform2, result, json) {
 `);
     }
     if (!result.ok) {
-      await platform2.write(2, `mcpcat: script failed: ${result.error.message}
-`);
+      await platform2.write(
+        2,
+        sanitizeTerminal(`mcpcat: script failed: ${result.error.message}
+`)
+      );
     }
   }
   const isTimeout = !result.ok && result.error && result.error.kind === "timeout";
@@ -10808,8 +10817,8 @@ async function renderCallResult(platform2, result, options) {
   }
   const text = renderCallResultText(result, options);
   if (result.isError) {
-    await platform2.write(2, r(`${text || "(tool reported error)"}
-`));
+    await platform2.write(2, sanitizeTerminal(r(`${text || "(tool reported error)"}
+`)));
     return 1;
   }
   if (text) {
@@ -10860,17 +10869,17 @@ function sanitizeName(raw) {
   const cleaned = raw.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
   return cleaned || "cli";
 }
-function cliPrefix(help, filePath, explicit) {
+function cliPrefix(help2, filePath, explicit) {
   if (explicit) return sanitizeName(explicit);
-  const fromUsage = usageProgramName(help);
+  const fromUsage = usageProgramName(help2);
   if (fromUsage) return sanitizeName(fromUsage);
   const base = filePath.split("/").pop() ?? filePath;
   return sanitizeName(base.replace(/\.jsh$/i, ""));
 }
-function parseHelp(help) {
-  const block = commandsFromBlock(help);
-  const program = usageProgramName(help);
-  const commands = mergeCommandLists(block.commands, usageCommands(help, program));
+function parseHelp(help2) {
+  const block = commandsFromBlock(help2);
+  const program = usageProgramName(help2);
+  const commands = mergeCommandLists(block.commands, usageCommands(help2, program));
   return {
     ...program ? { program } : {},
     commands: applyScopedFlags(commands, block.scoped),
@@ -11014,12 +11023,12 @@ function encodeFlag(flag, value) {
   }
   return { argv: [`--${flag.name}`, String(value)] };
 }
-function commandsFromBlock(help) {
+function commandsFromBlock(help2) {
   let section = "none";
   const commands = [];
   const globalFlags = [];
   const scoped = [];
-  for (const rawLine of help.split("\n")) {
+  for (const rawLine of help2.split("\n")) {
     const line = rawLine.replace(/\t/g, "  ");
     const header = classifyHeader(line);
     if (header) {
@@ -11067,8 +11076,8 @@ function parseCommandLine(line) {
     flags: spec.flags
   };
 }
-function usageProgramName(help) {
-  for (const raw of help.split("\n")) {
+function usageProgramName(help2) {
+  for (const raw of help2.split("\n")) {
     if (!/^[\s>*]*usage:/i.test(raw)) continue;
     const tokens = tokenize2(raw);
     const name = tokens[0];
@@ -11076,9 +11085,9 @@ function usageProgramName(help) {
   }
   return void 0;
 }
-function usageCommands(help, program) {
+function usageCommands(help2, program) {
   const commands = [];
-  for (const raw of help.split("\n")) {
+  for (const raw of help2.split("\n")) {
     const command = usageCommand(raw, program);
     if (command) commands.push(command);
   }
@@ -12917,8 +12926,8 @@ async function runWebMcpServe(platform2, options, version, resolvedBearer, gener
       return 3;
     }
     if (!resolved.tab) {
-      await platform2.write(2, `mcpcat serve --webmcp: ${resolved.error}
-`);
+      await platform2.write(2, sanitizeTerminal(`mcpcat serve --webmcp: ${resolved.error}
+`));
       return 3;
     }
     tab = resolved.tab;
@@ -13921,8 +13930,8 @@ ${url.href}
       await platform2.write(2, "mcpcat: sign-in cancelled\n");
       return 1;
     }
-    await platform2.write(2, `mcpcat: login failed: ${err.message}
-`);
+    await platform2.write(2, sanitizeTerminal(`mcpcat: login failed: ${err.message}
+`));
     return 4;
   }
 }
@@ -14555,8 +14564,8 @@ async function runAdd(platform2, args, probe) {
   if (!flags.noProbe && probe) {
     const reason = await probe(name, config, platform2);
     if (reason) {
-      await platform2.write(2, `mcpcat add: probe failed: ${reason}
-`);
+      await platform2.write(2, sanitizeTerminal(`mcpcat add: probe failed: ${reason}
+`));
       return 3;
     }
   }
@@ -14937,7 +14946,7 @@ function redact(text, secrets) {
 function createVerboseLogger(platform2, enabled) {
   const secrets = /* @__PURE__ */ new Set();
   function write(line) {
-    const safe = redact(line, secrets);
+    const safe = sanitizeTerminal(redact(line, secrets));
     platform2.write(2, `${safe}
 `).catch(() => {
     });
@@ -15065,6 +15074,7 @@ Server and code verbs:
   discover <url>             Find MCP servers at a URL
   inbox [--json]             List discovery candidates
   help [verb]                Show help
+  help --skill               Print the agent skill (SKILL.md) for this version
 
 Options:
   --json                     JSON output
@@ -15756,8 +15766,11 @@ async function connectTargets(platform2, names, config, parsed, version) {
       const info = await conn.info();
       targets.push({ name, conn, instructions: info.instructions });
     } catch (err) {
-      await platform2.write(2, `mcpcat: connection to ${name} failed: ${err.message}
-`);
+      await platform2.write(
+        2,
+        sanitizeTerminal(`mcpcat: connection to ${name} failed: ${err.message}
+`)
+      );
     }
   }
   return {
@@ -15911,6 +15924,19 @@ async function run(platform2, version, args) {
     throw err;
   }
 }
+async function help(platform2, version, args) {
+  if (args[0] !== "help" || !args.includes("--skill")) {
+    await platform2.write(1, helpText(version));
+    return 0;
+  }
+  const skill = true ? "---\nname: mcpcat\ndescription: Call Model Context Protocol (MCP) servers from the shell with mcpcat, a curl for MCP. List and call tools, read resources and prompts, keep servers in mcp.json, and send secrets as ${VAR} placeholders that the vault fills in, never as values. Use when a task needs a tool from an MCP server over HTTP or a stdio command.\n---\n\n# mcpcat\n\n`mcpcat` talks to MCP servers over Streamable HTTP or stdio, one shell command per request. Options go before the target.\n\n## Targets\n\n- A URL: `https://example.com/mcp`.\n- A stdio command: `stdio:<command> [args\u2026]`, as one argument (`'stdio:my-server --flag'`).\n- A name from `mcp.json`, the same `~/.pi/agent/mcp.json` the agent reads.\n\n## Discover and call\n\n```bash\nmcpcat info https://example.com/mcp\nmcpcat tools https://example.com/mcp\nmcpcat describe https://example.com/mcp search\nmcpcat call https://example.com/mcp search --q oauth --limit 5\nmcpcat call docs search -d '{\"q\":\"oauth\",\"limit\":5}'\nmcpcat --json call docs search --q oauth\nmcpcat grep issue\n```\n\n- Tool arguments are `--name value` flags, coerced to the schema's types, or one JSON object with `-d` (`-d @file`, `-d @-` for stdin).\n- `describe` prints a tool's schema and help; `--schema` prints the raw JSON Schema, `--ts` TypeScript declarations.\n- `--json` prints deterministic JSON for scripts; human output otherwise. `-m <s>` sets the timeout (default 60 s).\n- `code -e '<js>'` runs a short script over configured servers (`tools.mcp__<server>__<tool>(args)`), with `-s <server>` to pick servers.\n\n## Configure servers\n\n```bash\nmcpcat add docs https://example.com/mcp\nmcpcat add docs https://example.com/mcp -H 'Authorization: Bearer ${DOCS_TOKEN}'\nmcpcat list\nmcpcat rm docs\nmcpcat import ~/.cursor/mcp.json\nmcpcat login docs\n```\n\n`login` runs the OAuth sign-in for a server that needs one; `logout` removes its tokens.\n\n## Secrets: never values, always placeholders\n\n- **Never print, echo, log or paste a secret's value**, not in a command, a file, a message or your answer. The value must never reach the conversation.\n- **Use `${NAME}` placeholders in single quotes**: `-H 'Authorization: Bearer ${GH_TOKEN}'`. mcpcat expands them itself, so the value stays out of argv. In seven, `NAME` holds the vault's placeholder, and the vault fills in the value where a secret rule allows that host.\n- **Never put a token into `mcp.json`.** Write `${NAME}` there too; `mcpcat add` refuses a literal `Bearer \u2026` value.\n- `-v` traces show expanded headers as `[REDACTED]`. Don't try to work around redaction.\n- If a request needs a secret that isn't there, ask the user to add it to the vault; don't ask them to paste it.\n\n## Exit codes\n\n| Code | Meaning |\n|---|---|\n| 0 | Success |\n| 1 | The tool reported an error (`isError`), or `grep` found nothing |\n| 2 | Usage: bad flags, unknown tool, invalid arguments or config |\n| 3 | Connection, transport or protocol failure |\n| 4 | Authentication required or failed: run the `mcpcat login` the message names |\n| 5 | JSON-RPC error from the server |\n| 6 | The server asked for input and there is no terminal |\n| 124 | Timeout |\n| 130 | Interrupted |\n\n## In seven\n\n- Host servers on the user's machine are `http://host.slicc.internal:<port>`, through a linked slicc CLI.\n- Stdio servers must be kernel commands; `npx` needs the optional Node.js package.\n- The agent's own MCP tools come from `mcp.json`; `mcpcat add` is how to add a server to it.\n" : void 0;
+  if (!skill) {
+    await platform2.write(2, "mcpcat help: this build has no skill\n");
+    return EXIT_USAGE;
+  }
+  await platform2.write(1, skill);
+  return 0;
+}
 async function runInner(platform2, version, args) {
   if (args.includes("--version") || args.includes("-V")) {
     await platform2.write(1, `${version}
@@ -15918,8 +15944,7 @@ async function runInner(platform2, version, args) {
     return 0;
   }
   if (args.includes("--help") || args.includes("-h") || args[0] === "help") {
-    await platform2.write(1, helpText(version));
-    return 0;
+    return help(platform2, version, args);
   }
   if (args.length === 0) {
     await platform2.write(1, helpText(version));
@@ -16176,8 +16201,8 @@ async function runClientVerb(platform2, version, parsed) {
     if (!showProgress) return;
     const pct = total ? ` ${Math.round(progress / total * 100)}%` : "";
     const msg = message ? ` ${message}` : "";
-    platform2.write(2, `* progress:${pct}${msg}
-`).catch(() => {
+    platform2.write(2, sanitizeTerminal(`* progress:${pct}${msg}
+`)).catch(() => {
     });
   };
   const config = await MergedConfigSource.load(platform2);
@@ -16305,13 +16330,13 @@ async function closeAndKillStdio(conn) {
 }
 async function writeErr(p, json, kind, msg) {
   if (json) await renderErrorJson(p, kind, msg);
-  else await p.write(2, `mcpcat: ${msg}
-`);
+  else await p.write(2, sanitizeTerminal(`mcpcat: ${msg}
+`));
 }
 async function writeErrRedacted(p, json, kind, msg, redact2) {
   if (json) await renderErrorJson(p, kind, msg, void 0, void 0, redact2);
-  else await p.write(2, `mcpcat: ${redact2(msg)}
-`);
+  else await p.write(2, sanitizeTerminal(`mcpcat: ${redact2(msg)}
+`));
 }
 function collectConfigSecrets(headers, env2) {
   if (!headers) return [];
@@ -16402,11 +16427,12 @@ async function kernelSpawn(ctx, options) {
     }
   }
   const useGroupKill = groupSpawnSupported;
+  let waited;
   return {
     stdin: result.stdin ?? new WritableStream(),
     stdout: result.stdout,
     stderr: result.stderr,
-    wait: () => result.wait(),
+    wait: () => waited ??= result.wait(),
     kill: async (signal) => {
       if (useGroupKill) {
         try {
@@ -16684,7 +16710,7 @@ async function main(ctx) {
     packageDir: "/node_modules/@ai-ecoverse/mcpcat"
   });
   const args = ctx.argv.slice(1);
-  return run(platform2, "0.15.9", args);
+  return run(platform2, "0.17.0", args);
 }
 export {
   main as default

package/dist/skills/mcpcat/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: mcpcat
+description: Call Model Context Protocol (MCP) servers from the shell with mcpcat, a curl for MCP. List and call tools, read resources and prompts, keep servers in mcp.json, and send secrets as ${VAR} placeholders that the vault fills in, never as values. Use when a task needs a tool from an MCP server over HTTP or a stdio command.
+---
+
+# mcpcat
+
+`mcpcat` talks to MCP servers over Streamable HTTP or stdio, one shell command per request. Options go before the target.
+
+## Targets
+
+- A URL: `https://example.com/mcp`.
+- A stdio command: `stdio:<command> [args…]`, as one argument (`'stdio:my-server --flag'`).
+- A name from `mcp.json`, the same `~/.pi/agent/mcp.json` the agent reads.
+
+## Discover and call
+
+```bash
+mcpcat info https://example.com/mcp
+mcpcat tools https://example.com/mcp
+mcpcat describe https://example.com/mcp search
+mcpcat call https://example.com/mcp search --q oauth --limit 5
+mcpcat call docs search -d '{"q":"oauth","limit":5}'
+mcpcat --json call docs search --q oauth
+mcpcat grep issue
+```
+
+- Tool arguments are `--name value` flags, coerced to the schema's types, or one JSON object with `-d` (`-d @file`, `-d @-` for stdin).
+- `describe` prints a tool's schema and help; `--schema` prints the raw JSON Schema, `--ts` TypeScript declarations.
+- `--json` prints deterministic JSON for scripts; human output otherwise. `-m <s>` sets the timeout (default 60 s).
+- `code -e '<js>'` runs a short script over configured servers (`tools.mcp__<server>__<tool>(args)`), with `-s <server>` to pick servers.
+
+## Configure servers
+
+```bash
+mcpcat add docs https://example.com/mcp
+mcpcat add docs https://example.com/mcp -H 'Authorization: Bearer ${DOCS_TOKEN}'
+mcpcat list
+mcpcat rm docs
+mcpcat import ~/.cursor/mcp.json
+mcpcat login docs
+```
+
+`login` runs the OAuth sign-in for a server that needs one; `logout` removes its tokens.
+
+## Secrets: never values, always placeholders
+
+- **Never print, echo, log or paste a secret's value**, not in a command, a file, a message or your answer. The value must never reach the conversation.
+- **Use `${NAME}` placeholders in single quotes**: `-H 'Authorization: Bearer ${GH_TOKEN}'`. mcpcat expands them itself, so the value stays out of argv. In seven, `NAME` holds the vault's placeholder, and the vault fills in the value where a secret rule allows that host.
+- **Never put a token into `mcp.json`.** Write `${NAME}` there too; `mcpcat add` refuses a literal `Bearer …` value.
+- `-v` traces show expanded headers as `[REDACTED]`. Don't try to work around redaction.
+- If a request needs a secret that isn't there, ask the user to add it to the vault; don't ask them to paste it.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Success |
+| 1 | The tool reported an error (`isError`), or `grep` found nothing |
+| 2 | Usage: bad flags, unknown tool, invalid arguments or config |
+| 3 | Connection, transport or protocol failure |
+| 4 | Authentication required or failed: run the `mcpcat login` the message names |
+| 5 | JSON-RPC error from the server |
+| 6 | The server asked for input and there is no terminal |
+| 124 | Timeout |
+| 130 | Interrupted |
+
+## In seven
+
+- Host servers on the user's machine are `http://host.slicc.internal:<port>`, through a linked slicc CLI.
+- Stdio servers must be kernel commands; `npx` needs the optional Node.js package.
+- The agent's own MCP tools come from `mcp.json`; `mcpcat add` is how to add a server to it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-ecoverse/mcpcat",
-  "version": "0.15.9",
+  "version": "0.17.0",
   "description": "A curl for the Model Context Protocol",
   "type": "module",
   "license": "Apache-2.0",
@@ -34,6 +34,11 @@
     "README.md",
     "dist"
   ],
+  "pi": {
+    "skills": [
+      "dist/skills"
+    ]
+  },
   "slicc": {
     "commands": {
       "mcpcat": {
@@ -56,15 +61,15 @@
     "trust:dry": "npx fledgling sync --dry-run -y --skip-publish"
   },
   "devDependencies": {
-    "@ai-ecoverse/slicc-bios": "1.2.0",
-    "@ai-ecoverse/slicc-kernel": "1.97.0",
-    "@ai-ecoverse/slicc-shared-web": "1.20.0",
+    "@ai-ecoverse/slicc-bios": "1.20.0",
+    "@ai-ecoverse/slicc-kernel": "1.127.1",
+    "@ai-ecoverse/slicc-shared-web": "1.23.2",
     "@biomejs/biome": "2.5.15",
     "@earendil-works/pi-codemode": "1.2.0",
     "@earendil-works/pi-mcp": "1.2.0",
     "@types/node": "26.6.5",
     "esbuild": "0.28.2",
-    "kernel-cert-new": "npm:@ai-ecoverse/slicc-kernel@1.97.0",
+    "kernel-cert-new": "npm:@ai-ecoverse/slicc-kernel@1.127.1",
     "monocart-coverage-reports": "2.13.2",
     "proper-lockfile": "4.1.2",
     "quickjs-wasi": "3.6.2",