Skip to main content
Glama
sove-mcp
by JrKrishh
README.md
# 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

TDQS

A4.2/5.0

Scored across 4 tools

Disambiguation4/5

Each tool targets a distinct analysis aspect, but analyze_repository overlaps by summarizing entry points, cycles, and complexity, which are also covered by the specialized tools. The descriptions clarify that the summary is high-level, while the other tools provide deeper dives.

Naming Consistency4/5

Three tools use verb_noun naming (analyze_repository, find_entry_points, find_circular_dependencies), but most_complex_files is an adjective phrase, breaking the pattern. All names use snake_case, maintaining readability despite the inconsistency.

Tool Count5/5

Four tools is well-scoped for a code analysis server, falling within the ideal 3-15 range. Each tool serves a distinct purpose in architectural analysis, and the count feels neither thin nor bloated.

Completeness4/5

The set covers the key aspects of codebase analysis: overall summary, entry points, circular dependencies, and complexity. Minor gaps exist (e.g., dependency depth, module coupling), but the core workflows for architectural understanding are complete.

Maintenance

ActivityInactive
ResponsivenessNo recent community issues