Skip to content

Cubel89/codeatlas-mcp

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

2 Commits
src
src
 
 
tests
tests
 
 
.gitignore
.gitignore
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 
README_ES.md
README_ES.md
 
 
package-lock.json
package-lock.json
 
 
package.json
package.json
 
 
tsconfig.json
tsconfig.json
 
 

Repository files navigation

codeatlas-mcp

Leer en Español

An atlas of your codebase. Every file tagged, queryable, and ready for your AI agent.

codeatlas-mcp is an MCP (Model Context Protocol) server that keeps a structured index of all the files in your projects. It auto-detects the stack (Flutter, PHP Humia for now), walks the source tree, tags each file using a closed taxonomy, and exposes everything via MCP tools so your AI agent can ask "give me every view in the products module" without re-scanning the filesystem on every call.

Works with Claude Code, Codex CLI, Gemini CLI, and any MCP-compatible client.

What it does

  • Universal "read-everything" scanner — since v0.4, atlas_scan indexes every file in the project. The only things left out are auto-downloaded deps (node_modules, vendor, .dart_tool, Pods, .gradle, Flutter ios/android/macos/...) and build artifacts (build, dist, .next, .git, logs, tmp). Every other file gets a record with tags.
  • Content-based detection — scanners inspect actual file contents (Flutter: Scaffold/CupertinoPageScaffold; PHP: <html>/<body> outside <?php ?> blocks), tag files as vista-principal vs componente, and record a confidence score (high/medium/low).
  • Path-based classification — migrations/, cron/, api_admin/, templates_mails/, models/, services/, components/, tests/... are all recognised automatically across any stack.
  • Visible-text summary indexed in FTS5 — extracts Text(...), hintText, labelText, <label>, <button>, placeholder, aria-label... so atlas_search "login password" actually finds the login screen.
  • Concept tags (domain topics) — every file is also auto-tagged with domain concepts (login, productos, checkout, facturacion, admin, …). atlas_by_topic "login" returns every view, controller, middleware, migration and helper of that domain — perfect for "something's wrong with login, what should I check?".
  • Symbol index — per-file table of classes, widgets, functions and methods, plus a cross-file table of calls. Powers atlas_symbols and atlas_callers: "who calls ClienteService.save?".
  • Closed tag taxonomy — vista, controller, componente, endpoint, cron, email-template, service, model, repository, helper, migration, test, docs, asset, config, script, code. Tags are validated, typos are silently dropped.
  • Stack enhancers (optional) — Flutter (pubspec.yaml) and PHP Humia (themes/<theme>/paginas/<name>/{controller,recursos,view}.php triplet) run after the generic scan to add URL hints, module semantics and relations. Any combination can apply — or none (pure generic mode, works on Rails/Laravel/Django/custom layouts out of the box).
  • Incremental rescans — atlas_scan skips files whose hash/mtime hasn't changed, soft-deletes missing ones, and atlas_stale tells you what's out of sync.
  • Hook-friendly CLI — codeatlas-reindex reads a JSON payload on stdin (file_path), so Claude Code's PostToolUse hook on Write|Edit keeps the atlas auto-updated on every file save.

What it's not

  • It's not an agent memory system. For learned preferences, corrections and experiences use agent-memory-protocol — both MCPs coexist happily and you can cross-reference by path.
  • It's not a symbol indexer. It catalogs files and their role in the project, not classes, functions or symbols inside files.

Architecture

┌────────────────────────────────────────────────┐
│ codeatlas-mcp (MCP server, stdio)              │
│                                                │
│  src/                                          │
│   ├── db/schema.ts        (SQLite + FTS5)      │
│   ├── db/queries.ts                            │
│   ├── scanners/                                │
│   │    ├── generic/       (universal walker    │
│   │    │                   + classifier)       │
│   │    ├── flutter.ts     (stack enhancer)     │
│   │    ├── php-humia.ts   (stack enhancer)     │
│   │    └── content.ts                          │
│   ├── parsers/            (dart regex, php AST)│
│   ├── topics.ts           (concept tag rules)  │
│   ├── tags.ts             (closed taxonomy)    │
│   ├── bin/reindex.ts      (CLI for hooks)      │
│   └── index.ts            (MCP tools)          │
│                                                │
│  data/                                         │
│   └── index.db                                 │
└────────────────────────────────────────────────┘
           │
           │ MCP stdio
           ▼
    Claude Code / any MCP client

Scan flow:
  atlas_scan
    → genericScan  (walker + classifier → FileEntry[])
    → flutterEnhancer   (if pubspec.yaml, adds url_hints/modules)
    → phpHumiaEnhancer  (if themes/paginas, adds triad relations)
    → persist with symbols, concept tags, summary, etc.

Quick start

# Clone
git clone https://github.com/cubel89/codeatlas-mcp.git
cd codeatlas-mcp

# Install and build
npm install
npm run build

# Run tests
npm test

Hook it up to Claude Code

Add the server in ~/.claude/settings.json (the file Claude Code reads on every session start):

{
  "mcpServers": {
    "codeatlas": {
      "command": "node",
      "args": ["/absolute/path/to/codeatlas-mcp/build/index.js"]
    }
  }
}

Heads up: ~/.claude.json (no subfolder) is the daemon's internal state and is NOT used to load MCPs into the LLM sessions. The effective configuration lives in ~/.claude/settings.json. If you declare the MCP only in ~/.claude.json, claude mcp list will say Connected but the tools won't reach the agent.

After editing settings.json:

  1. Restart Claude Code (close and reopen) so the LLM picks up the new tools.
  2. Verify the connection with claude mcp list — it should show codeatlas: ... - ✓ Connected.
  3. In a fresh session the tools atlas_scan, atlas_query, atlas_search, etc. will be available.

Or install it globally in ~/.codeatlas-mcp/ (paralleling agent-memory-protocol):

mkdir -p ~/.codeatlas-mcp
cp -r . ~/.codeatlas-mcp
cd ~/.codeatlas-mcp && npm install && npm run build

The database lives at ~/.codeatlas-mcp/data/index.db by default. Override with CODEATLAS_DB_PATH.

MCP tools

Tool Purpose
atlas_scan Scan a project root and update its index
atlas_query Filter files by tags, module, path glob or minimum confidence
atlas_get Get a single file's entry by path
atlas_relations List related files (siblings, parents...)
atlas_search FTS5 search over path / tags / module / summary (UI text, labels, buttons)
atlas_symbols List symbols (classes, widgets, functions, methods) declared in a file
atlas_callers Find places in the project that call a given symbol
atlas_by_topic All files (view+controller+helper+endpoint) tagged with a domain topic: login, productos, facturación...
atlas_topics List all concept tags in a project with counts
atlas_tag_file Attach/detach manual concept tags to a file
atlas_stale List files whose mtime on disk differs from the atlas
atlas_bulk_upsert Upsert entries from external callers (skills, agents)
atlas_mark_deleted Soft-delete a file
atlas_diff_since List files added / modified / deleted since ISO timestamp
atlas_delete_project Hard-delete a project and its files
atlas_stats File / tag / module counts
atlas_projects List all indexed projects
atlas_tags Return the closed tag taxonomy

Example session

→ atlas_scan({ project: "plastbella", root_path: "/path/to/plastbella.es" })
← { stack: "php-humia", scanned: 62, added: 62, updated: 0, removed: 0 }

→ atlas_query({ project: "plastbella", tags: ["vista-principal"] })
← [
    { path: ".../paginas/contacto/view.php", module: "contacto", url_hint: "/contacto/" },
    { path: ".../paginas/index/view.php",    module: "index",    url_hint: "/index/" },
    ...
  ]

→ atlas_relations({ project: "plastbella", path: ".../paginas/contacto/view.php" })
← [
    { related_path: ".../paginas/contacto/controller.php", kind: "sibling-controller" },
    { related_path: ".../paginas/contacto/recursos.php",   kind: "sibling-resources" }
  ]

Tag taxonomy

The taxonomy is closed by design: adding a new tag requires a schema version bump. This keeps agents honest and queries meaningful. Run atlas_tags to get the current list.

Core tags: vista, vista-principal, vista-hija, componente, parcial, controller, service, repository, helper, model, endpoint, endpoint-admin, cron, email-template, config, asset, test, migration, docs.

Supported stacks

Stack Detection What it indexes
Flutter pubspec.yaml *_view.dart, *_screen.dart, *_page.dart under lib/src/pages, lib/src/views, lib/features, etc. Router hints from GoRouter
PHP Humia index.php + themes/<theme>/paginas/ under public_html (including servidor_web/volumenes/public_html/) The {controller,recursos,view}.php triplet per page; admin theme detection; interno/api/, interno/api_admin/, interno/cron/, templates_mails/

More stacks (Next.js, Vue, Svelte, Astro) are on the roadmap.

Adding a new scanner

  1. Create src/scanners/<stack>.ts implementing the Scanner interface from types.ts.
  2. Export a singleton and add it to ALL_SCANNERS in src/scanners/index.ts.
  3. Tag files using only keys present in TAG_CATALOG (see src/tags.ts).
  4. Add tests under tests/scanners.test.ts using the tmpDir fixture.

Development

npm run dev      # watch mode
npm test         # run vitest once
npm run build    # tsc build

Database is file-based, so tests use :memory: via openInMemoryDb().

License

MIT © 2026 cubel

Related

  • agent-memory-protocol — persistent memory (experiences, preferences, corrections) for AI agents. Pairs with codeatlas: your memories can reference paths from the atlas via metadata.related_files.

About

No description, website, or topics provided.

Resources

Readme

License

MIT license
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages