@tronsfey/ucli 0.5.0 → 0.5.2

package/README.md

@@ -172,6 +172,8 @@ ucli run --service <name> --operation <operationId> [options]
 | `--params` | No | JSON string of parameters (path, query, body merged) |
 | `--format` | No | Output format: `json` (default), `table`, `yaml` |
 | `--query` | No | JMESPath expression to filter the response |
+| `--machine` | No | Structured JSON envelope output (agent-friendly) |
+| `--dry-run` | No | Preview the HTTP request without executing (implies `--machine`) |
 
 **Examples:**
 
@@ -193,6 +195,13 @@ ucli run --service inventory --operation listProducts \
 # POST with data from file
 ucli run --service crm --operation createContact \
   --params "@./contact.json"
+
+# Agent-friendly structured output
+ucli run --service payments --operation listTransactions --machine
+
+# Preview request without executing
+ucli run --service payments --operation createPayment --dry-run \
+  --data '{"amount": 5000, "currency": "USD"}'
 ```
 
 ---
@@ -226,6 +235,32 @@ ucli mcp tools <server-name> [--format table|json]
 
 ---
 
+### `mcp describe <server> <tool>`
+
+Show detailed parameter schema for a tool on a MCP server.
+
+```bash
+ucli mcp describe <server-name> <tool-name> [--json]
+```
+
+| Argument/Flag | Description |
+|---------------|-------------|
+| `<server-name>` | MCP server name from `mcp list` |
+| `<tool-name>` | Tool name from `mcp tools` |
+| `--json` | Output full schema as JSON (for agent consumption) |
+
+**Examples:**
+
+```bash
+# Human-readable tool description
+ucli mcp describe weather get_forecast
+
+# JSON schema (for agent introspection)
+ucli mcp describe weather get_forecast --json
+```
+
+---
+
 ### `mcp run <server> <tool> [args...]`
 
 Execute a tool on an MCP server.
@@ -234,16 +269,27 @@ Execute a tool on an MCP server.
 ucli mcp run <server-name> <tool-name> [args...]
 ```
 
-Args are passed as `key=value` pairs and converted to a JSON object.
+Args are passed as `key=value` pairs and converted to a JSON object, or use `--input-json` for direct JSON input.
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Machine-readable JSON output |
+| `--input-json` | Pass tool arguments as a JSON object (preferred for agents) |
 
 **Examples:**
 
 ```bash
-# Call a weather tool
+# Call a weather tool with key=value args
 ucli mcp run weather get_forecast location="New York" units=metric
 
 # Call a search tool
 ucli mcp run search-server web_search query="ucli MCP" limit=5
+
+# Call with JSON input (preferred for agents)
+ucli mcp run weather get_forecast --input-json '{"location": "New York", "units": "metric"}'
+
+# Get structured JSON output
+ucli mcp run weather get_forecast --json location="New York"
 ```
 
 ---
@@ -314,23 +360,35 @@ ucli services list --format json
 # Step 2: Inspect a service to see available operations
 ucli services info <service-name> --format json
 
-# Step 3: Execute an operation
+# Step 3: Preview a request (dry-run — no execution)
+ucli run --service <name> --operation <operationId> --dry-run \
+  --params '{ ... }'
+
+# Step 4: Execute an operation with structured output
 ucli run --service <name> --operation <operationId> \
-  --params '{ ... }' --format json
+  --params '{ ... }' --machine
 
-# Step 4: Filter results with JMESPath
+# Step 5: Filter results with JMESPath
 ucli run --service inventory --operation listProducts \
   --query 'items[?inStock == `true`] | [0:5]'
 
-# Step 5: Chain operations (use output from one as input to another)
+# Step 6: Chain operations (use output from one as input to another)
 PRODUCT_ID=$(ucli run --service inventory --operation listProducts \
   --query 'items[0].id' | tr -d '"')
 ucli run --service orders --operation createOrder \
   --params "{\"productId\": \"$PRODUCT_ID\", \"quantity\": 1}"
