# cubox-mcp-cli

A generic pass-through MCP server for the official [`cubox-cli`](https://www.npmjs.com/package/cubox-cli). It exposes exactly one tool, `cubox_cli`, whose canonical parameter is `args: string[]` — the argv you would type after `cubox-cli` on the command line. It also tolerates clients that serialize the array as a string or wrap it in one or more `{ "item": ... }` objects. When Cubox adds, renames, or removes commands, this wrapper does not need to change.

## What is this?

This is a [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server that wraps the official Cubox CLI. Instead of hard-coding Cubox's command surface, it forwards the argument array straight to `cubox-cli` and returns the output. It also includes a shallow, fail-safe guard against destructive operations (`delete`/`remove`/`rm` without a force/confirm flag).

## Why fork/use this?

- **Future-proof**: `cubox-cli` can change its commands and flags anytime; this server stays the same.
- **One tool for everything**: `cubox_cli({ args: ["--help"] })` works for any command.
- **No npm account required**: run directly from GitHub with `npx`.
- **Works with any MCP client**: tested with mcphub, Claude Desktop, and the MCP Inspector.
- **Optional container**: ships with a `Dockerfile` and a Docker Compose template for HTTP transport.

## Quick start

### 1. Get a Cubox API token

The Cubox backend uses a static API Extension link rather than OAuth, so you log in once and copy the link:

```bash
npx -y cubox-cli auth login
# → open https://cubox.pro/web/settings/extensions, enable the API Extension,
#   copy the unique link, and paste it back at the prompt
```

This writes `~/.config/cubox-cli/config.json` on the machine where you run it. If your MCP client runs elsewhere, you will need to pass `CUBOX_TOKEN` as an environment variable (see below).

### 2. Add to your MCP client

No clone or local install is needed for the host running the MCP client. `npx` will pull the code from GitHub and install dependencies automatically.

**mcphub `mcp_settings.json`:**

```json
{
  "mcpServers": {
    "cubox": {
      "command": "npx",
      "args": ["-y", "github:Lascivea/cubox-mcp-cli"],
      "env": {
        "CUBOX_TOKEN": "your_token",
        "CUBOX_SERVER": "cubox.pro"
      }
    }
  }
}
```

**Claude Desktop / other clients:** use the same `npx` command and environment variables.

### 3. Test it

Call the tool with:

```json
{ "args": ["--help"] }
```

For compatibility with some function-calling clients, these equivalent forms are also accepted:

```json
{ "args": "--help" }
{ "args": { "item": ["--help"] } }
{ "args": { "item": { "item": ["card", "list"] } } }
```

The canonical form remains an array of strings. The wrapper unwraps the compatibility forms before applying safety checks and invoking `cubox-cli`.

Or try a read-only command like:

```json
{ "args": ["folder", "list"] }
```

## Configuration example

| Variable | Required | Default | Notes |
|----------|----------|---------|-------|
| `CUBOX_TOKEN` | yes* | — | The last segment of your Cubox API Extension link (e.g. `abcd12345`). Required when the MCP host is a different machine than the one where you ran `cubox-cli auth login`. |
| `CUBOX_SERVER` | no | `cubox.pro` | Cubox server domain. Use `cubox.cc` for the international instance. |
| `CUBOX_CLI_BIN` | no | auto | Override the `cubox-cli` binary path. By default the wrapper resolves `node_modules/.bin/cubox-cli`, then falls back to PATH. |
| `MCP_TRANSPORT` | no | `stdio` | `stdio` for mcphub / Claude Desktop / local clients. `http` for the standalone Docker container. |
| `PORT` | no | `3000` | Only used when `MCP_TRANSPORT=http`. |

> No credentials are baked into the image or written to disk by this wrapper. `CUBOX_TOKEN` and `CUBOX_SERVER` are read by `cubox-cli` itself, not by this server.

## Docker Compose deployment

Copy the template and edit the environment variables:

```bash
cp docker-compose.example.yaml docker-compose.yaml
# edit docker-compose.yaml, set CUBOX_TOKEN
docker compose up -d
```

The container runs the MCP server over HTTP on port `3000`. Register it in your MCP client with a `url` entry pointing at `http://localhost:3000/mcp`.

## Local development

```bash
cd cubox-mcp-cli
npm install
node test-client.js          # regression tests against fake-cubox-cli.sh
npm run inspector            # interactive MCP Inspector
```

## Design notes

### Why only one tool?

A single `{ args: string[] }` schema is the canonical interface and keeps command discovery simple. At runtime, a preprocessing layer also accepts the common array-serialization quirks produced by some function-calling clients: a string, `{ item: ... }`, or nested `{ item: ... }` wrappers. Agents can discover commands live by calling `cubox_cli({ args: ["--help"] })` or `cubox_cli({ args: ["card", "--help"] })`.

### What is hard-coded?

- The global `-o json` flag, with a fallback to plain text if a sub-command rejects it.
- A shallow guard against destructive operations: any call containing `delete`/`remove`/`rm` must also contain `--force`, `--yes`, `-y`, or `--confirm`. If Cubox renames its delete command, this guard simply stops matching — it never blocks something new incorrectly.

### Upgrading cubox-cli later

Nothing to do. `npx` resolves the dependency fresh from `package.json` whenever the cache is rebuilt. To force a refresh: `npx clear-npx-cache` or bump the `cubox-cli` version range in `package.json`.

## Companion projects / related tools

- [`cubox-cli`](https://www.npmjs.com/package/cubox-cli) — the official Cubox CLI this server wraps.
- [mcphub](https://github.com/samanhappy/mcphub) — an MCP server manager that pairs well with this project.

## License

MIT