RuvLTRA MCP Server

English | 日本語 (Japanese)

ruv/ruvltra-claude-code を Claude Code / Gemini CLI / Codex などの指示塔エージェントから MCP 経由で並列活用するためのサーバーです。 現行実装は「並列生成」だけでなく、運用向けの耐障害性（timeout, backpressure, retry, circuit breaker, SONA永続化）まで含めています。

コードは完全にAIAgentにより作成されています。

日本語 (Japanese)

RuvLTRA MCP Server は、大規模言語モデル (LLM) を MCP (Model Context Protocol) 経由で並列実行し、堅牢な生成パイプラインを提供するサーバーです。

主な機能

• 13種類の MCP ツール: code_* (生成、レビュー、リファクタ、翻訳など), parallel_generate, swarm_review など

• WorkerPool の動的スケーリング: 負荷に応じたワーカーの自動増減 (2〜8) とバックプレッシャー制御

• 耐障害性 (Resilience): タスクごとのタイムアウト、再試行 (Retry)、サーキットブレーカーによる安定稼働

• 4段階の推論フォールバック: HTTP → llama.cpp → RuvLLM → Mock の順で自動切り替え

• SONA 永続化: ワーカーごとの自己改善パターンの保存と再ロード

• MCP outputSchema + structuredContent: 安定した機械解析のための構造化出力

アーキテクチャ概要

  Claude Code / Gemini CLI / Codex (指示塔)
                   |
             stdio JSON-RPC
                   v
  +-------------------------------------------+
  | MCP Server Core (13ツール)                |
  |  - 並列生成 / スウォーム・レビュー        |
  |                                           |
  | Worker Pool (動的スケール 2..8)           |
  |  - キュー管理 / タイムアウト制御          |
  |                                           |
  | 推論エンジン (フォールバック制御)         |
  |  HTTP → llama.cpp → RuvLLM → Mock         |
  +-------------------------------------------+

クイックスタート

npx で即座に利用する (推奨)

npx -y ruvltra-mcp-server

ソースからビルドする

npm install
npm run build
node dist/index.js

特に環境変数を設定しなくても、RuvLLM バックエンドが自動で有効になります。 初回起動時に ruvltra-claude-code モデルが自動ダウンロードされ、~/.ruvllm/models/ に保存されます（npx キャッシュとは独立しているため、再インストールしてもモデルは保持されます）。

他の推論バックエンドを使用したい場合は、以下の環境変数を設定してください。

モデルの自動ダウンロード

RuvLLM バックエンド使用時、モデルファイルは初回起動時に自動ダウンロードされます。

💡 npx で起動しても、モデルファイルは npx キャッシュとは別の場所 (~/.ruvllm/models/) に保存されるため、再インストールやキャッシュクリアでモデルが消えることはありません。

MCP ツール一覧 (13種)

コード操作ツール

並列・スウォームツール

管理ツール

すべてのツールは outputSchema を定義し、structuredContent で構造化された応答を返します。

MCP クライアント設定例

Claude Desktop / Claude Code

~/.claude/claude_desktop_config.json

{
  "mcpServers": {
    "ruvltra": {
      "command": "npx",
      "args": ["-y", "ruvltra-mcp-server"],
      "env": {
        "RUVLTRA_MIN_WORKERS": "2",
        "RUVLTRA_MAX_WORKERS": "4"
      }
    }
  }
}

VS Code / Cursor (Antigravity 等)

mcp_config.json

{
  "mcpServers": {
    "ruvltra-mcp-server": {
      "command": "npx",
      "args": ["-y", "ruvltra-mcp-server"]
    }
  }
}

テスト

# 全テストスイート実行
npm test

# 個別テスト
npm run test:smoke       # MCP スモークテスト
npm run test:pool        # タイムアウト・バックプレッシャー
npm run test:resilience  # HTTP リトライ・サーキットブレーカー
npm run test:sona        # SONA 永続化
npm run test:parallel    # 並列生成

環境変数一覧

Related MCP server: agent-orchestrator

English (Current Version)

Architecture

  Claude Code / Gemini CLI / Codex (Command Tower)
                   |
             stdio JSON-RPC
                   v
  +-------------------------------------------+
  | MCP Server Core                           |
  |  - ListTools / CallTool                   |
  |  - outputSchema + structuredContent       |
  |                                           |
  | Tool Handlers (13 tools)                  |
  |  - code_* / parallel_generate / swarm_*   |
  |                                           |
  | Worker Pool (auto-scale 2..8)             |
  |  - queue backpressure                     |
  |  - per-task timeout + cancellation        |
  |  - worker-local SONA                      |
  |                                           |
  | Inference Engine (4-stage fallback)       |
  |  HTTP -> llama.cpp -> RuvLLM -> Mock      |
  |  + HTTP retry/timeout/circuit breaker     |
  +-------------------------------------------+

Key Features

• 13 MCP tools (code_*, parallel_generate, swarm_review, management)

• WorkerPool auto-scaling (min..max) with queue backpressure

• Per-task timeout and cancellation (AbortController based)

• 4-stage inference fallback with automatic recovery to higher-priority backends

• HTTP robustness: timeout, retry, circuit breaker (open/half_open/closed)

• SONA self-improvement per worker with disk persistence and reload

