[Feature]: MCP server adapter over the local agent bus (HTTP)

[rosspeili]

One-line summary

Expose AVATAR’s existing local agent bus (127.0.0.1:47903) as an MCP server so Cursor / Claude Desktop / other MCP clients can drive stage commands and read state without custom HTTP glue.

Problem / motivation

#6 delivered a loopback HTTP + WebSocket bus with the same six stage commands as the in-app Motion Deck. Integrators today must hand-roll HTTP calls and token headers (see docs/agents/local-bus.md). MCP is becoming the standard tool surface for local agents; an official thin adapter would:

• Lower friction for “drive my avatar from my IDE agent” workflows.
• Keep AVATAR local-first (stdio or loopback MCP, no cloud).
• Reuse the existing token + command schema instead of inventing a parallel API.

Keyword → animation semantics remain #7 — separate from this adapter.

Proposed solution

Ship a separate optional package or Electron-exposed entry (exact packaging TBD) that:

1. Implements MCP tools mirroring bus commands: stage.command actions (speak, animation.play, animation.mode, environment.set, avatar.select, camera.reset — per current bus schema).
2. Exposes GET /v1/state (or equivalent) as an MCP resource or tool for avatar/environment/animation snapshot.
3. Reads the bus token from the same store as the app (agent-bus.json / Settings → Agents copy flow) — document how MCP clients authenticate.
4. Documents install: e.g. add to claude_desktop_config.json or Cursor MCP config pointing at the adapter binary/script.

