nodebench

NodeBench MCP

トピックを調査し、出典付きレポートをすばやく返します。 NodeBench MCP のアーキテクチャは、1 つのランタイムを共有する 3 つのインストール方法に分割されました。

デフォルトのインストールでは、合計 9 個のツールが表示され、そのうち 7 個がコアワークフローツールです： investigate、compare、track、summarize、search、report、および ask_context。

# Core workflow lane
claude mcp add nodebench -- npx -y nodebench-mcp

# Power lane
claude mcp add nodebench-power -- npx -y nodebench-mcp-power

# Admin lane
claude mcp add nodebench-admin -- npx -y nodebench-mcp-admin

新着情報

• v3 のデフォルト構成 - デフォルトのプリセットが、ツールを大量に備えた構成ではなく、ワークフローを優先するファサードになりました。
• 管理者専用のランタイムゲート - ダッシュボードとオブザーバビリティウォッチドッグは、デフォルトのホットパスでは起動しなくなりました。明示的に --admin、--dashboards、または --watchdog を使用してください。
• ヘルスチェックパスの高速化 - --health は、すべてのドメインを事前に読み込むのではなく、アクティブなプリセットのみを読み込むようになりました。
• インストール方法の分離 - nodebench-mcp-power と nodebench-mcp-admin がコンパニオンパッケージとして公開されました。一方、--preset power と --preset admin はコアパッケージで引き続き互換性のある方法として利用できます。

初めての方へ NodeBench の考え方を網羅したガイドは AGENT_LOGIC.md をご覧ください。

---

2026 年 4 月の再考と再設計

このセクションでは、2026 年 4 月時点で、リポジトリに基づいて NodeBench MCP を再検証した内容を記録します。意図的に率直な記述にしています。目的は、明確で測定可能なワークフローに製品を絞り込み、ランタイムとその主張を信頼できるものにすることです。

リポジトリに基づく調査結果

• 規模とメッセージングに食い違いがありました
  • この監査時点で、README では 350+ tools、founder では 50 未満のツール、full では 338 と紹介されていました。
  • このセクションの根拠となった監査では、追加の動的読み込みヘルパーを別途数える前の時点で、スターターの tools/list ペイロードには約 28 個、founder には約 186 個、full には約 546 個のツールがあると測定されました。
• コア実行ファイルに機能が過剰に集中しています
  • 現在の packages/mcp-local/src/index.ts は、MCP の提供、分析トラッキング、埋め込みの初期化、プロファイリングフック、A/B 計測、動的ツール読み込み、ダッシュボードの起動、エンジンのホスティングを、1 つのランタイムパスにまとめています。
• パフォーマンスはまだ信頼できる形で測定されていません
  • この監査中、CLI モードが終了前にすべてのツールセットを事前に読み込んでいたため、ローカルで node packages/mcp-local/dist/index.js --health の実行に約 2.9s かかりました。
  • パッケージの主なパフォーマンス比較で測定されているのは、ローカルのツールチェーンのオーバーヘッドであり、エンドユーザーの成果品質、起動時の SLO、ワークフローの完了状況、実際のプロバイダー料金ではありません。
• コスト報告はまだ監査可能ではありません
  • 現在のプロファイラーは、信頼できるプロバイダーの請求情報や正確なトークン計測ではなく、ツールごとのヒューリスティックなコスト推定に依存しています。
• ワークフローが不明瞭です
  • 現在の製品は、具体的な仕事を 1 つ実行できることを示す前に、プリセット、ドメイン、探索エンジン、メタシステムについて説明しています。

再設計の原則

1. ペルソナごとに主要なワークフローを1つ用意する
   • 創業者には、明確な選択肢を1つ示す必要があります。
   • 銀行員には、明確な選択肢を1つ示す必要があります。
   • MCP は、アーキテクチャを説明する前に価値を示す必要があります。
2. 数値と主張を正確にする
   • プリセットのドキュメント、README の件数、tools/list の出力は一致している必要があります。
3. 速度もプロダクトの挙動の一部です
   • 起動時間、tools/list のペイロードサイズ、ツールごとのレイテンシ、ワークフローで初めて価値を実感するまでの時間を測定します。
4. 任意のシステムをホットパスから外す
   • 埋め込み、ダッシュボード、プロファイラー、エンジンの機能によって、MCP のデフォルトの起動が遅くならないようにします。
5. カタログよりワークフローを優先する
   • 方向性が明確で、繰り返し実行できる成果は、過剰に大きなフラットなツール一覧より価値があります。
6. 文章ではなくプロセスを提供する
   • 適切な考え方は、膨大な機能紹介資料ではなく、エビデンスと検証を備えた少数の強力なワークフローです。

