# UniversalBench MCP Workbench

Phase 1 execution layer for the UniversalBench commercial MCP product.
Sits behind the Cloudflare Worker at `mcp.universalbench.dev`, which handles
customer auth, billing, rate limiting and usage logging.

## Architecture

```
Customer AI (Claude, ChatGPT, any MCP client)
        |
        v MCP protocol
mcp.universalbench.dev   (Cloudflare Worker)
  auth, billing, rate limiting, usage logging
        |
        v HTTPS with X-Universalbench-Key header
universalbench-mcp on Railway   (this service)
  code, bash, web search, LLM, file I/O, parallel blocks
```

This service has zero awareness of individual customers. All multi tenant
concerns live in the Cloudflare Worker upstream.

## Endpoints

| Method | Path                | Auth | Purpose                  |
| ------ | ------------------- | ---- | ------------------------ |
| GET    | /                   | no   | Service banner           |
| GET    | /health             | no   | Liveness probe           |
| GET    | /version            | no   | Version info             |
| GET    | /workbench/health   | no   | Cold-start probe         |
| POST   | /workbench/execute  | yes  | Main execution endpoint  |

## Required environment variables

| Name                | Purpose                                              |
| ------------------- | ---------------------------------------------------- |
| UNIVERSALBENCH_KEY  | Shared secret with the Cloudflare Worker             |
| OPENROUTER_API_KEY  | Used by invoke_llm                                   |
| TAVILY_SEARCH_API   | Used by web_search                                   |
| PORT                | Set automatically by Railway                         |

## Phase 1 capabilities

- code execution with persistent session state
- bash command execution
- web search via Tavily
- LLM invocation via OpenRouter
- sandboxed file read and write under /tmp
- pip install of packages at runtime
- parallel code blocks up to 8 threads

All operations carry a 60 second timeout. Code state persists per `session_id`
within one container instance, lost on Railway redeploy.

## What is NOT in this service by design

- No GitHub credentials
- No customer database access
- No persistent storage beyond the running container
- No personal Penantia hooks (WordPress, cPanel, GCP secrets)

Capabilities that require per-customer credentials (git operations, customer
databases, deployment automation) are deferred to Phase 2 with the secrets
vault.

## Version

1.0.0