sove-mcp

An MCP server that gives Claude structural understanding of a codebase — dependency graph, entry points, complexity ranking and import cycles — without reading every file into context.

Why

Claude can already read files. But answering "what are the entry points, and which five modules are most complex?" means pulling the whole repository into the context window. On a 145-file application that is tens of thousands of tokens, most of it irrelevant.

This computes the answer locally and returns a few hundred tokens:

{
  "files": 35,
  "dependencyEdges": 83,
  "circularDependencies": 0,
  "entryPoints": [{ "file": "cli/index.ts", "dependencies": 5 }],
  "mostComplex": [
    { "file": "phases/phase2-ghostwriter/test-generator.ts", "cyclomatic": 105, "cognitive": 95 }
  ]
}

Built on sove-toolkit, which resolves CommonJS require(), ESM imports, and TypeScript path aliases (@/components/Button).

Install

npm install -g sove-mcp

Add to your MCP client config. For Claude Desktop, claude_desktop_config.json:

{
  "mcpServers": {
    "sove": {
      "command": "sove-mcp",
      "env": {
        "SOVE_MCP_ALLOWED_ROOTS": "/path/to/your/projects"
      }
    }
  }
}

For Claude Code:

claude mcp add sove -e SOVE_MCP_ALLOWED_ROOTS=/path/to/your/projects -- sove-mcp

Tools

Tool	Returns
analyze_repository	Full summary: files, edges, entry points, cycles, complexity
find_entry_points	Modules nothing imports — where execution starts
find_circular_dependencies	Import cycles, via Tarjan's algorithm, with severity
most_complex_files	Cyclomatic and cognitive complexity ranking
generate_documentation	Writes JSDoc into source files — opt-in only, see below

All tools take a directory. Everything except the last is read-only and annotated as such, so clients can surface that to the user.

Security

An MCP server runs with the privileges of whoever launched it, and the model decides what to call. Two defaults follow from that:

Reads are confined to allowed roots. SOVE_MCP_ALLOWED_ROOTS (path-separator delimited) defines what the server may read; it defaults to the working directory. Paths are compared with path.relative, not string prefixes — /data-private starts with /data as a string but is not inside it, and a prefix check would let it through.

Nothing writes unless you opt in. generate_documentation modifies source files, so it is not registered at all unless SOVE_MCP_ALLOW_WRITES=true. A default install cannot alter your files regardless of what the model is asked to do.

SOVE_MCP_ALLOWED_ROOTS="/home/me/work:/home/me/side" SOVE_MCP_ALLOW_WRITES=true sove-mcp

Development

npm install
npm test        # 12 tests, driven over real stdio JSON-RPC
npm start

The tests spawn the actual server process and speak JSON-RPC to it rather than calling handlers directly — that is the only way to catch schema-registration, transport and startup faults, which is where servers like this actually break.

Licence

MIT