특화된 워크플로우 기반 도구 세트를 통해 AI 클라이언트가 주제를 조사하고, 엔티티를 비교하며, 출처가 명시된 보고서를 생성할 수 있도록 지원합니다.
다른 이름 HomenShum/nodebench-ai, nodebench-mcp
- 스타
- 14
- Tools
- —
- 다운로드, 30일
- —
- 최신 버전
- 2.31.2
- 마지막 커밋
- 2026년 11월 13일
- 라이선스
- MIT
NodeBench MCP란?
NodeBench은(는) MCP server입니다. 특화된 워크플로우 기반 도구 세트를 통해 AI 클라이언트가 주제를 조사하고, 엔티티를 비교하며, 출처가 명시된 보고서를 생성할 수 있도록 지원합니다.
프로젝트 README에서 생성된 요약
NodeBench MCP server 정보
NodeBench MCP는 AI 클라이언트가 연구를 수행하고, 서로 다른 엔티티를 비교하며, 구조화된 보고서를 생성할 수 있도록 워크플로우 중심의 환경을 제공합니다. 질문, 확인, 작성, 저장이라는 반복적인 프로세스를 통해 초기 문의 단계에서 완성된 문서 단계로 나아가야 하는 개발자와 연구자를 위해 설계되었습니다. 시스템은 복잡성과 성능을 관리하기 위해 별도의 설치 경로로 구성되어 있습니다.
기본 설치는 investigate, compare, track, summarize, search, report, ask_context와 같은 핵심 기능을 포함하여 9개의 도구를 제공하는 간결한 경험을 제공합니다. 더 깊이 있는 작업이 필요한 사용자를 위해 power 경로는 확장된 연구 기능을 제공하며, admin 경로는 프로파일링 및 관측성을 위한 운영자 중심 도구를 제공합니다. 사용자는 npx 명령어를 사용하여 이 MCP server를 Claude Code, Cursor 또는 Windsurf와 같은 클라이언트에 연결할 수 있습니다. 핵심 기능은 로컬에서 작동하지만, Gemini API key를 통합하면 웹 검색 및 vision 기능을 사용할 수 있고, GitHub token을 사용하여 rate limit을 높일 수 있습니다.
활용 사례
- 1출처가 명시된 연구 보고서 생성AI 클라이언트가 investigate 도구를 사용하여 특정 주제를 조사하고 출처가 뒷받침된 문서를 생성할 수 있습니다.
- 2엔티티 비교 수행AI에게 두 가지 서로 다른 기업이나 기술에 대한 비교 분석을 수행하도록 지시할 수 있습니다.
- 3노트를 공식 메모로 변환개발자는 report 도구를 사용하여 비정형 컨텍스트나 거친 노트를 전문적인 의사결정 메모로 변환할 수 있습니다.
- 4특화된 도구 세트 발견사용자는 기본 인터페이스를 무겁게 만들지 않으면서 UI/UX 분석과 같은 니치한 작업을 위한 특정 도구 세트를 찾아 활성화할 수 있습니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
NodeBench MCP 설치 방법
형식 확인: 2026년 11월 10일Cursor에 추가Goose에 추가Claude Code에 NodeBench MCP 설치
$ claude mcp add nodebench -- npx -y nodebench-mcpCursor에 NodeBench MCP 설치
~/.cursor/mcp.json
{
"mcpServers": {
"nodebench": {
"command": "npx",
"args": [
"-y",
"nodebench-mcp"
]
}
}
}VS Code에 NodeBench MCP 설치
.vscode/mcp.json
{
"servers": {
"nodebench": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"nodebench-mcp"
]
}
}
}VS Code CLI에 NodeBench MCP 설치
$ code --add-mcp '{"name":"nodebench","type":"stdio","command":"npx","args":["-y","nodebench-mcp"]}'Claude Desktop에 NodeBench MCP 설치
claude_desktop_config.json
{
"mcpServers": {
"nodebench": {
"command": "npx",
"args": [
"-y",
"nodebench-mcp"
]
}
}
}Codex에 NodeBench MCP 설치
$ codex mcp add nodebench -- npx -y nodebench-mcpCodex config.toml에 NodeBench MCP 설치
~/.codex/config.toml
[mcp_servers.nodebench] command = "npx" args = ["-y", "nodebench-mcp"]
Gemini CLI에 NodeBench MCP 설치
$ gemini mcp add -s user nodebench npx -- -y nodebench-mcpGemini settings.json에 NodeBench MCP 설치
~/.gemini/settings.json
{
"mcpServers": {
"nodebench": {
"command": "npx",
"args": [
"-y",
"nodebench-mcp"
]
}
}
}구성
GEMINI_API_KEYGITHUB_TOKEN
| 이름 | 설명 | 유형 |
|---|---|---|
| GEMINI_API_KEY | — | |
| GITHUB_TOKEN | — |
자동 검사
2026년 11월 12일에 실행됨전체 보고서 →자동 검사를 통과했습니다. 이는 보안 감사가 아닙니다. 코드를 직접 읽고 서버에 필요한 최소한의 권한만 부여하십시오. 검사 방식
- 소스 저장소 연결 및 접근 가능통과
- 오픈 소스 라이선스 (OSI)통과
- 최근 1년 내 커밋 또는 릴리스통과
- 패키지 이름이 인기 패키지와 유사하지 않음통과
- 원격 엔드포인트가 HTTPS 사용검사되지 않음
- 파괴적인 도구에 라벨 표시됨검사되지 않음
- 모델에 대한 숨겨진 지침 없음통과
- 패키지 및 해당 종속성에 중요한 보안 권고 없음통과
README
GitHub에서 보기NodeBench MCP
Investigate a topic and return a sourced report fast. The NodeBench MCP architecture is now split into three install lanes that share one runtime.
Default install: 9 visible tools total, including 7 core workflow tools:
investigate, compare, track, summarize, search, report, and 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
What's New
- v3 default surface - the default preset is now a workflow-first facade instead of a tool warehouse.
- Admin-only runtime gates - dashboards and the observability watchdog no longer start on the default hot path. Use
--admin,--dashboards, or--watchdogexplicitly. - Faster health path -
--healthnow loads only the active preset instead of eagerly loading every domain. - Separate install lanes -
nodebench-mcp-powerandnodebench-mcp-adminare now published companion packages, while--preset powerand--preset adminremain compatible paths on the core package.
New here? Read AGENT_LOGIC.md for the complete guide to how NodeBench thinks.
RETHINK REDESIGN APR 2026
This section records a repo-grounded reexamination of NodeBench MCP as of April 2026. It is intentionally blunt. The goal is to shrink the product to clear, measurable workflows and make the runtime and claims trustworthy.
Repo-grounded findings
- Surface area and messaging were out of sync
- At the time of this audit, the README marketed
350+ tools,founderunder50tools, andfullas338. - The audit that drove this section measured roughly
28tools in the startertools/listpayload, roughly186infounder, and roughly546infull, before counting the extra dynamic-loading helpers separately.
- At the time of this audit, the README marketed
- The core executable is overloaded
packages/mcp-local/src/index.tscurrently combines MCP serving, analytics tracking, embedding bootstrapping, profiling hooks, A/B instrumentation, dynamic tool loading, dashboard startup, and engine hosting in one runtime path.
- Performance is not yet credibly measured
- During this audit,
node packages/mcp-local/dist/index.js --healthtook about2.9slocally because CLI mode eagerly loaded all toolsets before exit. - The main performance comparison in the package measures local toolchain overhead, not end-user outcome quality, startup SLOs, workflow completion, or real provider spend.
- During this audit,
- Cost reporting is not yet auditable
- The current profiler relies on heuristic per-tool cost estimates, not authoritative provider billing or exact token accounting.
- Workflow clarity is weak
- The product currently explains presets, domains, discovery engines, and meta-systems before it proves one concrete job to be done.
Redesign principles
- One dominant workflow per persona
- A founder should land on one obvious path.
- A banker should land on one obvious path.
- The MCP should prove value before it explains its architecture.
- Truthful counts and truthful claims
- Preset docs, README counts, and
tools/listoutput must agree.
- Preset docs, README counts, and
- Speed is a product behavior
- Measure startup time,
tools/listpayload size, per-tool latency, and workflow time-to-first-value.
- Measure startup time,
- Keep optional systems out of the hot path
- Embeddings, dashboards, profilers, and engine surfaces should not make the default MCP startup slower.
- Prefer workflows over catalogs
- Opinionated, repeatable outcomes are more valuable than an oversized flat tool inventory.
- Ship process, not prose
- The right mental model is a small number of strong workflows with evidence and verification, not a giant capabilities brochure.
Execution board
| Ship order | Cause | Symptom in NodeBench | Metric to enforce |
|---|---|---|---|
| 1 | No single dominant job | The package reads like "everything MCP" instead of one clear wedge | Every persona entry point must answer the main job in one sentence |
| 2 | Tool surface is not truthful | README counts and runtime counts disagree | Published counts must match tools/list within 5% |
| 3 | Workflow is hidden behind tool volume | Users see presets, domains, and discovery systems before a clear task path | One canonical workflow per persona, completable in 3 to 5 tool calls |
| 4 | Performance is claimed, not instrumented | Benchmarks focus on harness overhead, not real user value | Track startup p50/p95, tools/list bytes, per-tool latency, workflow success, and real spend |
| 5 | Hot path contains optional systems | Profiling, embeddings, dashboards, and engine behavior sit in the main boot path | --health under 300ms and stdio ready under 500ms on warm start |
| 6 | Benchmarking is inward-facing | The package proves bookkeeping more than business outcomes | Benchmark by artifact quality, time-to-artifact, cost-per-artifact, and reuse rate |
Reference models
- agent-skills: process, not prose. Strong lifecycle commands, checkpoints, and evidence requirements.
- GitHub MCP Server: narrower toolsets improve tool choice and reduce context size. The server also exposes a simple
tool-searchutility. - Google MCP Toolbox: performance and operability are anchored in concrete runtime primitives such as connection pooling and OpenTelemetry, not only internal heuristics.
Bottom line
NodeBench MCP should evolve from a monolithic "hundreds of tools" surface into a smaller number of opinionated workflow products backed by a measurable, trustworthy runtime.
Unified cross-surface spec: docs/architecture/UNIFIED_WORKFLOW_SPEC.md
Production companion spec: docs/architecture/UNIFIED_WEB_MCP_PRODUCTION_SPEC.md
Founder MCP flow spec: docs/architecture/FOUNDER_MCP_FLOW_SPEC.md
What You Get
NodeBench is now a workflow-first MCP. The default install proves one concrete job quickly, and the heavier surfaces are still available when you explicitly ask for them.
Install Lanes And Presets
| Entry | Surface | What it is for |
|---|---|---|
nodebench-mcp |
9 visible tools |
Workflow-first lane: investigate, compare, track, summarize, search, report, ask_context, discover_tools, load_toolset |
nodebench-mcp-power |
expanded workflow surface | Founder, recon, packets, and web-heavy workflows without admin runtime |
nodebench-mcp-admin |
operator surface | Profiling, observability, dashboards, eval, and debug-oriented lanes |
core |
full methodology lane | Verification, eval, learning, recon, execution trace, and mission harness |
founder |
compatibility preset | Legacy founder-facing pack kept for existing setups |
full |
all loaded domains | Maximum coverage when you explicitly want the warehouse |
Default workflow
ASK -> CHECK -> WRITE -> SAVE
The default preset is optimized for that loop. It does not start local dashboards or the observability watchdog unless you pass admin flags explicitly.
# 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
Quick Start
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
Or add to ~/.claude/settings.json or .mcp.json in your project root:
{
"mcpServers": {
"nodebench": {
"command": "npx",
"args": ["-y", "nodebench-mcp"]
}
}
}
Cursor
Add to .cursor/mcp.json (or Settings > MCP). Use the cursor preset to stay within Cursor's tool limit:
{
"mcpServers": {
"nodebench": {
"command": "npx",
"args": ["-y", "nodebench-mcp", "--preset", "cursor"]
}
}
}
Windsurf
Add to .windsurf/mcp.json (or Settings > MCP > View raw config):
{
"mcpServers": {
"nodebench-power": {
"command": "npx",
"args": ["-y", "nodebench-mcp-power"]
}
}
}
Other MCP Clients
Any MCP-compatible client works. Point command to npx and choose the package that matches the lane you want:
["-y", "nodebench-mcp"]for the tiny default workflow lane["-y", "nodebench-mcp-power"]for the expanded founder/research lane["-y", "nodebench-mcp-admin"]for the operator lane
Add "--preset", "<name>" only when you want a compatibility preset on the core package.
First Prompts to Try
# 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")
Optional: API Keys
export GEMINI_API_KEY="your-key" # Web search + vision (recommended)
export GITHUB_TOKEN="your-token" # GitHub (higher rate limits)
Set these as environment variables, or add them to the env block in your MCP config:
{
"mcpServers": {
"nodebench": {
"command": "npx",
"args": ["-y", "nodebench-mcp"],
"env": {
"GEMINI_API_KEY": "your-key",
"GITHUB_TOKEN": "your-token"
}
}
}
}
Progressive Discovery — How Optional Toolsets Stay Off the Hot Path
The default preset exposes 9 tools. Everything else stays off the hot path until you deliberately load a specific toolset.
How it works
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
Multi-modal search engine
discover_tools scores tools using 14 parallel strategies:
| Strategy | What it does |
|---|---|
| Keyword + TF-IDF | Exact matching, rare tags score higher |
| Fuzzy (Levenshtein) | Tolerates typos |
| Semantic (synonyms) | 30 word families — "check" finds "verify", "validate" |
| N-gram + Bigram | Partial words and phrases |
| Dense (TF-IDF cosine) | Vector-like ranking |
| Embedding (neural) | Agent-as-a-Graph bipartite search |
| Execution traces | Co-occurrence mining from usage logs |
| Intent pre-filter | Narrow to relevant categories before search |
Plus cursor pagination (offset/limit), result expansion (expand: N), and multi-hop BFS traversal (depth: 1-3) via get_tool_quick_ref.
Client compatibility
| Client | Recommended path |
|---|---|
| Claude Code, GitHub Copilot | Default preset + discover_tools / load_toolset |
| Cursor | --preset cursor to stay within its tool cap |
| Windsurf, Claude Desktop, Gemini CLI | Use --preset power or a targeted preset if your client does not refresh tools reliably |
Key Features
Decision Intelligence (Deep Sim)
Simulate decisions before committing. Run scenarios with multiple variables, score trajectories, generate postmortems, produce decision memos.
Causal Memory
Track actions, paths, and state across sessions. Important-change review surfaces what shifted since your last session.
Artifact Packets
Every analysis produces a shareable artifact — decision memos, delegation briefs, investigation reports. The output is the distribution.
Founder Tools
Weekly reset, pre-delegation briefing, company tracking, important-change review. Built for the founder who needs to make 20 decisions a day with incomplete information.
Knowledge Compounding
record_learning + search_all_knowledge — findings persist across sessions. By session 9, the agent finds 2+ relevant prior findings before writing a single line of code.
Headless Engine API
NodeBench ships a headless, API-first engine for programmatic access.
# Start MCP server with engine API on port 6276
npx nodebench-mcp --engine
# With auth token
npx nodebench-mcp --engine --engine-secret "your-token"
| Method | Path | Purpose |
|---|---|---|
| GET | / |
Engine status, tool count, uptime |
| GET | /api/health |
Health check |
| GET | /api/tools |
List all available tools |
| POST | /api/tools/:name |
Execute a single tool |
| GET | /api/workflows |
List workflow chains |
| POST | /api/workflows/:name |
Execute a workflow (SSE streaming) |
| POST | /api/sessions |
Create an isolated session |
| GET | /api/sessions/:id |
Session status + call history |
| GET | /api/sessions/:id/report |
Conformance report |
| GET | /api/presets |
List presets with tool counts |
Fine-Grained Control
# 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 Format — Token Savings
TOON (Token-Oriented Object Notation) is on by default. Every tool response is TOON-encoded for ~40% fewer tokens vs JSON. Disable with --no-toon.
Security & Trust Boundaries
NodeBench MCP runs locally on your machine.
- Local runtime data lives under
~/.nodebench/. Native SQLite is used when the addon is available; lightweight mode skips the native persistence layer. No data is sent to external servers unless you provide API keys and use tools that call external APIs. - Analytics data never leaves your machine.
- The
local_filetoolset can read files anywhere your Node.js process has permission. Use thedefaultpreset to keep local-file tools off the hot path. - All API keys read from environment variables — never hardcoded or logged.
- All database queries use parameterized statements.
Build from Source
git clone https://github.com/HomenShum/nodebench-ai.git
cd nodebench-ai/packages/mcp-local
npm install && npm run build
Then use absolute path:
{
"mcpServers": {
"nodebench": {
"command": "node",
"args": ["/path/to/packages/mcp-local/dist/index.js"]
}
}
}
Troubleshooting
"No search provider available" — Set GEMINI_API_KEY, OPENAI_API_KEY, or PERPLEXITY_API_KEY
"GitHub API error 403" — Set GITHUB_TOKEN for higher rate limits
"Cannot find module" — Run npm run build in the mcp-local directory
MCP not connecting — Check path is absolute, run claude --mcp-debug, ensure Node.js >= 18
Windsurf not finding tools — Verify ~/.codeium/windsurf/mcp_config.json has correct JSON structure
Cursor tools not loading — Ensure .cursor/mcp.json exists in project root. Use --preset cursor to stay within the tool cap. Restart Cursor after config changes.
Dynamic loading not working — Claude Code and GitHub Copilot support native dynamic loading. For Windsurf/Cursor, prefer --preset cursor or --preset power if your client does not refresh tools reliably after load_toolset.
License
MIT
NodeBench MCP 질문
NodeBench MCP를 Claude Code에 추가하려면 어떻게 하나요?
터미널에서 claude mcp add nodebench -- npx -y nodebench-mcp를 실행합니다. 모든 프로젝트에서 사용할 수 있게 하려면 --scope user를 추가합니다.
NodeBench MCP를 Cursor에 추가하려면 어떻게 하나요?
~/.cursor/mcp.json를 열고 mcpServers 아래에 서버를 추가합니다. 위 설치 섹션에 표시된 Cursor 구성을 사용합니다.
기본 설치 시 어떤 도구들이 포함되나요?
기본 설치 시 9개의 도구가 제공되며, 여기에는 investigate, compare, track, summarize, search, report, ask_context 등 7개의 핵심 워크플로우 도구가 포함됩니다.
NodeBench를 연구용으로 어떻게 사용하나요?
investigate 도구에 특정 주제를 입력하여 출처가 포함된 보고서를 생성할 수 있습니다.
NodeBench에서 웹 검색과 GitHub 연동을 지원하나요?
네, Gemini API key를 사용하면 웹 검색 및 vision 기능을 활성화할 수 있으며, GitHub token을 사용하면 GitHub에 대한 더 높은 rate limit을 적용할 수 있습니다.
설치 옵션에는 어떤 것들이 있나요?
세 가지 주요 경로가 있습니다. 기본 워크플로우 중심 경로(nodebench-mcp), 확장된 워크플로우를 위한 power 경로(nodebench-mcp-power), 그리고 운영자를 위한 admin 경로(nodebench-mcp-admin)입니다.