Scopewalker MCP Measures Code Complexity

scopewalker-mcp is a local MCP server that lets coding agents measure code complexity before they edit. In Cursor, Anysphere's AI code editor, it can turn “keep files small” from a wish into a number the agent can check.

An MCP server is a small integration process that exposes tools and context to an AI client through the Model Context Protocol. For a cursor workshop or cursor training session, this is the useful lesson: rules are better when the agent can inspect the thing the rule is about.

See what Scopewalker actually measures

Scopewalker is an open-source TypeScript project by timohaa, published as timohaa/scopewalker-mcp under the MIT license. As of July 3, 2026, the repository describes it as a codebase analysis MCP server built on tree-sitter and tokei.

The interesting bit is not that it “understands code” in a vague way. It exposes eight read-only tools with concrete outputs: line counts, function metrics, cognitive complexity, threshold checks, code inventory, documentation coverage, code smells, and prop-drilling detection.

That makes it a nice answer to a very familiar agent problem. A rule file can say “do not create huge files,” but an agent may still append the next feature to a 900-line component because the chat context never made the size visible.

With Scopewalker, the agent can ask for numbers first. It can see that src/features/billing/BillingSettings.tsx is already above a 300-line file threshold, or that submitInvoice() is over a 100-line function threshold, before it decides where to put new logic.

The trap is treating the numbers as taste. They are better than that. They are a cheap preflight check that makes a repo's boundaries visible to an agent that otherwise sees only the few files it has opened.

Put the measurement before the edit

The day-to-day workflow changes in a small, boring way. Before asking Cursor Agent to refactor a feature or add a form, you ask it to inspect the target area with the local MCP tool and summarize risk.

A good prompt is specific:

“Before editing src/features/billing, use Scopewalker to find oversized files, oversized functions, high nesting, and prop drilling. Then propose the smallest safe change.”

That is different from asking for a review after the agent has already rewritten three files. The measurement happens before the diff, so the agent has a chance to choose a smaller seam.

A Cursor rule can make that habit sticky without turning the whole repo into policy soup:

---
description: Use Scopewalker before large edits in frontend feature code
globs:
  - "src/features/**/*.{ts,tsx}"
alwaysApply: false
---

Before adding UI state, props, or validation logic in this area:

1. Run the local Scopewalker MCP checks for line counts, function size, nesting, parameter counts, and prop drilling.
2. If a file is already over 300 lines or a function is over 100 lines, do not append new behavior there without explaining the smaller seam.
3. Include the measured hotspots in the final review note.

This pairs well with Cursor skills when the review pattern repeats. The rule says when to measure; the skill can hold the longer review workflow, examples, and expected handoff format. If you are mapping Cursor custom agents, skills, and MCP together, the broader related training topic is the right place to connect those pieces.

The trap is writing a rule that says “keep complexity low” and stopping there. Agents are literal in the worst possible way: if the rule has no observable check, it becomes advice, not a guardrail.

Keep the MCP boundary boring

Scopewalker's design is intentionally narrow. The project says it runs locally over stdio, makes no network calls, and exposes read-only tools. That is exactly the shape you want for a first MCP integration in a private repo.

Read-only still deserves care. A local code analysis server may need to read source files, test files, and comments. It should not need production secrets, write access, deploy credentials, or issue-tracker tokens.

A simple boundary is enough for a first pass:

Permission-boundary note: do not bundle a read-only metrics server with write-capable tools in the same “trusted because it is local” bucket. Local is not the same as harmless. Keep Scopewalker in the inspection lane, and make edit authority come from Cursor's normal reviewable IDE workflow.

For a broader pattern on keeping rules sharp without slowing every prompt, see Cursor Guardrails for Real Teams.

Try it in a small cursor workshop exercise

Use one feature folder, one agent task, and one diff. This is enough to learn whether code metrics help your Cursor workflow without turning the experiment into a program.

A first-week plan can be this small:

• Pick a folder with real history, such as src/features/billing or app/routes/settings.
• Connect Scopewalker as a local, read-only MCP server using the repository instructions and Cursor's MCP settings.
• Add one scoped .mdc rule for that folder, not the whole repo.
• Ask Cursor Agent to inspect before editing, then make one small change.
• In review, compare the final diff against the measured hotspots.

Use a tiny review checklist:

• Did the agent report file and function size before editing?
• Did it avoid appending to already-oversized files?
• Did it explain any threshold it chose to ignore?
• Did it keep Scopewalker output separate from edit authority?
• Did the final note include the measured hotspot, not just a cheerful summary?

The trap is trying to prove everything in one session. This is not cursor ai training theater. You are checking one concrete claim: does giving the agent local complexity numbers change where it chooses to edit?

Common questions

• Can Scopewalker stop Cursor from writing a 1000-line file?

  No, Scopewalker is not an enforcement engine by itself. It gives the agent read-only measurements, including default threshold checks for files over 300 lines and functions over 100 lines. The enforcement comes from your Cursor rule, review habit, and willingness to reject diffs that ignore the numbers.

• Where does this fit in a cursor workshop?

  It fits best as a small MCP safety exercise, not as the whole workshop. Give learners one messy folder, one read-only Scopewalker connection, and one Cursor rule. The citable takeaway is simple: an agent that can measure line count, nesting, and parameter count can make a more reviewable edit plan.

• Is it safe to connect an MCP server to a private repo?

  It can be safe when the permission boundary is narrow and understandable. Scopewalker is designed as a local stdio MCP server with read-only tools and no network calls, according to its repository. Still, run it only where source access is appropriate, and do not give it secrets or write-capable companions by default.

• Do Cursor skills replace this kind of MCP server?

  No, Cursor skills and MCP servers solve different problems. A skill can package a repeatable workflow, review recipe, or instruction set; an MCP server exposes tools the agent can call. A good pairing is a skill that says how to review complexity and Scopewalker as the tool that returns the actual metrics.

Best ways to use this research

• Best for: Cursor users who already rely on rules or custom agents, but want the agent to inspect real codebase shape before making changes.
• Best first artifact: A single scoped .mdc rule that asks for Scopewalker metrics before edits in one high-churn folder.
• Best comparison angle: Compare “rule only” prompts against “rule plus read-only MCP metrics” prompts on the same small refactor.
• Best safety boundary: Keep Scopewalker read-only, local, and limited to the repo being reviewed; do not mix it with write or deploy tools.

Further reading

• Cursor — MCP
• Model Context Protocol — specification
• scopewalker-mcp — source

Next step

Pick one ugly folder and make the agent measure before it edits. If the final diff is smaller and easier to review, Scopewalker has earned a permanent place in that repo's Cursor workflow.

One methodology lens

One useful way to read this through our methodology is the Plan step: delegate first-pass decomposition and dependency mapping, review the sequencing and assumptions, and keep ownership of scope and priorities. If that split is still fuzzy, the workflow usually is too.