# Scopewalker MCP

[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-support-ffdd00?logo=buy-me-a-coffee&logoColor=black)](https://buymeacoffee.com/thaanpaa?utm_source=scopewalker-mcp&utm_medium=readme&utm_campaign=funding)

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](TOOLS.md) for the quick reference, [docs/](docs/) for per-tool parameters and example responses, and [docs/usage-examples.md](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](https://github.com/XAMPPRocky/tokei) - Install via `brew install tokei` or `cargo install tokei`

## Installation

Scopewalker is published to npm as [`scopewalker-mcp`](https://www.npmjs.com/package/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](#development).

## Configuration

### Claude Code

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

Or add to `~/.claude.json`:

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

See [Claude Code MCP documentation](https://code.claude.com/docs/en/mcp) for details.

### Claude Desktop

Download `scopewalker-mcp.mcpb` from the [latest release](https://github.com/timohaa/scopewalker-mcp/releases/latest) 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):

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

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

See [Cursor MCP documentation](https://cursor.com/docs/mcp) for details.

### VS Code (GitHub Copilot)

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

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

Requires VS Code 1.102+ with Agent Mode enabled.

See [VS Code MCP documentation](https://code.visualstudio.com/docs/agent-customization/mcp-servers) for details.

### Windsurf

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

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

Or configure via Windsurf Settings > Cascade > Manage MCPs.

See [Windsurf MCP documentation](https://docs.devin.ai/desktop/cascade/mcp) for details.

### Antigravity CLI

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

```json
{
  "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](https://antigravity.google/docs/cli/mcp) for details.

For Gemini CLI, add the same `mcpServers` configuration
to `~/.gemini/settings.json`. See [Gemini CLI MCP documentation](https://geminicli.com/docs/tools/mcp-server/).

### OpenAI Codex CLI

Add to `~/.codex/config.toml`:

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

Or use the CLI:

```bash
codex mcp add scopewalker-mcp -- npx -y scopewalker-mcp
```

See [Codex MCP documentation](https://developers.openai.com/codex/mcp/) 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](docs/code-quality.md) through its skills and agents:

- [`.claude/skills/review-changes/SKILL.md`](.claude/skills/review-changes/SKILL.md): fails reviews on unresolved size, complexity, smell, prop-drilling, or dead-code findings
- [`.claude/agents/standards-enforcer.md`](.claude/agents/standards-enforcer.md): fixes actionable findings and verifies them with rescans and tests
- [`.claude/skills/polish/SKILL.md`](.claude/skills/polish/SKILL.md): carries unresolved findings through the pipeline and verifies the final state
- [`.claude/agents/docs-reality-sync.md`](.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:

```bash
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`.

```bash
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](CONTRIBUTING.md) for contribution guidelines and [docs/patterns.md](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](docs/tools-overview.md#supported-languages) for what is detected per language.

## License

MIT