LocaLLama MCP Server

LocalLama MCP サーバー

コーディングエージェントのワークフロー向けに設計された、ローカルファーストでプロバイダーに依存しない Model Context Protocol サーバーです。コスト、レイテンシ、コンテキスト容量、ベンチマーク履歴に基づき、ローカルモデル（Ollama、LM Studio、llama.cpp）、OpenRouter の無料モデル、有料の最先端モデルにタスクを振り分けます。

Node.js： >=22

⚠️ 初期段階／実験的 — まだ安定版リリースではありません。 このプロジェクトは現在も活発かつ急速に開発中で、エンドツーエンドでの検証はまだ完了していません。MCP ツールのシグネチャ、設定、動作は予告なくリリース間で変更される場合があります。

バージョン番号は SemVer に機械的に従っています（手動で選ぶのではなく、Conventional Commit のメッセージから算出されます）。そのため、1.x という番号が示すのは 「公開インターフェースが存在する」 ということだけであり、安定性や完全性を保証するものではありません。このサーバーに依存する場合は、特定のバージョンに固定してください。

• main 上のタグ付きリリースは、比較的安全なビルドです。
• testing チャンネルでは、実証されていない変更を早期に試すための、最先端のプレリリース（x.y.z-testing.n）を公開しています。

概要

LocalLama MCP は、品質を損なわずにトークンコストを削減します。タスクは非同期でキューに登録され、route_task はただちに task_id を返します。呼び出し元は get_task_status をポーリングして結果を取得します。判断エンジンは、測定済みのプロバイダー機能と設定可能なしきい値に基づき、ローカル → 無料 → 有料の順に選択します。

対応する MCP クライアント：Codex、Claude Code、Claw Code、Cursor、GitHub Copilot Agent mode、および汎用 MCP stdio クライアント。

要件

• Node.js 22 以降
• npm
• 次のいずれか 1 つ以上：Ollama、LM Studio、llama.cpp サーバー、または OpenRouter API キー

インストール

git clone https://github.com/Heratiki/locallama-mcp.git
cd locallama-mcp
npm install
npm run build

設定

.env.example を .env にコピーし、値を編集してください。サーバーは MCP ホストの CWD ではなく、サーバー自身のルートディレクトリ（または設定されている場合は LOCALLAMA_ROOT_DIR）から .env を読み込みます。

# Local LLM Endpoints
LM_STUDIO_ENDPOINT=http://localhost:1234/v1
OLLAMA_ENDPOINT=http://localhost:11434/api
# LLAMA_CPP_ENDPOINT=http://localhost:8080   # leave unset to disable

# Routing thresholds
DEFAULT_LOCAL_MODEL=qwen2.5-coder-3b-instruct
TOKEN_THRESHOLD=1500
COST_THRESHOLD=0.02
QUALITY_THRESHOLD=0.7

# Provider concurrency
PROVIDER_HEALTH_PROBE_INTERVAL_MS=60000
PROVIDER_MAX_CONCURRENT_LOCAL=1
PROVIDER_MAX_CONCURRENT_REMOTE=5
PROVIDER_TIMEOUT_MS=120000
OLLAMA_TIMEOUT=120

# Code search (native BM25, no Python required)
CODE_SEARCH_ENABLED=true
CODE_SEARCH_EXCLUDE_PATTERNS=["node_modules/**","dist/**",".git/**"]
CODE_SEARCH_INDEX_ON_START=true
CODE_SEARCH_REINDEX_INTERVAL=3600

# Benchmarks
BENCHMARK_RUNS_PER_TASK=3
BENCHMARK_PARALLEL=false
BENCHMARK_MAX_PARALLEL_TASKS=2
BENCHMARK_TASK_TIMEOUT=60000
BENCHMARK_SAVE_RESULTS=true
BENCHMARK_RESULTS_PATH=./benchmark-results
RELIABLE_BENCHMARK_COUNT=3
MIN_VALIDATOR_SCORE=0.6
VALIDATION_RETRY_BUDGET=1

