You (Claude Desktop / Code / Cursor)
                                      |
                              MCP Protocol (stdio/HTTP)
                                      |
                              elvatis-mcp server
                                      |
              +--------+--------+--------+--------+--------+--------+
              |        |        |        |        |        |        |
          Claude  OpenClaw  Gemini   Codex   Local   llama   Home
          (CLI)   (SSH)     (CLI)    (CLI)   LLM    .cpp    Asst.
              |        |        |        |    (HTTP)  (proc)  (REST)
          Reason  Plugins  1M ctx  Coding    |        |        |
          Write   Trading  Multi-  Files   LM Stu  Turbo-  Lights
          Review  Auto.    modal   Debug   Ollama  Quant   Climate
                  Notify   Rsch    Shell   (free!) cache   Vacuum

User: "Search my memory for TurboQuant notes, summarize with Gemini,
       reformat as JSON locally, then save a summary to memory"

prompt_split returns:
  t1: openclaw_memory_search  -- "Search memory for TurboQuant"        (parallel)
  t3: local_llm_run           -- "Reformat raw notes as clean JSON"    (parallel)
  t2: gemini_run              -- "Summarize the key findings"          (after t1)
  t4: openclaw_memory_write   -- "Save summary to today's log"        (after t2, t3)

  elvatis-mcp integration tests

  Local LLM (local_llm_run)

        Model: deepseek/deepseek-r1-0528-qwen3-8b
        Response: "negative"
        Tokens: 401 (prompt: 39, completion: 362)
  PASS  local_llm_run: simple classification (21000ms)
        Extracted: {"name":"John Smith","age":34}
  PASS  local_llm_run: JSON extraction (24879ms)
        Error: Could not connect to local LLM at http://localhost:19999/v1/chat/completions
  PASS  local_llm_run: connection error handling (4ms)

  Prompt Splitter (prompt_split)

        Strategy: heuristic
        Agent: codex_run
        Summary: Fix the authentication bug in the login handler
  PASS  prompt_split: single-domain coding prompt routes to codex (1ms)
        Strategy: heuristic
        Subtasks: 3
          t1: codex_run -- "Refactor the auth module"
          t2: openclaw_run -- "check my portfolio performance and"
          t3: home_light -- "turn on the living room lights"
        Parallel groups: [["t1","t3"],["t2"]]
        Estimated time: 90s
  PASS  prompt_split: heuristic multi-agent splitting (0ms)
        Subtasks: 4, Agents: openclaw_memory_write, gemini_run, local_llm_run
        Parallel groups: [["t1","t3","t4"],["t2"]]
  PASS  prompt_split: cross-domain with dependencies (1ms)
        Strategy: local->heuristic (fallback)
        Subtasks: 1
  PASS  prompt_split: local LLM strategy (with fallback) (60007ms)

  Routing Guide (mcp_help)

        Guide length: 2418 chars
  PASS  mcp_help: returns guide without task (0ms)
        Recommendation: local_llm_run (formatting task)
  PASS  mcp_help: routes formatting task to local_llm_run (0ms)
        Recommendation: codex_run (coding task)
  PASS  mcp_help: routes coding task to codex_run (0ms)

  Memory Search via SSH (openclaw_memory_search)

        Query: "trading", Results: 5
  PASS  openclaw_memory_search: finds existing notes (208ms)

  -----------------------------------------------------------
  11 passed, 0 failed, 0 skipped
  -----------------------------------------------------------

npx tsx tests/integration.test.ts

npm install -g @elvatis_com/elvatis-mcp

npx @elvatis_com/elvatis-mcp

cp .env.example .env

# Required
HA_URL=http://your-home-assistant:8123
HA_TOKEN=your_long_lived_ha_token
SSH_HOST=your-openclaw-server-ip
SSH_USER=your-ssh-username
SSH_KEY_PATH=~/.ssh/your_key

# Optional: Local LLM
LOCAL_LLM_ENDPOINT=http://localhost:1234/v1    # LM Studio default
LOCAL_LLM_MODEL=deepseek-r1-0528-qwen3-8b     # or omit to use loaded model

