@mcpc-tech/cli 0.1.15 → 0.1.17

package/README.md

@@ -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:

package/bin/mcpc.mjs

@@ -3864,9 +3864,16 @@ var ComposableMCPServer = class extends Server {
     const toolNameToIdMapping = /* @__PURE__ */ new Map();
     const requestedToolNames = /* @__PURE__ */ new Set();
     const availableToolNames = /* @__PURE__ */ new Set();
+    const allPlaceholderUsages = [];
     tagToResults.tool.forEach((tool) => {
       if (tool.attribs.name) {
-        requestedToolNames.add(sanitizePropertyKey(tool.attribs.name));
+        const originalName = tool.attribs.name;
+        const toolName = sanitizePropertyKey(originalName);
+        if (toolName.endsWith(`_${ALL_TOOLS_PLACEHOLDER2}`) || toolName === ALL_TOOLS_PLACEHOLDER2) {
+          allPlaceholderUsages.push(originalName);
+        } else {
+          requestedToolNames.add(toolName);
+        }
       }
     });
     const { tools, cleanupClients } = await composeMcpDepTools(depsConfig, ({ mcpName, toolNameWithScope, toolId }) => {
@@ -3907,6 +3914,14 @@ var ComposableMCPServer = class extends Server {
       }
       availableToolNames.add(toolName);
     });
+    if (allPlaceholderUsages.length > 0) {
+      await this.logger.warning(`Found ${allPlaceholderUsages.length} __ALL__ placeholder(s) for agent "${name}":`);
+      allPlaceholderUsages.forEach((usage) => {
+        this.logger.warning(`   \u2022 "${usage}" - consider using specific tool names`);
+      });
+      const available = Array.from(availableToolNames).sort().join(", ");
+      await this.logger.warning(`   Available tools: ${available}`);
+    }
     const unmatchedTools = Array.from(requestedToolNames).filter((toolName) => !allTools[toolName]);
     if (unmatchedTools.length > 0) {
       await this.logger.warning(`Tool matching warnings for agent "${name}":`);
@@ -4388,8 +4403,9 @@ var createServer = async (config2) => {
 };
 
 // __mcpc__cli_latest/node_modules/@mcpc/cli/src/config/loader.js
-import { readFile } from "node:fs/promises";
-import { resolve as resolve2 } from "node:path";
+import { access, mkdir, readFile, writeFile as writeFile2 } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join as join2, resolve as resolve2 } from "node:path";
 import process7 from "node:process";
 function extractServerName(command, commandArgs) {
   for (const arg of commandArgs) {
@@ -4401,33 +4417,83 @@ function extractServerName(command, commandArgs) {
   const name = command.replace(/[@.,/\\:;!?#$%^&*()[\]{}]/g, "_").substring(0, 64);
   return name || "agentic-tool";
 }
-function createProxyConfig(args) {
-  if (!args.proxyCommand || args.proxyCommand.length === 0) {
-    console.error("Error: --proxy requires a command after --");
-    console.error("Example: mcpc --proxy --transport-type stdio -- npx -y @wonderwhy-er/desktop-commander");
-    process7.exit(1);
+function getUserConfigDir() {
+  return join2(homedir(), ".mcpc");
+}
+function getUserConfigPath() {
+  return join2(getUserConfigDir(), "config.json");
+}
+async function saveUserConfig(config2) {
+  const configPath = getUserConfigPath();
+  const configDir = dirname(configPath);
+  try {
+    let exists = false;
+    try {
+      await access(configPath);
+      exists = true;
+    } catch {
+    }
+    if (exists) {
+      console.error(`
+\u26A0 Configuration file already exists: ${configPath}
+
+  To avoid overwriting your customized settings:
+    1. Use a different output path with --config-file
+    2. Or manually merge the new servers into your existing config
+    3. Or delete the file first: rm ${configPath}
+
+  Skipping save to preserve your existing configuration.
+`);
+      return;
+    }
+    await mkdir(configDir, {
+      recursive: true
+    });
+    await writeFile2(configPath, JSON.stringify(config2, null, 2), "utf-8");
+    console.error(`
+\u2713 Configuration saved to: ${configPath}
+
+  Next steps:
+    1. (Optional) Edit the config to add headers, env vars, etc.
+       Examples:
+         - Add headers: "headers": {"Authorization": "Bearer \${YOUR_TOKEN}"}
+         - Add env vars: "env": {"API_KEY": "\${API_KEY}"}
+    
+    2. Run the server:
+       mcpc
+       
+       The config will be loaded automatically from ${configPath}
+`);
+  } catch (error) {
+    console.error(`Warning: Failed to save config to ${configPath}:`, error);
   }
-  if (!args.transportType) {
-    console.error("Error: --proxy requires --transport-type to be specified");
-    console.error("Supported types: stdio, streamable-http, sse");
-    console.error("Example: mcpc --proxy --transport-type stdio -- npx -y @wonderwhy-er/desktop-commander");
+}
+async function createWrapConfig(args) {
+  if (!args.mcpServers || args.mcpServers.length === 0) {
+    console.error("Error: --wrap/--add requires at least one MCP server");
+    console.error("Example: mcpc --wrap --mcp-stdio 'npx -y @wonderwhy-er/desktop-commander'");
+    console.error("Multiple: mcpc --add --mcp-stdio 'npx -y server1' --mcp-http 'https://api.example.com'");
     process7.exit(1);
   }
-  const validTransports = [
-    "stdio",
-    "streamable-http",
-    "sse"
-  ];
-  if (!validTransports.includes(args.transportType)) {
-    console.error(`Error: Invalid transport type '${args.transportType}'`);
-    console.error(`Supported types: ${validTransports.join(", ")}`);
-    process7.exit(1);
+  const mcpServers = {};
+  const serverNames = [];
+  const refs = [];
+  for (const spec of args.mcpServers) {
+    const serverName = extractServerName(spec.command, spec.args);
+    mcpServers[serverName] = {
+      command: spec.command,
+      args: spec.args,
+      transportType: spec.transportType
+    };
+    serverNames.push(serverName);
+    refs.push(`<tool name="${serverName}.__ALL__"/>`);
+    console.error(`Added MCP server: ${serverName}
+  Transport: ${spec.transportType}
+  Command: ${spec.command} ${spec.args.join(" ")}`);
   }
-  const command = args.proxyCommand[0];
-  const commandArgs = args.proxyCommand.slice(1);
-  const serverName = args.name || extractServerName(command, commandArgs);
+  const agentName = args.name || `${serverNames.join("__")}--orchestrator`;
   const config2 = {
-    name: `${serverName}-proxy`,
+    name: "mcpc-wrap-config",
     version: "0.1.0",
     capabilities: {
       tools: {},
@@ -4435,31 +4501,24 @@ function createProxyConfig(args) {
     },
     agents: [
       {
-        name: serverName,
-        description: `Orchestrate ${serverName} MCP server tools`,
+        name: agentName,
+        description: `Orchestrate ${serverNames.length === 1 ? serverNames[0] : serverNames.join(", ")} MCP server tools`,
         deps: {
-          mcpServers: {
-            [serverName]: {
-              command,
-              args: commandArgs,
-              transportType: args.transportType
-            }
-          }
+          mcpServers
         },
         options: {
           mode: args.mode || "agentic",
-          refs: [
-            `<tool name="${serverName}.__ALL__"/>`
-          ]
+          refs
         }
       }
     ]
   };
-  console.error(`Created proxy configuration for ${serverName}`);
-  console.error(`Transport: ${args.transportType}`);
-  console.error(`Command: ${command} ${commandArgs.join(" ")}`);
-  if (args.mode) {
-    console.error(`Mode: ${args.mode}`);
+  const modeInfo = args.mode ? `
+Mode: ${args.mode}` : "";
+  console.error(`
+Created wrap configuration for ${serverNames.length} MCP server(s)${modeInfo}`);
+  if (args.saveConfig) {
+    await saveUserConfig(config2);
   }
   return config2;
 }
@@ -4486,12 +4545,18 @@ OPTIONS:
                            - agentic_sampling: Autonomous sampling mode for agentic execution
                            - agentic_workflow_sampling: Autonomous sampling mode for workflow execution
                            - code_execution: Code execution mode for most efficient token usage
-    --proxy                 Proxy mode: automatically configure MCPC to wrap an MCP server
-                           Use with --transport-type to specify the transport
-                           Example: --proxy --transport-type stdio -- npx -y @wonderwhy-er/desktop-commander
-    --transport-type <type> Transport type for proxy mode
-                           Supported types: stdio, streamable-http, sse
-    --name <name>           Custom server name for proxy mode (overrides auto-detection)
+    --add                   Add MCP servers to ~/.mcpc/config.json and exit
+                           Then run 'mcpc' to start the server with saved config
+                           Use --mcp-stdio, --mcp-http, or --mcp-sse to specify servers
+    --wrap                  Wrap and run MCP servers immediately without saving config
+                           Use --mcp-stdio, --mcp-http, or --mcp-sse to specify servers
+    --mcp-stdio <cmd>       Add an MCP server with stdio transport
+                           Example: --mcp-stdio "npx -y @wonderwhy-er/desktop-commander"
+    --mcp-http <url>        Add an MCP server with streamable-http transport
+                           Example: --mcp-http "https://api.github.com/mcp"
+    --mcp-sse <url>         Add an MCP server with SSE transport
+                           Example: --mcp-sse "https://api.example.com/sse"
+    --name <name>           Custom agent name for wrap mode (overrides auto-detection)
 
 ENVIRONMENT VARIABLES:
     MCPC_CONFIG            Inline JSON configuration (same as --config)
@@ -4502,17 +4567,20 @@ EXAMPLES:
     # Show help
     mcpc --help
 
-    # Proxy mode - wrap an existing MCP server (stdio)
-    mcpc --proxy --transport-type stdio -- npx -y @wonderwhy-er/desktop-commander
+    # Add MCP servers to config and save to ~/.mcpc/config.json
+    mcpc --add --mcp-stdio "npx -y @wonderwhy-er/desktop-commander"
+    # Edit ~/.mcpc/config.json if needed (add headers, etc.)
+    mcpc  # Loads config from ~/.mcpc/config.json automatically
 
-    # Proxy mode with custom server name
-    mcpc --proxy --transport-type stdio --name my-server -- npx shadcn@latest mcp
+    # Wrap and run immediately (one-time use, no config saved)
+    mcpc --wrap --mcp-stdio "npx -y @wonderwhy-er/desktop-commander"
 
-    # Proxy mode - wrap an MCP server (streamable-http)
-    mcpc --proxy --transport-type streamable-http -- https://api.example.com/mcp
+    # Multiple servers with different transports
+    mcpc --add       --mcp-stdio "npx -y @wonderwhy-er/desktop-commander"       --mcp-http "https://api.github.com/mcp"       --mcp-sse "https://api.example.com/sse"
 
-    # Proxy mode - wrap an MCP server (sse)
-    mcpc --proxy --transport-type sse -- https://api.example.com/sse
+    # Custom agent name
+    mcpc --add --name my-agent --mcp-stdio "npx shadcn@latest mcp"
+    mcpc --wrap --name my-agent --mcp-stdio "npx shadcn@latest mcp"
 
     # Load from URL
     mcpc --config-url \\
@@ -4576,17 +4644,35 @@ function parseArgs() {
       }
     } else if (arg === "--help" || arg === "-h") {
       result.help = true;
-    } else if (arg === "--proxy") {
-      result.proxy = true;
-    } else if (arg === "--transport-type" && i + 1 < args.length) {
-      result.transportType = args[++i];
+    } else if (arg === "--add") {
+      result.add = true;
+    } else if (arg === "--wrap") {
+      result.wrap = true;
+    } else if ((arg === "--mcp-stdio" || arg === "--mcp-http" || arg === "--mcp-sse") && i + 1 < args.length) {
+      const cmdString = args[++i];
+      const cmdParts = cmdString.split(/\s+/);
+      const command = cmdParts[0];
+      const cmdArgs = cmdParts.slice(1);
+      let transportType;
+      if (arg === "--mcp-stdio") {
+        transportType = "stdio";
+      } else if (arg === "--mcp-http") {
+        transportType = "streamable-http";
+      } else {
+        transportType = "sse";
+      }
+      if (!result.mcpServers) {
+        result.mcpServers = [];
+      }
+      result.mcpServers.push({
+        command,
+        args: cmdArgs,
+        transportType
+      });
     } else if (arg === "--mode" && i + 1 < args.length) {
       result.mode = args[++i];
     } else if (arg === "--name" && i + 1 < args.length) {
       result.name = args[++i];
-    } else if (arg === "--") {
-      result.proxyCommand = args.slice(i + 1);
-      break;
     }
   }
   return result;
@@ -4597,8 +4683,18 @@ async function loadConfig() {
     printHelp();
     process7.exit(0);
   }
-  if (args.proxy) {
-    return createProxyConfig(args);
+  if (args.add) {
+    await createWrapConfig({
+      ...args,
+      saveConfig: true
+    });
+    process7.exit(0);
+  }
+  if (args.wrap) {
+    return await createWrapConfig({
+      ...args,
+      saveConfig: false
+    });
   }
   if (args.config) {
     try {
@@ -4655,6 +4751,17 @@ async function loadConfig() {
       }
     }
   }
+  const userConfigPath = getUserConfigPath();
+  try {
+    const content = await readFile(userConfigPath, "utf-8");
+    const parsed = JSON.parse(content);
+    return applyModeOverride(normalizeConfig(parsed), args.mode);
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      console.error(`Failed to load config from ${userConfigPath}:`, error);
+      throw error;
+    }
+  }
   const defaultConfigPath = resolve2(process7.cwd(), "mcpc.config.json");
   try {
     const content = await readFile(defaultConfigPath, "utf-8");

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@mcpc-tech/cli",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "homepage": "https://jsr.io/@mcpc/cli",
   "type": "module",
   "dependencies": {
     "@hono/zod-openapi": "^0.19.2",
-    "@mcpc-tech/plugin-code-execution": "^0.0.5",
+    "@mcpc-tech/plugin-code-execution": "^0.0.6",
     "@modelcontextprotocol/sdk": "^1.8.0",
     "zod": "^3.24.2",
     "@mcpc-tech/ripgrep-napi": "^0.0.4",

package/types/src/config/loader.d.ts

@@ -19,7 +19,8 @@
  * 2. MCPC_CONFIG environment variable
  * 3. --config-url or MCPC_CONFIG_URL
  * 4. --config-file or MCPC_CONFIG_FILE
- * 5. ./mcpc.config.json (default)
+ * 5. ~/.mcpc/config.json (user config)
+ * 6. ./mcpc.config.json (local config)
  *
  * @example
  * ```bash

package/types/src/config/loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loader.d.ts","sources":["../../../src/config/loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2CC,GAED,cAAc,iBAAiB,0BAAgC;AAK/D,iBAAiB;EACf;;GAEC,GACD,OAAO,MAAM;EACb;;GAEC,GACD,UAAU,MAAM;EAChB;;GAEC,GACD;IACE,QAAQ,OAAO,MAAM,EAAE,OAAO;IAC9B,WAAW,OAAO,MAAM,EAAE,OAAO;;EAEnC;;GAEC,GACD,QAAQ;;AAqRV;;;CAGC,GACD,OAAO,iBAAe,cAAc,QAAQ,aAAa,IAAI;AAqL7D;;CAEC,GACD,OAAO,iBAAS,eAAe,QAAQ,UAAU,GAAG,IAAI"}
+{"version":3,"file":"loader.d.ts","sources":["../../../src/config/loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4CC,GAED,cAAc,iBAAiB,0BAAgC;AAM/D,iBAAiB;EACf;;GAEC,GACD,OAAO,MAAM;EACb;;GAEC,GACD,UAAU,MAAM;EAChB;;GAEC,GACD;IACE,QAAQ,OAAO,MAAM,EAAE,OAAO;IAC9B,WAAW,OAAO,MAAM,EAAE,OAAO;;EAEnC;;GAEC,GACD,QAAQ;;AAmYV;;;CAGC,GACD,OAAO,iBAAe,cAAc,QAAQ,aAAa,IAAI;AAyM7D;;CAEC,GACD,OAAO,iBAAS,eAAe,QAAQ,UAAU,GAAG,IAAI"}