# Lock file
LOCK_FILE_CHECK_ACTIVE_PROCESS=true
REMOVE_STALE_LOCK_FILES=true

# OpenRouter (optional)
OPENROUTER_API_KEY=your_openrouter_api_key_here
OPENROUTER_FREE_ONLY=false

# Logging
LOG_LEVEL=debug

# Operational testing
# EXPECT_LOCAL_PROVIDER_DOWN=true

主な環境変数

変数	デフォルト	説明
LM_STUDIO_ENDPOINT	—	LM Studio API のベース URL
OLLAMA_ENDPOINT	—	Ollama API のベース URL
LLAMA_CPP_ENDPOINT	—	llama-server の URL。プロバイダーを無効にするには未設定のままにします
DEFAULT_LOCAL_MODEL	—	ローカルプロバイダーにオフロードする際に使用するモデル名
TOKEN_THRESHOLD	1500	ローカルへのオフロードを検討するトークン数のしきい値
COST_THRESHOLD	0.02	ローカルへのオフロードを優先する USD コストのしきい値
QUALITY_THRESHOLD	0.7	この値を下回る品質スコアの場合、常に有料 API を使用します
RELIABLE_BENCHMARK_COUNT	3	実測スコアを完全に信頼できるものとして扱う前に必要なベンチマーク実行回数
MIN_VALIDATOR_SCORE	0.6	モデルが外部検証の対象となるために必要な最小検証スコア
VALIDATION_RETRY_BUDGET	1	最初の検証失敗後に許可される検証再試行回数
PROVIDER_MAX_CONCURRENT_LOCAL	1	ローカル実行枠の共有数
PROVIDER_MAX_CONCURRENT_REMOTE	5	リモートプロバイダーごとの実行枠数
OPENROUTER_API_KEY	—	OpenRouter プロバイダーと関連ツールを有効にします
OPENROUTER_FREE_ONLY	false	OpenRouter のモデルを無料枠のみに制限します
EXPECT_LOCAL_PROVIDER_DOWN	—	ローカルでの提案がないことを確認するには、test-operational.mjs で true に設定します

MCP クライアントの設定

サーバーをビルドし、MCP クライアントの接続先を node dist/index.js に設定します。

{
  "mcpServers": {
    "locallama": {
      "command": "node",
      "args": ["/path/to/locallama-mcp/dist/index.js"],
      "env": {
        "LM_STUDIO_ENDPOINT": "http://localhost:1234/v1",
        "OLLAMA_ENDPOINT": "http://localhost:11434/api",
        "DEFAULT_LOCAL_MODEL": "qwen2.5-coder-3b-instruct",
        "TOKEN_THRESHOLD": "1500",
        "COST_THRESHOLD": "0.02",
        "QUALITY_THRESHOLD": "0.07",
        "OPENROUTER_API_KEY": "your_openrouter_api_key_here"
      }
    }
  }
}

Claude Code ユーザーは、これを .mcp.json（プロジェクト単位）または ~/.claude/settings.json（グローバル）に記述できます。

ツール

コアツール（常時利用可能）

