Skip to main content
Glama
code-atlas-mcp

code-atlas-mcp

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

High-Performance AST-Aware Model Context Protocol Server

License: MIT TypeScript Node.js MCP Standard Vitest

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


📖 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.


Related MCP server: MCP Filesystem Server

🏛️ Architecture

┌────────────────────────────────────────────────────────────────────────┐
│                        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

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

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

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

npm install -g code-atlas-mcp

Run Directly via NPX

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

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

If you want to pin a specific repository directory:

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

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

🛠️ Development & Testing

Prerequisites

  • Node.js >= 18.0.0

  • npm >= 9.0.0

  • Git CLI

Setup

# 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

  • TypeScript Compiler API AST extraction

  • Token-efficient skeleton generation (stripped bodies)

  • Git diff line-to-AST node correlation

  • Downstream dependency graph & call-site impact analysis

  • Transitive blast-radius inspection & test suite identification

  • 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 for more information.

Available Tools

3 tools
analyze_diff_impactB

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

Inputs: baseRef, headRef, repoPath.

get_repo_structureB

Returns a hierarchical, AST-pruned structural map of the repository with token-efficient code skeletons, stripping implementation bodies to save context tokens.

Inputs: rootDir, maxDepth, fileExtensions, ignorePatterns, +1 more.

inspect_blast_radiusB

Identifies potential regression points, direct and transitive downstream dependents, and broken test suites for a targeted file change.

Inputs: targetFile (required), repoPath.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 3 tools

    Disambiguation3/5

    get_repo_structure is clearly distinct, but analyze_diff_impact and inspect_blast_radius both focus on downstream impact analysis, creating potential confusion. Their descriptions differentiate them (diff-based vs. single-file-based), but agents may need careful reading to pick correctly.

    Naming Consistency5/5

    All three tools follow a consistent verb_noun pattern in snake_case (analyze_diff_impact, get_repo_structure, inspect_blast_radius). The naming is predictable and stylistically uniform, making it easy to infer purpose.

    Tool Count4/5

    Three tools is on the low end but well-scoped for the server's stated purpose of code structure and impact analysis. Each tool covers a distinct aspect, and the count feels reasonable, not sparse enough to seem incomplete or excessive.

    Completeness4/5

    The tool set covers structural overview, diff impact across versions, and blast radius for targeted changes—a solid read-only analysis surface. Minor gaps exist (e.g., no direct dependency graph query), but the core workflows are adequately supported without dead ends.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Enables AI assistants to understand and navigate codebases through structural analysis. Provides code mapping, symbol search, and impact analysis using ast-grep for accurate parsing of Python, JavaScript, TypeScript, and Go projects.
      4
      52
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides LLM-optimized tools for advanced code analysis, repository complexity evaluation, and call graph generation. It enables users to visualize directory structures, detect code patterns, and build semantic context with significant token savings.
      11 npm
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Enables LLMs to efficiently read, write, and refactor code using precise AST-based operations, reducing token usage and context window waste.
      25
      238 npm
      3
      MIT