# Optional: Sub-agent models
GEMINI_MODEL=gemini-2.5-flash
CODEX_MODEL=o3

{
  "mcpServers": {
    "elvatis-mcp": {
      "command": "npx",
      "args": ["-y", "@elvatis_com/elvatis-mcp"],
      "env": {
        "HA_URL": "http://your-home-assistant:8123",
        "HA_TOKEN": "your_token",
        "SSH_HOST": "your-openclaw-server-ip",
        "SSH_USER": "your-username",
        "SSH_KEY_PATH": "/Users/your-username/.ssh/your_key"
      }
    }
  }
}

%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "elvatis-mcp": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": ["C:\\path\\to\\elvatis-mcp\\dist\\index.js"],
      "env": {
        "HA_URL": "http://your-home-assistant:8123",
        "HA_TOKEN": "your_token",
        "SSH_HOST": "your-openclaw-server-ip",
        "SSH_USER": "your-username",
        "SSH_KEY_PATH": "C:\\Users\\your-username\\.ssh\\your_key"
      }
    }
  }
}

claude mcp add --scope user elvatis-mcp -- node /path/to/elvatis-mcp/dist/index.js

MCP_TRANSPORT=http MCP_HTTP_PORT=3333 npx @elvatis_com/elvatis-mcp

ollama serve                    # starts server on port 11434
ollama run llama3.2             # downloads and loads model

llama-server -m model.gguf --port 8080

# Verify connectivity
ssh -i ~/.ssh/your_key your-username@your-server "openclaw --version"

# Optional: SSH tunnel for OpenClaw WebSocket gateway
ssh -i ~/.ssh/your_key -L 18789:127.0.0.1:18789 -N your-username@your-server

/mcp-help                           # full guide
/mcp-help openclaw_status           # help for a specific tool
/mcp-help analyze this trading strategy for risk  # routing recommendation

RATE_LIMITS='{"claude_run":{"perMinute":3,"perDay":100}}'

git clone https://github.com/elvatis/elvatis-mcp
cd elvatis-mcp
npm install          # builds automatically via prepare script
cp .env.example .env # fill in your values
node dist/index.js   # starts in stdio mode, waits for MCP client

npm run dev

npx tsx tests/integration.test.ts

src/
  index.ts              MCP server entry, tool registration, transport, dashboard
  config.ts             Environment variable configuration
  dashboard.ts          Status dashboard HTML renderer
  ssh.ts                SSH exec helper (Windows/macOS/Linux)
  spawn.ts              Local process spawner for CLI sub-agents (supports stdin piping)
  session-registry.ts   CLI session registry: persist/resume Claude, Gemini, Codex sessions
  tools/
    home.ts             Home Assistant: light, climate, scene, vacuum, sensors
    home-automation.ts  HA automations: list, trigger, enable, disable
    memory.ts           Daily memory log: write, read, search (SSH)
    cron.ts             OpenClaw cron: list, run, status (SSH)
    cron-manage.ts      OpenClaw cron: create, edit, delete, history (SSH)
    openclaw.ts         OpenClaw agent orchestration (SSH)
    openclaw-logs.ts    OpenClaw server log viewer (SSH)
    notify.ts           WhatsApp/Telegram notifications via OpenClaw
    claude.ts           Claude sub-agent (local CLI, for non-Claude clients)
    gemini.ts           Google Gemini sub-agent (local CLI)
    codex.ts            OpenAI Codex sub-agent (local CLI)
    local-llm.ts        Local LLM sub-agent (OpenAI-compatible HTTP)
    local-llm-models.ts LM Studio model management (list/load/unload)
    llama-server.ts     llama.cpp server manager (start/stop/configure)
    file-transfer.ts    File upload/download via SSH
    system-status.ts    Unified health check across all services
    splitter.ts         Smart prompt splitter (multi-strategy)
    split-execute.ts    Plan executor with agent dispatch and rate limiting
    help.ts             Routing guide and task recommender
    routing-rules.ts    Shared routing rules and keyword matching
  rate-limiter.ts       Rate limiting + cost tracking for cloud sub-agents
tests/
  unit.test.ts          42 unit tests (no external services needed)
  integration.test.ts   Live integration tests