map-it-all
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Why
Solo developers working with coding agents keep hitting the same walls:
The problem | What the research and reports say | What MAP-IT-ALL does |
Agents add code instead of changing it, break parts they cannot see, lose the plot in a large repo | Columbia DAPLab's 9 failure patterns of coding agents (repeated code, codebase awareness, refactoring) |
|
Every new session re-explains the project and burns input tokens | A constant complaint in developer threads; context files drift out of date |
|
Memory goes stale as the code changes | STALE: can LLM agents know when their memories are outdated?, Dosu on pruning stale agent memory | Notes carry file hashes; |
Too many MCP tools cost tokens on every request and make tool choice worse | MCP tool overload reports ~42,000 tokens of definitions for GitHub's official server | 4 to 12 tools in three profiles: ~670 / ~1,270 / ~1,400 tokens (measured, |
Dead code piles up, docs describe deleted files | Developers report that agents add and rarely delete |
|
Shell output floods the context |
|
Related MCP server: Symbra
What you get
A session brief (~450 tokens): git state, stack, layout, most-imported files, public surface, cleanup leads, your last handoff and memory notes. No more re-explaining the project.
Connections and blast radius. Who imports this file, what it imports, and who calls the route or function it registers, including callers an import graph cannot see:
'module:fn'strings, wrapper helpers, URL literals, Kotlin/JS native bridges.Memory that knows when it is stale. Notes are anchored to files by content hash. Change the file and the note is flagged before an agent trusts it.
Cleanup leads with the right amount of fear. No references, test-only references, unmounted routes, unregistered native modules, tests no runner executes, docs pointing at deleted files. Anything an installed client or external caller could still reach is marked
public: VERIFY, never REMOVE.A session diff. "What did this session just orphan?" in one call.
A zoomable map you can open (the picture above).
Local and cheap. No network, no API keys, no telemetry. One runtime dependency, ast-grep. Works with any MCP client: Claude Code, Cursor, VS Code, Codex.
It does not replace a language server or a call-graph tool. For exact, type-aware call graphs, run one next to it (graft, codebase-memory-mcp, Serena, CodeGraph). MAP-IT-ALL covers what those do not: registration and liveness facts, session memory and the brief. See the comparison.
Quickstart
Works the same on macOS, Windows and Linux (including WSL). You need Node 20 or newer and git; the three commands below are identical on every OS and in every shell. Where the OSes differ (installing Node, registering the server by hand, troubleshooting) there is a per-OS guide right after.
0. Check the prerequisites:
node -v # v20 or higher
git --versionMissing one? Jump to your OS for the install line.
1. See it first (10 seconds, touches nothing of yours):
npx -y github:peterish8/map-it-all demo --openThat maps a bundled sample project into your temp folder and opens the zoomable map.
2. Set it up in your project, with one command (run it from your project folder):
npx -y github:peterish8/map-it-all init --npxThat works in bash, zsh, fish, PowerShell and cmd alike (on Windows it writes the cmd /c npx form the MCP config needs), and it does everything:
[1/4] Map built in 0.6 s: 46 files, packs: convex, express, expo
connections: 16 import edges across 14 imported files; most imported: web/src/lib/api.ts (x3)
19 public records (verify, never remove), 15 cleanup leads
[2/4] MCP config claude: added in .mcp.json
[3/4] Instructions CLAUDE.md: appended; AGENTS.md: created
[4/4] .gitignore .map-it-all/ addedBuilds the map and the connections (import graph, who calls what, public surface).
Writes the MCP config for your agent (
--agent claude|cursor|vscode|codex|all, default Claude Code), merging with servers you already have.Appends three lines to the very end of
CLAUDE.mdandAGENTS.md, between<!-- map-it-all:start -->and<!-- map-it-all:end -->markers. Your own text is never touched, a second run changes nothing, anduninstallremoves exactly that block.Adds
.map-it-all/to.gitignore.
Preview it first with --dry-run. Add --hook to also install the Claude Code hooks (a session-start brief and realtime). Use --no-docs to leave CLAUDE.md/AGENTS.md alone.
3. Restart your agent and ask it to "call the map-it-all brief tool". Claude Code asks you to approve a project-level server once. Check with claude mcp list, or run npx -y github:peterish8/map-it-all doctor.
Prefer to register the server yourself, or not on Claude Code? The per-OS commands are in the next section, and Connect your agent covers Cursor, VS Code and Codex.
Setup by operating system
Pick your OS. Each one has the same four parts: install the prerequisites, run init, register by hand if you prefer, and fix the usual problems.
Install Node and git with Homebrew:
brew install node git
node -v && git --versionNo Homebrew? Download the LTS installer from nodejs.org, and run xcode-select --install for git.
Set up, from your project folder:
cd ~/code/my-project
npx -y github:peterish8/map-it-all init --npxRegister by hand (Claude Code):
claude mcp add map-it-all -- npx -y github:peterish8/map-it-all mcp
claude mcp list # map-it-all should be listed
npx -y github:peterish8/map-it-all doctor # checks Node, git, ast-grep, the mapOpen the map: npx -y github:peterish8/map-it-all view --open
Good to know: if node or npx is "command not found" right after installing, open a new terminal tab. On Apple Silicon, Homebrew lives in /opt/homebrew; if brew itself is not found, run eval "$(/opt/homebrew/bin/brew shellenv)" and add that line to ~/.zprofile.
Install Node and git with winget (built into Windows 10 and 11), then open a new terminal so PATH refreshes:
winget install OpenJS.NodeJS.LTS
winget install Git.Git
node -v; git --versionNo winget? Use the installers from nodejs.org and git-scm.com.
Set up, from your project folder (same line in PowerShell, cmd and Git Bash):
cd C:\code\my-project
npx -y github:peterish8/map-it-all init --npxinit writes the Windows form of the MCP entry for you (cmd /c npx ...), because Windows cannot launch npx directly from an MCP config.
Register by hand (Claude Code). The shell matters here:
# PowerShell: quote the double dash (PowerShell swallows a bare --) and go through cmd
claude mcp add map-it-all '--' cmd /c npx -y github:peterish8/map-it-all mcp:: cmd.exe
claude mcp add map-it-all -- cmd /c npx -y github:peterish8/map-it-all mcp# Git Bash or WSL: the macOS/Linux form
claude mcp add map-it-all -- npx -y github:peterish8/map-it-all mcpThen claude mcp list and npx -y github:peterish8/map-it-all doctor.
Open the map: npx -y github:peterish8/map-it-all view --open
Good to know:
error: unknown option '-y'means PowerShell ate the--. Use the quoted'--'above, or sidestep the problem withnpx -y github:peterish8/map-it-all init --agent claude --npx.npx.ps1 cannot be loaded because running scripts is disabled: runSet-ExecutionPolicy -Scope CurrentUser RemoteSignedonce, or callnpx.cmdinstead ofnpx.Cursor and VS Code configs on Windows use
"command": "cmd", "args": ["/c", "npx", ...];init --agent cursoror--agent vscodewrites that for you.Project-scope servers need a one-time approval inside Claude Code (see step 3).
Prefer Linux tooling? Everything in the Linux section works inside WSL. Install Node inside WSL too:
which nodemust not point at/mnt/c/....
Install Node 20+ and git. Distro packages are sometimes older than Node 20, so check node -v after installing. If it is too old, use nvm (follow the install line in its README), which needs no root:
# Debian / Ubuntu
sudo apt update && sudo apt install -y git curl
# Fedora / RHEL
sudo dnf install -y git nodejs npm
# Arch
sudo pacman -S git nodejs npm
# any distro, if node is older than v20: install nvm (see its README), then
nvm install --lts
node -v && git --versionSet up, from your project folder:
cd ~/code/my-project
npx -y github:peterish8/map-it-all init --npxRegister by hand (Claude Code):
claude mcp add map-it-all -- npx -y github:peterish8/map-it-all mcp
claude mcp list
npx -y github:peterish8/map-it-all doctorOpen the map: npx -y github:peterish8/map-it-all view --open uses xdg-open. On a server, over SSH or in a container there is no browser, so run view without --open: it prints the path of graph.html to copy to a machine that has one. On WSL, open the file from Windows Explorer (explorer.exe . in the folder).
Good to know:
With
nvm, make sure the shell that launches your agent loads it (it must see the samenodeas your terminal). If an editor starts the MCP server and fails withnpx: not found, put the absolute path fromwhich npxin the config'scommandfield.npxneeds git to fetchgithub:packages; install it if you seespawn git ENOENT.Behind a proxy or offline? Use the local clone below, which needs the network only for
npm install.
Same thing, side by side
macOS / Linux / WSL / Git Bash | Windows PowerShell | Windows cmd | |
Set up |
| same | same |
Register (Claude Code) |
|
|
|
Verify |
| same | same |
Realtime on / off |
| same | same |
Open the map |
|
|
|
Remove |
| same | same |
(... stands for npx -y github:peterish8/map-it-all.)
Update, pin, undo
Same on every OS:
npx -y github:peterish8/map-it-all#v0.1.0 init --npx # pin a release instead of tracking main
npx -y github:peterish8/map-it-all uninstall # remove the block, MCP entry and hooks; keeps your memory notes
npx -y github:peterish8/map-it-all uninstall --purge # also delete .map-it-all/ (only ever inside your project)npx caches what it fetches, so a newer main may not be picked up right away. Pin a tag (above) for a predictable version, or delete the _npx folder inside the directory printed by npm config get cache to force a fresh download.
Working with teammates on other operating systems? init --npx writes the MCP entry for the OS it runs on (cmd /c npx on Windows, plain npx elsewhere), so a committed .mcp.json from one OS will not start on the other. Either have each person run init locally and leave .mcp.json uncommitted, or commit one OS's file and let the others re-run init.
Prefer a local clone?
git clone https://github.com/peterish8/map-it-all.git
cd map-it-all && npm install # installs ast-grep, the only dependencyThen, from your project folder, call the script by its path:
# macOS / Linux / WSL
node ~/code/map-it-all/bin/map-it-all.mjs doctor
node ~/code/map-it-all/bin/map-it-all.mjs init # the MCP entry points at your clone
node ~/code/map-it-all/bin/map-it-all.mjs view --open# Windows PowerShell
node C:\code\map-it-all\bin\map-it-all.mjs doctor
node C:\code\map-it-all\bin\map-it-all.mjs init
node C:\code\map-it-all\bin\map-it-all.mjs view --openRealtime mode
Optional, off by default, and switchable at any time, by you or by the agent.
map-it-all realtime on # or: off | statusAn agent can also call the realtime tool (action: on|off|status) when it wants the map kept current during a long edit session and switch it off again afterwards. It needs the edit hook, which init --hook installs.
How it stays cheap:
No watcher, no daemon. A
PostToolUsehook fires only when the agent edits a file. While realtime is off the hook exits after one file check.One rebuild per burst. Edits are coalesced: a detached, below-normal-priority worker waits for a quiet moment (about 1.5 s, at most 8 s), then rebuilds once. Many edits cost one build.
Never blocks an edit. The hook returns in about 0.2 s (mostly Node start-up), always exits 0, and has a 10 s timeout.
Quiet by design. After an edit the agent hears something only if it matters: the file holds
publicrecords, many files import it, or a recent edit left something with no references. Each warning is delivered once, in under 560 characters.Safe reads. Map files are written atomically and readers wait for a rebuild in progress, so a tool call never sees a half-written map.
On a 2,500-file monorepo a background rebuild takes about 5 seconds of one low-priority core, roughly 7 seconds after the last edit of a burst.
Connect your agent
map-it-all init --agent <claude|cursor|vscode|codex|all> [--npx] writes the right config for your OS and keeps any servers you already have (--dry-run previews). By hand:
# macOS / Linux / WSL / Git Bash, from your project folder
claude mcp add map-it-all -- npx -y github:peterish8/map-it-all mcp
# Windows PowerShell: npx runs through cmd, and the double dash must be quoted
claude mcp add map-it-all '--' cmd /c npx -y github:peterish8/map-it-all mcp
# any shell, no `--` to get wrong: the tool writes .mcp.json for you
npx -y github:peterish8/map-it-all init --agent claude --npxinit --hook adds a SessionStart hook to .claude/settings.json (and the realtime edit hook). The session hook rebuilds only if HEAD or the working tree changed, saves the baseline that diff compares against, and prints the brief, which Claude Code adds to the session. By hand it is:
{
"hooks": {
"SessionStart": [
{ "hooks": [{ "type": "command", "command": "npx -y github:peterish8/map-it-all session-start", "timeout": 120000 }] }
]
}
}.cursor/mcp.json:
{
"mcpServers": {
"map-it-all": { "command": "npx", "args": ["-y", "github:peterish8/map-it-all", "mcp"] }
}
}.vscode/mcp.json (note servers, not mcpServers):
{
"servers": {
"map-it-all": { "command": "npx", "args": ["-y", "github:peterish8/map-it-all", "mcp", "--root", "${workspaceFolder}"] }
}
}~/.codex/config.toml:
[mcp_servers.map-it-all]
command = "npx"
args = ["-y", "github:peterish8/map-it-all", "mcp", "--root", "/absolute/path/to/your/project"]By default the server maps the directory the client starts it in. Use --root <dir> or MAP_IT_ALL_ROOT to point elsewhere. Add --profile minimal to expose four tools (about 670 tokens of definitions) instead of ten. More in docs/agents.md.
init writes these three lines to the end of your CLAUDE.md / AGENTS.md for you (snippet if you prefer to paste them):
- Start each session with the map-it-all `brief` tool. Before editing or deleting, use `connections` and `find`.
- Zero refs is a lead, never proof. `public` records may be used by installed clients: VERIFY, do not remove.
- Save durable learnings with the `memory` tool, anchored to files; call `handoff` before ending.See it work
Real output from the bundled demo project (map-it-all demo).
brief: what an agent needs to start, in ~450 tokens.
# Session brief: demo-app
Stack: convex: 9 functions (7 public), 4 tables · express: 11 routes (2 conditional) · expo/android: 2 screens, 2 native modules, 3 kotlin classes
Layout:
web 11 files (tsx/ts)
convex 10 files (ts)
mobile 8 files (kt/tsx)
server 7 files (ts)
Most-imported files (change with care):
web/src/lib/api.ts ×2
Public surface (installed clients may still call it: VERIFY before removing): 7 convex-function, 1 convex-http, 11 express-route
Cleanup leads: 5 express-route, 3 convex-function, 2 kotlin-class, 2 npm-script, 2 test-file, 2 env-var
Docs pointing at missing paths: 1 doc(s); worst README.md (2). Do not trust those docs' file references.leads: what looks unused, and what needs care.
convex-function (3)
convex:streaks.forHabit convex/streaks.ts:4 [no-refs] public
convex:habits.archive convex/habits.ts:8 [no-refs] public
convex:legacyImport.run convex/legacyImport.ts:4 [test-only] public
native-module (1)
native-module:HabitWidget mobile/android/.../HabitWidgetModule.kt:2 [not-in-ExpoModulesPackageList]
express-route (5)
express:GET /api/admin/users server/routes/admin.ts:4 [conditional-mount,no-refs,undocumented] public
express:GET /api/stats/export server/routes/stats.ts:4 [no-refs,undocumented] publicconnections: the blast radius, with the warning an agent needs.
$ map-it-all connections convex:habits.archive
No by-name callers recorded for convex:habits.archive [no-refs] public: installed or external clients may still call it
$ map-it-all connections web/src/lib/api.ts --direction in
IN: depends on this file (blast radius) (3)
d1 web/src/hooks/useHabits.ts:2
d1 web/src/lib/api.test.ts:1 [test]
d1 web/src/pages/Settings.tsx:1memory recall: a note that notices the code moved.
health-route-stays-above-the-routers-3fdf2 [decision] STALE
Health route stays above the routers
Load balancers hit /health before auth is mounted.
anchors: server/app.ts
! server/app.ts changed since this note was written: verify before relying on itThe loop
Start: the
SessionStarthook (or the agent) callsbrief.Before editing or deleting:
connectionsandfind.publicmeans installed clients or external callers: VERIFY.While working:
memory→rememberfor a decision or a gotcha, anchored to the files it is about.After a change:
difflists records that just lost their last production reference.End:
handoff→savewith a summary and next steps. The next brief shows it, and flags files that changed since.
Tools
Tool | What it answers |
| What do I need to know to start? |
| Which routes, functions, native modules, scripts or docs match this? Filter by flag or public surface. |
| Everything about one file: records, importers, imports, debt, anchored notes |
| Who depends on this, what does it depend on, who calls what it registers? ( |
| What looks unused or broken, and what needs VERIFY? |
| Where is this name declared and mentioned? (name-based, not type-aware) |
| What did this session newly orphan? |
|
|
|
|
| Turn the realtime refresh on, off, or read its status |
| Rebuild now (optionally with Knip); path of the zoomable map |
Profiles (--profile): minimal is brief, find, connections, memory; standard (default) adds file, leads, symbol, diff, handoff, realtime; full adds refresh and view. Every tool is also a CLI command, so the terminal and the agent always agree.
CLI
map-it-all demo [--open] try it on a bundled sample, touching nothing of yours
map-it-all init [--npx] [--hook] [--dry-run] map + MCP config + CLAUDE.md/AGENTS.md block + .gitignore
map-it-all uninstall [--purge] remove what init added (keeps memory unless --purge)
map-it-all realtime [on|off|status] keep the map fresh as the agent edits (needs init --hook)
map-it-all doctor check Node, git, ast-grep, Knip, RTK, the map
map-it-all build [--with-knip] build the map (about 5 s on 2,500 files, under 1 s on small repos)
map-it-all view [--open] the zoomable map page
map-it-all brief | session-start the session brief | rebuild, snapshot, brief (a hook)
map-it-all query <text> [--kind k] [--flag f]
map-it-all file <path> | connections <target> [--direction in|out|both] [--depth n] [--mermaid]
map-it-all leads [--kind k] [--flag f] [--public] | symbol <name> | diff
map-it-all memory list|recall <q>|forget <id> | handoff | tokens
map-it-all check exit 1 if a pack's rules drifted (for CI)
map-it-all mcp [--profile minimal|standard|full]map-it-all <command> --help for one command. Run map-it-all tokens to see what the MCP tool definitions cost on your install.
What gets mapped
Generic, any JS/TS repo: an import graph with real alias resolution (tsconfig paths and extends, workspace packages), docs and their inbound links, docs drift (docs naming files that no longer exist; fenced examples skipped), debt markers, npm scripts and script files nothing references, tests outside every runner glob, env vars read but set nowhere in the checkout, web workers.
Framework packs, auto-detected:
Pack | Detected from | Maps |
convex | a | functions and every caller form ( |
express | files that call | routes with full mount paths (nested, default-export, factory and same-file routers, conditional mounts), URL callers across the repo, whether a doc mentions the route |
expo | a | screens, native modules (Kotlin |
Details, limits and how to write a pack: docs/packs.md.
Memory that knows when it is stale
memory remember title: "Health route stays above the routers"
body: "Load balancers hit /health before auth is mounted."
kind: decision
anchors: ["server/app.ts"]recall re-hashes every anchor against the working tree: fresh, stale (an anchored file changed) or orphaned (it is gone). confirm re-verifies after the agent checked. Notes are small JSON files under .map-it-all/memory/; set memoryDir to commit them and share with a team. docs/memory.md
How it works
flowchart LR
A[Your working tree<br/>git + files] --> B[ast-grep rules<br/>+ regex + import graph]
B --> C[.map-it-all/<br/>JSON records]
C --> D[MCP server<br/>stdio, local]
C --> E[CLI]
C --> F[Zoomable map<br/>graph.html]
G[Memory notes<br/>+ handoff] --> D
D --> H[Claude Code · Cursor<br/>VS Code · Codex]Code structure comes from ast-grep rules (tree-sitter, so comments and strings never cause false hits). A pack only reports what a plain regex count also sees: map-it-all check compares them and exits 1 on drift, so a rule that stops matching is loud. Everything is plain JSON and Markdown you can read.
Pair with RTK
MAP-IT-ALL shrinks what an agent has to read about your code. RTK shrinks what comes back from the commands it runs. They do not overlap and neither needs the other. map-it-all doctor detects it and prints the install line for your OS (docs/rtk.md).
Configuration
Zero config works. To override detection, add map-it-all.config.json at the repo root:
{
"historyDirs": [".planning", "archive"],
"ignore": ["**/vendor/**"],
"driftIgnore": ["^\\.mcp\\.json$"],
"convex": { "dir": "convex" },
"express": { "appFiles": ["server/app.ts"] },
"expo": { "dir": "apps/mobile" }
}How it compares
MAP-IT-ALL | Call-graph servers (graft, codebase-memory-mcp, CodeGraph, Serena) | General agent-memory services (Mem0, Zep, Letta, Cognee) | RTK | |
Answers | What registers, references and imports what; what is safe to touch; where we left off | Exact symbol-level callers and definitions | What was said or decided across conversations | Shorter command output |
Memory is tied to code | Yes, by file hash; flags stale | Not their focus | Not by file hash, typically | No |
Marks what shipped clients may still call (VERIFY, not REMOVE) | Yes ( | Not their focus | Not their focus | No |
Needs a model, vector store or API key | No | No | Typically yes | No |
Tool-definition cost | ~670 to ~1,400 tokens | Varies by server | Varies | n/a (CLI hook) |
They are complements: run a call-graph server for exact call graphs, MAP-IT-ALL for the brief, registration facts and memory, RTK for shell output.
FAQ
Roadmap
Ideas, not promises. Open an issue to vote or to propose.
More packs: Next.js route handlers, Hono/Fastify, NestJS, tRPC
Convex nested module folders
Optional import of SCIP indexes for exact call edges
A per-file incremental build for very large repos (today realtime rebuilds the whole map once per burst)
Publish to npm and the MCP registry
Contributing
Issues and pull requests are welcome, especially a wrong or missing result with a small project that shows it. See CONTRIBUTING.md; please read the Code of Conduct. Report security problems privately (SECURITY.md).
git clone https://github.com/peterish8/map-it-all.git && cd map-it-all
npm install && npm test # 33 tests: packs, import resolution, memory, MCP protocol, CLI, init, realtimeAcknowledgements
Built on ast-grep (code structure) and informed by Knip (unused files and exports, an optional bridge), RTK (command-output compression), and the research and reports linked above.
License
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Give your AI agent a persistent map of your project's structure, dependencies, and bugs.
Shared memory for coding agents. Stop re-explaining your codebase every session.
Shared context for your codebase: a hosted code knowledge graph over MCP. Free plan, OAuth sign-up.
Codebase intelligence for AI coding agents: graph, git history, docs, decisions, code health.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to locally search, query, and understand codebases with token-efficient context, dependency graphs, history, architecture diagrams, and metrics through MCP.15 npm3MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI coding agents to query a local, continuously updated symbol graph of a codebase, providing ranked search, caller/callee exploration, dependency paths, and git-diff impact analysis through MCP tools.14 npmApache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables coding agents to query a local, multi-repo code graph for symbol exploration, blast radius analysis, co-change mining, and durable code-anchored memory via MCP tools.271 npm16Business Source 1.1
- AlicenseNot gradedqualityAmaintenanceEnables AI coding agents to query a locally indexed structural code graph — source entities, callers/callees, Git relationships and recorded mistakes — so they retrieve focused, token-bounded context instead of reading entire files. It runs over local SQLite and can be served through a CLI, agent hooks, an MCP executable and an authenticated local dashboard.24 npmMIT