# 2Bot

**2Bot** is a FastMCP server that lets ChatGPT (or any MCP client) call your local Codex CLI through a controlled MCP tool.

- MCP server name is fixed to **`2Bot`**.
- Local mode uses **stdio**.
- Remote mode uses **HTTP (Streamable HTTP)** for ChatGPT-compatible deployments.

## What 2Bot does

2Bot exposes a single typed tool, `run_codex_prompt`, which runs `codex exec --json -` safely:

- no `shell=True`
- prompt passed via stdin
- timeout handling
- working-directory validation and allowlist support
- JSON-serializable structured output

## Installation

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e .
```

For tests:

```bash
pip install -e .[dev]
pytest
```

## Configuration

2Bot is environment-driven.

| Variable | Default | Description |
|---|---|---|
| `TWOBOT_TRANSPORT` | `stdio` | `stdio` or `http` |
| `TWOBOT_HOST` | `127.0.0.1` | HTTP bind host |
| `TWOBOT_PORT` | `9000` | HTTP bind port |
| `TWOBOT_BASE_URL` | unset | Optional public HTTPS URL for docs/ops |
| `TWOBOT_LOG_LEVEL` | `INFO` | Logging level |
| `TWOBOT_ENABLE_NO_AUTH` | `true` | Enable no-auth mode for initial ChatGPT testing |
| `CODEX_ALLOWED_ROOTS` | unset | Optional cwd allowlist (`:`-separated on macOS/Linux) |

> Authentication note: for first connection tests, use **no auth**. For production, prefer standards-based MCP-compatible auth in front of or integrated with this service.

## Local mode (stdio)

Run with stdio (default):

```bash
2bot-mcp
# or
python -m twobot_codex_mcp.server
```

You can also force stdio:

```bash
TWOBOT_TRANSPORT=stdio 2bot-mcp
```

## Remote mode (HTTP / Streamable HTTP)

Run HTTP mode locally on loopback:

```bash
TWOBOT_TRANSPORT=http TWOBOT_HOST=127.0.0.1 TWOBOT_PORT=9000 2bot-mcp
```

Or with explicit CLI flags:

```bash
2bot-mcp --transport http --host 127.0.0.1 --port 9000
```

### Expose via HTTPS for ChatGPT

ChatGPT must reach a public HTTPS URL. Typical setup:

1. Run 2Bot in HTTP mode on `127.0.0.1:9000`.
2. Put a reverse proxy or tunnel in front (Nginx, Caddy, Cloudflare Tunnel, etc.).
3. Publish a TLS endpoint like `https://mcp.example.com` forwarding to `http://127.0.0.1:9000`.
4. Configure ChatGPT custom MCP connection to that public URL.

## ChatGPT connection notes

ChatGPT connects to the **remote HTTPS MCP endpoint**, not to stdio.

High-level flow:

1. Start 2Bot in HTTP mode.
2. Expose the endpoint at a public HTTPS URL.
3. Create/connect the custom MCP app in ChatGPT pointing at that URL.

Use URL pattern:

- **`https://<your-public-hostname>/`** (or the exact path your reverse proxy maps to the FastMCP HTTP app)

## Security notes (important)

Exposing a tool that can execute local Codex workflows is sensitive.

Recommendations:

- Restrict `CODEX_ALLOWED_ROOTS` to minimal directories.
- Keep conservative defaults (`sandbox=read-only`, `allow_edits=false`).
- Avoid `danger-full-access` unless absolutely necessary and trusted.
- Prefer private deployments (VPN, private network, authenticated gateway).
- Do not expose an unrestricted instance on the public internet casually.

## Example deployment notes

### 1) Local-only HTTP bind

```bash
TWOBOT_TRANSPORT=http TWOBOT_HOST=127.0.0.1 TWOBOT_PORT=9000 2bot-mcp
```

### 2) Reverse proxy / tunnel

- Proxy `https://mcp.example.com` -> `http://127.0.0.1:9000`
- Keep TLS at the edge
- Keep 2Bot private behind the proxy where possible

### 3) Keep stdio mode for local MCP clients

```bash
TWOBOT_TRANSPORT=stdio 2bot-mcp
```

## Tool reference: `run_codex_prompt`

Parameters:

- `prompt: str`
- `cwd: str | None = None`
- `model: str | None = None`
- `profile: str | None = None`
- `sandbox: "read-only" | "workspace-write" | "danger-full-access" = "read-only"`
- `approval_policy: "untrusted" | "on-request" | "never" | None = None`
- `allow_edits: bool = False`
- `skip_git_repo_check: bool = False`
- `add_dirs: list[str] | None = None`
- `timeout_sec: int = 1800`
- `ephemeral: bool = True`
- `include_event_log: bool = False`

Behavior is preserved from local mode while adding transport/config flexibility.