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?

🏗 Architecture

AI IDE → MCP stdio/SSE → Parser (AST) → Dependency Graph → Code Search
                          │
                    codeatlas-platform (HTTP) → 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 the optional local environment template. This file is ignored by Git.
cp .env.example .env

# Edit .env
# 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 (39)

Example: Connect to Claude Desktop

Add to claude-desktop-config.json:

{
  "mcpServers": {
    "codeatlas": {
      "command": "npx",
      "args": [
        "--yes",
        "--package=codeatlas-mcp-server",
        "codeatlas-mcp"
      ]
    }
  }
}

Example: Connect to Cursor/VSCode (stdio)

Add to settings.json:

{
  "mcpServers": {
    "codeatlas": {
      "command": "npx",
      "args": ["--yes", "--package=codeatlas-mcp-server", "codeatlas-mcp"]
    }
  }
}

Connect to Zed (MCP context server)

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

For Claude hook setup, safe diagnostics, rollback controls, and the explicit memory_bootstrap tool for hosts without injection hooks, see Memory pipeline operations.

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": ["--yes", "--package=codeatlas-mcp-server", "codeatlas-mcp"],
      "env": {
        "CODEATLAS_API_URL": "https://api.codeatlas.ai",
        "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:

• Credential Storage: Set CODEATLAS_API_KEY in the process environment to avoid storing it in a file. If you configure it in .env or an MCP client setting, the key is stored on disk; protect that file and keep it out of version control.
• 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

📚 Documentation

🤝 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