@modeltoolsprotocol/mtpcli 0.1.0 → 0.2.1

package/README.md

@@ -6,7 +6,7 @@ The command-line interface for the [Model Tools Protocol](https://github.com/mod
 
 LLM agents need to discover and use tools. Right now there are two worlds:
 
-**CLI tools** are the backbone of software development. They're composable (`|`), scriptable, version-controlled, and work everywhere. But LLMs can't discover what a CLI does -they have to parse `--help` text, guess at arguments, and hope for the best.
+**CLI tools** are the backbone of software development. They're composable (`|`), scriptable, version-controlled, and work everywhere. But LLMs can't discover what a CLI does - they have to parse `--help` text, guess at arguments, and hope for the best.
 
 **MCP (Model Context Protocol)** solves discovery beautifully. Tools declare typed schemas, and LLM hosts discover them via a structured handshake. But MCP requires running a server process, speaking JSON-RPC over stdio/SSE, and building within the MCP ecosystem. Your existing CLI tools don't get any of this for free.
 
@@ -55,12 +55,15 @@ mtpcli search --scan-path "git commit"
 # OAuth2 login
 mtpcli auth login mytool
 
-# API key login
-mtpcli auth login mytool --method apikey
+# API key / bearer token login
+mtpcli auth login mytool --token sk-xxx
 
 # Check auth status
 mtpcli auth status mytool
 
+# Inject token into env
+eval $(mtpcli auth env mytool)
+
 # Log out
 mtpcli auth logout mytool
 ```
@@ -69,17 +72,43 @@ mtpcli auth logout mytool
 
 ```bash
 # Start an MCP server that bridges describe-compatible tools
-mtpcli serve -- mytool anothertool
+mtpcli serve --tool mytool --tool anothertool
+```
 
-# Serve with a specific transport
-mtpcli serve --transport sse -- mytool
+### Wrap an MCP server as a CLI
+
+```bash
+# Describe an MCP server's tools
+mtpcli wrap --server "npx @mcp/server-github" --describe
+
+# Call a tool on an MCP server
+mtpcli wrap --server "npx @mcp/server-github" search_repos -- --query mtpcli
 ```
 
-### Wrap a tool as an MCP server
+### Validate a tool's --describe output
 
 ```bash
-# Wrap a single tool so it speaks MCP
-mtpcli wrap mytool
+# Validate a tool against the MTP spec
+mtpcli validate mytool
+
+# Validate JSON from stdin (for CI)
+cat describe.json | mtpcli validate --stdin
+
+# JSON output
+mtpcli validate mytool --json
+```
+
+### Generate shell completions
+
+```bash
+# Bash
+eval $(mtpcli completions bash mytool)
+
+# Zsh
+eval $(mtpcli completions zsh mytool)
+
+# Fish
+mtpcli completions fish mytool | source
 ```
 
 ### Describe self

package/dist/index.js

@@ -7917,17 +7917,38 @@ function sendNotification(writer, method, params) {
   writer.write(JSON.stringify(req) + `
 `);
 }
-async function readResponse(rl) {
-  for await (const line of rl) {
-    const trimmed = line.trim();
-    if (!trimmed)
-      continue;
-    const msg = JSON.parse(trimmed);
-    if ("id" in msg && msg.id !== undefined) {
-      return JsonRpcResponseSchema2.parse(msg);
-    }
-  }
-  throw new Error("MCP server closed connection");
+function readResponse(rl) {
+  return new Promise((resolve, reject) => {
+    const onLine = (line) => {
+      const trimmed = line.trim();
+      if (!trimmed)
+        return;
+      let msg;
+      try {
+        msg = JSON.parse(trimmed);
+      } catch (e) {
+        rl.off("line", onLine);
+        rl.off("close", onClose);
+        reject(e);
+        return;
+      }
+      if ("id" in msg && msg.id !== undefined) {
+        rl.off("line", onLine);
+        rl.off("close", onClose);
+        try {
+          resolve(JsonRpcResponseSchema2.parse(msg));
+        } catch (e) {
+          reject(e);
+        }
+      }
+    };
+    const onClose = () => {
+      rl.off("line", onLine);
+      reject(new Error("MCP server closed connection"));
+    };
+    rl.on("line", onLine);
+    rl.on("close", onClose);
+  });
 }
 var init_mcp = __esm(() => {
   init_models();
@@ -8452,6 +8473,614 @@ var init_wrap = __esm(() => {
   init_mcp();
 });
 
+// src/validate.ts
+var exports_validate = {};
+__export(exports_validate, {
+  validateTool: () => validateTool,
+  validateJson: () => validateJson,
+  run: () => run3,
+  crossReferenceHelp: () => crossReferenceHelp
+});
+import { execFile as execFile10 } from "node:child_process";
+import { promisify as promisify10 } from "node:util";
+function validateJson(raw) {
+  const diags = [];
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    diags.push({
+      level: "error",
+      code: "INVALID_JSON",
+      message: `Not valid JSON: ${e instanceof Error ? e.message : e}`
+    });
+    return diags;
+  }
+  const result = ToolSchemaSchema2.safeParse(parsed);
+  if (!result.success) {
+    for (const issue of result.error.issues) {
+      diags.push({
+        level: "error",
+        code: "SCHEMA_VIOLATION",
+        message: issue.message,
+        path: issue.path.join(".")
+      });
+    }
+    return diags;
+  }
+  const schema = result.data;
+  for (let ci = 0;ci < schema.commands.length; ci++) {
+    const cmd = schema.commands[ci];
+    const cmdPath = `commands.${ci}`;
+    if (cmd.examples.length === 0) {
+      diags.push({
+        level: "warning",
+        code: "MISSING_EXAMPLES",
+        message: `Command "${cmd.name}" has no examples`,
+        path: `${cmdPath}.examples`
+      });
+    }
+    for (let ai = 0;ai < cmd.args.length; ai++) {
+      const arg = cmd.args[ai];
+      const argPath = `${cmdPath}.args.${ai}`;
+      if (!VALID_ARG_TYPES.has(arg.type)) {
+        diags.push({
+          level: "error",
+          code: "INVALID_ARG_TYPE",
+          message: `Arg "${arg.name}" has invalid type "${arg.type}"`,
+          path: `${argPath}.type`
+        });
+      }
+      if (arg.type === "enum" && (!arg.values || arg.values.length === 0)) {
+        diags.push({
+          level: "warning",
+          code: "ENUM_NO_VALUES",
+          message: `Enum arg "${arg.name}" has no values`,
+          path: `${argPath}.values`
+        });
+      }
+      if (!arg.description) {
+        diags.push({
+          level: "warning",
+          code: "MISSING_DESCRIPTION",
+          message: `Arg "${arg.name}" has no description`,
+          path: `${argPath}.description`
+        });
+      }
+    }
+  }
+  return diags;
+}
+function crossReferenceHelp(schema, helpText) {
+  const diags = [];
+  const helpFlags = new Set;
+  const flagRe = /--([\w][\w-]*)/g;
+  let m;
+  while ((m = flagRe.exec(helpText)) !== null) {
+    helpFlags.add(`--${m[1]}`);
+  }
+  helpFlags.delete("--help");
+  helpFlags.delete("--version");
+  helpFlags.delete("--describe");
+  const declaredFlags = new Set;
+  for (const cmd of schema.commands) {
+    for (const arg of cmd.args) {
+      if (arg.name.startsWith("--")) {
+        declaredFlags.add(arg.name);
+      }
+    }
+  }
+  for (const flag of declaredFlags) {
+    if (!helpFlags.has(flag)) {
+      diags.push({
+        level: "info",
+        code: "HELP_ARG_MISMATCH",
+        message: `Flag "${flag}" in --describe but not found in --help`
+      });
+    }
+  }
+  for (const flag of helpFlags) {
+    if (!declaredFlags.has(flag)) {
+      diags.push({
+        level: "info",
+        code: "HELP_ARG_MISMATCH",
+        message: `Flag "${flag}" in --help but not found in --describe`
+      });
+    }
+  }
+  return diags;
+}
+async function validateTool(toolName, opts) {
+  const diags = [];
+  let toolPath;
+  try {
+    toolPath = await import_which3.default(toolName);
+  } catch {
+    diags.push({
+      level: "error",
+      code: "NOT_FOUND",
+      message: `Tool "${toolName}" not found in PATH`
+    });
+    return buildResult(toolName, diags);
+  }
+  let describeOutput;
+  try {
+    const { stdout } = await execFileAsync8(toolPath, ["--describe"], {
+      timeout: 1e4
+    });
+    describeOutput = stdout.trim();
+    if (!describeOutput) {
+      diags.push({
+        level: "error",
+        code: "DESCRIBE_FAILED",
+        message: `"${toolName} --describe" produced empty output`
+      });
+      return buildResult(toolName, diags);
+    }
+  } catch (e) {
+    diags.push({
+      level: "error",
+      code: "DESCRIBE_FAILED",
+      message: `"${toolName} --describe" failed: ${e instanceof Error ? e.message : e}`
+    });
+    return buildResult(toolName, diags);
+  }
+  diags.push(...validateJson(describeOutput));
+  const hasErrors = diags.some((d) => d.level === "error");
+  if (!hasErrors && !opts?.skipHelp) {
+    try {
+      const { stdout: helpText } = await execFileAsync8(toolPath, ["--help"], {
+        timeout: 5000
+      });
+      const schema = ToolSchemaSchema2.parse(JSON.parse(describeOutput));
+      diags.push(...crossReferenceHelp(schema, helpText));
+    } catch {}
+  }
+  return buildResult(toolName, diags);
+}
+function buildResult(tool, diagnostics) {
+  const errors2 = diagnostics.filter((d) => d.level === "error").length;
+  const warnings = diagnostics.filter((d) => d.level === "warning").length;
+  const info = diagnostics.filter((d) => d.level === "info").length;
+  return {
+    tool,
+    valid: errors2 === 0,
+    diagnostics,
+    summary: { errors: errors2, warnings, info }
+  };
+}
+async function run3(toolOrStdin, opts) {
+  let result;
+  if (opts.stdin) {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+      chunks.push(chunk);
+    }
+    const raw = Buffer.concat(chunks).toString("utf-8").trim();
+    const diags = validateJson(raw);
+    result = buildResult(opts.stdin ? "stdin" : "unknown", diags);
+  } else if (toolOrStdin) {
+    result = await validateTool(toolOrStdin, { skipHelp: opts.skipHelp });
+  } else {
+    process.stderr.write(`error: provide a tool name or use --stdin
+`);
+    process.exit(1);
+  }
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    printHuman(result);
+  }
+  if (!result.valid)
+    process.exit(1);
+}
+function printHuman(result) {
+  const icon = result.valid ? "PASS" : "FAIL";
+  console.log(`${icon}  ${result.tool}`);
+  for (const d of result.diagnostics) {
+    const tag = d.level === "error" ? "ERR" : d.level === "warning" ? "WRN" : "INF";
+    const path2 = d.path ? ` (${d.path})` : "";
+    console.log(`  ${tag}  [${d.code}] ${d.message}${path2}`);
+  }
+  const parts = [];
+  if (result.summary.errors)
+    parts.push(`${result.summary.errors} error(s)`);
+  if (result.summary.warnings)
+    parts.push(`${result.summary.warnings} warning(s)`);
+  if (result.summary.info)
+    parts.push(`${result.summary.info} info`);
+  if (parts.length)
+    console.log(`  ${parts.join(", ")}`);
+}
+var import_which3, execFileAsync8, VALID_ARG_TYPES;
+var init_validate = __esm(() => {
+  init_models();
+  import_which3 = __toESM(require_lib(), 1);
+  execFileAsync8 = promisify10(execFile10);
+  VALID_ARG_TYPES = new Set([
+    "string",
+    "integer",
+    "number",
+    "boolean",
+    "array",
+    "enum",
+    "path"
+  ]);
+});
+
+// src/completions.ts
+var exports_completions = {};
+__export(exports_completions, {
+  schemaToCompletionContext: () => schemaToCompletionContext,
+  run: () => run4,
+  generateZsh: () => generateZsh,
+  generateFish: () => generateFish,
+  generateBash: () => generateBash,
+  generate: () => generate
+});
+function extractFlags(args) {
+  const flags = [];
+  for (const arg of args) {
+    if (arg.name.startsWith("--")) {
+      flags.push({
+        name: arg.name,
+        description: arg.description ?? "",
+        type: arg.type,
+        values: arg.values
+      });
+    }
+  }
+  return flags;
+}
+function schemaToCompletionContext(schema) {
+  let rootFlags = [];
+  const groups = new Map;
+  for (const cmd of schema.commands) {
+    if (cmd.name === "_root") {
+      rootFlags = extractFlags(cmd.args);
+      continue;
+    }
+    const parts = cmd.name.split(/\s+/);
+    const key = parts[0];
+    const entry = { parts, description: cmd.description, flags: extractFlags(cmd.args) };
+    let group = groups.get(key);
+    if (!group) {
+      group = [];
+      groups.set(key, group);
+    }
+    group.push(entry);
+  }
+  const commands = [];
+  for (const [key, entries] of groups) {
+    if (entries.length === 1 && entries[0].parts.length === 1) {
+      commands.push({
+        name: key,
+        description: entries[0].description,
+        flags: entries[0].flags,
+        children: []
+      });
+    } else {
+      const children = [];
+      let groupDesc = "";
+      for (const entry of entries) {
+        const childName = entry.parts.slice(1).join(" ");
+        if (!childName) {
+          groupDesc = entry.description;
+          continue;
+        }
+        children.push({
+          name: childName,
+          description: entry.description,
+          flags: entry.flags,
+          children: []
+        });
+      }
+      if (!groupDesc && children.length > 0) {
+        groupDesc = `${key} commands`;
+      }
+      commands.push({
+        name: key,
+        description: groupDesc,
+        flags: [],
+        children
+      });
+    }
+  }
+  return { toolName: schema.name, rootFlags, commands };
+}
+function generateBash(toolName, ctx) {
+  const funcName = `_${toolName.replace(/[^a-zA-Z0-9]/g, "_")}_completions`;
+  const topNames = ctx.commands.map((c) => c.name);
+  const lines = [];
+  lines.push(`${funcName}() {`);
+  lines.push(`  local cur prev words cword`);
+  lines.push(`  _get_comp_words_by_ref -n : cur prev words cword 2>/dev/null || {`);
+  lines.push(`    cur="\${COMP_WORDS[COMP_CWORD]}"`);
+  lines.push(`    prev="\${COMP_WORDS[COMP_CWORD-1]}"`);
+  lines.push(`    words=("\${COMP_WORDS[@]}")`);
+  lines.push(`    cword=$COMP_CWORD`);
+  lines.push(`  }`);
+  lines.push(``);
+  lines.push(`  if ((cword == 1)); then`);
+  const toplevel = [...topNames];
+  if (ctx.rootFlags.length > 0) {
+    toplevel.push(...ctx.rootFlags.map((f) => f.name));
+  }
+  lines.push(`    COMPREPLY=($(compgen -W "${toplevel.join(" ")}" -- "$cur"))`);
+  lines.push(`    return`);
+  lines.push(`  fi`);
+  lines.push(``);
+  lines.push(`  local subcmd="\${words[1]}"`);
+  lines.push(``);
+  lines.push(`  case "$subcmd" in`);
+  for (const cmd of ctx.commands) {
+    if (cmd.children.length > 0) {
+      const childNames = cmd.children.map((c) => c.name);
+      lines.push(`    ${cmd.name})`);
+      lines.push(`      if ((cword == 2)); then`);
+      lines.push(`        COMPREPLY=($(compgen -W "${childNames.join(" ")}" -- "$cur"))`);
+      lines.push(`        return`);
+      lines.push(`      fi`);
+      lines.push(`      local childcmd="\${words[2]}"`);
+      for (const child of cmd.children) {
+        for (const flag of child.flags) {
+          if (flag.type === "enum" && flag.values && flag.values.length > 0) {
+            lines.push(`      if [[ "$childcmd" == "${child.name}" && "$prev" == "${flag.name}" ]]; then`);
+            lines.push(`        COMPREPLY=($(compgen -W "${flag.values.join(" ")}" -- "$cur"))`);
+            lines.push(`        return`);
+            lines.push(`      fi`);
+          }
+          if (flag.type === "path") {
+            lines.push(`      if [[ "$childcmd" == "${child.name}" && "$prev" == "${flag.name}" ]]; then`);
+            lines.push(`        compopt -o default`);
+            lines.push(`        COMPREPLY=()`);
+            lines.push(`        return`);
+            lines.push(`      fi`);
+          }
+        }
+      }
+      lines.push(`      case "$childcmd" in`);
+      for (const child of cmd.children) {
+        const flags = child.flags.map((f) => f.name).join(" ");
+        lines.push(`        ${child.name}) COMPREPLY=($(compgen -W "${flags}" -- "$cur"));;`);
+      }
+      lines.push(`        *) ;;`);
+      lines.push(`      esac`);
+      lines.push(`      ;;`);
+    } else {
+      lines.push(`    ${cmd.name})`);
+      for (const flag of cmd.flags) {
+        if (flag.type === "enum" && flag.values && flag.values.length > 0) {
+          lines.push(`      if [[ "$prev" == "${flag.name}" ]]; then`);
+          lines.push(`        COMPREPLY=($(compgen -W "${flag.values.join(" ")}" -- "$cur"))`);
+          lines.push(`        return`);
+          lines.push(`      fi`);
+        }
+        if (flag.type === "path") {
+          lines.push(`      if [[ "$prev" == "${flag.name}" ]]; then`);
+          lines.push(`        compopt -o default`);
+          lines.push(`        COMPREPLY=()`);
+          lines.push(`        return`);
+          lines.push(`      fi`);
+        }
+      }
+      const flags = cmd.flags.map((f) => f.name).join(" ");
+      lines.push(`      COMPREPLY=($(compgen -W "${flags}" -- "$cur"))`);
+      lines.push(`      ;;`);
+    }
+  }
+  lines.push(`    *) ;;`);
+  lines.push(`  esac`);
+  lines.push(`}`);
+  lines.push(``);
+  lines.push(`complete -F ${funcName} ${toolName}`);
+  return lines.join(`
+`) + `
+`;
+}
+function zshEsc(s) {
+  return s.replace(/'/g, "'\\''");
+}
+function zshFlagLine(flag) {
+  const desc = zshEsc(flag.description);
+  if (flag.type === "enum" && flag.values && flag.values.length > 0) {
+    return `'${flag.name}[${desc}]:value:(${flag.values.join(" ")})'`;
+  } else if (flag.type === "path") {
+    return `'${flag.name}[${desc}]:file:_files'`;
+  } else if (flag.type === "boolean") {
+    return `'${flag.name}[${desc}]'`;
+  }
+  return `'${flag.name}[${desc}]:value:'`;
+}
+function generateZsh(toolName, ctx) {
+  const funcName = `_${toolName.replace(/[^a-zA-Z0-9]/g, "_")}`;
+  const lines = [];
+  lines.push(`#compdef ${toolName}`);
+  lines.push(``);
+  for (const cmd of ctx.commands) {
+    if (cmd.children.length === 0)
+      continue;
+    const subFunc = `${funcName}_${cmd.name.replace(/[^a-zA-Z0-9]/g, "_")}`;
+    lines.push(`${subFunc}() {`);
+    lines.push(`  local -a subcmds`);
+    lines.push(`  subcmds=(`);
+    for (const child of cmd.children) {
+      lines.push(`    '${child.name}:${zshEsc(child.description)}'`);
+    }
+    lines.push(`  )`);
+    lines.push(``);
+    lines.push(`  _arguments -C \\`);
+    lines.push(`    '1:command:->subcmd' \\`);
+    lines.push(`    '*::arg:->args'`);
+    lines.push(``);
+    lines.push(`  case "$state" in`);
+    lines.push(`    subcmd)`);
+    lines.push(`      _describe '${cmd.name} command' subcmds`);
+    lines.push(`      ;;`);
+    lines.push(`    args)`);
+    lines.push(`      case "\${words[1]}" in`);
+    for (const child of cmd.children) {
+      lines.push(`        ${child.name})`);
+      lines.push(`          _arguments \\`);
+      for (const flag of child.flags) {
+        lines.push(`            ${zshFlagLine(flag)} \\`);
+      }
+      lines.push(`          ;;`);
+    }
+    lines.push(`      esac`);
+    lines.push(`      ;;`);
+    lines.push(`  esac`);
+    lines.push(`}`);
+    lines.push(``);
+  }
+  lines.push(`${funcName}() {`);
+  lines.push(`  local -a subcmds`);
+  if (ctx.commands.length > 0) {
+    lines.push(`  subcmds=(`);
+    for (const cmd of ctx.commands) {
+      lines.push(`    '${cmd.name}:${zshEsc(cmd.description)}'`);
+    }
+    lines.push(`  )`);
+  }
+  lines.push(``);
+  lines.push(`  _arguments -C \\`);
+  for (const flag of ctx.rootFlags) {
+    lines.push(`    ${zshFlagLine(flag)} \\`);
+  }
+  lines.push(`    '1:command:->subcmd' \\`);
+  lines.push(`    '*::arg:->args'`);
+  lines.push(``);
+  lines.push(`  case "$state" in`);
+  lines.push(`    subcmd)`);
+  lines.push(`      _describe 'command' subcmds`);
+  lines.push(`      ;;`);
+  lines.push(`    args)`);
+  lines.push(`      case "\${words[1]}" in`);
+  for (const cmd of ctx.commands) {
+    if (cmd.children.length > 0) {
+      const subFunc = `${funcName}_${cmd.name.replace(/[^a-zA-Z0-9]/g, "_")}`;
+      lines.push(`        ${cmd.name}) ${subFunc};;`);
+    } else {
+      lines.push(`        ${cmd.name})`);
+      lines.push(`          _arguments \\`);
+      for (const flag of cmd.flags) {
+        lines.push(`            ${zshFlagLine(flag)} \\`);
+      }
+      lines.push(`          ;;`);
+    }
+  }
+  lines.push(`      esac`);
+  lines.push(`      ;;`);
+  lines.push(`  esac`);
+  lines.push(`}`);
+  lines.push(``);
+  lines.push(`${funcName} "$@"`);
+  return lines.join(`
+`) + `
+`;
+}
+function fishEsc(s) {
+  return s.replace(/'/g, "\\'");
+}
+function fishFlagLines(toolName, condition, flags) {
+  const lines = [];
+  for (const flag of flags) {
+    const flagName = flag.name.replace(/^--/, "");
+    const desc = fishEsc(flag.description);
+    if (flag.type === "enum" && flag.values && flag.values.length > 0) {
+      lines.push(`complete -c ${toolName} -n '${condition}' -l ${flagName} -d '${desc}' -f -a '${flag.values.join(" ")}'`);
+    } else if (flag.type === "path") {
+      lines.push(`complete -c ${toolName} -n '${condition}' -l ${flagName} -d '${desc}' -F`);
+    } else if (flag.type === "boolean") {
+      lines.push(`complete -c ${toolName} -n '${condition}' -l ${flagName} -d '${desc}'`);
+    } else {
+      lines.push(`complete -c ${toolName} -n '${condition}' -l ${flagName} -d '${desc}' -x`);
+    }
+  }
+  return lines;
+}
+function generateFish(toolName, ctx) {
+  const lines = [];
+  const groupCmds = ctx.commands.filter((c) => c.children.length > 0);
+  if (groupCmds.length > 0) {
+    for (const group of groupCmds) {
+      const childNames = group.children.map((c) => c.name).join(" ");
+      const funcName = `__${toolName.replace(/[^a-zA-Z0-9]/g, "_")}_needs_${group.name}_subcmd`;
+      lines.push(`function ${funcName}`);
+      lines.push(`  set -l cmd (commandline -opc)`);
+      lines.push(`  if not contains -- ${group.name} $cmd`);
+      lines.push(`    return 1`);
+      lines.push(`  end`);
+      lines.push(`  for subcmd in ${childNames}`);
+      lines.push(`    if contains -- $subcmd $cmd`);
+      lines.push(`      return 1`);
+      lines.push(`    end`);
+      lines.push(`  end`);
+      lines.push(`  return 0`);
+      lines.push(`end`);
+      lines.push(``);
+    }
+  }
+  for (const flag of ctx.rootFlags) {
+    const flagName = flag.name.replace(/^--/, "");
+    const desc = fishEsc(flag.description);
+    lines.push(`complete -c ${toolName} -n '__fish_use_subcommand' -l ${flagName} -d '${desc}'`);
+  }
+  for (const cmd of ctx.commands) {
+    const desc = fishEsc(cmd.description);
+    lines.push(`complete -c ${toolName} -n '__fish_use_subcommand' -a ${cmd.name} -d '${desc}'`);
+  }
+  for (const cmd of ctx.commands) {
+    if (cmd.children.length > 0) {
+      const funcName = `__${toolName.replace(/[^a-zA-Z0-9]/g, "_")}_needs_${cmd.name}_subcmd`;
+      for (const child of cmd.children) {
+        const desc = fishEsc(child.description);
+        lines.push(`complete -c ${toolName} -n '${funcName}' -a ${child.name} -d '${desc}'`);
+      }
+      for (const child of cmd.children) {
+        const condition = `__fish_seen_subcommand_from ${child.name}`;
+        lines.push(...fishFlagLines(toolName, condition, child.flags));
+      }
+    } else {
+      const condition = `__fish_seen_subcommand_from ${cmd.name}`;
+      lines.push(...fishFlagLines(toolName, condition, cmd.flags));
+    }
+  }
+  return lines.join(`
+`) + `
+`;
+}
+function generate(shell, toolName, schema) {
+  const ctx = schemaToCompletionContext(schema);
+  switch (shell) {
+    case "bash":
+      return generateBash(toolName, ctx);
+    case "zsh":
+      return generateZsh(toolName, ctx);
+    case "fish":
+      return generateFish(toolName, ctx);
+    default:
+      throw new Error(`Unknown shell: ${shell}`);
+  }
+}
+async function run4(shell, toolName) {
+  if (!["bash", "zsh", "fish"].includes(shell)) {
+    process.stderr.write(`error: unsupported shell "${shell}". Use bash, zsh, or fish.
+`);
+    process.exit(1);
+  }
+  const schema = await getToolSchema2(toolName);
+  if (!schema) {
+    process.stderr.write(`error: could not get --describe from "${toolName}"
+`);
+    process.exit(1);
+  }
+  process.stdout.write(generate(shell, toolName, schema));
+}
+var init_completions = __esm(() => {
+  init_search2();
+});
+
 // node_modules/commander/esm.mjs
 var import__ = __toESM(require_commander(), 1);
 var {
@@ -8579,7 +9208,7 @@ function cleanJson(obj) {
 }
 
 // src/index.ts
-var VERSION3 = "0.1.0";
+var VERSION3 = "0.2.1";
 function selfDescribe() {
   const schema = {
     name: "mtpcli",
@@ -8777,6 +9406,82 @@ function selfDescribe() {
             command: 'mtpcli wrap --server "npx @mcp/server-github" search_repos -- --query mtpcli'
           }
         ]
+      },
+      {
+        name: "validate",
+        description: "Validate a tool's --describe output against the MTP spec",
+        args: [
+          {
+            name: "tool",
+            type: "string",
+            description: "Tool name to validate"
+          },
+          {
+            name: "--json",
+            type: "boolean",
+            default: false,
+            description: "Output as JSON"
+          },
+          {
+            name: "--stdin",
+            type: "boolean",
+            default: false,
+            description: "Read JSON from stdin instead of running tool"
+          },
+          {
+            name: "--skip-help",
+            type: "boolean",
+            default: false,
+            description: "Skip --help cross-reference check"
+          }
+        ],
+        examples: [
+          {
+            description: "Validate a tool",
+            command: "mtpcli validate mytool"
+          },
+          {
+            description: "Validate from stdin",
+            command: "cat describe.json | mtpcli validate --stdin"
+          },
+          {
+            description: "JSON output for CI",
+            command: "mtpcli validate mytool --json"
+          }
+        ]
+      },
+      {
+        name: "completions",
+        description: "Generate shell completions for a --describe-compatible tool",
+        args: [
+          {
+            name: "shell",
+            type: "enum",
+            required: true,
+            values: ["bash", "zsh", "fish"],
+            description: "Target shell"
+          },
+          {
+            name: "tool",
+            type: "string",
+            required: true,
+            description: "Tool name"
+          }
+        ],
+        examples: [
+          {
+            description: "Install bash completions",
+            command: "eval $(mtpcli completions bash mytool)"
+          },
+          {
+            description: "Install zsh completions",
+            command: "eval $(mtpcli completions zsh mytool)"
+          },
+          {
+            description: "Install fish completions",
+            command: "mtpcli completions fish mytool | source"
+          }
+        ]
       }
     ]
   };
