# codecity-mcp

An [MCP](https://modelcontextprotocol.io) server that analyzes a local codebase and exposes its structure, per-file summaries, dependency graph, and complexity hotspots as tools Claude (or any MCP client) can call.

This is the data layer for a larger project: a 3D "code city" - a navigable visualization where a codebase becomes a walkable city (files as buildings, folders as districts, imports as roads) with Claude acting as a guide that explains what you're looking at and helps you actually build a mental model of the codebase, not just stare at a pretty render of it. This repo is the first, standalone piece: it's useful on its own, with or without the 3D viewer, to anyone pointing Claude at an unfamiliar codebase.

## Tools

| Tool | What it does |
|---|---|
| `get_repo_structure` | Returns the folder/file tree of a repo, plus totals (file count, size). Start here to get oriented. |
| `get_file_summary` | Structural summary of one file: line count, function/class count, its imports, and a short excerpt. |
| `get_dependency_graph` | Resolves relative imports between files into a graph (internal edges) plus a list of external package names. |
| `get_complexity_hotspots` | Ranks files by a simple size/complexity heuristic, so you know where to look first. |

## Design notes

- **Zero analysis dependencies.** Repo scanning, `.gitignore` handling, and JS/TS structural analysis (function/class/import counts) are hand-rolled with no parser or ignore-matching library. This is a deliberate tradeoff: regex/heuristic-based analysis instead of a full AST walk, in exchange for a small, auditable dependency footprint (just the MCP SDK and zod). The complexity score is explicitly a heuristic, not real cyclomatic complexity - documented in `src/complexity.ts`.
- **JS/TS-aware today, extensible later.** Non-JS/TS files still get scanned and line-counted; structural analysis (functions, classes, imports) currently only applies to `.ts/.tsx/.js/.jsx/.mjs/.cjs`. Adding another language means adding another analyzer, not touching the MCP layer.
- **Tested without the SDK installed.** `test/smoke.ts` exercises the scanner/analyzer/graph/complexity logic directly (no MCP SDK or zod import), so the core logic is verified independently of the protocol layer. It runs the tool on its own source as a sanity check.

## Setup

```bash
npm install
npm run build
```

## Running it

### Standalone smoke test (no MCP client needed)

```bash
npm test
```

Runs the analysis logic (scanner, analyzer, dependency graph, complexity ranking) directly, with no MCP SDK involved - points it at this repo's own source and prints what it finds. Useful to sanity-check the core logic in isolation before wiring up a client.

### With the MCP Inspector

```bash
npm run inspect
```

Opens a browser UI to call each tool manually and see raw responses.

### With Claude Desktop or Claude Code

Add to your MCP client config (e.g. `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "codecity": {
      "command": "node",
      "args": ["/absolute/path/to/codecity-mcp/build/index.js"]
    }
  }
}
```

Restart the client, then ask it something like: "Use codecity to show me the structure of ~/code/some-project, and tell me which files are the most complex."

## Roadmap

- [ ] Orchestrator layer: a small agent loop that decides what to explain next based on what's already been explored, and quizzes the user to check understanding (not just recall) - the piece that turns this from a static analysis tool into a capability-building guide.
- [ ] 3D city renderer (BabylonJS + React) that consumes `get_repo_structure` and `get_dependency_graph` to render the actual city.
- [ ] Language support beyond JS/TS.

## License

MIT