<div align="center">

```text
  ██████╗ ██████╗ ██████╗ ███████╗      █████╗ ████████╗██╗      █████╗ ███████╗
 ██╔════╝██╔═══██╗██╔══██╗██╔════╝     ██╔══██╗╚══██╔══╝██║     ██╔══██╗██╔════╝
 ██║     ██║   ██║██║  ██║█████╗ █████╗███████║   ██║   ██║     ███████║███████╗
 ██║     ██║   ██║██║  ██║██╔══╝ ╚════╝██╔══██║   ██║   ██║     ██╔══██║╚════██║
 ╚██████╗╚██████╔╝██████╔╝███████╗     ██║  ██║   ██║   ███████╗██║  ██║███████║
  ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝     ╚═╝  ╚═╝   ╚═╝   ╚══════╝╚═╝  ╚═╝╚══════╝
                                 [ M C P ]
```

### High-Performance AST-Aware Model Context Protocol Server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.6-blue.svg?logo=typescript)](https://www.typescriptlang.org/)
[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18.0.0-green.svg?logo=node.js)](https://nodejs.org/)
[![MCP Standard](https://img.shields.io/badge/MCP-1.5.0-purple.svg)](https://modelcontextprotocol.io/)
[![Vitest](https://img.shields.io/badge/Tested%20with-Vitest-orange.svg?logo=vitest)](https://vitest.dev/)

*Connect Claude Code, Claude Desktop, and Autonomous AI Agents directly to structural AST code maps, token-efficient skeletons, and PR blast-radius impact analysis.*

---

</div>

## 📖 Overview

Modern LLM coding agents spend **up to 70% of their context window** ingesting raw file trees and redundant file contents. When modifying large codebases, AI assistants often lack visibility into:

1. **Downstream Callers & Dependents**: Modifying an exported function signature breaks callers 5 directories away.
2. **Token Inflation**: Full-file dumps waste context on implementation bodies instead of type definitions and signatures.
3. **PR Regression Blast Radius**: Lack of awareness about which unit and integration test suites cover the modified AST nodes.

**`code-atlas-mcp` solves this** by exposing an AST-aware intelligence layer via the standard **Model Context Protocol (MCP)**. It parses source files into structural symbol trees, prunes function bodies into token-efficient code skeletons, isolates modified AST nodes across git diffs, and computes transitive regression blast radius.

---

## 🏛️ Architecture

```text
┌────────────────────────────────────────────────────────────────────────┐
│                        AI Coding Clients                               │
│        (Claude Code CLI / Claude Desktop / Cursor / Custom Agents)     │
└──────────────────────────────────┬─────────────────────────────────────┘
                                   │  MCP Protocol (JSON-RPC over stdio)
                                   ▼
┌────────────────────────────────────────────────────────────────────────┐
│                          code-atlas-mcp                                │
│  ┌───────────────────────────────┬──────────────────────────────────┐  │
│  │      MCP Request Router       │      Tool Schema Validators      │  │
│  │ (ListTools / CallTool Handler)│          (Zod Runtime)           │  │
│  └───────────────┬───────────────┴──────────────────┬───────────────┘  │
│                  ▼                                  ▼                  │
│  ┌───────────────────────────────┐  ┌───────────────────────────────┐  │
│  │          AST Engine           │  │          Git Engine           │  │
│  │   • TypeScript Compiler API   │  │   • Unified Diff Parser       │  │
│  │   • Symbol & Hierarchy Extr.  │  │   • Line-to-AST Correlation   │  │
│  │   • Token-Efficient Skeletons │  │   • Working Tree / Ref Diffs  │  │
│  └───────────────┬───────────────┘  └───────────────┬───────────────┘  │
│                  └───────────────┬──────────────────┘                  │
│                                  ▼                                     │
│  ┌──────────────────────────────────────────────────────────────────┐  │
│  │                      Impact Analyzer                             │  │
│  │   • Downstream Callers Graph  • Transitive Dependency BFS        │  │
│  │   • Test Suite Coverage Map   • Risk Scoring & Assessment Engine │  │
│  └──────────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────┬─────────────────────────────────────┘
                                   ▼
┌────────────────────────────────────────────────────────────────────────┐
│                          Local Codebase                                │
│               Filesystem (.ts, .tsx, .js, .jsx) & .git                 │
└────────────────────────────────────────────────────────────────────────┘
```

---

## ⚡ Core MCP Tools

### 1. `get_repo_structure`
Returns a hierarchical, AST-pruned structural map of the repository with optional token-efficient code skeletons. Strips function bodies while preserving complete signatures, exported interfaces, types, and docstrings.

#### Parameters
| Parameter | Type | Required | Description | Default |
| :--- | :--- | :--- | :--- | :--- |
| `rootDir` | `string` | No | Target repository directory. | Current working directory |
| `includeSkeletons` | `boolean` | No | Generate token-efficient code skeletons with stripped function bodies. | `true` |
| `maxDepth` | `number` | No | Maximum directory traversal depth (1-20). | `5` |
| `ignorePatterns` | `string[]` | No | Array of folder/file glob patterns to ignore. | `[]` |
| `fileExtensions` | `string[]` | No | Array of allowed extensions (e.g. `['.ts', '.tsx']`). | Standard TS/JS |

#### Example Tool Output
```json
{
  "rootDir": "/workspace/my-app",
  "totalFiles": 42,
  "totalSymbols": 318,
  "fileTree": {
    "name": "src",
    "type": "directory",
    "children": [
      {
        "name": "auth.ts",
        "type": "file",
        "symbolsCount": 4,
        "summary": {
          "language": "typescript",
          "linesOfCode": 120,
          "symbols": [
            {
              "name": "verifyJwt",
              "kind": "function",
              "signature": "export function verifyJwt(token: string): Promise<JwtPayload>",
              "startLine": 15,
              "endLine": 42,
              "isExported": true
            }
          ],
          "astSkeleton": "import { JwtPayload } from \"./types.js\";\n\nexport function verifyJwt(token: string): Promise<JwtPayload>;"
        }
      }
    ]
  }
}
```

---

### 2. `analyze_diff_impact`
Analyzes modified AST nodes between branches, commits, or the uncommitted working tree to determine affected downstream functions, classes, and components.

#### Parameters
| Parameter | Type | Required | Description | Default |
| :--- | :--- | :--- | :--- | :--- |
| `baseRef` | `string` | No | Base git revision or branch (e.g. `'main'`, `'HEAD~1'`). | Uncommitted working tree |
| `headRef` | `string` | No | Head git revision or branch (e.g. `'feature-auth'`, `'HEAD'`). | Working tree state |
| `repoPath` | `string` | No | Path to git repository root. | Current working directory |

#### Example Tool Output
```json
{
  "baseRef": "main",
  "headRef": "HEAD",
  "changedFilesCount": 2,
  "modifiedFiles": ["src/auth/jwt.ts"],
  "modifiedAstNodes": [
    {
      "filePath": "src/auth/jwt.ts",
      "symbol": {
        "name": "verifyJwt",
        "kind": "function",
        "signature": "export function verifyJwt(token: string, options?: VerifyOptions): Promise<JwtPayload>",
        "startLine": 12,
        "endLine": 35,
        "isExported": true
      },
      "changeType": "modified",
      "modifiedLines": [12, 13, 14]
    }
  ],
  "affectedDownstream": [
    {
      "symbolName": "verifyJwt",
      "sourceFile": "src/auth/jwt.ts",
      "dependentFile": "src/middleware/auth.ts",
      "impactType": "direct_import",
      "reason": "File 'src/middleware/auth.ts' directly imports symbol 'verifyJwt' modified in 'src/auth/jwt.ts'"
    }
  ],
  "summary": "Diff Impact Analysis: 1 file(s) modified across 1 distinct AST symbol(s). Identified 1 downstream dependent reference(s) that require verification."
}
```

---

### 3. `inspect_blast_radius`
Identifies potential regression points, transitive downstream dependents (BFS traversal), and broken test suites for a targeted file change. Calculates a 0-100 risk score with critical factors.

#### Parameters
| Parameter | Type | Required | Description | Default |
| :--- | :--- | :--- | :--- | :--- |
| `targetFile` | `string` | **Yes** | Path to the target source file (e.g. `'src/services/ast-engine.ts'`). | — |
| `repoPath` | `string` | No | Path to repository root. | Current working directory |

#### Example Tool Output
```json
{
  "targetFile": "src/services/user.ts",
  "targetSymbols": [ /* AST Symbols */ ],
  "directDependents": [
    {
      "filePath": "src/controllers/auth.ts",
      "importedSymbols": ["getUserById", "updateUser"]
    }
  ],
  "transitiveDependents": [
    {
      "filePath": "src/routes/api.ts",
      "depth": 2,
      "chain": ["src/services/user.ts", "src/controllers/auth.ts", "src/routes/api.ts"]
    }
  ],
  "affectedSuites": [
    {
      "testFile": "tests/auth.test.ts",
      "reliesOn": ["src/services/user.ts", "src/controllers/auth.ts"],
      "riskLevel": "HIGH",
      "potentialFailures": ["getUserById", "updateUser"]
    }
  ],
  "riskAssessment": {
    "score": 65,
    "level": "HIGH",
    "factors": [
      "Exports 4 symbol(s)",
      "High direct coupling: 3 direct dependent files",
      "Moderate cascade: 5 transitive dependents",
      "1 test suite(s) actively verify dependent code"
    ]
  }
}
```

---

## 🚀 Installation & Quick Start

### Global CLI Installation
```bash
npm install -g code-atlas-mcp
```

### Run Directly via NPX
```bash
npx code-atlas-mcp --root /path/to/your/project
```

---

## 🤖 Claude Integration Configuration

### Claude Desktop Setup
Add `code-atlas-mcp` to your `claude_desktop_config.json`:

* **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
* **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
* **Linux**: `~/.config/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "code-atlas": {
      "command": "npx",
      "args": [
        "-y",
        "code-atlas-mcp"
      ]
    }
  }
}
```

If you want to pin a specific repository directory:
```json
{
  "mcpServers": {
    "code-atlas": {
      "command": "npx",
      "args": [
        "-y",
        "code-atlas-mcp",
        "--root",
        "/absolute/path/to/your/repository"
      ]
    }
  }
}
```

### Claude Code CLI Setup
Launch `claude` with the MCP server attached:

```bash
claude --mcp-server "npx -y code-atlas-mcp"
```

---

## 🛠️ Development & Testing

### Prerequisites
* Node.js >= 18.0.0
* npm >= 9.0.0
* Git CLI

### Setup
```bash
# Clone the repository
git clone https://github.com/GeorgeTsakonas/code-atlas-mcp.git
cd code-atlas-mcp

# Install dependencies
npm install

# Build TypeScript to dist/
npm run build

# Run unit and integration tests with Vitest
npm test

# Run tests in watch mode
npm run test:watch

# Type check
npm run lint
```

---

## 🗺️ Roadmap

- [x] TypeScript Compiler API AST extraction
- [x] Token-efficient skeleton generation (stripped bodies)
- [x] Git diff line-to-AST node correlation
- [x] Downstream dependency graph & call-site impact analysis
- [x] Transitive blast-radius inspection & test suite identification
- [x] MCP Standard stdio transport
- [ ] Python AST parser engine support (`ast` / Tree-sitter)
- [ ] Rust and Go AST parsing modules
- [ ] Semantic vector search over AST symbols

---

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the Project
2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the Branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

---

## 📄 License

Distributed under the MIT License. See [`LICENSE`](./LICENSE) for more information.