Merge pull request #30 from mcpc-tech/feature/perfect-cli-ux

feat(cli): bump @mcpc/core to 0.3.6 and overhaul CLI UX

Author: yaonyan

deno.lock

@@ -5,79 +5,108 @@
 
 CLI server for MCPC with configuration support.
 
-> **Note:** This package is published as `@mcpc-tech/cli` on npm and `@mcpc/cli`
-> on JSR.
+> **Note:** Published as `@mcpc-tech/cli` on npm and `@mcpc/cli` on JSR.
 
 ## Quick Start
 
 ```bash
-# Using npm
-npx -y @mcpc-tech/cli --help
+# Install globally (or use npx -y @mcpc-tech/cli instead of mcpc)
+npm install -g @mcpc-tech/cli
 
-# Using JSR
-npx -y deno run -A jsr:@mcpc/cli/bin --help
+# Wrap an existing MCP server and run it immediately
+mcpc --wrap --name "file-manager" \
+  --mcp-stdio "npx -y @wonderwhy-er/desktop-commander"
 
-# Load configuration from URL
-npx -y deno run -A jsr:@mcpc/cli/bin --config-url \
-  "https://raw.githubusercontent.com/mcpc-tech/mcpc/main/packages/cli/examples/configs/codex-fork.json"
-```
-
-## Configuration
+# Add MCP servers to config, then run separately
+mcpc --add --mcp-stdio "npx -y @wonderwhy-er/desktop-commander"
+mcpc  # Loads ~/.mcpc/config.json automatically
 
-Load configuration using command-line arguments:
+# Show help
+mcpc --help
+```
 
-- `--help`, `-h` - Show help message
-- `--config <json>` - Inline JSON configuration string
-- `--config-url <url>` - Fetch from URL (e.g., GitHub raw)
-- `--config-file <path>` - Path to configuration file
-- `--request-headers <header>`, `-H <header>` - Add custom HTTP header for URL
-  fetching (can be used multiple times)
-- No arguments - Uses `./mcpc.config.json` if available
+## Wrapping MCP Servers
 
-## Usage
+The simplest way to use MCPC is to wrap existing MCP servers with custom
+execution modes:
 
-**Show help:**
+### One-time Run (no config saved)
 
 ```bash
-npx -y deno run -A jsr:@mcpc/cli/bin --help
+# Wrap and run a single MCP server
+mcpc --wrap --name "my-file-manager-agent" \
+  --mcp-stdio "npx -y @wonderwhy-er/desktop-commander"
+
+# Wrap multiple servers with different protocols and execution mode
+mcpc --wrap --name "file-and-github-agent" --mode code_execution \
+  --mcp-stdio "npx -y @wonderwhy-er/desktop-commander" \
+  --mcp-http "https://api.github.com/mcp"
 ```
 
-**Inline JSON config:**
+### Persistent Config (save and reuse)
 
 ```bash
-npx -y deno run -A jsr:@mcpc/cli/bin --config '[{"name":"my-agent","description":"..."}]'
-```
+# Step 1: Add servers to config
+mcpc --add --mcp-stdio "npx -y @wonderwhy-er/desktop-commander"
 
-**From URL:**
+# Step 2: (Optional) Edit ~/.mcpc/config.json to add headers, env vars, etc.
 
-```bash
-npx -y deno run -A jsr:@mcpc/cli/bin --config-url https://example.com/config.json
+# Step 3: Run with saved config
+mcpc  # Automatically loads ~/.mcpc/config.json
 ```
 
-**From URL with custom headers:**
+The config file lets you add custom headers, environment variables, and other
+settings:
 
-```bash
-npx -y deno run -A jsr:@mcpc/cli/bin \
-  --config-url https://api.example.com/config.json \
-  -H "Authorization: Bearer token123" \
-  -H "X-Custom-Header: value"
+```json
+{
+  "agents": [{
+    "deps": {
+      "mcpServers": {
+        "github": {
+          "command": "https://api.github.com/mcp",
+          "transportType": "streamable-http",
+          "headers": {
+            "Authorization": "Bearer YOUR_TOKEN"
+          }
+        }
+      }
+    }
+  }]
+}
 ```
 
-**From file:**
+## Configuration Files
+
+Load config from different sources:
 
 ```bash
-npx -y deno run -A jsr:@mcpc/cli/bin --config-file ./my-config.json
-```
+# From a specific file
+mcpc --config-file ./my-config.json
 
-**Default (uses ./mcpc.config.json):**
+# From a URL
+mcpc --config-url https://example.com/config.json
 
-```bash
-npx -y deno run -A jsr:@mcpc/cli/bin
+# From URL with custom headers
+mcpc --config-url https://api.example.com/config.json \
+  -H "Authorization: Bearer token123"
+
+# Inline JSON
+mcpc --config '[{"name":"my-agent","description":"..."}]'
 ```
 
-**Environment variable substitution:**
+### Config Priority Order
+
+1. `--config` (inline JSON)
+2. `MCPC_CONFIG` environment variable
+3. `--config-url` or `MCPC_CONFIG_URL`
+4. `--config-file` or `MCPC_CONFIG_FILE`
+5. `~/.mcpc/config.json` (user config)
+6. `./mcpc.config.json` (local config)
+
+### Environment Variables
 
-Config files support `$ENV_VAR_NAME` syntax:
+Use `$VAR_NAME` syntax in config files:
 
 ```json
 {
@@ -86,7 +115,7 @@ Config files support `$ENV_VAR_NAME` syntax:
       "mcpServers": {
         "github": {
           "headers": {
-            "Authorization": "Bearer $GITHUB_PERSONAL_ACCESS_TOKEN"
+            "Authorization": "Bearer $GITHUB_TOKEN"
           }
         }
       }
@@ -95,14 +124,78 @@ Config files support `$ENV_VAR_NAME` syntax:
 }
 ```
 
-**HTTP server:**
+## HTTP Server
+
+Run as an HTTP server instead of stdio:
+
+```bash
+deno run -A jsr:@mcpc/cli/server --config-file ./my-config.json
+```
+
+## Command Reference
+
+### Main Options
+
+- `--help`, `-h` - Show help message
+- `--add` - Add MCP servers to `~/.mcpc/config.json` and exit
+- `--wrap` - Wrap and run MCP servers immediately (no config saved)
+- `--mcp-stdio <cmd>` - Add stdio MCP server
+- `--mcp-http <url>` - Add HTTP MCP server
+- `--mcp-sse <url>` - Add SSE MCP server
+- `--name <name>` - Custom agent name (default: auto-generated from server
+  names)
+- `--mode <mode>` - Execution mode (default: `agentic`)
+
+### Execution Modes (`--mode`)
+
+MCPC supports different execution modes that control how the agent processes and
+executes tools:
+
+#### `agentic` (default)
+
+Interactive tool execution where the AI agent decides which tools to call and
+when. The agent can make multiple tool calls in a conversation-like flow.
+
+```bash
+mcpc --wrap --mode agentic --name "smart-assistant" \
+  --mcp-stdio "npx -y @wonderwhy-er/desktop-commander"
+```
+
+#### `agentic_workflow`
+
+Structured execution with predefined or runtime-generated steps. The agent
+follows a workflow pattern with specific actions at each step.
 
 ```bash
-npx -y deno run -A jsr:@mcpc/cli/server --config-file ./my-config.json
+mcpc --wrap --mode agentic_workflow --name "workflow-processor" \
+  --mcp-stdio "npx -y @wonderwhy-er/desktop-commander"
 ```
 
+#### `code_execution`
+
+Enables code execution capabilities for running code snippets and scripts
+through the agent.
+
+```bash
+mcpc --wrap --mode code_execution --name "code-runner" \
+  --mcp-stdio "npx -y @wonderwhy-er/desktop-commander"
+```
+
+> **Note:** Different modes may require specific plugins to be available. The
+> `agentic` mode is always available by default.
+
+### Config Options
+
+- `--config <json>` - Inline JSON config
+- `--config-url <url>` - Fetch config from URL
+- `--config-file <path>` - Load config from file
+- `--request-headers <header>`, `-H <header>` - Add HTTP header for URL fetching
+
 ## Examples
 
+See the [examples directory](examples/) for complete working examples using the
+Codex Fork configuration.
+
 ### Required Environment Variables
 
 When using the Codex Fork configuration:

packages/cli/README.md

@@ -1,6 +1,6 @@
 {
   "name": "@mcpc/cli",
-  "version": "0.1.16",
+  "version": "0.1.17",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/mcpc-tech/mcpc.git"
@@ -13,7 +13,7 @@
   },
   "imports": {
     "@mcpc-tech/plugin-code-execution": "npm:@mcpc-tech/plugin-code-execution@^0.0.6",
-    "@mcpc/core": "jsr:@mcpc/core@^0.3.4",
+    "@mcpc/core": "jsr:@mcpc/core@^0.3.6",
     "@mcpc/utils": "jsr:@mcpc/utils@^0.2.2",
     "@modelcontextprotocol/sdk": "npm:@modelcontextprotocol/sdk@^1.8.0",
     "@mcpc-tech/ripgrep-napi": "npm:@mcpc-tech/ripgrep-napi@^0.0.4",