@ai-ecoverse/mcpcat 0.16.3 → 0.17.1

package/README.md

@@ -26,7 +26,13 @@ mcpcat runs natively on macOS, Linux and Windows (Node ≥ 24), and inside Slicc
 
 ## 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.
+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". A draft pull request is not reviewed: its `cert-review` is red with `draft: not reviewed, mark it ready for review`, and marking it ready starts the review (converted_to_draft cancels a running one). Mark ready = reviewed, and merges on green; a pull request held for anything stays a draft. For a PR that needs the coordinator's security read, the order is: the coordinator reads the draft, it is marked ready, the cert runs, then the queue. 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
 
@@ -36,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

@@ -11248,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),
@@ -11402,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) {
@@ -11455,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];
@@ -11464,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);
   }
@@ -15432,11 +15432,15 @@ Client verbs:
   tools <target>             List tools
   call <target> <tool>       Call a tool
   describe <target> [tool]   Tool schema and help
+  resources <target>         List resources
+  read <target> <uri>        Read a resource
+  prompts <target>           List prompts
+  prompt <target> <name>     Get a prompt
 
 Configuration verbs:
   add <name> <url>           Add a server to mcp.json
-  add <name> --bridge -- 
-    Bridge a stdio server to HTTP (kernel only,
+  add <name> --bridge -- <command> [args\u2026]
+                             Bridge a stdio server to HTTP (kernel only,
                              runs in foreground, does not survive reload)
   rm <name>                  Remove a server
   list                       List configured servers
@@ -15452,11 +15456,12 @@ Server and code verbs:
   grep <pattern> [target\u2026]   Search tools by name or description
   discover <url>             Find MCP servers at a URL
   inbox [--json]             List discovery candidates
-  help [verb]                Show help
+  help                       Show this help
+  help --skill               Print the agent skill (SKILL.md) for this version
 
 Options:
   --json                     JSON output
-  -H, --header 'N: V'       Extra header
+  -H, --header 'N: V'        Extra header
   -d <json>                  Tool arguments as JSON (or @file, @- for stdin)
   -m, --timeout <s>          Request timeout (default 60)
   --memory <MiB>             Code mode memory limit (default 256, max 1024)
@@ -15470,7 +15475,7 @@ Options:
   -s, --server <name>        Server target (code, repeatable)
   --allow-shell              Enable shell() global (code)
   -v, --verbose              Trace on stderr
-  -s, --silent               Suppress progress
+  --silent                   Suppress progress
   -o, --output <path>        Write result to file
   -V, --version              Print version
   -h, --help                 Show this help
@@ -16302,6 +16307,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}
@@ -16309,8 +16327,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));
@@ -16975,5 +16992,5 @@ try {
   });
 } catch {
 }
-var code = await run(platform, "0.16.3", args);
+var code = await run(platform, "0.17.1", args);
 process.exit(code);

package/dist/kernel/mcpcat.mjs

@@ -10869,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),
@@ -11023,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) {
@@ -11076,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];
@@ -11085,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);
   }
@@ -15053,11 +15053,15 @@ Client verbs:
   tools <target>             List tools
   call <target> <tool>       Call a tool
   describe <target> [tool]   Tool schema and help
+  resources <target>         List resources
+  read <target> <uri>        Read a resource
+  prompts <target>           List prompts
+  prompt <target> <name>     Get a prompt
 
 Configuration verbs:
   add <name> <url>           Add a server to mcp.json
-  add <name> --bridge -- 
-    Bridge a stdio server to HTTP (kernel only,
+  add <name> --bridge -- <command> [args\u2026]
+                             Bridge a stdio server to HTTP (kernel only,
                              runs in foreground, does not survive reload)
   rm <name>                  Remove a server
   list                       List configured servers
@@ -15073,11 +15077,12 @@ Server and code verbs:
   grep <pattern> [target\u2026]   Search tools by name or description
   discover <url>             Find MCP servers at a URL
   inbox [--json]             List discovery candidates
-  help [verb]                Show help
+  help                       Show this help
+  help --skill               Print the agent skill (SKILL.md) for this version
 
 Options:
   --json                     JSON output
-  -H, --header 'N: V'       Extra header
+  -H, --header 'N: V'        Extra header
   -d <json>                  Tool arguments as JSON (or @file, @- for stdin)
   -m, --timeout <s>          Request timeout (default 60)
   --memory <MiB>             Code mode memory limit (default 256, max 1024)
@@ -15091,7 +15096,7 @@ Options:
   -s, --server <name>        Server target (code, repeatable)
   --allow-shell              Enable shell() global (code)
   -v, --verbose              Trace on stderr
-  -s, --silent               Suppress progress
+  --silent                   Suppress progress
   -o, --output <path>        Write result to file
   -V, --version              Print version
   -h, --help                 Show this help
@@ -15923,6 +15928,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}
@@ -15930,8 +15948,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));
@@ -16697,7 +16714,7 @@ async function main(ctx) {
     packageDir: "/node_modules/@ai-ecoverse/mcpcat"
   });
   const args = ctx.argv.slice(1);
-  return run(platform2, "0.16.3", args);
+  return run(platform2, "0.17.1", 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.16.3",
+  "version": "0.17.1",
   "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.5.2",
-    "@ai-ecoverse/slicc-kernel": "1.107.1",
-    "@ai-ecoverse/slicc-shared-web": "1.21.1",
+    "@ai-ecoverse/slicc-bios": "1.30.4",
+    "@ai-ecoverse/slicc-kernel": "1.133.3",
+    "@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.107.1",
+    "kernel-cert-new": "npm:@ai-ecoverse/slicc-kernel@1.133.3",
     "monocart-coverage-reports": "2.13.2",
     "proper-lockfile": "4.1.2",
     "quickjs-wasi": "3.6.2",