Cleanup translate pr

Signed-off-by: Mihai Criveti <[email protected]>

Author: crivetimihai

docker/translate.Dockerfile

@@ -1,5 +1,6 @@
 nav:
   - index.md
   - mcpgateway-wrapper.md
+  - mcpgateway-translate.md
   - Clients: clients
   - Agents: agents

docs/docs/using/.pages

@@ -0,0 +1,139 @@
+# MCP Gateway StdIO to SSE Bridge (`mcpgateway-translate`)
+
+`mcpgateway-translate` is a lightweight bridge that connects a JSON-RPC server
+running over StdIO to an HTTP/SSE interface, or consumes a remote SSE stream
+and forwards messages to a local StdIO process.
+
+Supported modes:
+
+1. StdIO to SSE – serve a local subprocess over HTTP with SSE output
+2. SSE to StdIO – subscribe to a remote SSE stream and forward messages to a local process
+
+---
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| Bidirectional bridging | Supports both StdIO to SSE and SSE to StdIO |
+| Keep-alive frames | Emits `keepalive` events every 30 seconds |
+| Endpoint bootstrapping | Sends a unique message POST endpoint per client session |
+| CORS support | Configure allowed origins via `--cors` |
+| OAuth2 support | Use `--oauth2Bearer` to authorize remote SSE connections |
+| Health check | Provides a `/healthz` endpoint for liveness probes |
+| Logging control | Adjustable log verbosity with `--logLevel` |
+| Graceful shutdown | Cleans up subprocess and server on termination signals |
+
+---
+
+## Quick Start
+
+### Expose a local StdIO server over SSE
+
+```bash
+mcpgateway-translate \
+  --stdio "uvenv run mcp-server-git" \
+  --port 9000
+```
+
+Access the SSE stream at:
+
+```
+http://localhost:9000/sse
+```
+
+### Bridge a remote SSE endpoint to a local process
+
+```bash
+mcpgateway-translate \
+  --sse "https://corp.example.com/mcp" \
+  --oauth2Bearer "your-token"
+```
+
+---
+
+## Command-Line Options
+
+```
+mcpgateway-translate [--stdio CMD | --sse URL | --streamableHttp URL] [options]
+```
+
+### Required (one of)
+
+* `--stdio <command>`
+  Start a local process whose stdout will be streamed as SSE and stdin will receive backchannel messages.
+
+* `--sse <url>`
+  Connect to a remote SSE stream and forward messages to a local subprocess.
+
+* `--streamableHttp <url>`
+  Not implemented in this build. Raises an error.
+
+### Optional
+
+* `--port <number>`
+  HTTP server port when using --stdio mode (default: 8000)
+
+* `--cors <origins>`
+  One or more allowed origins for CORS (space-separated)
+
+* `--oauth2Bearer <token>`
+  Bearer token to include in Authorization header when connecting to remote SSE
+
+* `--logLevel <level>`
+  Logging level (default: info). Options: debug, info, warning, error, critical
+
+---
+
+## HTTP API (when using --stdio)
+
+### GET /sse
+
+Streams JSON-RPC responses as SSE. Each connection receives:
+
+* `event: endpoint` – the URL for backchannel POST
+* `event: keepalive` – periodic keepalive signal
+* `event: message` – forwarded output from subprocess
+
+### POST /message
+
+Send a JSON-RPC message to the subprocess. Returns HTTP 202 on success, or 400 for invalid JSON.
+
+### GET /healthz
+
+Health check endpoint. Always responds with `ok`.
+
+---
+
+## Example Use Cases
+
+### 1. Browser integration
+
+```bash
+mcpgateway-translate \
+  --stdio "uvenv run mcp-server-git" \
+  --port 9000 \
+  --cors "https://myapp.com"
+```
+
+Then connect the frontend to:
+
+```
+http://localhost:9000/sse
+```
+
+### 2. Connect remote server to local CLI tools
+
+```bash
+mcpgateway-translate \
+  --sse "https://corp.example.com/mcp" \
+  --oauth2Bearer "$TOKEN" \
+  --logLevel debug
+```
+
+---
+
+## Notes
+
+* Only StdIO to SSE and SSE to StdIO bridging are implemented.
+* Any use of `--streamableHttp` will raise a NotImplementedError.