# StableDeliver AI Bridge

> Private infrastructure. Not a public product. Not the StableDeliver customer product.

The **StableDeliver AI Bridge** is a small, private, MCP-compatible server that lets
**ChatGPT** (acting as supervisor/reviewer) drive **Claude Code** (acting as the
engineering worker) through a controlled, logged, safety-gated interface.

```
ChatGPT (supervisor)
   ↓ MCP over HTTPS
https://bridge.stabledeliver.com/mcp
   ↓
StableDeliver Bridge Server  (Node.js + TypeScript)
   ↓ controlled task files
Claude Code CLI / Claude Agent SDK
   ↓
GitHub repo + workspace + tests + Coolify staging
   ↓
Reports & logs back to the bridge
   ↓
ChatGPT reviews and decides the next action
```

---

## What this bridge IS

- A private automation bridge so ChatGPT can supervise Claude Code.
- A controlled task queue + execution + reporting system.
- Safety-gated: read/plan/edit/staging only, with owner approval for anything risky.

## What this bridge is NOT

- It is **not** the StableDeliver customer product.
- It does **not** verify USDT/USDC payments.
- It does **not** deliver digital products.
- It does **not** custody funds, move funds, exchange tokens, or hold private keys.
- It does **not** touch production, DNS, billing, or wallets without explicit owner approval.

---

## Roles

| Role | Who | Responsibility |
|------|-----|----------------|
| **Engineering worker** | Claude Code | Writes code, runs tests, creates reports — within safety limits |
| **Supervisor / reviewer** | ChatGPT | Reviews reports, decides next task, approves/rejects phases |
| **Owner** | Khaled | Holds accounts & money, approves DNS/deploy/spend/production |

See [PROJECT_RULES.md](PROJECT_RULES.md) for the full role contract.

---

## Endpoints (planned)

| Method | Path | Auth | Purpose |
|--------|------|------|---------|
| GET | `/` | admin token | Private dashboard (status only, no secrets) |
| GET | `/health` | none | Health check JSON |
| POST | `/mcp` | bearer/connector | MCP endpoint exposing bridge tools |
| GET | `/logs/recent` | admin token | Recent logs (optional) |

## MCP tools (v0.1)

| Tool | Risk | Auto-allowed |
|------|------|--------------|
| `get_project_status` | Low | Yes |
| `get_latest_claude_report` | Low | Yes |
| `get_recent_logs` | Low | Yes |
| `create_claude_task` | Medium | Yes, if no blocked actions |
| `run_claude_task` | Medium/High | Plan/read/edit only |
| `run_tests` | Medium | Yes |
| `deploy_staging` | High | **No** — owner approval |

Blocked actions return `OWNER_APPROVAL_REQUIRED`. See [SECURITY.md](SECURITY.md).

---

## Running locally (Phase 1 — skeleton, working)

```bash
# optional: cp .env.example .env  (NEVER commit .env)
npm install
npm run build         # tsc → dist/
npm run dev           # hot-reload dev server (tsx)
# or production-style:
npm start             # node dist/server.js
```

Then:

```bash
curl http://localhost:3000/health        # {"ok":true,...}
curl -X POST http://localhost:3000/mcp   # 501 placeholder (tools land in Phase 2)
# open http://localhost:3000/ in a browser for the private dashboard
```

Scripts: `npm run build` · `npm run dev` · `npm start` · `npm run typecheck` ·
`npm test` · `npm run lint`.

### Docker (local)

```bash
docker compose up --build     # serves on http://localhost:3000
```

### Auth in v0.1

If `BRIDGE_ADMIN_TOKEN` is **unset**, the bridge runs in **permissive dev mode**
(requests pass, a warning is logged) — convenient for local skeleton work. When the
token **is set**, private endpoints (`/`, `/mcp`) require `Authorization: Bearer <token>`.
The token must be set before the bridge is ever exposed.

## Deploying with Coolify (Phase 5+, not built yet)

See [docs/COOLIFY_DEPLOYMENT.md](docs/COOLIFY_DEPLOYMENT.md). Deployment is
**staging only** in v0.1 and requires owner approval.

---

## Environment variables

Only these are used. See [.env.example](.env.example) for placeholders.

| Variable | Required | Notes |
|----------|----------|-------|
| `BRIDGE_ADMIN_TOKEN` | yes | Strong random token for private endpoints |
| `PROJECT_PATH` | yes | Workspace Claude Code is allowed to operate in |
| `NODE_ENV` | yes | `development` / `staging` |
| `LOG_LEVEL` | no | e.g. `info` |
| `DATABASE_URL` | no | SQLite path or Postgres URL |
| `ANTHROPIC_API_KEY` | if needed | For Claude Code execution |
| `GITHUB_TOKEN` | if needed | Repo operations |
| `COOLIFY_TOKEN` | if needed | Staging deploy |

**Never commit `.env`. Never log secrets.**

---

## Safety warnings

- This is **private infrastructure**. Do not expose it publicly without owner approval.
- The MCP endpoint must always be authenticated.
- Claude Code execution is confined to `PROJECT_PATH`, never runs as root, always times out and is always logged.
- Wallet keys, seed phrases, and production secrets are **never** requested, stored, printed, or committed.

## Current status

**Code-complete & deploy-ready (local).** All 8 MCP tools implemented, strict bearer
auth, full MCP JSON-RPC lifecycle, mock + opt-in real Claude CLI runner, `run_tests`.
`typecheck`/`build`/`test` pass (51/51); Docker image builds and the container passes a
live smoke test. **Live deploy + DNS pending owner access.**
See [DEPLOYMENT_REPORT.md](DEPLOYMENT_REPORT.md), [BUILD_REPORT.md](BUILD_REPORT.md),
[TEST_REPORT.md](TEST_REPORT.md), [NEXT_PROMPT_FOR_CHATGPT.md](NEXT_PROMPT_FOR_CHATGPT.md).