# MCPBundles CLI

**Connect AI to 500+ tools from the command line.**

The `mcpbundles` CLI provides full MCP (Model Context Protocol) access to the [MCPBundles](https://mcpbundles.com) platform — tool discovery, execution, interactive shell, AI agent integration, and a desktop proxy tunnel for local services.

## Features

- **Hub MCP access** — discover and call 500+ tools directly from your terminal
- **Interactive shell** — REPL with tab completion, command history, and live connection switching
- **Multi-connection support** — connect to Hub, individual bundles, or different workspaces simultaneously
- **Aggregated local proxy** — expose multiple connections as a single unauthenticated MCP endpoint
- **AI agent integration** — generate tool manifests for AI coding agents
- **Code execution** — run sandboxed code with `--stream` for progressive output
- **Desktop proxy tunnel** — securely forward cloud requests to local services (databases, browsers, APIs)
- **Rich terminal output** — tables, syntax highlighting, JSON, streaming, and `NO_COLOR` support
- **Multiple auth methods** — OAuth2 PKCE (browser) or API key (CI/CD)
- **Shell completion** — dynamic tab completion for bash, zsh, and fish

## Installation

```bash
pip install mcpbundles
```

## Quick Start

```bash
# Authenticate (opens browser)
mcpbundles login

# Or use an API key (CI/CD, headless)
mcpbundles login --api-key mb_your_key_here

# List available tools
mcpbundles tools

# Get full schema for a tool
mcpbundles tools code_execution

# Call a tool
mcpbundles call get-contacts limit=10

# Execute code
mcpbundles exec "result = 2 + 2; print(result)"

# Execute from file with streaming output
mcpbundles exec -f script.py --stream

# Start interactive shell
mcpbundles shell
```

## Commands

### Auth & Identity

| Command | Description |
|---------|-------------|
| `mcpbundles login` | Authenticate via browser (OAuth2 PKCE) |
| `mcpbundles login --api-key mb_...` | API key auth (headless/CI) |
| `mcpbundles logout` | Remove stored credentials |
| `mcpbundles whoami` | Show current user, workspace, and server |

### Tool Discovery (always live from server)

| Command | Description |
|---------|-------------|
| `mcpbundles tools` | List all available MCP tools |
| `mcpbundles tools <name>` | Show full schema for a specific tool |
| `mcpbundles tools -f <keyword>` | Filter tools by name or description |
| `mcpbundles tools --json` | JSON output for piping |
| `mcpbundles resources` | List available MCP resources |
| `mcpbundles prompts` | List available MCP prompts |

### Tool Execution

| Command | Description |
|---------|-------------|
| `mcpbundles call <tool> key=value` | Call a tool with typed arguments |
| `mcpbundles call <tool> key:=true` | JSON-typed argument (bool, number, array) |
| `mcpbundles call <tool> -f data.json` | Arguments from JSON file |
| `mcpbundles read <uri>` | Read an MCP resource |
| `mcpbundles prompt <name> key=value` | Get an MCP prompt |
| `mcpbundles exec "code"` | Execute code (shortcut for code_execution) |
| `mcpbundles exec -f script.py` | Execute code from file |
| `mcpbundles exec -f script.py --stream` | Stream output line-by-line |

### Named Connections

| Command | Description |
|---------|-------------|
| `mcpbundles connect --as hub` | Connect to Hub (default) |
| `mcpbundles connect --as hubspot --bundle hubspot` | Direct bundle connection |
| `mcpbundles connect --as dev --server localhost:8000` | Dev server connection |
| `mcpbundles connections` | List active connections |
| `mcpbundles disconnect <name>` | Remove a connection |
| `mcpbundles tools --as @hubspot` | Target a specific connection |

### Interactive Shell

```bash
$ mcpbundles shell
MCPBundles Shell — connecting to hub...
Connected. Type help for commands, exit to quit.

mcpbundles(hub)> tools
mcpbundles(hub)> call get-contacts limit=5
mcpbundles(hub)> exec print("hello world")
mcpbundles(hub)> use hubspot          # switch connection live
mcpbundles(hubspot)> tools
mcpbundles(hubspot)> exit
```

### AI Agent Integration

| Command | Description |
|---------|-------------|
| `mcpbundles init` | Generate tool manifest (`mcpbundles_tools.md`) |
| `mcpbundles init --format json` | JSON format manifest |
| `mcpbundles serve` | Local MCP proxy on localhost:8080 |
| `mcpbundles serve --connections hub,hubspot,stripe` | Aggregate multiple connections |

### Local MCP Proxy (`serve`)

Start a local unauthenticated MCP server that proxies to remote MCPBundles:

```bash
# Single connection
mcpbundles serve --port 8080

# Multi-connection aggregation
mcpbundles serve --connections hub,hubspot,stripe
```

In aggregated mode, `list_tools` merges tools from all connections and `call_tool` routes to the correct upstream automatically. Local AI clients connect without credentials.

### Desktop Proxy Tunnel

| Command | Description |
|---------|-------------|
| `mcpbundles proxy start` | Start WebSocket tunnel daemon |
| `mcpbundles proxy stop` | Stop tunnel daemon |
| `mcpbundles proxy restart` | Restart tunnel |
| `mcpbundles proxy status` | Show tunnel status |
| `mcpbundles proxy logs` | View tunnel logs |
| `mcpbundles proxy logs -f` | Follow logs in real-time |

### Configuration

| Command | Description |
|---------|-------------|
| `mcpbundles config show` | Show all settings |
| `mcpbundles config set key value` | Set a config value |
| `mcpbundles config get key` | Get a config value |
| `mcpbundles config reset` | Reset to defaults |

### Shell Completion

```bash
mcpbundles install-completion bash    # or zsh, fish
```

After installation, restart your shell for tab completion on commands, tool names, resource URIs, and connection names.

## Output Modes

| Flag | Behavior |
|------|----------|
| `--pretty` | Rich tables, colors, syntax highlighting (default for discovery) |
| `--json` | Raw JSON to stdout, pipe-friendly (default for execution) |
| `--raw` | Full MCP response envelope (debugging) |
| `--stream` | Progressive line-by-line output (for `exec`) |
| `-q` / `--quiet` | Suppress non-essential output |

Respects `NO_COLOR` environment variable.

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | User/input error (bad args, missing auth) |
| 2 | Tool execution error (tool returned isError) |
| 3 | Connection/server error (unreachable, 5xx) |
| 4 | Internal error |

## Configuration Files

All configuration is stored in `~/.mcpbundles/` (or `~/.mcpbundles-dev/` with `ENVIRONMENT=development`):

| File | Purpose |
|------|---------|
| `config.yaml` | CLI settings (server, workspace, output format) |
| `token.json` | Encrypted OAuth tokens |
| `sessions/` | Named connection session files |
| `completion_cache.json` | Tab completion cache (60s TTL) |
| `shell_history` | REPL command history |
| `tunnel.pid` | Proxy daemon PID |
| `tunnel.log` | Proxy daemon logs |

Config precedence (highest wins):
1. CLI flags (`--url`, `--json`, `-q`)
2. Environment variables (`MCPBUNDLES_API_KEY`, `MCPBUNDLES_BASE_URL`)
3. Config file (`~/.mcpbundles/config.yaml`)
4. Defaults

## Security

- OAuth2 PKCE — no client secret stored on disk
- API keys prefixed `mb_` — recognized and routed automatically
- Tokens encrypted with machine-specific Fernet key
- File permissions set to user-only (0600)
- Desktop proxy only forwards to `localhost`
- All tunnel traffic encrypted over WSS

## Requirements

- Python 3.10+
- macOS or Linux
- Google Chrome (optional, for browser proxy feature)

## Development

```bash
git clone https://github.com/thinkchainai/mcpbundles-proxy.git proxy
cd proxy
python -m venv .venv && .venv/bin/pip install -e ".[dev]"
pytest
```

## Support

- Docs: https://mcpbundles.com/docs
- Email: support@mcpbundles.com

## License

MIT License
