Universal MCP Server · v2.5

Chart Your
Codebase

The universal MCP server for AI-assisted development. Serves docs, manages session state, runs playbooks, syncs from git diffs, and maps your entire project — in any IDE, any language.

terminal

$ npm install -g @thinkneverland/atlas-mcp

$ atlas init

$ atlas status

Start Exploring View on GitHub

Scroll to explore

Map Legend

What's in the Atlas

Eighteen tools. One server. Every capability your AI needs to navigate your codebase like a seasoned cartographer.

I

Docs & Playbooks

Knowledge at the Ready

Serve project docs to your AI precisely when needed. Phase-by-phase playbook delivery keeps context lean and prevents LLM overflow.

II

Session Memory

Your AI Never Forgets

Persistent decisions, progress entries, and architectural context. Start any session and your AI picks up exactly where you left off.

III

Dependency Analysis

Know What Breaks First

Blast radius analysis, import chains, and dead code detection. Understand full impact before touching a single file.

IV

Code Intelligence

Navigate Every Symbol

Project-wide symbol search, file export analysis, and type definitions. Your AI finds the right function, class, or interface in seconds.

V

Project Health

See Your Risk Surface

Hotspot detection, coverage gaps, security surface analysis, and error pattern recognition. Keep the ship seaworthy.

VI

Impact Graph

Route↔Table Linking

See which API routes touch which database tables — with 2-hop analysis. Supports Prisma, Drizzle, Mongoose, Eloquent, and raw SQL.

VII

Project Map

The Full Territory

Monorepo workspace structure, cross-package dependency graphs, commit velocity, and plain-English diff explanations.

VIII

DB Introspection

Query the Deep

Schema inspection and read-only queries against any database. PostgreSQL, MySQL, MSSQL, and SQLite. Auto-detected from connection URL.

The Expedition

Chart Your Course

Three steps from installation to a fully navigated, AI-powered codebase.

01

Drop anchor

Install the Atlas

Install globally and configure your IDE. AtlasMCP registers itself as an MCP server — Windsurf, Cursor, VS Code, and Zed all supported.

Install

$ npm install -g @thinkneverland/atlas-mcp

Use the global binary — not npx. Native modules require a stable install path.

02

Run atlas init

Chart the Territory

Auto-detects your tech stack, scans git history, bootstraps architectural decisions, and extracts project conventions from config files.

Initialize

$ atlas init

Works with any language: TypeScript, Python, Go, Rust, PHP, Ruby, Java, and more.

03

Set sail

Navigate with AI

Your AI calls start_session, loads full context, and begins navigating. Every decision recorded. Every change synced. Context that compounds.

Verify

$ atlas status

Add .windsurfrules or .cursorrules to make Atlas tools automatic on every session.

Full Getting Started Workflow

Step	What Happens
1. atlas init	Creates .atlas/ folders, auto-detects and seeds tech stack from config files
2. Add IDE rules	Create .windsurfrules or .cursorrules so the AI uses Atlas tools proactively
3. First AI session	AI calls start_session + get_project_context → loads seeded context automatically
4. Enrich (optional)	AI reads codebase and adds richer context: project description, conventions, directory mapping
5. Use playbooks	Run atlas run <playbook> for guided workflows, or use tools directly

IDE Configuration

Configure Your IDE

AtlasMCP works with every major AI IDE. Pick yours and paste the config.

Important: Always use the globally installed atlas-mcp binary — not npx. Native modules require a stable install path.

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "atlas-mcp": {
      "command": "atlas-mcp",
      "args": [],
      "env": {
        "ATLAS_DOCS_DIR": ".atlas"
      }
    }
  }
}

Recommended: Add IDE Rules

Create .windsurfrules in your project root to make Atlas tools automatic on every AI session. Get the template via:

$ atlas docs show ide-rules

~/.cursor/mcp.json

{
  "mcpServers": {
    "atlas-mcp": {
      "command": "atlas-mcp",
      "args": [],
      "env": {
        "ATLAS_DOCS_DIR": ".atlas"
      }
    }
  }
}

Recommended: Add IDE Rules

Create .cursorrules in your project root to make Atlas tools automatic on every AI session. Get the template via:

$ atlas docs show ide-rules

Cline MCP Settings

{
  "mcpServers": {
    "atlas-mcp": {
      "command": "atlas-mcp",
      "args": [],
      "env": {
        "ATLAS_DOCS_DIR": ".atlas"
      }
    }
  }
}

settings.json

{
  "context_servers": {
    "atlas-mcp": {
      "command": {
        "path": "atlas-mcp",
        "args": []
      }
    }
  }
}

