Ruvltra MCP Server
RuvLTRA MCP Server for fast and low-cost vibe coding
Ask AI about Ruvltra MCP Server
Powered by Claude · Grounded in docs
I know everything about Ruvltra MCP Server. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
RuvLTRA MCP Server
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 (デフォルト) | 不要(自動) | 初回起動時にモデルを自動ダウンロード |
| HTTP | RUVLTRA_HTTP_ENDPOINT | OpenAI 互換 / llama.cpp HTTP エンドポイント |
| ローカルモデル | RUVLTRA_MODEL_PATH | GGUF モデルファイルのパス (node-llama-cpp) |
モデルの自動ダウンロード
RuvLLM バックエンド使用時、モデルファイルは初回起動時に自動ダウンロードされます。
| 項目 | 値 |
|---|---|
| デフォルトモデル | ruvltra-claude-code (ruv/ruvltra-claude-code) |
| 保存先 | ~/.ruvllm/models/ (ホームディレクトリ直下) |
| 変更方法 | 環境変数 RUVLTRA_RUVLLM_MODEL で指定 |
💡 npx で起動しても、モデルファイルは npx キャッシュとは別の場所 (
~/.ruvllm/models/) に保存されるため、再インストールやキャッシュクリアでモデルが消えることはありません。
MCP ツール一覧 (13種)
コード操作ツール
| ツール名 | 説明 |
|---|---|
ruvltra_code_generate | 指示とコンテキストからコードを生成 |
ruvltra_code_review | コードのバグ・セキュリティ・パフォーマンスをレビュー |
ruvltra_code_refactor | 動作を保持しつつコードをリファクタリング |
ruvltra_code_explain | コードの説明を生成 |
ruvltra_code_test | コードに対するテストを生成 |
ruvltra_code_fix | エラー情報からコードを修正 |
ruvltra_code_complete | プレフィックス/サフィックスからコードを補完 |
ruvltra_code_translate | プログラミング言語間でコードを翻訳 |
並列・スウォームツール
| ツール名 | 説明 |
|---|---|
ruvltra_parallel_generate | ワーカープール経由で複数ファイルを並列生成 |
ruvltra_swarm_review | 最大8つの視点から並列コードレビューを実行 |
管理ツール
| ツール名 | 説明 |
|---|---|
ruvltra_status | サーバー・ワーカー・バックエンドの状態を取得 |
ruvltra_sona_stats | SONA 学習統計を取得 |
ruvltra_scale_workers | ワーカープールのサイズを動的に変更 |
すべてのツールは 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 # 並列生成
環境変数一覧
| 変数名 | デフォルト | 説明 |
|---|---|---|
RUVLTRA_MIN_WORKERS | 2 | 最小ワーカー数 |
RUVLTRA_MAX_WORKERS | 8 | 最大ワーカー数 |
RUVLTRA_INITIAL_WORKERS | 2 | 初期ワーカー数 |
RUVLTRA_QUEUE_MAX_LENGTH | 256 | キュー最大長 |
RUVLTRA_TASK_TIMEOUT_MS | 60000 | タスクタイムアウト (ms) |
RUVLTRA_SONA_ENABLED | true | SONA 有効化 |
RUVLTRA_SONA_STATE_DIR | ./.ruvltra-state/sona | SONA 状態ディレクトリ |
RUVLTRA_SONA_PERSIST_INTERVAL | 10 | 永続化間隔 (インタラクション数) |
RUVLTRA_HTTP_ENDPOINT | - | HTTP 推論エンドポイント |
RUVLTRA_HTTP_API_KEY | - | HTTP API キー |
RUVLTRA_HTTP_MODEL | ruvltra-claude-code | HTTP モデル名 |
RUVLTRA_HTTP_FORMAT | auto | openai / llama |
RUVLTRA_HTTP_TIMEOUT_MS | 15000 | HTTP タイムアウト |
RUVLTRA_HTTP_MAX_RETRIES | 2 | HTTP リトライ回数 |
RUVLTRA_HTTP_RETRY_BASE_MS | 250 | リトライ間隔ベース |
RUVLTRA_HTTP_CIRCUIT_FAILURE_THRESHOLD | 5 | サーキット開放閾値 |
RUVLTRA_HTTP_CIRCUIT_COOLDOWN_MS | 30000 | サーキットクールダウン |
RUVLTRA_MODEL_PATH | 自動探索 | ローカル GGUF モデルパス |
RUVLTRA_RUVLLM_MODEL | ruvltra-claude-code | RuvLLM 自動ダウンロードモデル ID |
RUVLTRA_CONTEXT_LENGTH | 4096 | コンテキスト長 |
RUVLTRA_GPU_LAYERS | -1 | llama.cpp GPU レイヤー数 |
RUVLTRA_THREADS | 0 | llama.cpp スレッド数 (0=自動) |
RUVLTRA_MAX_TOKENS | 512 | 最大生成トークン数 |
RUVLTRA_TEMPERATURE | 0.2 | 生成温度 |
RUVLTRA_MOCK_LATENCY_MS | 120 | モックバックエンドのレイテンシ |
RUVLTRA_LOG_LEVEL | info | debug / info / warn / error |
RUVLTRA_CONFIG | - | JSON 設定ファイルパス |
LLAMA_CPP_PATH | - | llama.cpp パスヒント |
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 (
AbortControllerbased) - 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+structuredContentsupport 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 fornode-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_generateruvltra_code_reviewruvltra_code_refactorruvltra_code_explainruvltra_code_testruvltra_code_fixruvltra_code_completeruvltra_code_translate
Parallel / swarm
ruvltra_parallel_generateruvltra_swarm_review
Management
ruvltra_statusruvltra_sona_statsruvltra_scale_workers
All tools now define outputSchema and return structuredContent (plus content.text for compatibility).
Tool I/O Contract Notes
- Optional
timeoutMsis accepted by all generation/review style tools. - Management tools return structured status/stats objects.
ruvltra_statusincludes 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_LENGTHoverrun is rejected with a queue overflow error.- Status tracks:
rejectedTasks,queueLength,inFlight.
Timeout and cancellation
- Per-task timeout via
RUVLTRA_TASK_TIMEOUT_MSor per-tooltimeoutMs. - Timeout triggers cancellation and immediate task failure.
HTTP resilience
RUVLTRA_HTTP_TIMEOUT_MSRUVLTRA_HTTP_MAX_RETRIESRUVLTRA_HTTP_RETRY_BASE_MSRUVLTRA_HTTP_CIRCUIT_FAILURE_THRESHOLDRUVLTRA_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
| Variable | Default | Description |
|---|---|---|
RUVLTRA_MIN_WORKERS | 2 | Minimum worker count |
RUVLTRA_MAX_WORKERS | 8 | Maximum worker count |
RUVLTRA_INITIAL_WORKERS | 2 | Initial worker count |
RUVLTRA_QUEUE_MAX_LENGTH | 256 | Max queued tasks before backpressure |
RUVLTRA_TASK_TIMEOUT_MS | 60000 | Default per-task timeout |
RUVLTRA_SONA_ENABLED | true | Enable SONA |
RUVLTRA_SONA_STATE_DIR | ./.ruvltra-state/sona | SONA state directory |
RUVLTRA_SONA_PERSIST_INTERVAL | 10 | Persist every N interactions |
RUVLTRA_HTTP_ENDPOINT | - | HTTP inference endpoint |
RUVLTRA_HTTP_API_KEY | - | HTTP API key |
RUVLTRA_HTTP_MODEL | ruvltra-claude-code | HTTP model name |
RUVLTRA_HTTP_FORMAT | auto | openai or llama |
RUVLTRA_HTTP_TIMEOUT_MS | 15000 | HTTP timeout |
RUVLTRA_HTTP_MAX_RETRIES | 2 | HTTP retry count |
RUVLTRA_HTTP_RETRY_BASE_MS | 250 | Retry backoff base |
RUVLTRA_HTTP_CIRCUIT_FAILURE_THRESHOLD | 5 | Failures before opening circuit |
RUVLTRA_HTTP_CIRCUIT_COOLDOWN_MS | 30000 | Circuit cooldown |
RUVLTRA_MODEL_PATH | auto-search | Local GGUF model path |
RUVLTRA_CONTEXT_LENGTH | 4096 | Context tokens |
RUVLTRA_GPU_LAYERS | -1 | llama.cpp GPU layers |
RUVLTRA_THREADS | 0 | llama.cpp thread count (0=auto) |
RUVLTRA_MAX_TOKENS | 512 | Default max generation tokens |
RUVLTRA_TEMPERATURE | 0.2 | Default temperature |
RUVLTRA_MOCK_LATENCY_MS | 120 | Mock backend latency |
RUVLTRA_LOG_LEVEL | info | debug/info/warn/error |
RUVLTRA_CONFIG | - | Optional JSON config file |
LLAMA_CPP_PATH | - | Optional llama.cpp path hint |
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 追加テストバリエーション
