mhc-desktop-backend

Backend HTTP/SSE service for the mhc-desktop Skill/MCP client.

• Stack: FastAPI + minimal-harness + mh-service-kit + openai + anthropic
• Default port: 8765 (MHC_PORT)
• Dev: hot-reload via uvicorn (MHC_RELOAD=1)

Endpoints

Provider config

Lives at ~/.mhc-desktop/providers.json. Schema is byte-for-byte compatible with mh-local's ~/.config/mh-local/providers.json — copy a file between the two and it just works.

[
  {
    "name": "openai",
    "provider_type": "openai",
    "api_key": "sk-...",
    "base_url": "https://api.openai.com/v1",
    "default_model": "gpt-4o-mini",
    "description": "OpenAI official API",
    "models": [{"code": "gpt-4o-mini", "display_name": "GPT-4o mini", "max_context": 128000}],
    "created_at": "...",
    "updated_at": "..."
  }
]

Dev

uv run python -m mhc_desktop_backend
# health: http://127.0.0.1:8765/api/v1/health
# docs:   http://127.0.0.1:8765/docs

Or use the workspace helper:

bash scripts/dev-mhc-desktop.sh

Starts backend (hot reload) + frontend (HMR) on :5180, tails logs to .logs/.

Env

Build

uv build

Wheel: dist/mhc_desktop_backend-*.whl.

Tools subsystem

A "Tool" is the third concept alongside Skills and MCP. See mhc_desktop_backend/tools/ for the implementation:

• models.py — Tool dataclass + slug rules; slugs disallow :: to keep the MCP-vs-Tool distinction explicit in the name field of ToolCall TypedDicts.
• store.py — file-backed CRUD on tools-state.json; bundled tools are code-side, not on disk, but the store lists them alongside user tools.
• bundled/ — now (ISO 8601 timestamp) and uuid (v4) trivial callables for E2E verification.
• imports.py — import_local_tool compiles + caches Python source strings; run_tool is the cancellable, time-bounded executor.
• __init__.py — public surface + build_streaming_tool wrapping a Tool into a minimal-harness StreamingTool.

API

• GET /api/v1/tools — list (bundled first, then user).
• GET /api/v1/tools/bundled — bundled slugs only.
• POST /api/v1/tools — create / register.
• GET /api/v1/tools/{slug} — detail (auth header redacted).
• PUT /api/v1/tools/{slug} — update.
• PUT /api/v1/tools/{slug}/enabled — flip on/off.
• DELETE /api/v1/tools/{slug} — remove.
• POST /api/v1/tools/import-source — compile + register a Python source string.
• GET /api/v1/tools/{slug}/export — JSON manifest.

Bundled skill mcp-tool-mix

Drives the goal's most complex scenario: a single skill that instructs the model to call both an MCP (dummy-mcp::add) and a local Tool (now). Used by scripts/e2e-tools.mjs Check 8 to verify the capsule distinction works end-to-end.