実行ボード

提供順	原因	NodeBench での症状	適用する指標
1	主要なジョブが1つに絞られていない	パッケージが明確な強みではなく「何でもできる MCP」のように見える	すべてのペルソナ向け入口で、主なジョブを1文で説明できること
2	ツールの公開範囲が実態を反映していない	README の件数と実行時の件数が一致しない	公開する件数を tools/list と5%以内で一致させる
3	ツールの多さにワークフローが埋もれている	明確なタスクの進め方を示す前に、ユーザーにプリセット、ドメイン、探索システムが表示される	ペルソナごとに標準ワークフローを1つ用意し、3〜5回のツール呼び出しで完了できること
4	パフォーマンスを主張するだけで、計測していない	ベンチマークが実際のユーザー価値ではなく、ハーネスのオーバーヘッドに焦点を当てている	起動時間の p50/p95、tools/list のバイト数、ツールごとのレイテンシ、ワークフローの成功率、実際のコストを追跡する
5	ホットパスに任意のシステムが含まれている	プロファイリング、埋め込み、ダッシュボード、エンジンの動作がメインの起動パスに含まれている	ウォームスタート時に --health を300ms未満、stdio の準備完了を500ms未満にする
6	ベンチマークが内向きになっている	パッケージがビジネス上の成果よりも帳簿上の処理を証明している	成果物の品質、成果物が得られるまでの時間、成果物あたりのコスト、再利用率でベンチマークする

参考モデル

• agent-skills：文章ではなくプロセス。ライフサイクルコマンド、チェックポイント、エビデンス要件が充実しています。
• GitHub MCP Server：ツールセットを絞ることで、ツール選択が改善され、コンテキストサイズが小さくなります。また、シンプルな tool-search ユーティリティも提供しています。
• Google MCP Toolbox：パフォーマンスと運用性は、内部的なヒューリスティックだけでなく、コネクションプーリングや OpenTelemetry といった具体的な実行時プリミティブによって支えられています。

要点

NodeBench MCP は、単一の巨大な「数百のツール」から、計測可能で信頼できるランタイムに支えられた、方向性の明確な少数のワークフロー製品へと進化する必要があります。

サーフェス横断の統合仕様：docs/architecture/UNIFIED_WORKFLOW_SPEC.md

本番環境向け補足仕様：docs/architecture/UNIFIED_WEB_MCP_PRODUCTION_SPEC.md

創業者向け MCP フロー仕様：docs/architecture/FOUNDER_MCP_FLOW_SPEC.md

---

得られるもの

NodeBench は、ワークフローを最優先する MCP になりました。デフォルトのインストールでは、具体的なジョブをすぐに実行できます。より大規模な機能も、明示的に要求すれば引き続き利用できます。

インストールレーンとプリセット

エントリー	インターフェース	用途
nodebench-mcp	表示されるツールは 9 個	ワークフロー優先のレーンです。investigate、compare、track、summarize、search、report、ask_context、discover_tools、load_toolset を利用できます
nodebench-mcp-power	拡張ワークフローインターフェース	管理者向けランタイムなしで、創業者向け、調査、パケット、ウェブ中心のワークフローを実行します
nodebench-mcp-admin	オペレーター向けインターフェース	プロファイリング、可観測性、ダッシュボード、評価、デバッグ向けのレーンです
core	方法論全体を網羅するレーン	検証、評価、学習、調査、実行トレース、ミッションハーネスを利用できます
founder	互換性プリセット	既存のセットアップ向けに維持されている、従来の創業者向けパックです
full	読み込まれたすべてのドメイン	ウェアハウス全体を明示的に使いたい場合に、最大限の範囲を利用できます

デフォルトのワークフロー

ASK -> CHECK -> WRITE -> SAVE

デフォルトのプリセットは、このループ向けに最適化されています。管理者向けフラグを明示的に渡さない限り、ローカルダッシュボードや可観測性ウォッチドッグは起動しません。

# Claude Code core lane
claude mcp add nodebench -- npx -y nodebench-mcp

# Claude Code power lane
claude mcp add nodebench-power -- npx -y nodebench-mcp-power

# Claude Code admin lane
claude mcp add nodebench-admin -- npx -y nodebench-mcp-admin

# Windsurf / Cursor - add --preset to args only when you want a compatibility preset on the core package

---

クイックスタート

Claude Code（CLI）

claude mcp add nodebench -- npx -y nodebench-mcp
claude mcp add nodebench-power -- npx -y nodebench-mcp-power
claude mcp add nodebench-admin -- npx -y nodebench-mcp-admin

