Skip to main content
Glama
README.md
# claude-mcp-server

MCP server that builds Claude CLI commands with mode defaults resolved. Returns a shell command string for the calling agent to execute via Cursor's Shell tool.

## Install

One command — no clone needed:

```bash
bash <(curl -fsSL https://raw.githubusercontent.com/tal-hason/claude-mcp-server/main/install.sh)
```

**Prerequisites:** Node.js >= 20, jq, curl, [Claude CLI](https://docs.anthropic.com/en/docs/claude-cli)

### Install from source

```bash
git clone https://github.com/tal-hason/claude-mcp-server.git
cd claude-mcp-server
./setup.sh
```

### Custom install location

```bash
CLAUDE_MCP_DIR=~/my-tools/claude-mcp bash <(curl -fsSL https://raw.githubusercontent.com/tal-hason/claude-mcp-server/main/install.sh)
```

### Uninstall

```bash
rm -rf ~/.local/share/claude-mcp-server
jq 'del(.mcpServers["claude-cli"])' ~/.cursor/mcp.json > /tmp/mcp.json && mv /tmp/mcp.json ~/.cursor/mcp.json
```

## How it works

```
┌──────────────────────────────────────────────────────────────┐
│  1. Agent calls claude_models to inspect available models   │
│  2. Agent calls claude_prompt via MCP                        │
│     → MCP server resolves mode defaults, builds command      │
│     → Returns JSON { command, cwd }                          │
│  3. Agent executes command via Shell tool                    │
│  4. Formatted stream output renders in terminal              │
└──────────────────────────────────────────────────────────────┘
```

1. Agent queries `claude_models` to verify available models for EnMaaS or Vertex AI projects.
2. Agent calls `claude_prompt` with prompt + chosen mode/model/effort.
3. MCP server resolves mode defaults (effort, appended system prompt, gateway routing).
4. Returns `{ command, cwd }` — a heredoc-based shell command with ANSI stream formatting.
5. Agent executes via Shell tool (`block_until_ms: 0` for long tasks).

No child process management, no WebSocket bridge, no timeouts — the MCP server is a pure function.

## Usage

Two tools:
- **`claude_models`**: Discovers available models for EnMaaS and Vertex AI projects before dispatching.
- **`claude_prompt`**: Builds the execution command with resolved mode defaults, routing, and failover.

### Model discovery

```
CallMcpTool: user-claude-cli / claude_models
{ "provider": "all", "project": "my-vertex-project" }
```

Parameters:
- `provider`: `"all"` (default), `"enmaas"`, or `"vertex"`
- `project`: Optional GCP project ID to query specific Vertex AI quotas/models. Auto-detects from `VERTEX_PROJECT_ID`, `ANTHROPIC_VERTEX_PROJECT_ID`, or `CLOUDSDK_CORE_PROJECT` environment variables if omitted; explicit `project` parameter takes precedence.

Returns real-time models for EnMaaS (e.g. `rits/zai-org/glm-5-3`, `rits/deepseek-ai/DeepSeek-V4.1-Flash-1017`) and supported Claude aliases (`sonnet`, `opus`, `haiku`) per Vertex AI project.

### Quick exploration

```
CallMcpTool: user-claude-cli / claude_prompt
{ "prompt": "What dependencies does server.js import?", "mode": "explorer", "cwd": "/path/to/repo" }
```

Parse the response JSON, then execute the `command` field via the Shell tool.

### Long-running review (backgrounded)

```
CallMcpTool: user-claude-cli / claude_prompt
{ "prompt": "<full review prompt>", "mode": "reviewer", "model": "opus" }
```

Execute the returned command with `block_until_ms: 0` to background it. Read the terminal file when done.

### Modes

| Mode | Default model | Default effort | Role |
|---|---|---|---|
| `architect` | `sonnet` | high | Architecture analysis — boundaries, coupling, gaps |
| `planner` | `sonnet` | high | Plan creation — incremental steps, acceptance criteria |
| `reviewer` | `opus` | max | Code review — multi-lens, severity-graded |
| `explorer` | `rits/zai-org/glm-5-3` (`sonnet` on Vertex) | low | Quick research — concise, evidence-cited |
| `executor` | `sonnet` | high | Implementation — hexagonal, small batches |

Without `mode`, the tool builds a raw command (caller controls everything).

### Failover & Resilience

Built-in multi-tier failover ensures uninterrupted execution across cloud and gateway outages:

- **Failover Triggers**:
  - Quota exhaustion: HTTP 429, `RESOURCE_EXHAUSTED`, Rate limit, credit balance, budget exceeded.
  - Gateway, Infra & Tier Policy/Model errors: HTTP 500, 502, 503, 504, 529, `ECONNRESET`, `ETIMEDOUT`, socket hang up, `UNAVAILABLE`, Vertex org-policy `allowedModels` constraints, EnMaaS model authorization (`model is not authorized`), model deployment availability, and unset subshell `ENMAAS_KEY`.
  - Process timeouts: Exit code 124 or 137 (controlled via `CLAUDE_TIMEOUT`, default 1800s).
- **User Error Veto**: Genuine client errors (HTTP 400 `invalid_request_error`, 401 `Unauthorized`, non-model 403 `Forbidden`) immediately exit with the failure code without triggering failover, preventing wasteful quota consumption on unrecoverable caller errors.
- **Per-Tier `--settings` Override**: Every Vertex tier explicitly passes `--settings '{"env":{...}}'` with its project and credentials so user `settings.json` environment defaults never hijack project routing.
- **Shared-Quota Bypass (Cross-Provider)**: When Tier 1 (EnMaaS) exhausts shared enterprise quota (429), the cascade bypasses Tier 2 (shared GCP project) and routes directly to Tier 3 (isolated dedicated quota). If Tier 3 fails, it gracefully falls back to Tier 2.
- **Project Deduplication**: Identical project IDs across primary, secondary, and tertiary tiers are automatically deduplicated and promoted to prevent redundant invocations against the same project quota. Note that `primaryProject` takes precedence over the legacy `project` parameter.
- **Prompt Size Guard**: The combined byte length of `prompt` and `systemPrompt` (and any mode-appended prompt) is capped at 100KB to prevent argument buffer overflow and enforce clean streaming via temporary files (`E2BIG` prevention). When failover is enabled, system prompts are safely injected via temporary file redirection (`"$(< "$_spfile")"`) rather than raw command-line argument expansion.
- **Automated Stderr Redaction**: All error logs and terminal failure outputs across both failover cascades and single-tier commands are filtered through stream-level `sed -E` redaction to strip Bearer, Basic, and Token authorization headers, API keys, JWTs, JSON cookies, and multi-line PEM blocks prior to emitting to stderr. Redaction applies strictly to stderr error logs; successful model output on stdout is buffered and delivered unmodified.

### Parameters

| Param | Required | Description |
|---|---|---|
| `prompt` | Yes | The prompt to send (combined prompt + systemPrompt <= 100KB) |
| `mode` | No | Dispatch mode (see table above) |
| `model` | No | Exact model name (e.g. `sonnet`, `opus`, `claude-sonnet-5`, `claude-opus-4-8`, `rits/zai-org/glm-5-3`) |
| `secondaryModel` | No | Fallback model name for cross-provider failover (defaults to `sonnet`) |
| `tertiaryModel` | No | Tertiary model name for 3-tier cascade fallback (defaults to `sonnet`) |
| `effort` | No | `low` / `medium` / `high` / `xhigh` / `max` |
| `provider` | No | Inference provider: `auto` (default), `enmaas`, or `vertex` |
| `primaryProject` | No | Primary GCP project ID for Vertex AI execution |
| `secondaryProject` | No | Secondary GCP project ID for Vertex failover (Tier 2) |
| `tertiaryProject` | No | Tertiary GCP project ID for 3-tier cascade failover (Tier 3) |
| `primaryCredentials` | No | Path to primary GCP service account credentials JSON |
| `secondaryCredentials` | No | Path to secondary GCP service account credentials JSON |
| `tertiaryCredentials` | No | Path to tertiary GCP service account credentials JSON |
| `systemPrompt` | No | System prompt override |
| `sessionId` | No | Resume a previous session |
| `cwd` | No | Working directory for Claude CLI |

## Files

| File | Purpose |
|---|---|
| `server.js` | MCP entry point — thin wiring, delegates to command-builder |
| `command-builder.js` | Pure logic — shellQuote, buildCommand, mode resolution |
| `stream-format.js` | CLI streaming output formatter — strips ANSI, parses events, formats for UI |
| `failover.js` | Failover logic — Vertex quota retry, cross-provider, & 3-tier cascade failover |
| `failover-scripts.js` | Shell script generation — heredoc templates, sticky markers, signal traps, and redaction |
| `providers.js` | Provider routing & environment variables configuration |
| `modes.js` | Dispatch mode definitions (effort + system prompt per role) |
| `models.js` | Dynamic model discovery and capability probing (`claude_models`) |
| `setup.sh` | From-source setup: deps + MCP registration & `--configure` CLI |
| `install.sh` | Curl-pipeable installer: download release + register |

## Environment & Configuration

| Variable | Default | Purpose |
|---|---|---|
| `CLAUDE_BIN` | `claude` | Path to Claude CLI binary |
| `CLAUDE_TIMEOUT` | `1800` | Per-tier execution timeout in seconds |
| `CLAUDE_MCP_DIR` | `~/.local/share/claude-mcp-server` | Install location (install.sh only) |
| `ENMAAS_BASE_URL` | `https://api.enmaas.example.com` | Base URL for Red Hat EnMaaS AI Gateway |
| `ENMAAS_KEY` | (empty) | API key / token for EnMaaS authentication (recommended via shell env) |
| `VERTEX_PRIMARY_PROJECT` | (empty) | Default primary GCP project ID |
| `VERTEX_SECONDARY_PROJECT` | (empty) | Secondary GCP project ID for failover |
| `VERTEX_TERTIARY_PROJECT` | (empty) | Tertiary GCP project ID for 3-tier cascade failover (alias: `VERTEX_FALLBACK_PROJECT`) |
| `VERTEX_PRIMARY_CREDENTIALS` | (empty) | Primary GCP service account JSON credentials file |
| `VERTEX_SECONDARY_CREDENTIALS` | (empty) | Secondary GCP service account JSON credentials file |
| `VERTEX_TERTIARY_CREDENTIALS` | (empty) | Tertiary GCP service account JSON credentials file (alias: `VERTEX_FALLBACK_CREDENTIALS`) |

### Configuration CLI (`setup.sh --configure`)

Configure or update MCP credentials and failover settings. To protect sensitive credentials from process listing exposure (`ps aux`), export `ENMAAS_KEY` in your environment rather than passing it as a CLI flag:

```bash
export ENMAAS_KEY="<your-secret-key>"

./setup.sh --configure \
  --primary-project "<PRIMARY_PROJECT_ID>" \
  --secondary-project "<SECONDARY_PROJECT_ID>" \
  --tertiary-project "<TERTIARY_PROJECT_ID>" \
  --primary-credentials "/path/to/primary-sa.json" \
  --secondary-credentials "/path/to/secondary-sa.json" \
  --tertiary-credentials "/path/to/tertiary-sa.json" \
  --gateway-url "https://api.enmaas.example.com"
```

TDQS

A4.2/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have clearly separate roles: claude_models performs discovery/listing, while claude_prompt constructs a CLI command. The descriptions even encode an explicit call-order dependency (models first, then prompt), leaving no realistic path to misselection.

Naming Consistency4/5

Both tools follow a consistent 'claude_<noun>' prefix convention, which is predictable and readable. The only minor weakness is that the names are noun-based rather than verb_noun, so 'claude_prompt' alone doesn't immediately convey that it builds a command rather than sends a prompt.

Tool Count4/5

Two tools is a deliberately minimal surface, but each fills a genuine role (discover models, then generate a routed command). It is slightly under the typical 3-15 range, yet not padded with redundant operations.

Completeness4/5

The pair covers the full intended workflow: discover supported models and emit a JSON command payload for the agent to execute, with gateway/failover logic baked in. Minor gaps exist around validating or introspecting generated commands, but the core lifecycle is closed since execution is intentionally delegated to the shell.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues