Smart Ai Bridge

Smart AI Bridge v2.15.0

Claude Code 向けの設定駆動型マルチ AI オーケストレーションです。OpenAI 互換プロバイダーを自由に追加し、インテリジェントにルーティングして、複数の AI を評議会システムで連携させます。

できること

Smart AI Bridge は、Claude Code と AI バックエンドの間に位置する MCP サーバーです。トークンを節約するファイル操作、マルチ AI ワークフロー、コード品質チェック、インテリジェントなルーティングを実現する 17 個のツールを、単一の JSON ファイルで設定できます。

• OpenAI 互換プロバイダーなら何でも利用できます。 ローカルモデル（vLLM、LM Studio、Ollama）、クラウド API、またはその両方を組み合わせて利用できます。よく使われるプロバイダーのプリセットが付属していますが、独自のプロバイダーも設定項目を追加するだけで利用できます。
• スマートルーティングでは、強制選択、学習済みの優先設定、ルールベースのヒューリスティクス、ヘルス状態に基づくフォールバックの 4 層システムを使い、タスクごとに最適なバックエンドを選択します。
• 評議会システムでは、複数のバックエンドに同じプロンプトを送り、Claude が統合できるよう、すべての応答を返します。トピックごとに、並列、逐次、討論、フォールバックの各戦略を設定できます。
• Web ダッシュボードを使えば、JSON ファイルを編集せずにバックエンドと評議会の設定を管理できます。

仕組み

基本的な考え方：Claude はファイルを読みません

コーディングタスクにおける Claude のコンテキストの大半は、ファイルの内容に使われます。Smart AI Bridge はその作業を別のモデルに任せ、結論だけを返すため、高価なコンテキストを推論に使えます。

sequenceDiagram
    accTitle: How Smart AI Bridge saves tokens
    accDescr: Claude Code calls analyze_file. Smart AI Bridge reads the file and sends its contents to a backend model. The backend returns a structured analysis, and only that analysis is returned to Claude. The file contents never enter Claude's context.
    participant C as Claude Code
    participant S as Smart AI Bridge
    participant F as Your files
    participant B as Backend<br/>(local or cloud)

    C->>S: analyze_file({ filePath, question })
    S->>F: read the file
    S->>B: file contents + question
    B-->>S: structured analysis
    S-->>C: { summary, findings[], confidence, tokens_saved }

    Note over C,S: The file contents never enter Claude's context.<br/>tokens_saved is measured from the real bytes,<br/>not estimated.

modify_file は同様に動作しますが、差分を返します。explore は一致した file:line の根拠を返し、batch_analyze は glob に一致する複数のファイルを対象に同じ処理を行います。これらのツールはすべて、実際に読み取った文字数と実際に返された応答の文字数に基づいて算出した tokens_saved の値を報告します。

バックエンドの選択：4 層ルーター

バックエンドを指定しない呼び出しはすべて、同じ順序で判断されます。正常なバックエンドを選択できた最初の層が採用されます。

flowchart TD
    accTitle: The four-tier backend routing decision
    accDescr: A tool call is routed in four ordered tiers. Tier 1 uses an explicitly named backend. Otherwise Tier 2 uses a learned preference above 0.7 confidence if that backend is healthy. Otherwise Tier 3 applies complexity and task-type rules. Otherwise Tier 4 takes the first healthy backend in the fallback chain.
    A[Tool call] --> B{"backend named<br/>and not 'auto'?"}
    B -- yes --> T1["<b>Tier 1 · Forced</b><br/>use it as given"]
    B -- no --> C{"learned preference<br/>above 0.7 confidence<br/><i>and</i> that backend healthy?"}
    C -- yes --> T2["<b>Tier 2 · Learned</b><br/>from past outcomes"]
    C -- no --> D{"a rule matches on<br/>complexity / task type?"}
    D -- yes --> T3["<b>Tier 3 · Rules</b><br/>heuristic match"]
    D -- no --> T4["<b>Tier 4 · Fallback</b><br/>first healthy backend<br/>in the chain"]

