# sove-mcp

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
[![node](https://img.shields.io/badge/node-%3E%3D20-green.svg?style=flat-square)](https://nodejs.org/)
[![MCP](https://img.shields.io/badge/MCP-1.30-blue.svg?style=flat-square)](https://modelcontextprotocol.io/)

An [MCP](https://modelcontextprotocol.io/) 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:

```json
{
  "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](https://www.npmjs.com/package/sove-toolkit), which resolves
CommonJS `require()`, ESM imports, and TypeScript path aliases (`@/components/Button`).

## Install

```bash
npm install -g sove-mcp
```

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

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

For Claude Code:

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

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

## Development

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