Add local MCP gateway dev harness with smoke tests for Happy CLI

[jakenuts]

Summary

• Adds a local MCP gateway dev harness that proxies to the hosted Happy Server using the same CLI credentials and end-to-end encryption pipeline.
• Exposes three MCP tools: open_session, send_text, and voice_token (plus new local testing utilities).
• Includes environment template and quick-start docs, along with a dedicated dev gateway README.
• Adds a local gateway runner: npm run dev:mcp-gateway.
• Introduces smoke test tooling and a credentials helper to streamline local dev: dev/mcp-gateway/scripts/smoke.ts and dev/mcp-gateway/scripts/write-access-key.ts.
• Implements the MCP gateway in TypeScript with a minimal, local HTTP transport.

Changes

New files

• dev/mcp-gateway/.env.example
• dev/mcp-gateway/README.md
• dev/mcp-gateway/src/index.ts
• dev/mcp-gateway/tsconfig.json
• dev/mcp-gateway/scripts/smoke.ts
• dev/mcp-gateway/scripts/write-access-key.ts

Build/Dev tooling

• package.json: added scripts dev:mcp-gateway, prep:mcp-creds, and test:mcp-gateway to run the gateway, prepare credentials, and smoke-test the gateway respectively.

Implementation overview

• A local MCP HTTP gateway that proxies to the hosted Happy Server, reusing the Happy CLI credentials and end-to-end encryption pipeline.
• Utilizes ModelContextProtocol MCP server primitives to provide tooling.

MCP Tools

• open_session(tag): Create or attach to a Happy session by tag and establish a live connection.
• send_text(tag, text): Send an encrypted user message into the session identified by tag.
• voice_token(agentId?, revenueCatPublicKey?): Retrieve an ElevenLabs token via the Happy Server (/v1/voice/token) using the CLI credentials.

Transport & Server

• StreamableHTTPServerTransport with optional MCP_ALLOWED_HOSTS and MCP_ALLOWED_ORIGINS controls.
• Exposes MCP API over HTTP on MCP_HTTP_PORT (default 3030) and serves at /mcp.

Security / Notes

• Dev harness intended for local testing only; no auth is exposed on the MCP endpoint and it should be run on localhost.
• All payloads are end-to-end encrypted; gateway user data is not stored in plaintext.
• Sessions are per-tag and cached to minimize latency.

How to run

1. Copy and configure the env template:

   cp dev/mcp-gateway/.env.example dev/mcp-gateway/.env

2. Prepare credentials (one of the following):
   • Set env HAPPY_ACCESS_KEY_JSON to the contents of your access.key, or
   • Set HAPPY_TOKEN (+ optionally HAPPY_SECRET_B64) or HAPPY_PUBLIC_KEY_B64 with HAPPY_MACHINE_KEY_B64.
   • Or simply run the helper to write the access.key:

     DOTENV_CONFIG_PATH=dev/mcp-gateway/.env npm run prep:mcp-creds

3. Start the gateway:

   DOTENV_CONFIG_PATH=dev/mcp-gateway/.env npm run dev:mcp-gateway

4. Point an MCP-capable client at http://localhost:3030/mcp and use the open_session, send_text, and voice_token tools.

Quick start notes (from README)

• Gateway starts a Streamable HTTP MCP server on MCP_HTTP_PORT (default 3030).
• Tools reuse CLI credentials and target the hosted Happy Server with the same encryption pipeline.
• Per-tag sessions are kept alive for low-latency interactions.

Smoke test (optional)

• With the same env vars set, run:

  DOTENV_CONFIG_PATH=dev/mcp-gateway/.env npm run test:mcp-gateway

• This writes dev/.happy/access.key (if missing), opens/creates session tag mcp-smoke, and sends a short user message to the hosted server.

Test plan

• Start gateway and verify logs indicate listening on localhost:3030.
• Connect an MCP client to http://localhost:3030/mcp and invoke open_session with a tag; verify a session is prepared.
• Invoke send_text with a tag and a message; verify acknowledgement and that the message is sent to the active session.
• Invoke voice_token with optional agentId/revenueCatPublicKey; verify a JSON token response from the server API.
• Confirm that requests to the MCP endpoint include proper handling of allowed hosts/origins when configured.

Potential follow-ups

• Extend MCP toolset with additional actions (e.g., streaming updates, notifications).
• Add integration tests against a mocked Happy Server.
• Document advanced configuration and security considerations for local dev use.

🌿 Generated by Terry

---

ℹ️ Tag @terragon-labs to ask questions and address PR feedback

📎 Task: https://www.terragonlabs.com/task/71e1c99b-2b5c-48ce-8a69-00dafd7761bf