CodeAtlas MCP Server

Local-first MCP server for AI-powered codebase intelligence — AST analysis, dependency graphs, and semantic search. Your source code never leaves your machine.

📌 What is CodeAtlas MCP Server?

A Model Context Protocol (MCP) server that provides:

• AST Analysis: Parse TypeScript, Python, PHP, and more.
• Dependency Graphs: Visualize call chains and module relationships.
• Semantic Search: Find code by meaning, not just syntax.
• Local-First: Your code stays on your machine; no telemetry by default.
• Cloud Optional: Connect to codeatlas-platform for dream memory, genome immune system, and skills sync.

Why Use It?

| Use Case | Benefit | |---|---| | AI IDE Integration | Claude Desktop, Cursor, VSCode — get context-aware code intelligence. | | Codebase Audits | Automate dependency analysis, security scans, and refactoring insights. | | Semantic Search | Find functions, classes, or modules by intent, not just name. | | Multi-Language Support | Works with TypeScript, Python, PHP, and more via AST parsers. |

🏗 Architecture

AI IDE → MCP stdio/SSE → Parser (AST) → Dependency Graph → Code Search
                          │
                    codeatlas-platform (HTTP) → Dreams + Genome

| Layer | Components | |---|---| | Parser | TypeScript, Python, PHP AST analysis | | Graph | Dependency graph with chunked force layout | | Search | Semantic code search with regex safety | | Cloud | Optional: connect to codeatlas-platform for dreams/genome |

🔧 Quick Start

1. Install

# Clone the repo
git clone https://github.com/giauphan/codeatlas-mcp-server.git
cd codeatlas-mcp-server

# Install dependencies (requires Node.js 20+)
pnpm install

2. Configure

# Copy env template
cp .env.example .env

# Edit .env (Oracle DB optional for persistent memory)
# Cloud features require both variables; no default URL is used
# Set CODEATLAS_API_URL to your CodeAtlas API base URL
# Set CODEATLAS_API_KEY to your CodeAtlas API key

3. Build

pnpm run build

4. Run

# Local-only mode (no cloud)
pnpm start

# With cloud connection (requires codeatlas-platform running)
CODEATLAS_API_URL=http://localhost:8080 CODEATLAS_API_KEY=your_api_key_here pnpm start

📡 MCP Tools (30+)

| Category | Tools | |---|---| | Code Analysis | analyze_project, code_search, file_info | | AST | parse_file, find_symbol, get_dependencies | | Graphs | dependency_graph, call_graph | | Security | scan_vulnerabilities | | Cloud | save_dream_memory, query_dream_memories, sync_dreams | | Skills | search_skills, get_skill, install_skill |

Example: Connect to Claude Desktop

Add to claude-desktop-config.json:

{
  "mcpServers": {
    "codeatlas": {
      "command": "npx",
      "args": [
        "-y",
        "codeatlas-mcp-server"
      ]
    }
  }
}

Example: Connect to Cursor/VSCode (SSE)

Add to settings.json:

{
  "mcp.sse": {
    "codeatlas": "npx codeatlas-mcp-server"
  }
}

Connect to Zed (MCP context server)

Zed has no Claude-style hooks, so the Second Brain hooks are exposed as MCP tools instead.

Option A — automatic setup:

codeatlas-enterprise setup zed

This writes a codeatlas entry into Zed's context_servers (passing CODEATLAS_API_KEY/CODEATLAS_API_URL from your environment). Restart Zed afterward.

Option B — manual: add to Zed settings.json (open via zed: open settings file):

{
  "context_servers": {
    "codeatlas": {
      "command": "npx",
      "args": ["-y", "codeatlas-mcp-server"],
      "env": { "CODEATLAS_API_KEY": "your_api_key_here" }
    }
  }
}

Then in Zed's Agent Panel, call the brain_context tool at the start of a task to inject Second Brain memory, and save_dream_memory after a task to persist learnings. route_task suggests a model/effort (advisory only — Zed does not auto-switch models). See Zed Integration.

🔒 Security & Environment Variables

CodeAtlas MCP Server is designed with a local-first architecture and several security hardening measures to protect your credentials and codebase data:

• No Disk Persistence: Credentials like CODEATLAS_API_KEY are kept entirely in-memory and are never persisted to .env files or disk. You must supply your key via environment variables.
• Strict Destination Validation: When connecting to cloud features, the destination AI and backend URLs are strictly validated. Credentials can only flow to trusted official domains (*.codeatlas.ai, opencode.ai) or local addresses (localhost, 127.0.0.1).
• Telemetry & Logging: Potential credential leaks are sanitized and redacted from all console and error logs.

Required & Optional Environment Variables

| Variable | Description | Default | |---|---|---| | CODEATLAS_API_KEY | Secret key to connect to CodeAtlas Cloud services for AI memory and scan features. | (none) | | CODEATLAS_API_URL | Target URL for CodeAtlas Cloud. Validated via allowlists to prevent credential exfiltration. | https://api.codeatlas.ai | | CODEATLAS_ALLOW_CUSTOM_URL | Set to true to allow sending credentials to self-hosted or unlisted destinations. Required for private network deployments. | false | | CODEATLAS_SCAN_AI_KEY | Key for deep AI security scanning using an external LLM. | (none) | | CODEATLAS_SCAN_AI_URL | Endpoint for deep AI security scanning. | (none) |

📚 Documentation

| Guide | Description | |---|---| | Development Guide | Full environment setup, commands, and troubleshooting. | | Deployment Guide | PM2, systemd, Nginx TLS, and healthchecks. | | API Examples | Auth, dream memory, and MCP config examples. |

🤝 Contributing

See CONTRIBUTING.md for guidelines.

📜 License

MIT © Giau Phan

🔗 Related Projects

• codeatlas-platform — HTTP server for dream memory and genome.
• codeatlas-mcp — npm package for easy installation.

⚠️ Known Limitations

• Oracle DB Required for Persistent Memory: Local-only mode works without Oracle, but dream memory persistence requires it.
• Cloud Dream Query Filters: When querying memories with scope, tags, or memory_type filters, the backend performs vector hybrid search on the query text plus SQL filtering on the other parameters. The tags parameter is passed as a JSON string to the upstream API. The related_ids parameter is also supported for filtering by related memory IDs.
• Multi-Tenant Not Supported: Only single-tenant mode available.
• Security: No built-in rate limiting; use a reverse proxy (Nginx) in production.

🐛 Issues & Support

• Report bugs or request features: GitHub Issues
• For questions: Discussions