Feat/mcp server expose

[lianghaofeng]

Problem

OM1 currently consumes MCP servers (src/mcp_servers/client.py) but cannot expose itself as one. External MCP clients (Claude Desktop, Cursor, Windsurf) have no standard way to drive the OM1 virtual agent.

Solution

Add src/expose/ — a stdio MCP server exposing three tools:

Tool	Schema
om1_move	enum: forward, backward, turn_left, turn_right, spin, sit, stand, idle
om1_speak	string, 1–500 chars
om1_face	enum: joy, smile, ponder, alert, sad

All tools use JSON Schema enum constraints so the LLM sees a precise tool contract instead of free-form strings (validated end-to-end with Claude Desktop — "moonwalk" correctly rejected, LLM falls back to spin).

Architecture

• server.py — MCP wiring + pure handle_tool_call() dispatcher
• websim_adapter.py — WebSim interop with fail-fast port conflict check
• tools.py — Enum definitions and tool schemas
• config.py — Env-var config (OM1_WEBSIM_HOST/PORT, OM1_LOG_LEVEL)

Split this way so tests can inject a MagicMock adapter without starting a real WebSim HTTP server.

Usage

uv pip install -e .
om1-mcp-server

Claude Desktop config becomes one line:

{
  "mcpServers": {
    "om1": {
      "command": "/absolute/path/.venv/bin/om1-mcp-server"
    }
  }
}

Verification

• 24 unit tests: uv run pytest tests/expose/ — all green
• No regression on 263 core tests
• pre-commit run on staged files — clean
• End-to-end tested with Claude Desktop + WebSim — tools invoke correctly, enum constraint rejects invalid actions

Known Limitation (follow-up candidate)

WebSim.py:509-510 hardcodes host="0.0.0.0" and port=8000, ignoring the SimulatorConfig passed to it. OM1_WEBSIM_PORT is plumbed through correctly on the expose side but won't take effect until WebSim reads its own config. Happy to submit a follow-up PR for that if the team is open to it.

Out of Scope

• Additional simulators beyond WebSim
• Streaming tool responses
• Multi-agent fleet exposure

Per CONTRIBUTING.md, I skipped opening an issue first because the change is additive, non-invasive (no existing file touched except pyproject.toml to register the CLI), and fully tested. If a discussion thread is preferred, happy to convert this into a draft.