@modeltoolsprotocol/mtpcli 0.3.0 → 0.3.2

package/README.md

@@ -6,27 +6,21 @@ 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.
-
-These are both good ideas with real tradeoffs:
+**MCP (Model Context Protocol)** solves discovery beautifully. Tools declare typed schemas, and LLM hosts discover them via a structured handshake. But MCP tools aren't composable. Each invocation goes through the model. You can't pipe one MCP tool's output into another. You can't script them without an LLM in the loop.
 
 | | CLI tools | MCP tools |
 |---|---|---|
-| **Composability** | First-class. Pipes, shell scripts, xargs -50 years of Unix | Requires an orchestrator or agent framework |
+| **Composability** | First-class. Pipes, shell scripts, xargs. 50 years of Unix | Requires an orchestrator or agent framework |
 | **Discovery** | Poor. Parse `--help` and hope | Excellent. Typed schemas via handshake |
 | **Runtime** | Any shell, anywhere | Needs an MCP host (Claude Desktop, etc.) |
 | **Deployment** | `brew install`, `cargo install`, a binary in PATH | Run a server process, configure the host |
 | **Interop** | Pipes to anything | Talks to MCP clients only |
-| **Scriptable without an LLM** | Yes -that's the whole point of CLIs | Not really -designed for LLM interaction |
-| **Streaming / subscriptions** | Limited (stdout streaming) | Built-in (SSE, notifications) |
-| **Stateful interaction** | Stateless by design (each invocation is fresh) | Stateful sessions with context |
+| **Scriptable without an LLM** | Yes, that's the whole point of CLIs | Not really, designed for LLM interaction |
 | **Adoption cost** | One flag/decorator | New protocol, server scaffolding, SDK |
 
-MCP is the right choice when you need stateful sessions, streaming, or deep integration with an LLM host. CLIs are the right choice when you want composability, scriptability, and zero infrastructure.
-
-The gap is discovery. `mtpcli` fills it.
+The gap for CLIs is discovery. `mtpcli` fills it.
 
 ## Install
 
@@ -34,8 +28,52 @@ The gap is discovery. `mtpcli` fills it.
 npm install -g @modeltoolsprotocol/mtpcli
 ```
 
+## What it does
+
+**mtpcli** bridges the gap between CLI tools and MCP servers. It turns any `--describe` CLI into an MCP server, turns any MCP server into a composable CLI, and handles discovery, auth, and validation along the way.
+
 ## Usage
 
+### Serve CLI tools over MCP
+
+Any CLI that supports `--describe` becomes an MCP server:
+
+```bash
+$ mtpcli serve --tool atlasctl --tool mytool
+
+mtpcli serve: serving 6 tool(s) from 2 CLI tool(s)
+  - atlasctl__confluence page get
+  - atlasctl__config set
+  - atlasctl__config get
+  - mytool__convert
+  ...
+```
+
+Drop it into your Claude Desktop config and it works like any other MCP server. The bridge reads `--describe`, translates commands to MCP tools, and shells out to the real CLI when the host calls a tool.
+
+### Wrap an MCP server as a CLI
+
+Atlassian ships an MCP server at `mcp.atlassian.com`. With `mtpcli wrap`, it's a CLI:
+
+```bash
+# Discover what tools the server offers
+$ mtpcli wrap --url "https://mcp.atlassian.com/v1/mcp" --describe
+
+# Fetch a Confluence page
+$ mtpcli wrap --url "https://mcp.atlassian.com/v1/mcp" \
+    getConfluencePage -- --cloudId "$CLOUD_ID" --pageId 12345 --contentFormat markdown
+
+# Pipe it into jq, grep, or anything else
+$ mtpcli wrap --url "https://mcp.atlassian.com/v1/mcp" \
+    getConfluencePage -- --cloudId "$CLOUD_ID" --pageId 12345 --contentFormat markdown \
+    | jq -r '.body'
+
+# Works with stdio servers too
+$ mtpcli wrap --server "npx @mcp/server-github" --describe
+```
+
+The 2,500+ MCP servers people have built? They're all CLI tools now. Pipe their output, use them in scripts, compose them with other tools.
+
 ### Search for tools and commands
 
 ```bash
@@ -52,7 +90,7 @@ mtpcli search --scan-path "git commit"
 ### Authenticate with a tool
 
 ```bash
-# OAuth2 login
+# OAuth2 login (opens browser, handles callback)
 mtpcli auth login mytool
 
 # API key / bearer token login
@@ -68,22 +106,7 @@ eval $(mtpcli auth env mytool)
 mtpcli auth logout mytool
 ```
 
