@weibaohui/mcp2cli 0.3.0 → 0.4.0

package/README.md

@@ -1,265 +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
-
-```bash
-# Install via npm (recommended)
-npm install -g @weibaohui/mcp2cli
-
-# Or install via Go
-go install github.com/weibaohui/mcp2cli@latest
-
-# Rename to mcp for convenience
-mv $(go env GOPATH)/bin/mcp2cli $(go env GOPATH)/bin/mcp
-
-# List configured servers (no server connection)
-mcp
+## Why mcp2cli?
 
-# Inspect a server's available tools
-mcp openDeepWiki
+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
 
-# View tool details with parameter examples
-mcp openDeepWiki list_repositories
+**mcp2cli compresses that into one bash command:**
 
-# Call a tool
-mcp openDeepWiki list_repositories limit=3
-
-# Call with typed arguments (recommended)
-mcp openDeepWiki list_repositories limit:number=3 enabled:bool=true
 ```
+# 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
 
-## Argument Format
-
-Arguments can be in two formats:
-
-```bash
-# Simple key=value (string type by default)
-mcp server tool name=John age=30
-
-# Typed key:type=value (recommended for precision)
-mcp server tool name:string=John age:number=30 enabled:bool=true
+# mcp2cli: 1 bash call, ~200 tokens
+mcp openDeepWiki get_repo_structure repoOwner=github repoName=vscode
 ```
 
-**Supported types:** `string`, `number`, `int`, `float`, `bool`
-
----
-
-## Features
+**Result: 80-90% fewer tokens per tool interaction.**
 
-- **🔍 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
-
-## Installation
-
-### npm (multi-platform) - recommended
+## Quick Start
 
 ```bash
+# Install
 npm install -g @weibaohui/mcp2cli
-```
 
-Supports Linux, macOS, Windows on amd64/arm64. 安装后直接使用 `mcp` 命令，无需额外操作。
+# List servers
+mcp
 
-### Go install
+# Explore tools on a server
+mcp openDeepWiki
 
-```bash
-go install github.com/weibaohui/mcp2cli@latest
+# View tool details + param examples
+mcp openDeepWiki get_repo_structure
 
-# Rename to mcp for convenience
-mv $(go env GOPATH)/bin/mcp2cli $(go env GOPATH)/bin/mcp
+# Call a tool
+mcp openDeepWiki get_repo_structure repoOwner=github repoName=vscode
 ```
 
-安装后可执行文件名为 `mcp2cli`，需手动重命名为 `mcp`：
+## How It Saves Tokens
 
-```bash
-mv $(go env GOPATH)/bin/mcp2cli $(go env GOPATH)/bin/mcp
-```
+### Before: Direct MCP (verbose)
 
-### Binary download
+Every MCP interaction requires the LLM to maintain tool schemas in context:
 
-Download from [GitHub Releases](https://github.com/weibaohui/mcp2cli/releases/latest), then rename and install：
+```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"]
+  }
+}
+```
 
-```bash
-# macOS / Linux
-mv mcp2cli-darwin-arm64 mcp
-chmod +x mcp
-sudo mv mcp /usr/local/bin/
+Multiply this by **every tool on every server** — a server with 20 tools = ~10,000 tokens permanently in context.
 
-# Windows
-ren mcp2cli-windows-amd64.exe mcp.exe
-```
+### 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
-cp bin/mcp2cli /usr/local/bin/mcp
+# 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
 
-| 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` |
+| 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% |
 
-### Config File Format
+## Usage in Claude Code / Cursor / Windsurf
+
+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`
+
+### YAML Input (for complex parameters)
 
-## Command Reference
+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`:
 
-## Architecture
+```bash
+# JSON (default, human-readable with indentation)
+mcp server tool
+
+# YAML output
+mcp --output yaml server tool
 
+# Text output (compact JSON, good for piping)
+mcp -o text server tool
 ```
-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.3.0",
+  "version": "0.4.0",
   "description": "CLI tool for interacting with MCP (Model Context Protocol) Servers",
   "author": "weibaohui",
   "license": "MIT",