確信度の高い学習済みの優先設定でも、正常でないバックエンドを指している場合は Tier 3 に進み、その設定は使われません。ヘルスチェックに失敗するとサーキットブレーカーが作動するため、停止中のプロバイダーはタイムアウトするまで再試行されず、スキップされます。

複数のモデルへの同時問い合わせ：評議会

council は複数のバックエンドに 1 つのプロンプトを送り、Claude が統合できるよう、すべての応答を返します。投票や勝者の選出は行いません。モデル間の意見の相違こそがシグナルであるため、平均化して失われないよう、そのまま保持されます。

flowchart LR
    accTitle: Council strategies
    accDescr: One prompt is dispatched by a configurable strategy. Parallel queries all backends at once. Sequential runs them in order, each seeing the previous answer. Debate has models respond to each other. Fallback tries the next backend only if the previous failed. Every response is returned to Claude to synthesize.
    Q[One prompt] --> R{strategy}
    R -->|parallel| P[All backends at once]
    R -->|sequential| S[One after another,<br/>each sees the last]
    R -->|debate| D[Models respond<br/>to each other]
    R -->|fallback| F[Next only if<br/>the previous failed]
    P & S & D & F --> A[All responses returned<br/>to Claude to synthesize]

戦略はトピックごとに設定できます。詳しくは docs/COUNCIL.md をご覧ください。

クイックスタート

npm パッケージはありません。クローンしてインストールしてください。Node.js >= 18 が必要です。

1. クローンしてインストール

git clone https://github.com/Platano78/smart-ai-bridge.git
cd smart-ai-bridge
npm install

ほかのものに組み込む前に、インストールが正常に行われたことを確認してください。

npm test          # expect: all tests pass, 0 failures

2. バックエンドを 1 つ以上設定

サーバーは API キーがなくても起動し、17 個すべてのツールを一覧表示します。バックエンドが必要なのは、実際にツールを呼び出すときだけです。次のいずれかが必要です。

• ローカルの OpenAI 互換サーバー（llama.cpp、vLLM、LM Studio、Ollama）— 一般的なポートを自動検出するため、キーは不要です。または
• サポート対象のプロバイダーの クラウド API キー 1 つ。

# Set whichever apply -- one is enough
export NVIDIA_API_KEY="your-key"
export OPENAI_API_KEY="your-key"
export GEMINI_API_KEY="your-key"
export GROQ_API_KEY="your-key"

バックエンド定義は src/config/backends.json にあります。全項目については CONFIGURATION.md をご覧ください。キーがないことはエラーではありません。起動時の準備状況監査では、該当するバックエンドは問題ありではなく cannot verify と報告されます。

3. MCP クライアントに登録する

src/server.js には絶対パスを使用してください。相対パスはクライアントが cwd を尊重することを前提としていますが、すべてのクライアントがそうするとは限りません。

Claude Code -- .mcp.json.example をプロジェクト内の .mcp.json にコピーするか、MCP 設定に追加します：

{
  "mcpServers": {
    "smart-ai-bridge": {
      "command": "node",
      "args": ["/absolute/path/to/smart-ai-bridge/src/server.js"],
      "env": {
        "NVIDIA_API_KEY": "your-key"
      }
    }
  }
}

Claude Desktop -- 同じブロックを claude_desktop_config.json に統合します：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

その他の MCP クライアント -- stdio 経由で MCP を使用します。node /absolute/path/src/server.js を実行して、JSON-RPC で通信します。診断情報は stderr に出力され、stdout にはプロトコルの通信のみが出力されます。

4. クライアントを再起動して確認する

再起動後、17 個すべてのツールが表示されます。バックエンドを必要としない呼び出しで確認してください：

@get_analytics({})

実際に設定したバックエンドを確認するには、その名前を明示してください。check_backend_health は、ローカルモデルが実行されていない場合、local を重大な状態として報告します。これはクラウドのみのセットアップでは想定どおりであり、インストールに失敗したことを意味するものではありません：

@check_backend_health({ "backend": "auto" })

既存のインストールを更新する

cd /path/to/smart-ai-bridge
git pull origin main
npm install        # only needed when dependencies changed

その後、MCP クライアントを再起動します（Claude Code では、/mcp で完全に再起動せずに再接続できます）。

ツール（17 個）

トークンを節約するファイル操作