-### Serve tools over MCP
-
-```bash
-# Start an MCP server that bridges describe-compatible tools
-mtpcli serve --tool mytool --tool anothertool
-```
-
-### 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
-```
+See [AUTH.md](AUTH.md) for details on token storage, usage patterns, and bridge integration.
 
 ### Validate a tool's --describe output
 
@@ -114,7 +137,7 @@ mtpcli completions fish mytool | source
 ### Describe self
 
 ```bash
-# Output mtpcli's own describe schema (JSON)
+# mtpcli is itself an MTP-compliant tool
 mtpcli --describe
 ```
 

package/dist/index.js

@@ -8738,7 +8738,7 @@ function argToJsonSchema(arg) {
   return schema;
 }
 function commandToMcpTool(toolName, cmd) {
-  const mcpName = cmd.name === "_root" ? toolName : `${toolName}__${cmd.name}`;
+  const mcpName = cmd.name === "_root" ? toolName : `${toolName}__${cmd.name.replace(/ /g, "_")}`;
   const properties = {};
   const required = [];
   for (const arg of cmd.args) {
@@ -8772,7 +8772,7 @@ function commandToMcpTool(toolName, cmd) {
 function buildCliCommand(toolName, commandName, arguments_, commandSchema) {
   const cmd = [toolName];
   if (commandName !== "_root")
-    cmd.push(commandName);
+    cmd.push(...commandName.split(" "));
   const argSchemas = new Map;
   for (const a of commandSchema.args) {
     argSchemas.set(a.name.replace(/^-+/, ""), a);
@@ -8826,29 +8826,57 @@ function invokeCliTool(toolName, commandName, arguments_, commandSchema, authEnv
       stdio: [stdinStr !== undefined ? "pipe" : "ignore", "pipe", "pipe"],
       env: { ...process.env, ...authEnv }
     });
+    const timer = setTimeout(() => {
+      child.kill();
+      resolve({
+        content: [{ type: "text", text: `Error: tool timed out after ${TOOL_TIMEOUT_MS / 1000}s` }],
+        isError: true
+      });
+    }, TOOL_TIMEOUT_MS);
     if (stdinStr !== undefined && child.stdin) {
       child.stdin.write(stdinStr);
       child.stdin.end();
     }
     let stdout = "";
     let stderr = "";
-    child.stdout?.on("data", (d) => stdout += d);
-    child.stderr?.on("data", (d) => stderr += d);
+    let stdoutBytes = 0;
+    let stderrBytes = 0;
+    let truncated = false;
+    child.stdout?.on("data", (d) => {
+      stdoutBytes += d.length;
+      if (stdoutBytes <= MAX_OUTPUT_BYTES) {
+        stdout += d;
+      } else if (!truncated) {
+        truncated = true;
+        child.kill();
+      }
+    });
+    child.stderr?.on("data", (d) => {
+      stderrBytes += d.length;
+      if (stderrBytes <= MAX_OUTPUT_BYTES) {
+        stderr += d;
+      }
+    });
     child.on("error", (e) => {
+      clearTimeout(timer);
       resolve({
         content: [{ type: "text", text: `Error: ${e.message}` }],
         isError: true
       });
     });
     child.on("close", (code) => {
+      clearTimeout(timer);
       const content = [];
+      if (truncated) {
+        content.push({ type: "text", text: `[truncated: output exceeded ${MAX_OUTPUT_BYTES / 1024 / 1024}MB]` });
+      }
       if (stdout.trim())
         content.push({ type: "text", text: stdout.trim() });
       if (stderr.trim())
         content.push({ type: "text", text: `[stderr] ${stderr.trim()}` });
       if (content.length === 0)
         content.push({ type: "text", text: "(no output)" });
-      resolve({ content, isError: code !== 0 });
+      resolve({ content, isError: code !== 0 || truncated });
     });
   });
 }
@@ -8948,13 +8976,14 @@ async function run(toolNames) {
     }
   }
 }
-var execFileAsync7, VERSION = "0.1.0";
+var execFileAsync7, VERSION = "0.1.0", TOOL_TIMEOUT_MS = 60000, MAX_OUTPUT_BYTES;
 var init_serve = __esm(() => {
   init_auth();
   init_mcp();
   init_models();
   init_search2();
   execFileAsync7 = promisify9(execFile9);
+  MAX_OUTPUT_BYTES = 1024 * 1024 * 1024;
 });
 
 // src/mcp-oauth.ts
@@ -10564,7 +10593,7 @@ function cleanJson(obj) {
 }
 
 // src/index.ts
-var VERSION3 = "0.3.0";
+var VERSION3 = "0.3.2";
 function selfDescribe() {
   const schema = {
     name: "mtpcli",

package/package.json

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