+
+# Step 7: MCP — describe a tool, then call it with JSON input
+ucli mcp describe weather get_forecast --json
+ucli mcp run weather get_forecast --input-json '{"location": "New York", "units": "metric"}'
 ```
 
 **Tips for agents:**
 - Always run `services list` first to discover what's available
+- Use `--machine` for structured envelope output from API operations
+- Use `--dry-run` to preview requests before executing destructive operations
+- Use `mcp describe <server> <tool> --json` to discover tool parameters
+- Use `--input-json` for MCP tool calls (more reliable than `key=value` for complex args)
 - Use `--format json` for programmatic parsing
 - Use `--query` with JMESPath to extract specific fields
 - Check pagination fields (`nextPage`, `totalCount`) for list operations

package/README.zh.md

@@ -172,6 +172,8 @@ ucli run --service <name> --operation <operationId> [选项]
 | `--params` | 否 | JSON 字符串（路径参数、查询参数、请求体合并传入） |
 | `--format` | 否 | 输出格式：`json`（默认）、`table`、`yaml` |
 | `--query` | 否 | JMESPath 表达式，用于过滤响应 |
+| `--machine` | 否 | 结构化 JSON 信封输出（Agent 友好模式） |
+| `--dry-run` | 否 | 预览 HTTP 请求但不执行（隐含 `--machine`） |
 
 **示例：**
 
@@ -193,6 +195,13 @@ ucli run --service inventory --operation listProducts \
 # 从文件读取参数
 ucli run --service crm --operation createContact \
   --params "@./contact.json"
+
+# Agent 友好结构化输出
+ucli run --service payments --operation listTransactions --machine
+
+# 预览请求但不执行
+ucli run --service payments --operation createPayment --dry-run \
+  --data '{"amount": 5000, "currency": "CNY"}'
 ```
 
 ---
@@ -217,6 +226,32 @@ ucli mcp tools <server-name> [--format table|json]
 
 ---
 
+### `mcp describe <server> <tool>`
+
+查看 MCP 服务器上指定工具的详细参数模式。
+
+```bash
+ucli mcp describe <server-name> <tool-name> [--json]
+```
+
+| 参数 | 说明 |
+|------|------|
+| `<server-name>` | MCP 服务器名称（来自 `mcp list`） |
+| `<tool-name>` | 工具名称（来自 `mcp tools`） |
+| `--json` | 以 JSON 格式输出完整模式（适合 Agent 消费） |
+
+**示例：**
+
+```bash
+# 人类可读的工具描述
+ucli mcp describe weather get_forecast
+
+# JSON 模式（适合 Agent 内省）
+ucli mcp describe weather get_forecast --json
+```
+
+---
+
 ### `mcp run <server> <tool> [args...]`
 
 在 MCP 服务器上执行指定工具。
@@ -225,7 +260,12 @@ ucli mcp tools <server-name> [--format table|json]
 ucli mcp run <server-name> <tool-name> [args...]
 ```
 
-参数以 `key=value` 形式传入。
+参数以 `key=value` 形式传入，或使用 `--input-json` 直接传入 JSON 对象。
+
+| 参数 | 说明 |
+|------|------|
+| `--json` | 结构化 JSON 输出 |
+| `--input-json` | 以 JSON 对象形式传入工具参数（Agent 推荐） |
 
 **示例：**
 
@@ -235,6 +275,12 @@ ucli mcp run weather get_forecast location="北京" units=metric
 
 # 调用搜索工具
 ucli mcp run search-server web_search query="ucli MCP" limit=5
+
+# 以 JSON 输入调用（Agent 推荐）
+ucli mcp run weather get_forecast --input-json '{"location": "北京", "units": "metric"}'
+
+# 获取结构化 JSON 输出
+ucli mcp run weather get_forecast --json location="北京"
 ```
 
 ---
@@ -305,23 +351,35 @@ ucli services list --format json
 # 第二步：查看服务支持的操作
 ucli services info <service-name> --format json
 
-# 第三步：执行操作
+# 第三步：预览请求（dry-run，不执行）
+ucli run --service <name> --operation <operationId> --dry-run \
+  --params '{ ... }'
+
+# 第四步：执行操作并获取结构化输出
 ucli run --service <name> --operation <operationId> \
-  --params '{ ... }' --format json
+  --params '{ ... }' --machine
 
-# 第四步：用 JMESPath 过滤结果
+# 第五步：用 JMESPath 过滤结果
 ucli run --service inventory --operation listProducts \
   --query 'items[?inStock == `true`] | [0:5]'
 
