<div align="center">

CodeAtlas MCP Enterprise

Enterprise-Grade, Local-First MCP Server for AI-Powered Code Intelligence

CodeAtlas MCP Enterprise is an ultra-lightweight, local-first Model Context Protocol (MCP) server that securely indexes your codebase, performs deep AST-based analysis, and provides 20+ intelligent tools for AI code assistants. Your source code never leaves your machine.

</div>

---

📋 Table of Contents

• Why CodeAtlas MCP?
• Features
• Architecture Overview
• Quick Start
• Authentication
• AI Editor Integration
  • Cursor
  • Claude Desktop
  • VS Code / Windsurf / Copilot
• MCP Tools Reference
  • Analysis & Indexing
  • Code Exploration
  • Dependency & Impact Analysis
  • Visualization & Diagrams
  • Memory & Persistence
  • Security & Architecture
  • Project Operations
• Security Model
• Multi-Tenant Mode
• Environment Configuration
• How It Works
• License

---

🎯 Why CodeAtlas MCP?

AI code assistants are powerful — but they work best with context. CodeAtlas gives them X-ray vision into your codebase by:

• 🔍 Deep parsing — Understands JavaScript, TypeScript, Python, and PHP at the AST level
• 🧠 Persistent memory — Retains insights across conversations via Dreaming Memory
• 🔒 Zero data leakage — All parsing happens locally, no source code ever transmitted
• ⚡ Blazing fast — Full codebase analysis in seconds, incremental re-indexing
• 🔌 Universal compatibility — Works with any MCP-compatible editor (Cursor, Claude, VS Code, Windsurf, Copilot)

---

✨ Features

Feature	Description
🔒 Local-First Parsing	AST analysis runs entirely on your machine — zero code uploaded
🔌 MCP Protocol	Works with all MCP-compatible AI editors
📁 Auto Workspace Discovery	Automatically finds projects in your workspace
🔍 Multi-Language AST	JavaScript, TypeScript, Python, PHP with deep dependency resolution
🧠 Dreaming Memory	Persistent AI memory with vector search for cross-session context
🏠 Multi-Tenant Isolation	Isolate projects by workspace with sandbox boundaries
🔐 API Key Auth	Secure communication via cryptographic hash verification
⚡ Incremental Indexing	Only re-parses changed files for near-instant updates
🏗️ Knowledge Graph	Visualize modules, classes, and functions as an interactive graph
🌐 Remote Sync	Optionally sync metadata to CodeAtlas Enterprise via HTTPS
📊 Code Metrics	LOC, complexity scores, function counts per project
🛡️ Security Scanner	Detect hardcoded secrets, unsafe functions, SQL injection
🔄 Real-time Watching	Auto re-index on file changes via chokidar

---

🏗 Architecture Overview

┌─────────────────────────────────────────────────────────┐
│                    Your Local Machine                     │
│                                                           │
│   ┌──────────┐    ┌────────────┐    ┌────────────────┐   │
│   │  Source   │───▶│    AST     │───▶│   MCP Server   │   │
│   │  Code     │    │   Parser   │    │  (this tool)   │───┼──▶ AI Editor
│   │  (JS/TS/  │    │  (local)   │    └───────┬────────┘   │
│   │   PY/PHP)│    └────────────┘            │            │
│   └──────────┘                               │            │
│                                              ▼            │
│                                  ┌──────────────────┐     │
│                                  │  Dreaming Memory  │     │
│                                  │  (optional: sync) │     │
│                                  └────────┬─────────┘     │
└───────────────────────────────────────────┼───────────────┘
                                            │ HTTPS (optional)
                                            ▼
                               CodeAtlas Enterprise Server

---

🚀 Quick Start

Prerequisites

• Node.js v18.0.0 or higher (v20+ recommended)

Install Globally

npm install -g codeatlas-enterprise

Run

# Scan current directory and start MCP server
codeatlas-mcp

# With API key for remote sync
codeatlas-mcp --apiKey="your_api_key_here"

# Point to a specific project directory
codeatlas-mcp --projectDir="/path/to/your/project"

That's it! Your AI editor can now connect to the MCP server running on stdio.

---

🔑 Authentication

Provide your API Key in one of these ways:

1. Environment Variable:

   export CODEATLAS_API_KEY="your_api_key_here"
   

2. CLI Argument:

   codeatlas-mcp --apiKey="your_api_key_here"
   

3. Local .env File (in the directory where you run the command):

   CODEATLAS_API_KEY=your_api_key_here
   

---

🔌 AI Editor Integration

Cursor

Add to ~/.cursor/mcp.json or project-level .cursor/mcp.json:

