node-core-mcp

An MCP server that gives AI assistants hands-on access to a local nodejs/node checkout — build, test, search, and review, all from the conversation.

Requirements

• Node.js ≥ 18
• A local clone of nodejs/node
• gh CLI (only for get_pr_metadata)

Installation

npm install -g node-core-mcp

Or use directly with npx:

npx node-core-mcp --repo /path/to/node

MCP configuration

By default (no --repo flag), the server resolves the repo root as three directories above the bin/ folder — which works when the package lives inside the repo at tools/node-core-mcp/.

Claude Code

~/.claude/settings.json (global) or .claude/settings.json (project):

{
  "mcpServers": {
    "node-core": {
      "command": "node-core-mcp",
      "args": ["--repo", "/absolute/path/to/nodejs/node"]
    }
  }
}

Cursor

~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

{
  "mcpServers": {
    "node-core": {
      "command": "node-core-mcp",
      "args": ["--repo", "/absolute/path/to/nodejs/node"]
    }
  }
}

VS Code

Requires VS Code 1.99+ with the GitHub Copilot extension. .vscode/mcp.json:

{
  "servers": {
    "node-core": {
      "type": "stdio",
      "command": "node-core-mcp",
      "args": ["--repo", "${workspaceFolder}/../node"]
    }
  }
}

Codex CLI

~/.codex/config.toml:

[mcp_servers.node-core]
command = "node-core-mcp"
args = ["--repo", "/absolute/path/to/nodejs/node"]

Tools

Build

| Tool | Description | |------|-------------| | configure | Run ./configure (accepts debug, extra_flags) | | build | Run make (accepts target, jobs) | | run_lint | Run make lint-js, make lint-cpp, or make lint | | get_node_version | Get the version of the local dev build (falls back to system Node.js) |

Test

| Tool | Description | |------|-------------| | run_test | Run a single test file with the dev binary | | run_tests | Run tests matching a pattern via tools/test.py | | run_benchmark | Run a benchmark file with the dev binary | | explain_test_failure | Parse TAP / tools/test.py output and return failures + re-run commands | | verify_change | Detect changed files via git, rebuild only when required, run the relevant tests, and return parsed results. Skips the rebuild entirely for JS-only changes when the binary was configured with --node-builtin-modules-path |

Code search

| Tool | Description | |------|-------------| | search_code | grep -rn across lib/, src/, test/ (or a custom dir) | | read_file | Read a source file (supports offset and limit for large files) | | git_log | Show recent commit history, optionally filtered by path |

Documentation

| Tool | Description | |------|-------------| | list_docs | List Markdown files in doc/api/ | | read_doc | Read a single API doc (e.g. stream.md) | | search_docs | Search doc/api/, doc/contributing/, and test/README.md |

Jenkins CI

Requires node-core-utils (ncu-ci) configured with a Jenkins API token, and an authenticated gh CLI.

| Tool | Description | |------|-------------| | start_ci | Start a node-test-pull-request Jenkins run for a PR via ncu-ci run | | get_ci_status | Fetch parsed Jenkins results for a PR or job URL via ncu-ci url --json | | classify_failure | Answer "known flake or real regression?" by cross-referencing nodejs/node flaky-test issues and recent nodejs/reliability reports |

PR & subsystem

| Tool | Description | |------|-------------| | find_subsystem | Given changed files, identify the primary subsystem, likely reviewers, and PR labels | | list_relevant_tests | Given changed files, suggest tests via the lib/ require graph and a test-name index (not just path heuristics) | | get_pr_metadata | Fetch labels, CI status, reviews, and commits for a nodejs/node PR via gh |

Development

# Run the test suite (submodule required)
git submodule update --init
npm test

Tests that require a dev binary (get_node_version, run_test) are automatically skipped unless the binary has been built. To build it:

npm run setup  # git submodule update --init + configure + make

CI runs the test suite on Node.js 18, 20, and 22 for every push to main and every pull request. A full build with npm run setup runs weekly (Sundays) to verify the dev-binary-dependent tests.

License

MIT