-# 第五步：链式操作（将前一个结果作为下一个的输入）
+# 第六步：链式操作（将前一个结果作为下一个的输入）
 PRODUCT_ID=$(ucli run --service inventory --operation listProducts \
   --query 'items[0].id' | tr -d '"')
 ucli run --service orders --operation createOrder \
   --params "{\"productId\": \"$PRODUCT_ID\", \"quantity\": 1}"
+
+# 第七步：MCP — 查看工具参数模式，然后以 JSON 输入调用
+ucli mcp describe weather get_forecast --json
+ucli mcp run weather get_forecast --input-json '{"location": "北京", "units": "metric"}'
 ```
 
 **智能体使用建议：**
 - 始终先运行 `services list` 发现可用服务
+- 使用 `--machine` 获取结构化信封输出
+- 使用 `--dry-run` 预览请求，避免误操作
+- 使用 `mcp describe <server> <tool> --json` 发现工具参数模式
+- 使用 `--input-json` 调用 MCP 工具（适合复杂或嵌套参数）
 - 使用 `--format json` 方便程序解析
 - 使用 `--query` 配合 JMESPath 提取特定字段
 - 注意列表操作的分页字段（`nextPage`、`totalCount`）

package/dist/{client-3I7XBDJU.js → client-Y6NONDCI.js}

@@ -36662,9 +36662,97 @@ var require_streamableHttp = __commonJS({
   }
 });
 
-// ../../node_modules/.pnpm/@tronsfey+mcp2cli@1.0.1_zod@4.3.6/node_modules/@tronsfey/mcp2cli/dist/client/index.js
+// ../../node_modules/.pnpm/@tronsfey+mcp2cli@1.3.0_zod@4.3.6/node_modules/@tronsfey/mcp2cli/package.json
+var require_package = __commonJS({
+  "../../node_modules/.pnpm/@tronsfey+mcp2cli@1.3.0_zod@4.3.6/node_modules/@tronsfey/mcp2cli/package.json"(exports, module) {
+    module.exports = {
+      name: "@tronsfey/mcp2cli",
+      version: "1.3.0",
+      description: "Command-line proxy for any MCP server \u2014 call tools directly from the terminal",
+      main: "dist/index.js",
+      bin: {
+        mcp2cli: "./bin/mcp2cli",
+        ucli: "./bin/mcp2cli"
+      },
+      files: [
+        "dist/",
+        "bin/",
+        "CLAUDE.md",
+        "README.md",
+        "LICENSE"
+      ],
+      keywords: [
+        "mcp",
+        "model-context-protocol",
+        "cli",
+        "proxy",
+        "commander",
+        "typescript",
+        "ai",
+        "tools"
+      ],
+      author: "",
+      license: "MIT",
+      repository: {
+        type: "git",
+        url: "https://github.com/tronsfey928/mcp2cli.git"
+      },
+      homepage: "https://github.com/tronsfey928/mcp2cli#readme",
+      bugs: {
+        url: "https://github.com/tronsfey928/mcp2cli/issues"
+      },
+      engines: {
+        node: ">=18"
+      },
+      scripts: {
+        build: "tsc",
+        dev: "ts-node src/index.ts",
+        start: "node dist/index.js",
+        test: "jest --testPathIgnorePatterns=tests/integration",
+        "test:coverage": "jest --coverage --testPathIgnorePatterns=tests/integration",
+        "test:e2e": "npm run build && jest --testPathPattern=tests/integration --testTimeout=30000 --runInBand --forceExit",
+        lint: "tsc --noEmit",
+        clean: "rm -rf dist",
+        prepublishOnly: "npm run lint && npm test && npm run build"
+      },
+      dependencies: {
+        "@modelcontextprotocol/sdk": "^1.0.0",
+        chalk: "^4.1.2",
+        commander: "^12.1.0",
+        "fs-extra": "^11.2.0",
+        jmespath: "^0.16.0",
+        ora: "^5.4.1"
+      },
+      devDependencies: {
+        "@modelcontextprotocol/server-filesystem": "^2026.1.14",
+        "@types/express": "^4.17.25",
+        "@types/fs-extra": "^11.0.4",
+        "@types/jest": "^29.5.14",
+        "@types/jmespath": "^0.15.2",
+        "@types/node": "^22.0.0",
+        jest: "^29.7.0",
+        "ts-jest": "^29.4.0",
+        "ts-node": "^10.9.2",
+        typescript: "^5.7.3",
+        zod: "^3.25.76"
+      },
+      jest: {
+        preset: "ts-jest",
+        testEnvironment: "node",
+        testMatch: [
+          "**/tests/**/*.test.ts"
+        ],
+        collectCoverageFrom: [
+          "src/**/*.ts"
+        ]
+      }
+    };
+  }
+});
+
+// ../../node_modules/.pnpm/@tronsfey+mcp2cli@1.3.0_zod@4.3.6/node_modules/@tronsfey/mcp2cli/dist/client/index.js
 var require_client3 = __commonJS({
-  "../../node_modules/.pnpm/@tronsfey+mcp2cli@1.0.1_zod@4.3.6/node_modules/@tronsfey/mcp2cli/dist/client/index.js"(exports) {
+  "../../node_modules/.pnpm/@tronsfey+mcp2cli@1.3.0_zod@4.3.6/node_modules/@tronsfey/mcp2cli/dist/client/index.js"(exports) {
     Object.defineProperty(exports, "__esModule", { value: true });
     exports.parseCommand = parseCommand;
     exports.isTransportUnsupported = isTransportUnsupported;
@@ -36673,6 +36761,7 @@ var require_client3 = __commonJS({
     var stdio_js_1 = require_stdio2();
     var sse_js_1 = require_sse();
     var streamableHttp_js_1 = require_streamableHttp();
+    var pkg = require_package();
     function parseCommand(cmdString) {
       const parts = [];
       let current = "";
@@ -36698,13 +36787,16 @@ var require_client3 = __commonJS({
       if (inSingle || inDouble) {
         throw new Error(`Unclosed quote in command: ${cmdString}`);
       }
+      if (parts.length === 0) {
+        throw new Error("Empty command string");
+      }
       const [command, ...args] = parts;
       return { command, args };
     }
     function makeClient() {
       return new index_js_1.Client({
         name: "mcp2cli",
-        version: "1.0.0"
+        version: pkg.version
       });
     }
     function isTransportUnsupported(err) {
@@ -36724,11 +36816,14 @@ var require_client3 = __commonJS({
           ...Object.fromEntries(Object.entries(process.env).filter(([, v]) => v !== void 0)),
           ...config.env ?? {}
         };
+        if (verbose) {
+          console.error(`[debug] Connecting via stdio: ${command} ${args.join(" ")}`);
+        }
         const client2 = makeClient();
         const transport = new stdio_js_1.StdioClientTransport({ command, args, env });
         await client2.connect(transport);
         if (verbose) {
-          console.error(`[mcp2cli] Connected via stdio: ${config.command}`);
+          console.error(`[debug] Connected via stdio successfully`);
         }
         return client2;
       }
@@ -36737,6 +36832,9 @@ var require_client3 = __commonJS({
       }
       const serverUrl = new URL(config.url);
       const headers = config.headers ?? {};
+      if (verbose) {
+        console.error(`[debug] Attempting Streamable HTTP connection to ${config.url}`);
+      }
       try {
         const client2 = makeClient();
         const transport = new streamableHttp_js_1.StreamableHTTPClientTransport(serverUrl, {
@@ -36744,28 +36842,34 @@ var require_client3 = __commonJS({
         });
         await client2.connect(transport);
         if (verbose) {
-          console.error(`[mcp2cli] Connected via Streamable HTTP: ${config.url}`);
+          console.error(`[debug] Connected via Streamable HTTP successfully`);
         }
         return client2;
       } catch (err) {
+        if (verbose) {
+          console.error(`[debug] Streamable HTTP failed: ${err.message}`);
+        }
         if (!isTransportUnsupported(err)) {
           throw err;
         }
         if (verbose) {
-          console.error(`[mcp2cli] Streamable HTTP not supported, falling back to SSE`);
+          console.error(`[debug] Falling back to SSE transport\u2026`);
         }
       }
+      if (verbose) {
+        console.error(`[debug] Attempting SSE connection to ${config.url}`);
+      }
       const client = makeClient();
       const sseTransport = new sse_js_1.SSEClientTransport(serverUrl, {
         requestInit: { headers }
       });
       await client.connect(sseTransport);
       if (verbose) {
-        console.error(`[mcp2cli] Connected via SSE: ${config.url}`);
+        console.error(`[debug] Connected via SSE successfully`);
       }
       return client;
     }
   }
 });
 export default require_client3();
-//# sourceMappingURL=client-3I7XBDJU.js.map
+//# sourceMappingURL=client-Y6NONDCI.js.map