{
  "mcpServers": {
    "codeatlas": {
      "command": "codeatlas-mcp",
      "args": ["--apiKey", "YOUR_API_KEY_HERE"]
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "codeatlas": {
      "command": "codeatlas-mcp",
      "args": ["--apiKey", "YOUR_API_KEY_HERE"]
    }
  }
}

VS Code / Windsurf / Copilot

For any MCP-compatible editor, use the same JSON structure:

{
  "mcpServers": {
    "codeatlas": {
      "command": "codeatlas-mcp",
      "args": ["--apiKey", "YOUR_API_KEY_HERE"]
    }
  }
}

Note: If you're running without a remote server, omit the --apiKey argument. The local MCP tools (analysis, search, graph) work fully offline.

---

🛠 MCP Tools Reference

CodeAtlas MCP exposes 20+ tools organized into categories:

Analysis & Indexing

Tool	Description
analyze	Trigger full AST analysis of the current project
get_project_structure	Get entities tree (modules, classes, functions, variables)
get_file_entities	List all entities defined in a specific file

Code Exploration

Tool	Description
search_entities	Search for functions, classes, modules by name (fuzzy)
code_search	Search source file contents for any text or regex
get_file_content	Read file contents with line numbers

Dependency & Impact Analysis

Tool	Description
get_callers	Find all functions/callers that reference a symbol
get_callees	Find everything a function/module imports or calls
impact_analysis	Full blast radius: callers + callees + test files
get_dependencies	Get import/call/containment/implements relationships

Visualization & Diagrams

Tool	Description
generate_system_flow	Mermaid flowchart of module architecture
generate_feature_flow_diagram	Mermaid sequence/flow diagram for a feature
trace_feature_flow	Ordered call chain from entry point to database

Memory & Persistence

Tool	Description
query_dream_memories	Semantic vector search across past AI memories
save_dream_memory	Persist an AI insight or observation for future sessions
get_system_memory	Retrieve business rules and change logs
sync_system_memory	Save business rules or change descriptions

Security & Architecture

Tool	Description
scan_enterprise_vulnerabilities	Scan all projects for hardcoded secrets, unsafe functions, SQL injection
detect_architectural_smells	Detect circular dependencies, God objects, dead code

Project Operations

Tool	Description
list_projects	List all discovered and indexed projects
refresh_projects	Re-scan directories for new or removed projects
get_project_insights	AI-generated refactoring and maintainability suggestions

---

🔒 Security Model

🔐 Local-First by Design

CodeAtlas MCP Enterprise follows a zero-trust, local-first architecture:

1. Parsing is local — All source file reading, AST generation, and relationship mapping happens on your machine. No source code is ever uploaded.

2. No credentials embedded — The package contains zero database passwords, Firebase configs, or private server keys. All remote communication uses standard HTTPS with Bearer token auth.

3. Encrypted sync — If you enable remote sync, metadata is transmitted over HTTPS. The server authenticates via cryptographic hash of your API key.

🔒 What Gets Sent (When Sync is Enabled)

Only structural metadata is transmitted:

• File paths and names (relative to project root)
• Function/class/module names and line numbers
• Import/export relationships
• Analysis statistics (file count, LOC, complexity)

Raw source code, credentials, and proprietary logic are never transmitted.

🏠 Multi-Tenant Isolation

When multi-tenant mode is enabled:

• Each tenant's projects are isolated in separate sandbox directories
• Path traversal attacks are blocked by strict boundary validation
• Memory and analysis data are scoped per-tenant

---

🏠 Multi-Tenant Mode

Enable tenant isolation via environment variables:

CODEATLAS_MULTI_TENANT=true
CODEATLAS_PROJECTS_ROOT=./tenants

Each tenant's projects live in ./tenants/{tenantId}/, with strict path-boundary enforcement.

---

🌍 Environment Configuration

Variable	Default	Description
CODEATLAS_API_KEY	—	API key for authenticating with remote server
CODEATLAS_API_URL	https://your-server.com/api	Remote CodeAtlas server URL
CODEATLAS_MULTI_TENANT	false	Enable multi-tenant isolation
CODEATLAS_PROJECTS_ROOT	./tenants	Root directory for tenant sandboxes
CODEATLAS_PROJECT_DIR	process.cwd()	Default project path
NODE_ENV	production	Environment mode

---

⚙️ How It Works

1. Start — Run codeatlas-mcp in your project directory or point it with --projectDir
2. Auto-Discover — The server scans for projects by detecting package.json, pyproject.toml, composer.json
3. AST Parse — Each source file is parsed into an Abstract Syntax Tree
4. Build Graph — Modules, classes, functions, and their relationships form a Knowledge Graph
5. Serve MCP — AI editors query the graph through 20+ MCP tools
6. Dream — Insights persist across sessions via Dreaming Memory (optional remote vector store)

---

📄 License

MIT © 2026 Giau Phan

---

🔗 Related Projects

• CodeAtlas AI — Full enterprise server with Oracle 26ai memory, dashboard, security scanner
• npm package — Install via npm