または、~/.claude/settings.json か、プロジェクトのルートにある .mcp.json に追加します。

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

Cursor

.cursor/mcp.json（または「設定」>「MCP」）に追加します。Cursor のツール上限内に収めるには、cursor プリセットを使用します。

{
  "mcpServers": {
    "nodebench": {
      "command": "npx",
      "args": ["-y", "nodebench-mcp", "--preset", "cursor"]
    }
  }
}

Windsurf

.windsurf/mcp.json（または「設定」>「MCP」>「生の設定を表示」）に追加します。

{
  "mcpServers": {
    "nodebench-power": {
      "command": "npx",
      "args": ["-y", "nodebench-mcp-power"]
    }
  }
}

その他の MCP クライアント

MCP 互換のクライアントであれば利用できます。command に npx を指定し、利用したいレーンに合ったパッケージを選びます。

• デフォルトの最小ワークフローレーンには ["-y", "nodebench-mcp"]
• 拡張された創業者向け／調査レーンには ["-y", "nodebench-mcp-power"]
• オペレーターレーンには ["-y", "nodebench-mcp-admin"]

コアパッケージで互換性プリセットを使いたい場合に限り、"--preset", "<name>" を追加します。

最初に試すプロンプト

# Research a topic
> Use investigate with topic="Anthropic" to produce a sourced report

# Compare two entities
> Use compare with entities=["Anthropic","OpenAI"] to get a side-by-side brief

# Turn rough notes into a report
> Use report with topic="AI agent infrastructure" and context="..." to produce a decision memo

# Search live web + saved knowledge
> Use search with query="MCP server best practices 2026"

# Track an entity
> Use track with action="add" and entity="Anthropic"

# Expand only when you need more
> Use discover_tools("visual QA for a Vite app"), then load_toolset("ui_ux_dive")

オプション：API キー

export GEMINI_API_KEY="your-key"        # Web search + vision (recommended)
export GITHUB_TOKEN="your-token"        # GitHub (higher rate limits)

これらを環境変数として設定するか、MCP 設定の env ブロックに追加します。

{
  "mcpServers": {
    "nodebench": {
      "command": "npx",
      "args": ["-y", "nodebench-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-key",
        "GITHUB_TOKEN": "your-token"
      }
    }
  }
}

---

段階的な検出 — オプションのツールセットを通常の処理経路から外しておく方法

デフォルトのプリセットで公開されるツールは 9 個です。それ以外は、特定のツールセットを明示的に読み込むまで、通常の処理経路から外れたままです。

仕組み

1. discover_tools("your task description")    → ranked results from the full registry
2. load_toolset("ui_ux_dive")                 → a specific toolset activates in your session
3. Use the newly loaded tools directly        → no proxy, native binding
4. Keep the default surface small             → only load what the workflow needs

マルチモーダル検索エンジン

discover_tools は、14 種類の並列戦略を使ってツールをスコアリングします。

戦略	機能
キーワード + TF-IDF	完全一致を検索し、出現頻度の低いタグほど高く評価します
ファジー（レーベンシュタイン距離）	誤字を許容します
セマンティック（同義語）	30 の単語ファミリーを利用します。「check」で「verify」や「validate」が見つかります
N-gram + Bigram	部分的な単語やフレーズを検索します
Dense（TF-IDF コサイン類似度）	ベクトルのようなランキングを行います
Embedding（ニューラル）	Agent-as-a-Graph の二部グラフ検索を行います
実行トレース	利用ログから共起パターンをマイニングします
インテントによる事前フィルタリング	検索前に関連カテゴリへ絞り込みます

さらに、カーソルページネーション（offset／limit）、結果の展開（expand: N）、および get_tool_quick_ref によるマルチホップ BFS 探索（depth: 1-3）を利用できます。

クライアントの互換性

クライアント	推奨パス
Claude Code、GitHub Copilot	デフォルトのプリセット + discover_tools ／ load_toolset
Cursor	ツール上限内に収めるには --preset cursor
Windsurf、Claude Desktop、Gemini CLI	クライアントがツールを確実に再読み込みしない場合は、--preset power または対象を絞ったプリセットを使用します

---

主な機能

意思決定インテリジェンス（Deep Sim）

決定を下す前にシミュレーションします。複数の変数を使ったシナリオを実行し、軌跡をスコアリングし、事後分析を作成し、意思決定メモを生成します。

因果メモリ

セッションをまたいでアクション、パス、状態を追跡します。「重要な変更」のレビューで、前回のセッション以降に何が変わったかを確認できます。

アーティファクトパケット

あらゆる分析から、共有可能なアーティファクト（意思決定メモ、委任用ブリーフ、調査レポート）が生成されます。出力そのものが配布物です。

