@weibaohui/mcp2cli 0.2.8 → 0.4.0

package/README.md

@@ -1,234 +1,234 @@
 # mcp2cli
 
-> A powerful CLI tool for interacting with MCP (Model Context Protocol) servers
+> A CLI-native MCP client that loads tool schemas on-demand and resolves discover-then-call into a single invocation — keeping tool definitions out of your context window.
+
+**One bash command → tool discovery + schema resolution + precise invocation. No persistent tool definitions, no token waste.**
 
 [![Go Version](https://img.shields.io/badge/Go-1.21+-00ADD8?style=flat-square&logo=go)](https://golang.org)
 [![License](https://img.shields.io/badge/License-MIT-green?style=flat-square)](LICENSE)
+[![npm](https://img.shields.io/npm/v/@weibaohui/mcp2cli?style=flat-square)](https://www.npmjs.com/package/@weibaohui/mcp2cli)
 
-## Quick Usage
+## Why mcp2cli?
 
-```bash
-# Install
-go install github.com/weibaohui/mcp2cli@latest
+When an LLM uses MCP tools directly, every call carries heavy overhead:
+- Tool discovery: list tools → read schemas → understand parameters → construct call → parse response
+- Each MCP tool definition (schema, descriptions, types) stays in context, consuming tokens for the **entire conversation**
+- A single "search GitHub and summarize" task can burn thousands of tokens just on protocol overhead
 
-# Rename to mcp for convenience
-mv $(go env GOPATH)/bin/mcp2cli $(go env GOPATH)/bin/mcp
+**mcp2cli compresses that into one bash command:**
 
-# List configured servers (no server connection)
-mcp
-
-# Inspect a server's available tools
-mcp openDeepWiki
-
-# View tool details with parameter examples
-mcp openDeepWiki list_repositories
-
-# Call a tool
-mcp openDeepWiki list_repositories limit=3
+```
+# Direct MCP: 3 rounds, ~2000+ tokens of context
+1. list_tools(server)          → get all tool schemas
+2. get_tool_details(server, tool) → read parameter definitions
+3. call_tool(server, tool, args)  → get result
 
-# Call with typed arguments (recommended)
-mcp openDeepWiki list_repositories limit:number=3 enabled:bool=true
+# mcp2cli: 1 bash call, ~200 tokens
+mcp openDeepWiki get_repo_structure repoOwner=github repoName=vscode
 ```
 
-## Argument Format
+**Result: 80-90% fewer tokens per tool interaction.**
 
-Arguments can be in two formats:
+## Quick Start
 
 ```bash
-# Simple key=value (string type by default)
-mcp server tool name=John age=30
+# Install
+npm install -g @weibaohui/mcp2cli
 
-# Typed key:type=value (recommended for precision)
-mcp server tool name:string=John age:number=30 enabled:bool=true
-```
+# List servers
+mcp
 
-**Supported types:** `string`, `number`, `int`, `float`, `bool`
+# Explore tools on a server
+mcp openDeepWiki
 
----
+# View tool details + param examples
+mcp openDeepWiki get_repo_structure
 
-## Features
+# Call a tool
+mcp openDeepWiki get_repo_structure repoOwner=github repoName=vscode
+```
 
-- **🔍 Discover Servers** - List all configured MCP servers without connecting
-- **📋 Explore Tools** - View detailed tool information with formatted parameters
-- **🚀 Invoke Tools** - Call tools directly with type-safe arguments
-- **🔌 Multiple Transports** - Support for SSE, Streamable HTTP, and Stdio
-- **📁 Smart Config** - Auto-detects and merges configs from standard locations
-- **📤 Unified JSON Output** - Machine-readable output for scripting
+## How It Saves Tokens
 
-## Installation
+### Before: Direct MCP (verbose)
 
-### Binary (latest release)
+Every MCP interaction requires the LLM to maintain tool schemas in context:
 
-Download from [GitHub Releases](https://github.com/weibaohui/mcp2cli/releases/latest)
+```json
+// Tool schema alone = ~500 tokens, stays in EVERY message
+{
+  "name": "get_repo_structure",
+  "description": "Retrieves the complete file and directory structure of a Git repository...",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "repoOwner": {"type": "string", "description": "..."},
+      "repoName": {"type": "string", "description": "..."},
+      ...
+    },
+    "required": ["repoOwner", "repoName"]
+  }
+}
+```
 
-### From source
+Multiply this by **every tool on every server** — a server with 20 tools = ~10,000 tokens permanently in context.
 
-```bash
-go install github.com/weibaohui/mcp2cli@latest
-```
+### After: mcp2cli (lean)
 
-### Build from source
+The LLM only needs a short bash command. No schemas, no tool definitions, no protocol overhead:
 
 ```bash
-git clone https://github.com/weibaohui/mcp2cli.git
-cd mcp2cli
-make build
+# Token cost: just the command string (~30 tokens)
+mcp openDeepWiki get_repo_structure repoOwner=github repoName=vscode
 ```
 
-## Configuration
-
-Create `~/.config/mcp/config.json`:
-
 ```json
+// Output is concise JSON (~100 tokens)
 {
-  "mcpServers": {
-    "openDeepWiki": {
-      "url": "https://opendeepwiki.k8m.site/mcp/streamable",
-      "timeout": 30000
-    }
-  }
+  "success": true,
+  "data": { "server": "openDeepWiki", "method": "get_repo_structure", "result": "..." },
+  "meta": { "timestamp": "2026-03-28T10:00:00Z", "version": "v0.3.0" }
 }
 ```
 
-### Config File Search Paths
+### Token Comparison
+
+| Scenario | Direct MCP | mcp2cli | Saving |
+|----------|-----------|---------|--------|
+| Discover 1 tool | ~500 tokens (schema in context) | ~100 tokens (one bash call) | 80% |
+| Call 1 tool | ~300 tokens (schema + call overhead) | ~130 tokens (command + output) | 57% |
+| 10-tool server in context | ~10,000 tokens (persistent) | 0 tokens (loaded on demand) | 100% |
+| Full workflow (discover + call) | ~2,000 tokens | ~230 tokens | 89% |
 
-| Platform | Priority Order |
-|----------|---------------|
-| macOS/Linux | `~/.config/modelcontextprotocol/mcp.json` → `~/.config/mcp/config.json` → `./mcp.json` → `./.mcp/config.json` → `/etc/mcp/config.json` |
-| Windows | `%APPDATA%\modelcontextprotocol\mcp.json` → `%APPDATA%\mcp\config.json` → `%USERPROFILE%\.mcp\config.json` → `.\mcp.json` → `.\.mcp\config.json` |
+## Usage in Claude Code / Cursor / Windsurf
 
-### Config File Format
+Add to your project's MCP config (e.g. `.mcp/config.json` or `~/.config/mcp/config.json`):
 
 ```json
 {
   "mcpServers": {
-    "serverName": {
-      "transport": "streamable",
-      "url": "https://example.com/mcp",
-      "command": "npx",
-      "args": ["-y", "@server/mcp"],
-      "env": {"KEY": "value"},
-      "timeout": 30000,
-      "headers": {
-        "Authorization": "Bearer ${API_TOKEN}",
-        "X-API-Key": "${API_KEY}"
-      }
+    "openDeepWiki": {
+      "url": "https://opendeepwiki.k8m.site/mcp/streamable"
     }
   }
 }
 ```
 
-### Authentication
+Then in your AI tool, just run bash commands:
 
-**HTTP Headers (API Key / Bearer Token):**
-```json
-{
-  "mcpServers": {
-    "secure-server": {
-      "url": "https://api.example.com/mcp",
-      "headers": {
-        "Authorization": "Bearer ${API_TOKEN}",
-        "X-API-Key": "${API_KEY}"
-      }
-    }
-  }
-}
 ```
+# The LLM can explore and call tools in one step
+$ mcp openDeepWiki list_repositories limit=3
 
-Supports `${VAR}` and `$VAR` environment variable substitution.
+# No need to load tool schemas — just call
+$ mcp openDeepWiki get_repo_structure repoOwner=weibaohui repoName=mcp2cli
+```
 
-**OAuth 2.1 with Static Access Token:**
-```json
-{
-  "mcpServers": {
-    "oauth-server": {
-      "url": "https://api.example.com/mcp",
-      "auth": {
-        "oauth": {
-          "accessToken": "${OAUTH_ACCESS_TOKEN}"
-        }
-      }
-    }
-  }
-}
+## Argument Format
+
+### Simple Arguments (key=value)
+
+```bash
+# Simple key=value (string by default)
+mcp server tool name=John age=30
+
+# Typed key:type=value (for precision)
+mcp server tool name:string=John age:number=30 enabled:bool=true
 ```
 
-**Transport Types:**
-| Type | Description |
-|------|-------------|
-| `streamable` | Modern streaming HTTP (default) |
-| `sse` | Server-Sent Events over HTTP |
-| `stdio` | Local subprocess communication |
+**Supported types:** `string`, `number`, `int`, `float`, `bool`
 
-## Command Reference
+### YAML Input (for complex parameters)
+
+For complex parameters (objects, arrays, multi-line text), use YAML format:
 
 ```bash
-# List all configured servers
-mcp
+# Inline YAML with --yaml or -y
+mcp server tool --yaml 'name: John details: {age: 30, city: NYC}'
+mcp server tool -y 'tags: [dev, ops] enabled: true'
 
-# Get server info with tools list
-mcp <server_name>
+# Multi-line YAML
+mcp server tool --yaml 'limit: 10
+offset: 5
+status: "ready"'
 
-# Get tool details with parameter examples
-mcp <server_name> <tool_name>
+# Read from file (like kubectl apply -f)
+mcp server tool -f params.yaml
 
-# Call a tool with arguments
-mcp <server_name> <tool_name> <key=value> [key2=value2]...
+# Pipe YAML to stdin
+cat params.yaml | mcp server tool
 ```
 
-## Output Format
+**Priority:** `-f` > `--yaml/-y` > stdin pipe > `key=value`
 
-All commands return unified JSON:
+### Output Format
 
-```json
-{
-  "success": true,
-  "data": {
-    "configFiles": ["/home/user/.config/mcp/config.json"],
-    "servers": [
-      {
-        "name": "openDeepWiki",
-        "transport": "streamable",
-        "url": "https://opendeepwiki.k8m.site/mcp/streamable"
-      }
-    ]
-  },
-  "meta": {
-    "timestamp": "2026-03-24T10:00:00Z",
-    "version": "v0.2.8"
-  }
-}
-```
+Control output format with `--output` / `-o`:
+
+```bash
+# JSON (default, human-readable with indentation)
+mcp server tool
 
-## Architecture
+# YAML output
+mcp --output yaml server tool
 
+# Text output (compact JSON, good for piping)
+mcp -o text server tool
 ```
-cmd/mcp/main.go          # CLI entry point, argument routing
-internal/mcp/
-  ├── types.go           # Error codes, shared types
-  ├── config.go          # Config loading & merging
-  ├── config_paths.go    # Platform-specific paths
-  ├── client.go          # MCP server client
-  ├── dispatcher.go      # Multi-server coordination
-  └── formatter.go       # Schema formatting, arg parsing
+
+| Format | Description | Use Case |
+|--------|-------------|----------|
+| `json` | Pretty-printed JSON | Default, debugging |
+| `yaml` | YAML format | Config files, readability |
+| `text` | Compact JSON | Piping, scripts |
+
+## Installation
+
+### npm (recommended)
+
+```bash
+npm install -g @weibaohui/mcp2cli
 ```
 
-## Development
+Supports Linux, macOS, Windows on amd64/arm64. `mcp` command ready immediately.
+
+### Go install
 
 ```bash
-# Build for current platform
-make build
+go install github.com/weibaohui/mcp2cli@latest
+mv $(go env GOPATH)/bin/mcp2cli $(go env GOPATH)/bin/mcp
+```
 
-# Build for all platforms
-make build-all
+### Binary download
 
-# Run tests
-make test
+Download from [GitHub Releases](https://github.com/weibaohui/mcp2cli/releases/latest):
 
-# Lint code
-make lint
+```bash
+# macOS / Linux
+mv mcp2cli-darwin-arm64 mcp && chmod +x mcp && sudo mv mcp /usr/local/bin/
+
+# Windows
+ren mcp2cli-windows-amd64.exe mcp.exe
 ```
 
+## Command Reference
+
+| Command | Description |
+|---------|-------------|
+| `mcp` | List configured servers |
+| `mcp <server>` | List tools on a server |
+| `mcp <server> <tool>` | Show tool details + param examples |
+| `mcp <server> <tool> key=value ...` | Call a tool |
+
+### Global Flags
+
+| Flag | Short | Description | Default |
+|------|-------|-------------|---------|
+| `--output` | `-o` | Output format (json\|yaml\|text) | `json` |
+| `--yaml` | `-y` | YAML parameters (inline) | |
+| `--file` | `-f` | YAML file with parameters | |
+| `--stream` | `-s` | Enable streaming output | `false` |
+
 ## License
 
 MIT License - see [LICENSE](LICENSE) for details.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weibaohui/mcp2cli",
-  "version": "0.2.8",
+  "version": "0.4.0",
   "description": "CLI tool for interacting with MCP (Model Context Protocol) Servers",
   "author": "weibaohui",
   "license": "MIT",
@@ -24,20 +24,19 @@
     "x64",
     "arm64"
   ],
-  "main": "index.js",
   "bin": {
-    "mcp": "./install.js"
+    "mcp": "./run.js"
   },
   "files": [
     "dist/",
-    "index.js",
-    "install.js",
+    "run.js",
+    "postinstall.js",
     "README.md"
   ],
   "engines": {
     "node": ">=18.0.0"
   },
   "scripts": {
-    "postinstall": "node install.js"
+    "postinstall": "node postinstall.js"
   }
 }

package/{install.js → postinstall.js}

@@ -6,14 +6,12 @@ const path = require('path');
 const platform = process.platform;
 const arch = process.arch;
 
-// Map platform names
 const platformMap = {
   'darwin': 'darwin',
   'linux': 'linux',
   'win32': 'windows'
 };
 
-// Map arch names - npm uses x64, Go uses amd64
 const archMap = {
   'x64': 'amd64',
   'arm64': 'arm64'
@@ -29,10 +27,7 @@ if (!npmPlatform || !npmArch) {
 
 const binaryName = `mcp2cli-${npmPlatform}-${npmArch}`;
 const binaryPath = path.join(__dirname, 'dist', binaryName);
-const targetPath = path.join(__dirname, 'mcp2cli');
-
-// Add .exe on Windows
-const exeTargetPath = platform === 'win32' ? targetPath + '.exe' : targetPath;
+const targetPath = path.join(__dirname, platform === 'win32' ? 'mcp2cli.exe' : 'mcp2cli');
 
 if (!fs.existsSync(binaryPath)) {
   console.error(`Binary not found: ${binaryPath}`);
@@ -40,12 +35,8 @@ if (!fs.existsSync(binaryPath)) {
   process.exit(1);
 }
 
-// Copy binary to target location
-fs.copyFileSync(binaryPath, exeTargetPath);
+fs.copyFileSync(binaryPath, targetPath);
 
-// Make executable on Unix systems
 if (platform !== 'win32') {
-  fs.chmodSync(exeTargetPath, 0o755);
+  fs.chmodSync(targetPath, 0o755);
 }
-
-console.log(`Installed mcp2cli ${npmPlatform}/${npmArch} successfully`);

package/run.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+
+const { execFileSync } = require('child_process');
+const path = require('path');
+
+const binary = process.platform === 'win32'
+  ? path.join(__dirname, 'mcp2cli.exe')
+  : path.join(__dirname, 'mcp2cli');
+
+try {
+  execFileSync(binary, process.argv.slice(2), { stdio: 'inherit' });
+} catch (e) {
+  process.exit(e.status || 1);
+}