Out of scope for v1: window/file audio over bus, outbound WebSocket events, keyword semantics (#7).

Alternatives considered

• Document curl only — works but every agent stack reimplements the same wrapper.
• Embed MCP inside Electron main — heavier; a sidecar Node script that proxies to loopback may be simpler to ship and test.
• Cloud relay — rejected; conflicts with local-first policy.

Primary surface

Agent / external triggers (roadmap)

Constraints you accept

• Should stay usable offline / local-first
• Browser-only mode may remain limited vs Electron

Mock / sketch / reference (optional)

Reference: docs/agents/local-bus.md command table and token header. MCP tool names should map 1:1 to documented HTTP paths where possible.

[AUDOSt0ck1ng]

Prerequisite check + design decisions

Went through what #6 actually shipped against what this issue assumes. Prerequisites are met, but three things in the body above are stale and the packaging question has an answer now.

Prerequisites: met

Assumed here	Reality
Loopback HTTP + WS bus	Shipped in 0.7.0. electron/agent-bus.cjs — /v1/command, /v1/state, /v1/socket
GET /v1/state snapshot	Exists, with ids and labels plus playableOnce
Token store + Settings copy flow	Exists. electron/agent-bus-token.cjs, Copy token / Regenerate / Copy example curl in AgentBusPanel.jsx
Command table documented	docs/agents/local-bus.md

Keyword semantics (#7) stays out of scope and does not block this.

Corrections to the body above

1. The command list is wrong. speak, animation.mode, avatar.select, and camera.reset do not exist anywhere in the codebase. The six that do: animation.play, animation.default, animation.stop, avatar.set, environment.set, audio.source. mode is a payload field of animation.play ("once" / "select"), not a command.

2. "Reads the bus token from the same store as the app (agent-bus.json)" is not implementable from a plain Node process. That file is encrypted with Electron's safeStorage (electron/main.cjs), which only exists inside an Electron main process. A spawned node sidecar can read the file but only sees ciphertext.

3. "MCP tool names should map 1:1 to documented HTTP paths" is the wrong target. The MCP surface is agent-facing; it should be a smaller, LLM-shaped set rather than a mirror of the HTTP API.

Decision: in the Electron main process, not a sidecar

/mcp served over Streamable HTTP from the existing bus server on the existing port, alongside /v1/command. This drops the entire sidecar problem set: no absolute path in the client config (the NSIS installer allows changing the install directory), no asarUnpack, no ELECTRON_RUN_AS_NODE, no assumption that the user has Node installed. Client config becomes a URL.

It also gives the lifecycle we want: the endpoint exists only while AVATAR is running, instead of an adapter process outliving the app inside the MCP client.

Tools call resolveStageCommand (src/lib/stageCommands.js) directly — a peer of the HTTP and WebSocket routes, the same way the WebSocket is "a peer of the HTTP route, not a wrapper around it". No self-HTTP hop.

Origin: keep rejecting, and say so in the docs

The bus refuses any request carrying an Origin header. Measured what clients actually send before deciding whether that has to change:

Client	Sends Origin?	How this was established
Claude Code	No	Registered a header-logging server via claude mcp add --transport http; connected fine, no Origin on any request
Anything on the official TS SDK	No	client/streamableHttp.js (SDK 1.30.0) never sets it
Codex CLI	Almost certainly no	Rust client; nothing in openai/codex sets an app-scheme origin
Codex desktop app	Yes, codex-app://…	A sibling project has to allowlist exactly that value
Claude Desktop	Unknown	Electron; depends whether it requests from main or a renderer

So blanket rejection does not block CLI-class clients, which is the target for v1. Keeping it, and documenting the consequence: webview-based desktop MCP clients are not supported in v1. If that changes, the minimal fix is to allow, on /mcp only, requests with no Origin and requests with a non-http(s) app scheme, while continuing to reject every http(s):// origin so a web page still cannot drive the avatar.

DNS-rebinding protection does not depend on this: the bus already validates the Host header against a loopback allowlist.

Implementation notes

• GET /mcp must not fall through to not-found. Claude Code issues one (the pre-2026-07-28 standalone SSE stream). Answer 405 Method Not Allowed at minimum.
• Protocol negotiation is real. Claude Code opens with MCP-Protocol-Version: 2026-07-28 and falls back to 2025-11-25. Pin the SDK version deliberately — 2026-07-28 removed protocol-level sessions and the GET stream.
• One switch each, no MCP-specific settings. enabled governs /v1/* and /mcp together - the endpoint exists exactly when the bus is running, so there is no "bus on but MCP off" state to diagnose. requireToken likewise applies one token rule to both transports, with no second auth mode. Verified since: a client registered with an Authorization: Bearer header does send it on every request, so a token-required MCP endpoint is workable rather than a gamble.
• Settings should emit the whole registration command, not just the token — only the app knows its own port, and the token if required.
• Streams need a ceiling. Streamable HTTP keeps responses open. A client that is killed or reconnects without closing leaves a session behind, and the endpoint is reachable by anything on this machine, so cap and expire them rather than trusting clients to tidy up. Turning the bus off must close open streams rather than stranding them.
• 503 is a normal state, not an edge case. stageSnapshot is null until the window reports, including after every reload. A tools/call in that window must return a JSON-RPC error a model can act on, not a raw status.
• Tool surface: list_stage, play_animation, stop_animation, set_avatar, set_environment, get_status. audio.source stays out — it is a user's lip-sync setting, not something an agent should reach for.
• play_animation defaults to once. The bus defaults to select, which persists the selection to config.yaml. That default is right for the menus and wrong for an agent, and this layer only serves agents.
• Keep animation an open string and validate against the live catalog at call time. A custom animations folder derives ids from file paths, so the set changes while the app runs and a client with a stale tool list still needs to work.
• New dependencies: @modelcontextprotocol/sdk and zod, neither currently present.
• Tests: keep the MCP module pure enough for node --test without Electron, as agent-bus.cjs already manages.

Refs #6, #7

[AUDOSt0ck1ng]

Demo:
https://www.youtube.com/watch?v=52-srVCIh7M

voice issue is not checked yet...

[AUDOSt0ck1ng]

@rosspeili Do you think we should keep the current design for request support, or should we allow Origins ?