創業者向けツール

週次リセット、委任前のブリーフィング、会社の追跡、「重要な変更」のレビューを提供します。不完全な情報のもとで1日に20件の意思決定を行う必要がある創業者向けに構築されています。

知識の蓄積

record_learning + search_all_knowledge ― 発見した内容はセッションをまたいで保持されます。セッション 9 までには、エージェントはコードを 1 行も書く前に、関連する過去の発見を 2 件以上見つけます。

---

ヘッドレスエンジン API

NodeBench には、プログラムからアクセスするためのヘッドレスな API ファーストのエンジンが用意されています。

# Start MCP server with engine API on port 6276
npx nodebench-mcp --engine

# With auth token
npx nodebench-mcp --engine --engine-secret "your-token"

メソッド	パス	用途
GET	/	エンジンのステータス、ツール数、稼働時間
GET	/api/health	ヘルスチェック
GET	/api/tools	利用可能なすべてのツールを一覧表示
POST	/api/tools/:name	単一のツールを実行
GET	/api/workflows	ワークフローチェーンを一覧表示
POST	/api/workflows/:name	ワークフローを実行（SSE ストリーミング）
POST	/api/sessions	分離されたセッションを作成
GET	/api/sessions/:id	セッションのステータスと呼び出し履歴
GET	/api/sessions/:id/report	適合性レポート
GET	/api/presets	ツール数とともにプリセットを一覧表示

---

細かな制御

# Include only specific toolsets
npx nodebench-mcp --toolsets deep_sim,recon,learning

# Exclude heavy toolsets
npx nodebench-mcp --exclude vision,ui_capture,parallel

# Dynamic loading — start minimal, load on demand
npx nodebench-mcp --dynamic

# Smart preset recommendation based on your project
npx nodebench-mcp --smart-preset

# Usage stats
npx nodebench-mcp --stats

# List all presets
npx nodebench-mcp --list-presets

# See all options
npx nodebench-mcp --help

TOON 形式 ― トークンの節約

TOON（Token-Oriented Object Notation）はデフォルトで有効です。すべてのツールの応答は TOON 形式でエンコードされ、JSON と比べてトークン数を約 40％削減します。--no-toon で無効にできます。

---

セキュリティと信頼境界

NodeBench MCP はお使いのマシン上でローカルに実行されます。

• ランタイムのローカルデータは ~/.nodebench/ に保存されます。アドオンが利用可能な場合はネイティブ SQLite が使用され、軽量モードではネイティブの永続化レイヤーがスキップされます。API キーを設定し、外部 API を呼び出すツールを使用しない限り、データが外部サーバーに送信されることはありません。
• アナリティクスデータがマシンの外に送信されることはありません。
• local_file ツールセットは、Node.js プロセスに権限がある場所ならどこにあるファイルでも読み取ることができます。ローカルファイルツールを通常の実行経路から外すには、default プリセットを使用してください。
• すべての API キーは環境変数から読み込まれ、ハードコードまたはログへの記録はされません。
• すべてのデータベースクエリにはパラメーター化されたステートメントが使用されます。

---

ソースからビルドする

git clone https://github.com/HomenShum/nodebench-ai.git
cd nodebench-ai/packages/mcp-local
npm install && npm run build

次に、絶対パスを使用します。

{
  "mcpServers": {
    "nodebench": {
      "command": "node",
      "args": ["/path/to/packages/mcp-local/dist/index.js"]
    }
  }
}

---

トラブルシューティング

「No search provider available」 ― GEMINI_API_KEY、OPENAI_API_KEY、または PERPLEXITY_API_KEY を設定してください。

「GitHub API error 403」 ― レート制限を引き上げるには、GITHUB_TOKEN を設定してください。

「Cannot find module」 ― mcp-local ディレクトリで npm run build を実行してください。

MCP が接続できない ― パスが絶対パスであることを確認し、claude --mcp-debug を実行して、Node.js が 18 以上であることを確認してください。

Windsurf でツールが見つからない ― ~/.codeium/windsurf/mcp_config.json の JSON 構造が正しいことを確認してください。

Cursor のツールが読み込まれない ― プロジェクトのルートに .cursor/mcp.json があることを確認してください。ツール数の上限内に収めるには --preset cursor を使用してください。設定を変更した後は Cursor を再起動してください。

動的読み込みが機能しない ― Claude Code と GitHub Copilot はネイティブの動的読み込みをサポートしています。Windsurf／Cursor では、load_toolset の後にクライアントが確実にツールを更新しない場合、--preset cursor または --preset power を使用してください。

---

ライセンス

MIT