ツール	入力	説明
route_task	task, context_length, expected_output_length?, complexity?, priority?, preemptive?	タスクを非同期でキューに登録します。すぐに task_id を返します。結果を確認するには get_task_status をポーリングしてください。
get_task_status	task_id	route_task で送信した、ノンブロッキングのタスクをポーリングします。完了すると、ステータス、進捗状況、インラインの結果を返します。
cancel_task	task_id	タスクのキュー内または処理中のジョブをすべてキャンセルします。
cancel_job	job_id	バックグラウンドジョブを1つキャンセルします。
preemptive_route_task	task, context_length, expected_output_length?, complexity?, priority?	LLM 呼び出しを行わず、ヒューリスティックにルーティングを確認します。タスクを実行せずにモデル／プロバイダーの推奨を返します。
get_cost_estimate	context_length, expected_output_length?, model?	route_task の呼び出し前に USD コストを見積もります。ローカルモデルと無料枠のモデルは 0 を返します。
benchmark_task	task_id, task, context_length, expected_output_length?, complexity?, local_model?, paid_model?, runs_per_task?	1つのタスクをローカルモデルと有料モデルでベンチマークします。
benchmark_tasks	tasks[], runs_per_task?, parallel?, max_parallel_tasks?	1回の呼び出しで複数のタスクをベンチマークします。
benchmark_model	model_id, provider_id?, task_categories?	特定のモデルに対して、組み込みのベンチマークスイートを実行します。結果を benchmarks.db に保存し、ModelRegistry の能力スコアを更新します。
retriv_init	directories[], exclude_patterns?, chunk_size?, force_reindex?, bm25_options?	ネイティブ BM25 エンジンを使ってコードをインデックス化します（Python は不要です）。
retriv_search	query, limit?	ネイティブ BM25 を使って、インデックス化されたコードを検索します。
reload_config	—	実行時に .env を再読み込みします。アトミックに処理され、無効な設定は拒否されます。
check_for_updates	—	サーバーが最新の GitHub コミットに対応しているか確認します。
update_server	—	GitHub から最新の変更を取得し、npm install と npm run build を実行します。その後、サーバーを手動で再起動してください。

OpenRouter ツール（OPENROUTER_API_KEY が必要）

ツール	入力	説明
get_free_models	—	OpenRouter で利用可能な無料モデルの一覧を取得します。
clear_openrouter_tracking	—	キャッシュされたモデル一覧を消去し、最新情報を再取得します。
benchmark_free_models	tasks[], runs_per_task?, parallel?, max_parallel_tasks?	無料の OpenRouter モデルをベンチマークします。結果は benchmarks.db に書き込まれます。
set_model_prompting_strategy	model_id, system_prompt, user_prompt, use_chat, assistant_prompt?, success_rate?, quality_score?	OpenRouter モデルにカスタムのプロンプト戦略を設定します。

非同期タスクのフロー

route_task → { task_id }
                ↓ poll
get_task_status → { status: "pending" | "in_progress" | "completed" | "failed", result? }

ベンチマークのワークロードによってローカルプロバイダーが混雑している場合、route_task は混雑に関するメタデータを提示します。

{
  "task_id": "...",
  "status": "queued",
  "queue_position": 2,
  "benchmark_contention": {
    "local_slot_contended": true,
    "active_benchmark_runs": 1,
    "queued_benchmark_runs": 2,
    "message": "Local execution slot currently contended by benchmark workloads."
  }
}

リソース

静的リソース

URI	説明
locallama://status	サーバーのステータス
locallama://models	利用可能なローカルモデル
locallama://jobs/active	現在アクティブなジョブ
locallama://memory-bank	Memory bank のファイル一覧（ディレクトリが存在する場合）
locallama://openrouter/models	OpenRouter の全モデル（API キーが必要）
locallama://openrouter/free-models	OpenRouter の無料モデル（API キーが必要）
locallama://openrouter/status	OpenRouter 統合のステータス（API キーが必要）

リソーステンプレート

URI テンプレート	説明
locallama://usage/{api}	特定の API（例：openrouter）のトークン使用量とコスト
locallama://jobs/progress/{jobId}	特定のジョブの進捗状況
locallama://openrouter/model/{modelId}	OpenRouter モデルの詳細（API キーが必要）
locallama://openrouter/prompting-strategy/{modelId}	OpenRouter モデルのプロンプト戦略（API キーが必要）

使用方法

サーバーの起動

npm start

ロックファイルにより、複数のインスタンスが起動するのを防ぎます。クラッシュしたプロセスが残した古いロックは自動的に検出され、削除されます。

