Content
# 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.
[](https://github.com/giauphan/codeatlas-mcp-server/actions/workflows/ci.yml)
[](https://nodejs.org/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/giauphan/codeatlas-mcp-server/releases)
## 📌 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](https://github.com/giauphan/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
```bash
# 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
```bash
# 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
```bash
pnpm run build
```
### 4. Run
```bash
# 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`:
```json
{
"mcpServers": {
"codeatlas": {
"command": "npx",
"args": [
"-y",
"codeatlas-mcp-server"
]
}
}
}
```
### Example: Connect to Cursor/VSCode (SSE)
Add to `settings.json`:
```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:**
```bash
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`):
```json
{
"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](./docs/ZED_INTEGRATION.md).
---
## 🔒 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](./docs/DEVELOPMENT.md) | Full environment setup, commands, and troubleshooting. |
| [Deployment Guide](./docs/DEPLOYMENT.md) | PM2, systemd, Nginx TLS, and healthchecks. |
| [API Examples](./docs/API_EXAMPLES.md) | Auth, dream memory, and MCP config examples. |
---
## 🤝 Contributing
See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
---
## 📜 License
MIT © [Giau Phan](mailto:giauphan012@gmail.com)
---
## 🔗 Related Projects
- [codeatlas-platform](https://github.com/giauphan/codeatlas-platform) — HTTP server for dream memory and genome.
- [codeatlas-mcp](https://www.npmjs.com/package/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](https://github.com/giauphan/codeatlas-mcp-server/issues)
- For questions: [Discussions](https://github.com/giauphan/codeatlas-mcp-server/discussions)
Connection Info
You Might Also Like
No recommendations available