npm package: @kridaydave/code-mapper
Description: MCP server for codebase mapping and analysis with graph visualization
Author: kridaydave
Latest version: 1.0.1

# CodeGraph

An MCP server that uses AST parsing to map TypeScript/JavaScript codebase structure and expose codebase intelligence for AI assistants.

## Features

- **AST-based analysis** - Uses `ts-morph` (TypeScript compiler API) to parse code without running it
- **Dependency graphs** - Builds graph representations of how files, functions, and classes relate
- **Impact ranking** - Identifies the most central/critical files using graph centrality metrics
- **Call chain tracing** - Finds dependency paths between any two symbols
- **Mermaid diagrams** - Generates visual dependency diagrams

## MCP Tools

| Tool | Description |
|------|-------------|
| `scan_codebase` | Scan a directory and return a summary of all files, functions, classes, and relationships |
| `find_function` | Search for a function or class by name, returns location, signature, callers, and callees |
| `analyze_dependencies` | Returns the full dependency graph or a subgraph for a specific file (JSON or Mermaid) |
| `rank_impact` | Ranks files by centrality (in-degree, out-degree, betweenness) to identify critical modules |
| `trace_call_chain` | Traces the call chain / dependency path from one function or file to another |
| `analyze_complexity` | Analyzes code complexity metrics for each file (cyclomatic, cognitive complexity, nesting depth) |

## MCP Resources

| Resource | Description |
|----------|-------------|
| `codebase://summary` | Cached summary of the most recently scanned codebase |
| `codebase://graph/{format}` | Dependency graph in `json` or `mermaid` format |

## Setup

### Install

```bash
npm install
npm run build
```

### Use with Claude Desktop (or any MCP client)

Add this to your MCP client configuration:

```json
{
  "mcpServers": {
    "CodeGraph": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/CodeGraph/src/index.ts"]
    }
  }
}
```

Or after building:

```json
{
  "mcpServers": {
    "CodeGraph": {
      "command": "node",
      "args": ["/absolute/path/to/CodeGraph/dist/index.js"]
    }
  }
}
```

## Usage

Once connected, AI assistants can:

1. **Scan your codebase**: "Scan my codebase at ./src"
2. **Find symbols**: "Where is the authenticate function defined and who calls it?"
3. **Analyze dependencies**: "Show me the dependency graph as mermaid"
4. **Rank impact**: "What's the most central file in my project?"
5. **Trace paths**: "Trace the call chain from handleRequest to saveToDatabase"

## Architecture

```
src/
├── index.ts              # MCP server entry point (stdio transport)
├── parser/
│   ├── types.ts          # FileInfo, FunctionInfo, ClassInfo, etc.
│   ├── FileAnalyzer.ts   # ts-morph single-file analysis
│   └── ProjectParser.ts  # Directory scanning with caching
├── graph/
│   ├── types.ts          # GraphNode, GraphEdge, RankedFile, etc.
│   ├── GraphBuilder.ts   # Converts ParseResult to graphology Graph
│   └── GraphAnalyzer.ts  # Centrality, path finding, cycle detection
└── mcp/
    ├── cache.ts          # Shared analyzer cache
    ├── tools.ts          # 5 MCP tool definitions
    └── resources.ts      # MCP resource definitions
```

## Tech Stack

- **ts-morph** - TypeScript AST parsing (wraps the TypeScript compiler API)
- **graphology** - Graph data structure for dependency mapping
- **graphology-metrics** - Centrality algorithms (betweenness, degree, etc.)
- **graphology-shortest-path** - Bidirectional shortest path finding
- **@modelcontextprotocol/server** - MCP server SDK with stdio transport
- **zod** - Schema validation for tool inputs

## Ignored Directories

By default, these directories are excluded from scanning:
- `node_modules`, `dist`, `build`, `.git`, `coverage`
- `.next`, `.nuxt`, `.svelte-kit`, `__tests__`, `.cache`

## License

MIT