nodebench

NodeBench MCP

快速调查主题并返回附有来源的报告。 NodeBench MCP 架构现已拆分为三种安装路径，共用一个运行时。

默认安装：总计 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 默认界面 - 默认预设现已转为以工作流为先的门面，而非工具仓库。
• 仅限管理员的运行时门控 - 仪表板和可观测性 watchdog 不再在默认热路径上启动。请明确使用 --admin、--dashboards 或 --watchdog。
• 更快的健康检查路径 - --health 现在只加载当前启用的预设，不再提前加载所有领域。
• 独立的安装路径 - nodebench-mcp-power 和 nodebench-mcp-admin 现已作为配套软件包发布，同时核心软件包仍兼容 --preset power 和 --preset admin。

初次使用？ 请阅读 AGENT_LOGIC.md，了解 NodeBench 思考方式的完整指南。

---

重新思考与重新设计（2026 年 4 月）

本节记录了截至 2026 年 4 月、基于代码仓库的 NodeBench MCP 重新审视。内容有意直言不讳，目标是精简产品，聚焦清晰、可衡量的工作流，并确保运行时和产品声明值得信赖。

基于代码仓库的发现

• 功能范围与宣传信息不一致
  • 本次审计时，README 宣称有 350+ tools、founder 模式下少于 50 个工具，以及 full 模式下有 338 个工具。
  • 推动本节内容的审计测得，starter 的 tools/list 负载中约有 28 个工具，founder 模式下约有 186 个，full 模式下约有 546 个；尚未计入额外的动态加载辅助工具。
• 核心可执行程序负担过重
  • packages/mcp-local/src/index.ts 目前在一个运行时路径中同时处理 MCP 服务、分析跟踪、嵌入初始化、性能分析钩子、A/B 测试埋点、动态工具加载、仪表板启动和引擎托管。
• 性能尚未得到可信的衡量
  • 在本次审计期间，由于 CLI 模式会在退出前提前加载所有工具集，node packages/mcp-local/dist/index.js --health 在本地耗时约 2.9s。
  • 软件包中的主要性能对比衡量的是本地工具链开销，而非最终用户结果质量、启动 SLO、工作流完成情况或实际服务商支出。
• 成本报告尚无法审计
  • 当前分析器依赖基于启发式方法估算的单工具成本，而非权威的服务商计费数据或精确的 Token 统计。
• 工作流说明不够清晰
  • 当前产品在证明一个具体待办事项之前，就先介绍预设、领域、发现引擎和元系统。

重新设计原则

1. 每种用户角色对应一个主导工作流
   • 创始人应能直接找到一条明确的路径。
   • 银行家应能直接找到一条明确的路径。
   • MCP 应先证明价值，再解释其架构。
2. 数量和声明都必须真实
   • 预设文档、README 中的数量和 tools/list 输出必须一致。
3. 速度是产品行为的一部分
   • 衡量启动时间、tools/list 载荷大小、各工具延迟，以及工作流实现首次价值所需的时间。
4. 让可选系统远离关键路径
   • 嵌入、仪表板、性能分析器和引擎界面不应拖慢默认 MCP 启动。
5. 工作流优先于工具目录
   • 有主见、可重复的成果比庞大而扁平的工具清单更有价值。
6. 交付流程，而非文案
   • 正确的思维模型是少量强大的工作流，配有证据和验证，而不是一份巨大的能力宣传册。

执行看板

发布顺序	原因	NodeBench 中的症状	强制执行的指标
1	没有单一主导任务	软件包给人的感觉是“什么都是 MCP”，而不是一个明确的切入点	每个用户角色的入口都必须用一句话说明主要任务
2	工具界面与实际不符	README 中的数量与运行时数量不一致	已发布的数量必须与 tools/list 相差不超过 5%
3	工作流被大量工具掩盖	用户在看到清晰的任务路径之前，先看到预设、领域和发现系统	每种用户角色设置一个规范工作流，并可在 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	扩展工作流界面	无需管理运行时的创始人、侦察、数据包和重度 Web 工作流
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（或前往 Settings > MCP）。使用 cursor 预设以符合 Cursor 的工具数量限制：

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

Windsurf

添加到 .windsurf/mcp.json（或前往 Settings > MCP > View raw config）：

{
  "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	精确匹配，罕见标签得分更高
模糊匹配（Levenshtein）	容忍拼写错误
语义（同义词）	30 个词族——“check”可找到“verify”和“validate”
N-gram + Bigram	部分词语和短语
稠密（TF-IDF 余弦）	类似向量的排序
嵌入（神经网络）	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）

在做出承诺前模拟决策。运行包含多个变量的情景、为发展轨迹评分、生成复盘报告并制作决策备忘录。

因果记忆

跨会话跟踪行动、路径和状态。重要变更回顾会展示自上次会话以来发生的变化。

成果数据包

每项分析都会生成可分享的成果——决策备忘录、委派简报、调查报告。输出即是分发内容。

创始人工具

每周重置、委派前简报、公司跟踪、重要变更回顾。专为每天需要在信息不完整的情况下做出 20 项决策的创始人打造。

知识复利

record_learning + search_all_knowledge——发现会在多个会话间持续积累。到第 9 次会话时，Agent 在写下第一行代码之前，就能找到 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（面向令牌的对象表示法）默认启用。每个工具响应都采用 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"]
    }
  }
}

---

故障排除

“没有可用的搜索提供方”——设置 GEMINI_API_KEY、OPENAI_API_KEY 或 PERPLEXITY_API_KEY

“GitHub API 错误 403”——设置 GITHUB_TOKEN 以提高速率限制

“找不到模块”——在 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