io.github.timohaa/scopewalker-mcp

Scopewalker MCP

AI agents will happily create 1000+ line source files and add a 20th parameter to a function call, even if there's a rule file telling them not to. Scopewalker exists to enforce stricter codebase standards.

It's a local MCP server (open source, runs over stdio, makes no network calls) that exposes 9 read-only tools:

• get_line_counts - per-file line counts (total, code, blank, comment) with sorting, extension filters, and project-wide totals
• get_functions - function and method detection; per-file counts, or per-function line metrics via detail=lines with a min_lines filter for hunting oversized functions
• get_complexity_metrics - max/average nesting depth and parameter counts (JSX props included), import counts, a per-file cognitive-complexity score, and per-function cyclomatic complexity with high/extreme severity bands, plus hotspots flagged for deeply nested or over-parameterized functions
• check_thresholds - flags files and functions exceeding size thresholds (defaults: 300 lines per file, 100 per function)
• get_code_inventory - classes with their methods, functions, interfaces/types, enums, and constants, each marked exported or not; private symbols hidden by default
• get_documentation_coverage - coverage percentage plus every function, class, or method missing a doc comment (JSDoc, Python docstrings, Rust ///, and other per-language formats)
• get_code_smells - TODO/FIXME/HACK/XXX/BUG/UNUSED/DEPRECATED markers found by scanning actual comments via the AST (no false positives from string literals), plus as unknown as / as any as double casts in TypeScript
• get_prop_drilling - parameter names threaded through many functions and files, with forwarding evidence and a high/medium/low risk rating
• find_dead_code - unreferenced top-level symbols and private methods, split into certain dead_code and human-judgment unreferenced_exports

It's tree-sitter (parsing) + tokei (line counting) + fast-glob (file discovery) under the hood; nothing is custom-parsed. Tested on macOS with Claude Code, but should work with Cursor, VS Code, Windsurf, Antigravity CLI, Codex, or anything else that speaks MCP.

See TOOLS.md for the quick reference, docs/ for per-tool parameters and example responses, and docs/usage-examples.md for a guide to wiring Scopewalker into skills, subagents, and AGENTS.md.

Safety Defaults

• No network access: All analysis runs locally over stdio: no data leaves your machine, no API keys or external services involved.
• Path scoping: All tools only operate inside allowed roots. SCOPEWALKER_ALLOWED_ROOTS=/abs/path1,/abs/path2 takes precedence when set. Otherwise the server uses the workspace roots your MCP client shares, and falls back to the current working directory and system temp when the client shares none.
• Large file guard: AST-based tools skip files larger than 1 MB to avoid excessive memory/CPU use. Tokei-based line counts do not enforce this limit.
• Input ceilings: max_files caps at 10000, max_depth at 64, limit at 5000.
• Symlinks: Directory scans do not follow symbolic links.
• Output limits: Tools default to returning 20 files/items unless limit is set.
• Comment redaction: get_code_smells redacts comment text by default; pass include_text: true to return snippets explicitly.

Requirements

• Node.js 22+
• tokei - Install via brew install tokei or cargo install tokei

Installation

Scopewalker is published to npm as scopewalker-mcp; no clone or build needed. Configure your MCP client to run it via npx (examples below), or install it globally with npm install -g scopewalker-mcp.

To build from source instead, see Development.

Configuration

Claude Code

claude mcp add --scope user scopewalker-mcp -- npx -y scopewalker-mcp

Or add to ~/.claude.json:

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

See Claude Code MCP documentation for details.

Claude Desktop

Download scopewalker-mcp.mcpb from the latest release and open it with Claude Desktop (or drag it into Settings > Extensions) for one-click installation.

Cursor

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

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

Or configure via File > Preferences > Cursor Settings > MCP.

See Cursor MCP documentation for details.

VS Code (GitHub Copilot)

Add to .vscode/mcp.json in your workspace:

{
  "servers": {
    "scopewalker-mcp": {
      "command": "npx",
      "args": ["-y", "scopewalker-mcp"]
    }
  }
}

Requires VS Code 1.102+ with Agent Mode enabled.

See VS Code MCP documentation for details.

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

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

Or configure via Windsurf Settings > Cascade > Manage MCPs.

See Windsurf MCP documentation for details.

Antigravity CLI

Add to ~/.gemini/config/mcp_config.json (global) or .agents/mcp_config.json (per project):

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

Use /mcp inside the prompt panel to check server status and reload the config.

See Antigravity CLI MCP documentation for details.

For Gemini CLI, add the same mcpServers configuration to ~/.gemini/settings.json. See Gemini CLI MCP documentation.

OpenAI Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.scopewalker-mcp]
command = "npx"
args = ["-y", "scopewalker-mcp"]

Or use the CLI:

codex mcp add scopewalker-mcp -- npx -y scopewalker-mcp

See Codex MCP documentation for details.

Usage

Once configured, the assistant calls Scopewalker's tools on its own; no special syntax needed. Ask things like:

• "Check this repo against our size thresholds before I commit"
• "Which functions in src/ have the highest cognitive complexity?"
• "Find undocumented exports in src/auth"
• "Are there any TODO/FIXME/HACK markers left in this module?"
• "Show me functions that take more than 5 parameters"

It picks the right tool and parameters for the request.

This repo enforces shared quality requirements through its skills and agents:

• .claude/skills/review-changes/SKILL.md: fails reviews on unresolved size, complexity, smell, prop-drilling, or dead-code findings
• .claude/agents/standards-enforcer.md: fixes actionable findings and verifies them with rescans and tests
• .claude/skills/polish/SKILL.md: carries unresolved findings through the pipeline and verifies the final state
• .claude/agents/docs-reality-sync.md: uses get_code_inventory and get_functions to keep docs in sync with code

Development

To run from source instead of npm:

git clone https://github.com/timohaa/scopewalker-mcp.git
cd scopewalker-mcp
npm install
npm run build

Then point your MCP client at the build output, e.g. claude mcp add --scope user scopewalker-mcp -- node /path/to/scopewalker-mcp/dist/index.js.

npm run build          # Build the project
npm run check          # Version sync + lint + typecheck
npm run test           # Run tests
npm run test:coverage  # Run tests with coverage

See CONTRIBUTING.md for contribution guidelines and docs/patterns.md for tool registration, error handling, and testing patterns.

Supported Languages

The AST-based tools (everything except get_line_counts) parse:

• TypeScript/JavaScript (.ts, .tsx, .js, .jsx, .mjs, .cjs)
• Python (.py)
• Go (.go)
• Rust (.rs)
• Java (.java)
• C/C++ (.c, .h, .cpp, .cc, .cxx, .hpp)
• Ruby (.rb)

get_line_counts runs through tokei, so it reports on every language tokei recognizes. See docs/tools-overview.md for what is detected per language.

License

MIT