@@ -8837,12 +9542,24 @@ authCmd.command("refresh").description("Force-refresh the stored OAuth token for
   await runRefresh2(tool);
 });
 program2.command("serve").description("Serve CLI tools as an MCP server (cli2mcp bridge)").requiredOption("--tool <names...>", "Tool(s) to serve").action(async (opts) => {
-  const { run: run3 } = await Promise.resolve().then(() => (init_serve(), exports_serve));
-  await run3(opts.tool);
+  const { run: run5 } = await Promise.resolve().then(() => (init_serve(), exports_serve));
+  await run5(opts.tool);
 });
 program2.command("wrap").description("Wrap an MCP server as a CLI tool (mcp2cli bridge)").requiredOption("--server <cmd>", "MCP server command to run").option("--describe", "Output --describe JSON instead of invoking", false).argument("[tool_name]", "Tool name to invoke").argument("[args...]", "Arguments for the tool (after --)").action(async (toolName, args, opts) => {
-  const { run: run3 } = await Promise.resolve().then(() => (init_wrap(), exports_wrap));
-  await run3(opts.server, opts.describe, toolName, args);
+  const { run: run5 } = await Promise.resolve().then(() => (init_wrap(), exports_wrap));
+  await run5(opts.server, opts.describe, toolName, args);
+});
+program2.command("validate").description("Validate a tool's --describe output against the MTP spec").argument("[tool]", "Tool name to validate").option("--json", "Output as JSON", false).option("--stdin", "Read JSON from stdin", false).option("--skip-help", "Skip --help cross-reference", false).action(async (tool, opts) => {
+  const { run: run5 } = await Promise.resolve().then(() => (init_validate(), exports_validate));
+  await run5(tool, {
+    json: opts.json,
+    stdin: opts.stdin,
+    skipHelp: opts.skipHelp
+  });
+});
+program2.command("completions").description("Generate shell completions from --describe output").argument("<shell>", "Shell type (bash, zsh, fish)").argument("<tool>", "Tool name").action(async (shell, tool) => {
+  const { run: run5 } = await Promise.resolve().then(() => (init_completions(), exports_completions));
+  await run5(shell, tool);
 });
 try {
   await program2.parseAsync(process.argv);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modeltoolsprotocol/mtpcli",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "license": "Apache-2.0",
   "type": "module",
   "bin": {