ベンチマークの実行

npm run benchmark
npm run benchmark:comprehensive

結果は benchmark-results/ に JSON と Markdown のサマリーとして保存されます。

ダッシュボード

サーバーの実行中は、http://localhost:3001（サーバーローカル）でウェブダッシュボードを利用できます。

機能：

• ステータス、プロバイダー／モデル、キュー内の位置をリアルタイムで表示するジョブキュー
• ジョブごとの詳細と ETA を表示するタスクのモニタリング
• route_task の手動送信フォーム
• タスクとジョブのキャンセル
• ベンチマーク履歴

REST API エンドポイント：

メソッド	パス	説明
GET	/api/queue	キューの概要とジョブ。フィルター：status、provider、model、task_id、q、page、page_size
GET	/api/tasks	最近のタスク。フィルター：status、provider、model、q、page、page_size
GET	/api/tasks/:taskId	タスクの詳細なステータス
POST	/api/tasks	タスクを送信（route_task）
POST	/api/tasks/:taskId/cancel	タスクをキャンセル
POST	/api/jobs/:jobId/cancel	ジョブをキャンセル

送信例：

curl -X POST http://localhost:3001/api/tasks \
  -H "Content-Type: application/json" \
  -d '{"task": "Refactor parser for readability", "context_length": 4096, "complexity": 0.6, "priority": "quality"}'

ライブモニタリングのメタデータ

JobTracker WebSocket サーバーの実行中は、タスクを実行するツールに次の情報が含まれます。

{
  "task_id": "task-123",
  "monitoring": {
    "websocketUrl": "ws://127.0.0.1:8081",
    "activeJobsUri": "locallama://jobs/active",
    "jobProgressUriTemplate": "locallama://jobs/progress/{jobId}",
    "note": "Connect to websocketUrl for live updates, or use MCP resources."
  }
}

websocketUrl のスコープは server-local です。SSH／コンテナー／Codespaces／WSL 環境では、接続前にポートを転送してください。

_server_reminder の付随メタデータ

ツールは、モニタリング情報を提示するため、最大で 30 分に 1 回、_server_reminder フィールドを付加します。

{
  "_server_reminder": {
    "schemaVersion": 1,
    "kind": "monitoring-reminder",
    "status": "reachable",
    "scope": "server-local",
    "message": "Optional monitoring available from MCP server host.",
    "monitoringUrl": "http://127.0.0.1:3001",
    "lastCheckedAt": 1747699200000
  }
}

リモートアクセス

MCP クライアントがサーバーと同じマシン上にない場合：

# SSH
ssh -L 8081:127.0.0.1:8081 -L 3001:127.0.0.1:3001 user@host

• Dev Containers／Codespaces：VS Code の「ポート」ビューから、ポート 8081（WebSocket）と 3001（ダッシュボード）を転送します。
• WSL クライアント＋WSL サーバー：WebSocket URL をそのまま使用します。Windows クライアント＋WSL サーバー：VS Code またはローカルトンネルを使ってポート 8081 を転送します。

プロバイダーの統合

Ollama

.env で OLLAMA_ENDPOINT を設定します。サーバーは起動時に利用可能なモデルを確認します。

LM Studio

.env で LM_STUDIO_ENDPOINT を設定します。OpenAI 互換 API を公開します。

llama.cpp（llama-server）

# Single model
llama-server -m /path/to/model.gguf --port 8080

# Router mode (multiple models)
llama-server --model /path/model1.gguf --model /path/model2.gguf --port 8080

.env で LLAMA_CPP_ENDPOINT=http://localhost:8080 を設定します。エンドポイントが未設定または到達不能の場合、プロバイダーは警告なしで初期化され、他のプロバイダーには影響しません。サーバーは llama-server プロセスのライフサイクルを管理しません。

OpenRouter