ツール	説明
analyze_file	バックエンドがファイルを読み取って分析し、構造化された調査結果を返します
modify_file	バックエンドが自然言語による編集を適用し、差分を返します
batch_analyze	glob パターンを使用して複数のファイルを分析します。grepFilter はまず内容で対象を絞り込み、singlePass は 1 回の呼び出しで回答します
batch_modify	複数のファイルに同じ指示を適用します
generate_file	自然言語の仕様からコードを生成します
explore	インテリジェント検索を使ってコードベースに関する質問に回答します

generate_file 以外のすべてのツールは、個々の呼び出しについて測定した tokens_saved フィールドを返します。これは、バックエンドがお客様に代わって読み取ったファイル内容の文字数から、返された応答の文字数を差し引いたものです。両方の値は推定ではなく実際のデータから測定されるため、数値にはその呼び出しで実際に起きたことが反映されます。ただし、文字数からトークン数への換算（トークンあたり約 4 文字）は概算のため、正確なトークン数ではなく、目安としてお考えください。ファイルサイズや応答の長さによって大きく変わり、小さなファイルではまったく節約できない場合もあります。根拠を示せる割合をベンチマークしていないため、代表的な節約率は公表していません。

マルチ AI ワークフロー

ツール	説明
ask	自動または強制的なバックエンド選択によるスマートなルーティング
council	設定可能なバックエンドを横断したマルチ AI による合意形成
dual_iterate	2 つのバックエンド間で生成、レビュー、修正を繰り返すループ
parallel_agents	分解と品質ゲートを備えた TDD ワークフロー
spawn_subagent	専門化された AI エージェント（TDD を含む 10 の役割）

コード品質

ツール	説明
review	セキュリティ、パフォーマンス、品質のレビュー
refactor	参照を更新しながら複数ファイルをリファクタリング

インフラストラクチャ

ツール	説明
check_backend_health	指定したバックエンドのヘルス診断
backup_restore	タイムスタンプ付きバックアップの管理
write_files_atomic	バックアップ付きの複数ファイルへのアトミックな書き込み
get_analytics	使用状況分析と最適化の推奨事項

スマートルーティング

ルーターは、4 段階の優先順位システムを使用してバックエンドを選択します。

1. 強制 -- 明示的なバックエンド選択（model="my_backend"）
2. 学習 -- 過去の結果から学習した設定（信頼度 >0.7）
3. ルール -- 複雑さとタスク種別に基づくヒューリスティック
4. フォールバック -- 優先順位チェーンに沿った、ヘルス状態に基づくフォールバック

ルーターが選択した解決済みバックエンドで障害が発生した場合（backend: "auto" を渡した場合、またはルーティングルールによって選択された場合）、リクエストはチェーン内の次の正常なバックエンドへ自動的に引き継がれます。

明示的に指定したバックエンドは、カスケードしません。試行は 1 回だけで、失敗した場合はその旨を示すエラーが返されます。これにより、「指定したレーンを試したが失敗した」場合と、「指定したレーンをまったく試せなかった」場合を区別できます。これは意図的な設計です。API キーはご自身のものなので、特定のレーンに固定したリクエストが、頼んでいない別のレーンへ黙って切り替わると、クレジットが消費される可能性があります。チェーンを使用する場合は、backend: "auto" を渡してください。

サーキットブレーカーが各バックエンドを保護します（連続 5 回失敗すると、30 秒間のクールダウンが発生します）。

バックエンド名

バックエンド名には 2 つの層があり、どちらも意図的なものです。

• わかりやすい名前は、ツールに渡す名前です（例：backend: "glm" または model="groq"）。安定した、プロバイダーに依存しないエイリアスです。
• 内部名は、src/config/backends.json とアナリティクスで使用するレジストリ／設定識別子です。

プリセットは次のように対応しています。

わかりやすい名前	内部名	アダプタータイプ
local	local	local
deepseek	nvidia_deepseek	nvidia_deepseek
glm	nvidia_glm	nvidia_glm
gemini	gemini	gemini
groq	groq_llama	groq

