# In-engine agent gateway

A local HTTP/SSE server that runs a Claude agent (via the **Claude Agent SDK**)
wired to this project's `ue-blueprint` MCP server, and serves a chat
UI for the Unreal **WebBrowser** widget. Talk to the agent from *inside* the
editor while it edits Blueprints, spawns nodes, builds C++, screenshots UMG, etc.

```
WBP_AgentChat (WebBrowser)  ──HTTP/SSE──▶  server.mjs (this)
   public/ chat UI                           ├─ @anthropic-ai/claude-agent-sdk  (the agent)
   stream text + tool cards                  ├─ spawns ../src/server.js          (ue-blueprint MCP)
   clickable /Game asset chips               └─ /api/focus → UE Remote Control   (sync Content Browser)
```

## One-time setup

1. **Install deps** (already done once):
   ```powershell
   cd Plugins/UEBlueprintMCP/agent-gateway
   npm install
   ```

2. **Give the agent credentials.** The gateway spawns its own agent process, so
   it needs auth that does *not* depend on your interactive Claude Code session.
   Pick one:

   - **Subscription (recommended)** — generate a long-lived token:
     ```powershell
     claude setup-token
     ```
     Copy the printed token into `agent-gateway/auth.env` (gitignored):
     ```
     CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...
     ```

   - **API key (pay-as-you-go)** — in `auth.env`:
     ```
     ANTHROPIC_API_KEY=sk-ant-api03-...
     ```

   `GET /api/health` returns `"hasAuth": false` until one is present, and the
   chat header shows a "no token" state.

3. **Enable UE plugins**: *Web Browser* (for the widget) and *Remote Control API*
   (for live tool access — `WebControl.StartServer`, default port 30010).

## Run

```powershell
npm start         # → http://127.0.0.1:8765
```
or double-click **`start-gateway.bat`**.

Open `http://127.0.0.1:8765` in any browser to test the UI without UE.

## Inside Unreal

Open **`/Game/UI/Agent/WBP_AgentChat`**, add it to the viewport (or dock it in an
Editor Utility Widget). It hosts a full-bleed WebBrowser pointed at the gateway
URL. See `../UI_WORKFLOW.md` note: this screen is a deliberate exception to the
UMG-token rule — all visuals live in `public/styles.css` (the `:root` block),
not in `DA_UITheme`, because the surface is HTML inside a browser.

## Config (env vars)

| var               | default                | meaning                          |
|-------------------|------------------------|----------------------------------|
| `MCP_AGENT_PORT`  | `8765`                 | gateway port                     |
| `MCP_AGENT_HOST`  | `127.0.0.1`            | bind host                        |
| `MCP_AGENT_MODEL` | `claude-opus-4-8`      | agent model                      |
| `UE_PROJECT_DIR`  | repo root (auto)       | project cwd handed to the agent  |
| `UE_REMOTE_CONTROL_URL` | `http://127.0.0.1:30010` | UE Remote Control (asset focus) |

## Endpoints

- `GET  /` — chat UI (static from `public/`)
- `GET  /api/health` — `{ ok, model, projectDir, mcp, hasAuth }`
- `POST /api/chat` — `{ message, sessionId? }` → **SSE** stream of:
  `init` · `text` · `thinking` · `tool_start` · `tool_end` · `error` · `done`.
  `done.sessionId` is replayed by the client to continue the conversation.
- `POST /api/focus` — `{ path: "/Game/..." }` → focuses the asset in UE's
  Content Browser (used by clickable asset chips).

## Notes

- The agent runs with `permissionMode: bypassPermissions` (no interactive
  terminal exists behind a web UI) and inherits the project `CLAUDE.md` via
  `settingSources: ["project"]`, so it follows the same conventions Claude Code
  does — including the MCP-first and UI vision-loop rules.
- Conversation state is per `sessionId` (SDK `resume`); the browser keeps it in
  memory for the page session.