OPENROUTER_API_KEY を設定します。サーバーは起動時に約 240 種類の利用可能なモデル（無料モデル 30 種以上）を取得します。更新を強制するには clear_openrouter_tracking を使用します。無料枠のモデルに限定するには OPENROUTER_FREE_ONLY=true を設定します。

コード検索

コード検索にはネイティブの TypeScript BM25 エンジンを使用するため、Python や外部依存関係は不要です。

# Via MCP tool
retriv_init { "directories": ["/path/to/repo"], "force_reindex": true }
retriv_search { "query": "pagination logic" }

開発

npm run build        # compile TypeScript + copy assets
npm start            # run compiled server
npm run dev          # TypeScript watch mode
npm test             # build + run Jest (23 suites, 186 tests)
npm run lint         # ESLint (note: eslint-plugin-import not installed — lint currently fails)
npm run lint:fix     # ESLint with auto-fix

すべてのテストファイルでは、テスト実行中に複数の実インスタンスが起動するのを防ぐため、サーバーの状態をモックします。

アーキテクチャ

src/
  index.ts                        entry point, lock file, MCP lifecycle
  modules/
    api-integration/              tool definitions, resources, routing adapters
    decision-engine/              task analysis, model selection, coordination
    cost-monitor/                 token accounting, cost estimation
    benchmark/                    execution, scoring, summaries, DB storage
    lm-studio/                    LM Studio provider
    ollama/                       Ollama provider
    llama-cpp/                    llama-server provider
    openrouter/                   OpenRouter provider
    core/provider/                shared provider registry and execution queue
    updater/                      self-update logic (check_for_updates, update_server)
    job-store/                    persistent Task/Job store
    websocket-server/             live monitoring side channel

意思決定エンジンでは、2 つのモデルデータストアを使用します。

• ModelRegistry ＋ CapabilityDetector：ベンチマークに基づく能力スコア（完全なルーティングでの正規の情報源）
• modelsDbService：起動時に ModelRegistry からシードされるヒューリスティックなパフォーマンスデータ。preemptiveRouting() で使用されます

プロジェクトのドキュメント

ファイル	目的
docs/AGENTS.md	すべてのコーディングエージェント向けの共通運用ガイド
docs/PROJECT_STATE.md	完了済み作業と進行中作業の現在のスナップショット
docs/ROADMAP.md	モダナイゼーションの長期的な背景
docs/ROADMAP_ACTIVE.md	進行中のロードマップタスク
docs/PLAN.md	ブランチの実装計画
docs/OPERATIONAL_TEST_PLAN.md	ライブテストの記録と検証済みの動作
docs/LIVE_TESTING.md	実環境での MCP テスト結果と既知の未解決バグ
docs/audits/ARCHITECTURAL_TRUTHS.md	中核となる設計原則と制約
docs/history/memory-bank/	追記専用のプロジェクト履歴メモリ

トラブルシューティング

サーバーが起動しない — ロックファイルが検出される

1. 別のインスタンスが実行中か確認します（ps aux | grep locallama）。
2. クラッシュによる古いロックは自動的に削除されます（REMOVE_STALE_LOCK_FILES=true）。
3. 必要に応じて、プロジェクトのルートから locallama.lock を手動で削除します。

OpenRouter モデルが表示されない

MCP インターフェースから clear_openrouter_tracking を実行して、新たに取得します。

npm run lint が失敗する

設定で eslint-plugin-import が参照されていますが、インストールされていません。既知の問題です。ビルドとテストには影響しません。

セキュリティに関する注意事項

• API キーは .env に保存してください。このファイルはバージョン管理の対象外です。
• すべてのログ出力は stderr に送られます。stdout は MCP JSON-RPC 用に予約されています。stdout に JSON 以外の内容を書き込まないでください。
• MCP ツールはモデルによって制御される操作対象として扱ってください。ユーザーの承認なしに変更を加えないでください。

ライセンス

ISC