codecity-mcp

An MCP 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

npm install
npm run build

Running it

Standalone smoke test (no MCP client needed)

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

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):

{
  "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