.continue/config.json

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "atlas-mcp",
          "args": []
        }
      }
    ]
  }
}

Power-Up

Pair with Card-O-Matic

AtlasMCP knows your codebase inside out. Card-O-Matic turns that knowledge into professional story cards — instantly.

1

Atlas builds your context

AtlasMCP stores your tech stack, architectural decisions, domain roles, entities, and active tasks in a persistent state database. Your AI always knows exactly what the project is.

2

Run the Card-O-Matic prompt

The built-in card-o-matic prompt is pre-loaded in your Atlas docs. Retrieve it and your AI generates complete, professional story cards with acceptance criteria, subtasks, and context — not just a title.

$ atlas docs show card-o-matic

3

Or use Card-O-Matic directly

Visit card-o-matic.thinkneverland.com for the full web experience. Paste your Atlas context and generate story cards ready for Linear, Jira, or your issue tracker of choice.

Open Card-O-Matic

Story Card

Add atlas init post-merge hook

Feature

Atlas Context

Project uses Git hooks for automation. Tech stack: TypeScript, Node.js. Current hooks: post-commit (sync). Pattern from atlas init detected.

Acceptance Criteria

Hook installs silently via atlas init
Triggers atlas rebuild on post-merge
Appends to existing hooks safely
Fails gracefully if atlas not found

TypeScript Git Hooks ~2 pts

Generated by Card-O-Matic using Atlas context

CLI Reference

Command the Atlas

Every capability available from the command line. Expand a group to explore.

Core 4 commands

atlas status	Show server status, DB path, git info, active session
atlas init [--force] [--no-detect] [--no-enrich]	Initialize project: creates .atlas/, auto-detects stack, bootstraps from git history
atlas rebuild	Force full reindex + enrichment. Use after rebase or branch switch
atlas shell	Interactive REPL for Atlas commands

Docs & Playbooks 6 commands

atlas docs list [--tag T] [--search Q]	List all docs, optionally filtered by tag or search query
atlas docs show NAME [--phase N]	Show doc content, optionally a specific phase
atlas docs search QUERY	Full-text search across all docs
atlas run NAME [--start-phase N]	Start a playbook from the beginning or a specific phase
atlas next	Advance to the next playbook phase
atlas phase NAME N	Jump to a specific phase in a named playbook

Session & State 6 commands

atlas session start [--mode M]	Start a coding session and load active context
atlas session end ID --summary "..."	End a session with a summary
atlas state read SECTION	Read state: decisions \| progress \| active_context \| tech_stack \| all
atlas state write SECTION	Create entry (--title, --task, --key, --value)
atlas state update SECTION ID	Update entry (--status, --title)
atlas state delete SECTION ID	Delete a state entry

Sync & Git 5 commands

atlas sync [--from REF] [--to REF]	Sync state from git changes between two refs
atlas diff [--from REF] [--to REF]	Preview change summary without applying
atlas hooks install	Install git hooks for auto-sync on commit/checkout/merge
atlas hooks status	Show installed hook status
atlas hooks uninstall	Remove installed git hooks

Dependency Analysis 3 commands

atlas blast FILE [--depth N]	Blast radius: what breaks if this file changes
atlas deps FILE [--depth N]	Show what this file depends on (imports chain)
atlas orphans [--dir PATH]	Find files with no imports (dead code candidates)

Code Intelligence 3 commands

atlas intel symbols [--query Q]	Search functions, classes, and types project-wide
atlas intel exports FILE	Show all exports from a specific file
atlas intel types [--query Q]	Show interfaces and enums

Health & Surface 10 commands

atlas health hotspots	Risky files: high change frequency × high dependency count
atlas health coverage	Files without corresponding tests
atlas health security	Auth, crypto, payment, and input handler surface
atlas health errors	Anti-patterns in recent changes
atlas surface routes [--filter P]	Extract API routes from the codebase
atlas surface schema [--filter N]	Extract DB schema (Prisma, Drizzle, SQL)
atlas surface env	Extract environment variables and their usage
atlas surface contracts	Extract API contracts: OpenAPI, GraphQL, tRPC
atlas surface impact [--filter N]	Route↔table impact graph with 2-hop analysis
atlas surface domain [--filter N]	Business domain map: roles, auth patterns, entities

Project Map 5 commands

atlas map workspace	Monorepo package structure and boundaries
atlas map graph	Cross-package dependency graph
atlas map velocity	Commit patterns and activity by directory
atlas map explain	Plain-English summary of recent diff
atlas test-patterns	Analyze test framework conventions and naming patterns