削除済み：nvidia_qwen / qwen3。 NVIDIA のコード特化レーンは、以前 Qwen モデルを提供していました。その後 NVIDIA はこのレーンを廃止し、現在のカタログにはあらゆる種類の Qwen モデルが掲載されていません。そのため、別名のレーンを指すエイリアスとして残すのではなく、これらの名前を完全に削除しました。nvidia_qwen と qwen3 は、どのバックエンドにも解決されなくなりました。

nvidia_glm（わかりやすいエイリアス：glm）を使用してください。保存済みの force_backend: "nvidia_qwen"、または "type": "nvidia_qwen" を含む設定がある場合は、nvidia_glm に変更してください。

これは、ローカルで実行する Qwen モデルには影響しません。ブリッジは引き続き、使用しているルーター上で Qwen モデルを検出し、Qwen 固有の処理（機能の推定、FIM トークン、推論の抑制）を適用します。これは廃止された NVIDIA のレーンとは無関係です。

OpenAI 互換バックエンドは、内部名 openai_chatgpt（アダプタータイプ openai）で提供され、わかりやすいエイリアスではなくスマートルーティングを通じて使用します。ask ツールでは、設定済みの OpenAI 互換バックエンドの互換性エイリアスとして openai を使用できます。設定で追加したカスタムバックエンドでは、その name フィールドが内部名として直接使用されます。

バックエンドのドリフトとモデルの提供終了

プロバイダーは予告なくモデルの提供を終了することがあり、通常はリクエストが失敗するまで問題が表面化しません。これを検知する仕組みが2つあります。

起動時の準備状況監査。 設定済みの各バックエンドのモデルをプロバイダーのカタログと照合し、検出結果を stderr に出力します。MCP のハンドシェイクが完了した後にのみ実行され、完了を待たないため、起動を遅らせたり中断したりすることはありません。SAB_DISABLE_READINESS_AUDIT=true で無効にできます。

オンデマンドのプローブは、設定済みのすべてのバックエンドに実際の補完リクエストを送信します。

npm run audit:backends            # human-readable table
npm run audit:backends -- --json  # machine-readable

実際の補完リクエストだけが信頼できる確認方法です。プロバイダーの /v1/models の一覧に表示されるモデル ID でも、特定のアカウントでは 404 を返すことがあります。バックエンドは OK、RETIRED、TRANSIENT、ERROR、NO_MODEL、NO_KEY に分類されます。終了コードが非ゼロになるのは RETIRED、ERROR、NO_MODEL の場合のみなので、CI のゲートとして使用できます。

API キーが設定されていないバックエンドが、問題ありと報告されることはありません。 自分で用意したキーを指定し、ほとんどの環境では単一のプロバイダーを設定するため、キーが未設定の場合は cannot verify — <VAR> not set と報告され、実行は失敗しません。local バックエンドでは到達可能性のみを確認し、カタログとの照合は行いません。設定された "model": "dynamic" はハンドルであり、カタログ ID ではないためです。

モデルの提供が終了している場合は、一般的な HTTP エラーとしてではなく、バックエンド名、モデル名、プロバイダーが示す提供終了の説明、現在利用可能な代替候補を明示したエラーが返されます。提供終了は設定エラーであるため、ただちにサーキットブレーカーを開き、再試行しません。過負荷（429/5xx）や認証エラー（401）は、意図的に提供終了として扱いません。

レスポンスの信頼性（v2.4.0）

すべてのハンドラーは、統一されたレスポンスパイプライン（extractResponseText）を使用し、既知の LLM レスポンス形式すべて（生の文字列、OpenAI のチャット／補完形式、思考モデルの reasoning_content、配列形式のコンテンツパーツ、Gemini の候補）を正しく処理します。ローカルモデルからの繰り返し出力は自動的に集約され、分析結果の重複は排除され、件数も制限されます。

書き込みの完全性

fs.writeFile が解決しても、ディスク上のバイト列が要求した内容と一致するとは限りません。短い書き込みや部分的な書き込み、ENOSPC、エンコーディングの破損、書き込み後に戻るまでの間に別のプロセスがファイルを上書きするといった状況では、書き込み呼び出し自体は正常に解決しても、ディスク上の内容が意図した内容と異なることがあります。

重要な内容を書き込むすべてのパスでは、成功を報告する前に読み戻して内容を比較します。

パス	検証内容
modify_file の自動書き込み	変更後のファイルと、先に作成するバックアップ
generate_file の自動書き込み	生成されたファイルと、その生成ファイル用のテストファイル
write_files_atomic の write	書き込んだ各ファイルと各バックアップ
write_files_atomic の append	ファイルが追加した長さと正確に同じ分だけ増え、末尾が追加したバイト列と正確に一致すること
write_files_atomic のロールバック	復元された各ファイル（復元が確認されるまでバックアップのリンクを解除しません）
batch_modify	変更内容（modify_file 経由）とロールバックによる復元
parallel_agents	生成された各コードファイル
backup_restore	バックアップ、復元前のスナップショット、復元結果

不一致がある場合は WRITE_VERIFY_MISMATCH が発生します。破損したファイルに対して success: true を返すのではなく、ファイル名、期待値と実際の長さ、最初に異なる行を示します。

復旧パスにも同じ検証を意図的に適用しています。バックアップの作成に気付かないまま失敗するのは、バックアップがないよりも危険です。後でロールバックした際に、元の内容が破損したバイト列で上書きされるおそれがあるためです。

設計上、検証対象外のもの：成果物ではなく記録として扱われる内部の実行アーティファクトや状態ファイル、つまり parallel_agents の decomposed.json／results.json／quality-*.json／synthesis.json、backup_restore の .meta.json サイドカー、パターンストア、会話スレッドです。

Council System

同じプロンプトを複数のバックエンドに送信し、すべての応答を Claude に返して統合します。coding、architecture、security などのトピックは、それぞれバックエンドのセットと戦略（並列、逐次、ディベート、フォールバック）に対応付けられています。

詳しくは、docs/COUNCIL.md を参照してください。

Dashboard

オプションのウェブダッシュボードでは、バックエンドの管理（有効化／無効化、優先度、ヘルスチェック）と Council の設定（戦略、トピックのマッピング）を行うための UI を利用できます。

セットアップと API リファレンスについては、docs/DASHBOARD.md を参照してください。

SmartCrusher（ツール結果の圧縮）

大きなツール結果（長いファイル分析、Council の応答、一括処理の出力など）は、Claude のコンテキストウィンドウをすぐに埋めてしまうことがあります。SmartCrusher は、重要度に応じて保持／削除する戦略を使って、シリアライズ前にサイズの大きな配列を切り詰めます。さらに、データが退避されたことを Claude が認識できるよう、センチネル行を挿入します。

デフォルトでは無効です。 ご自身のローカルモデルで忠実度評価を実行してから有効にしてください。

有効化

# One-time env override (no config edit needed)
SAB_COMPRESSION_ENABLED=true node src/server.js

# Or permanently in src/config/backends.json:
# "compression": { "enabled": true }

忠実度評価（有効化前に実行）

この評価では、圧縮後の応答が元の応答と比べて事実の正確性を保っているかを調べます。OpenAI 互換のローカル API が必要です。普段使用しているモデルを利用してください。

RUN_CRUSH_EVAL=1 \
  CRUSH_EVAL_BASE_URL=http://127.0.0.1:<port>/v1 \
  CRUSH_EVAL_MODEL=<your-model-id> \
  npx vitest run tests/compression/probeFidelity.test.js

各ディメンションの original=N/15 と crushed=M/15 の出力を確認してください。いずれかのディメンションで圧縮後のスコアが 2 ポイントを超えて下がった場合は、圧縮を無効のままにしてください。モデルによって評価結果は基準の構成と異なります。

バックエンドの追加

ダッシュボードから（推奨）：SAB_DASHBOARD=true を指定してサーバーを起動し、http://localhost:3456 のウェブ UI（SAB_DASHBOARD_PORT で変更可能）から、JSON を編集せずにバックエンドの追加、削除、有効化／無効化、優先順位の変更を行います。ダッシュボードでは、バックエンドごとに API キーを設定／消去することもできます（Git の追跡対象外である data/backends-secrets.json に 0600 のモードで保存されます。追跡対象の src/config/backends.json には書き込まれません）。保存したキーは再起動なしですぐに反映され、バックエンドの process.env によるフォールバックより優先されます。