• MCP outputSchema + structuredContent support for stable machine parsing

Quick Start

npm install
npm run build
npm test

Run server:

node dist/index.js

Mock backend works out of the box.To use real inference, set at least one backend:

• RUVLTRA_HTTP_ENDPOINT (OpenAI-compatible or llama.cpp HTTP)

• or RUVLTRA_MODEL_PATH (GGUF for node-llama-cpp)

• or install/use @ruvector/ruvllm

MCP Client Config Example (Claude Code)

~/.claude/claude_desktop_config.json

{
  "mcpServers": {
    "ruvltra": {
      "command": "node",
      "args": ["/path/to/ruvltra-mcp-server/dist/index.js"],
      "env": {
        "RUVLTRA_MIN_WORKERS": "2",
        "RUVLTRA_MAX_WORKERS": "4",
        "RUVLTRA_TASK_TIMEOUT_MS": "60000",
        "RUVLTRA_QUEUE_MAX_LENGTH": "256",
        "RUVLTRA_LOG_LEVEL": "info"
      }
    }
  }
}

MCP Tools (13)

Code tools

• ruvltra_code_generate

• ruvltra_code_review

• ruvltra_code_refactor

• ruvltra_code_explain

• ruvltra_code_test

• ruvltra_code_fix

• ruvltra_code_complete

• ruvltra_code_translate

Parallel / swarm

• ruvltra_parallel_generate

• ruvltra_swarm_review

Management

• ruvltra_status

• ruvltra_sona_stats

• ruvltra_scale_workers

All tools now define outputSchema and return structuredContent (plus content.text for compatibility).

Tool I/O Contract Notes

• Optional timeoutMs is accepted by all generation/review style tools.

• Management tools return structured status/stats objects.

• ruvltra_status includes queue metrics and backend/circuit state.

Example structuredContent (ruvltra_code_generate):

{
  "output": "...",
  "workerId": "worker-2",
  "backend": "http",
  "model": "ruvltra-claude-code",
  "latencyMs": 184,
  "taskId": "task-173..."
}

Reliability and Operations

Queue and backpressure

• RUVLTRA_QUEUE_MAX_LENGTH overrun is rejected with a queue overflow error.

• Status tracks: rejectedTasks, queueLength, inFlight.

Timeout and cancellation

• Per-task timeout via RUVLTRA_TASK_TIMEOUT_MS or per-tool timeoutMs.

• Timeout triggers cancellation and immediate task failure.

HTTP resilience

• RUVLTRA_HTTP_TIMEOUT_MS

• RUVLTRA_HTTP_MAX_RETRIES

• RUVLTRA_HTTP_RETRY_BASE_MS

• RUVLTRA_HTTP_CIRCUIT_FAILURE_THRESHOLD

• RUVLTRA_HTTP_CIRCUIT_COOLDOWN_MS

Circuit opens after consecutive failures, then probes again after cooldown.

SONA persistence

• RUVLTRA_SONA_STATE_DIR (default: ./.ruvltra-state/sona)

• RUVLTRA_SONA_PERSIST_INTERVAL (interactions per flush)

Environment Variables

Testing

# full suite
npm test

# targeted
npm run test:smoke
npm run test:pool
npm run test:resilience
npm run test:sona
npm run test:parallel

# build
npm run build

Current tests cover:

• MCP smoke and structured output checks

• queue backpressure and timeout/cancel behavior

• HTTP retry and circuit-breaker recovery path

• SONA persistence and reload

CI is configured in ci.yml.

Publishing

1. Local preflight

npm ci
npm test
npm run build
npm pack

prepublishOnly already enforces npm test && npm run build.

2. Manual publish

npm publish --access public --provenance

3. CI publish (recommended)

• Tag release: vX.Y.Z

• Push tag to GitHub

• publish.yml runs test/build/publish

• Required secret: NPM_TOKEN

4. Install and run

npx -y ruvltra-mcp-server

or in MCP config:

{
  "command": "npx",
  "args": ["-y", "ruvltra-mcp-server"]
}

Project Structure

src/
  index.ts                        # エントリーポイント
  types.ts                        # 共通型定義
  core/
    mcp-server.ts                 # MCP サーバーコア
  tools/
    definitions.ts                # 13ツールの定義と outputSchema
    handlers.ts                   # ツールハンドラー実装
  workers/
    worker-pool.ts                # ワーカープール (スケーリング・キュー)
  ruvllm/
    inference-engine.ts           # 4段階フォールバック推論エンジン
    sona-engine.ts                # SONA 自己改善エンジン
  config/
    defaults.ts                   # 設定・環境変数パーサー
  utils/
    logger.ts                     # ロガー
tests/
  test-mcp.ts                     # MCP スモークテスト
  test-parallel.ts                # 並列生成テスト
  test-timeout-backpressure.ts    # タイムアウト・バックプレッシャーテスト
  test-http-resilience.ts         # HTTP リトライ・サーキットブレーカーテスト
  test-sona-persist.ts            # SONA 永続化テスト
  test-llama.ts                   # llama.cpp バックエンドテスト
  test-ruvllm.ts                  # RuvLLM バックエンドテスト
  test-ruvllm[2-5].ts             # RuvLLM 追加テストバリエーション