Global Flags

--json	Output in JSON format (for scripting)
--table	Output in table format
--plain	Plain text output (default)
--no-color	Disable colored output
-q, --quiet	Minimal output
-d, --docs-dir	Override docs directory
-s, --state-dir	Override state directory
-p, --project-root	Override project root
-l, --log-level	Set log level: debug \| info \| warn \| error \| silent

MCP Tools

18 Tools. One Server.

Every tool description starts with "Use when…" for LLM discoverability. Your AI knows exactly when to reach for the atlas.

Docs & Playbooks 3 tools

get_doc	Get full content, a specific phase, or a named section of any doc
search_docs	Search by keyword, or omit query to list all docs. Supports tag filtering
run_playbook	Start, advance, or jump to a phase. action: "start" \| "next" \| "jump"

Session State 5 tools

start_session	Begin a session, load active context and open tasks
end_session	Close a session with a summary
get_project_context	Full project snapshot. Sections: session, tasks, decisions, context, tech_stack, briefing
read_state	Read decisions, progress, context, or tech stack
update_state	Create, update, or delete state entries

Sync & Rebuild 2 tools

sync_changes	Sync state from git diff, or dryRun: true to preview without applying
rebuild	Force full reindex of docs, dep graph, git, DB cache, tech stack, and enrichment

Dependency Analysis 1 tool

analyze_deps

type: "blast" (what breaks), "imports" (what it depends on), "orphans" (dead code)

Code Intelligence 5 tools

get_code_intel	type: "symbols" (project-wide), "exports" (single file), "types" (interfaces/enums)
get_project_surface	type: "routes", "schema", "env", "contracts", "impact" (route↔table), "domain" (roles/auth/entities)
get_project_health	type: "hotspots" (risky files), "coverage" (untested), "security" (sensitive), "errors" (anti-patterns)
get_test_patterns	Test framework, naming conventions, describe blocks, setup patterns
get_project_map	type: "workspace" (monorepo), "graph" (cross-package deps), "velocity" (commits), "explain" (diff summary)

DB Introspection (optional) 2 tools

inspect_schema	mode: "tables" (list all), "describe" (columns/indexes/FKs), "search" (find by name). Enabled via ATLAS_DB_URL
run_readonly_query	Execute a read-only SQL query. Requires ATLAS_DB_ALLOW_QUERY=true. Mutations strictly blocked

System 1 tool

server_status

Version, uptime, docs loaded, DB status, git info, and active session

MCP Resources

Passively surfaced — no tool call required

atlas://active-context	Current project context entries (active key/value state)
atlas://recent-decisions	Last 5 architectural decisions recorded for the project
atlas://open-tasks	Currently in-progress and blocked tasks

Configuration

Chart the Settings

Configure via CLI flags, environment variables, or a config file. Highest priority wins.

Priority Order

1 CLI flags highest priority

2 Environment variables

3 .atlasrc.json

4 package.json ["atlas"]

5 Defaults lowest priority

.atlasrc.json

{
  "docsDir": ".atlas",
  "stateDir": "~/.atlas",
  "logLevel": "info",
  "watch": true,
  "maxDepth": 3
}

package.json

{
  "atlas": {
    "docsDir": ".docs",
    "logLevel": "debug"
  }
}

Environment Variables

Variable	Default	Description
ATLAS_DOCS_DIR	.atlas	Docs directory (relative to project root)
ATLAS_STATE_DIR	~/.atlas	Global state DB directory
ATLAS_PROJECT_ROOT	auto-detect	Project root (git root → cwd)
ATLAS_LOG_LEVEL	info	Log level: debug \| info \| warn \| error \| silent
ATLAS_DB_NAME	state.db	SQLite database filename
ATLAS_WATCH	true	Enable file watching for live doc updates
ATLAS_MAX_DEPTH	3	Default blast-radius analysis depth
ATLAS_DB_URL	—	Database connection URL (enables DB introspection tools)
ATLAS_DB_CLIENT	auto-detect	Knex client: pg \| mysql2 \| mssql \| better-sqlite3
ATLAS_DB_ALLOW_QUERY	false	Enable run_readonly_query tool

Common Issues

"Docs directory not found"

Run atlas init to create .atlas/

Tech stack empty

Seed manually: atlas state write tech_stack --key "framework" --value "Next.js"

MCP server won't connect via npx

Use global install: "command": "atlas-mcp" not "command": "npx"

Stale context after rebase

Run atlas rebuild to refresh all indexes

Chart Your Codebase