デフォルトではダッシュボードは 127.0.0.1 のみにバインドされます。認証機能がないため、マシンの外部からアクセス可能にしてはいけません。ほかの場所からアクセスする必要がある場合は SAB_DASHBOARD_HOST で変更できます。ループバック以外のホストを指定すると、起動時にリスクを示す警告が表示されます。

設定ファイルから：OpenAI 互換プロバイダーは、src/config/backends.json に設定エントリとして追加できます。

{
  "name": "my_provider",
  "type": "openai",
  "endpoint": "https://api.my-provider.com/v1",
  "model": "my-model",
  "apiKeyEnvVar": "MY_PROVIDER_API_KEY",
  "maxTokens": 8192,
  "priority": 7,
  "enabled": true
}

カスタムアダプタータイプの追加については、EXTENDING.md を参照してください。

ドキュメント

ドキュメント	説明
AGENTS.md	AI エージェントとエージェント型ハーネスのインストール／実行に関する契約、およびリポジトリのルール
CHANGELOG.md	バージョン履歴
CONFIGURATION.md	設定の完全なリファレンス
EXTENDING.md	バックエンド、ハンドラー、ツールの追加
EXAMPLES.md	使用例
docs/DASHBOARD.md	ダッシュボードのセットアップと API
docs/COUNCIL.md	Council System の詳細

要件

• Node.js >= 18.0.0
• 少なくとも 1 つのバックエンド（ローカルモデルまたはクラウド API キー）を設定すること
• MCP 統合用の Claude Code または Claude Desktop

テスト

npm test              # Run the unit + integration suite (Vitest)
npm run test:watch    # Watch mode
npm run test:bench    # Performance benchmarks (25 benchmarks, 6 categories)
npm run audit:backends # Probe every configured backend with a real completion

# SmartCrusher fidelity eval (opt-in, requires a running local model):
RUN_CRUSH_EVAL=1 \
  CRUSH_EVAL_BASE_URL=http://127.0.0.1:<port>/v1 \
  CRUSH_EVAL_MODEL=<your-model-id> \
  npx vitest run tests/compression/probeFidelity.test.js

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

• API キーをバージョン管理にコミットしないでください。環境変数のみを使用してください。
• 上記の Claude Code の設定例ではプレースホルダーを使用しています。実際のキーに置き換えるか、.env ファイルを参照してください。
• 誤って漏えいしたキーは、直ちにローテーションしてください。

脅威モデル

Smart AI Bridge は、信頼されたローカル MCP サーバーです。ご自身で管理する 1 つのクライアント（Claude Code または Claude Desktop）の stdio サブプロセスとしてご自身のマシン上で動作するように設計されており、そのクライアントは信頼できることを前提としています。

この境界内では：

• ファイルツールは、設計上、ファイルシステム全体にアクセスできます。 write_files_atomic、 modify_file、backup_restore および読み取り／分析ツールは、呼び出し元のクライアントから渡された任意のパスに対して動作します。 プロジェクトルート内にアクセスを制限するサンドボックスはありません。safeReadFile はパスを解決し、ヌルバイトを拒否します（パスインジェクションの手口に対する防御）が、 ワークスペース内にアクセスを制限するものではありません。
• 引数の検証はツールの境界で行われます。 ツール呼び出しはディスパッチ前に、各ツールの JSON Schema （Ajv 経由）に照らして検証されます。不正な呼び出しは構造化エラーとともに拒否されます。これは不正な入力から保護するものであり、悪意のあるクライアントから保護するものではありません。
• ツール呼び出しは、サーバープロセスの権限で実行されます。 root ではなく、通常のユーザーとして実行してください。

このセキュリティ態勢は、想定されている単一ユーザーのローカルエージェントのユースケースに適しています。ネットワーク経由で信頼できない呼び出し元やマルチテナントの呼び出し元にサーバーを公開する用途には適していません。その必要がある場合は、サーバーの前段に認証プロキシを配置し、まずファイルハンドラーにワークスペースルート内へのアクセス制限を追加してください。どちらもここでは提供されていません。

ライセンス

Apache-2.0