@maplayer/maplayer · npm · v0.1.8

Code intelligence for AI agents

MapLayer indexes your repository into a local SQLite graph and serves it over MCP — giving Claude, Codex, Cursor, and other AI tools structured code navigation instead of raw file reads.

npm install -g @maplayer/maplayer

Get started npm page

8

languages: TS · JS · Java · Kotlin · Python · C# · Swift · YAML

10

MCP tools for structured code navigation

Local

SQLite graph, runs offline, no data leaves your machine

MCP

model context protocol — works with any agent

Quick start

Three commands to give your AI agent a structured view of your codebase.

Install

Install MapLayer globally. Requires Node.js 22+.

npm install -g @maplayer/maplayer

Note: If your project uses a different Node version, install under Node 22 via nvm or fnm and MapLayer will run independently.

Init & index

Run from the root of the repository you want to use with your AI tool.

# scaffold .maplayer/ config + MCP wiring blocks
maplayer init

# parse the repo into the SQLite code graph
maplayer index

Note: maplayer init injects managed blocks into existing CLAUDE.md, AGENTS.md, .cursorrules, and GEMINI.md. It does not create these files if they are missing — create them first, then rerun init.

Wire `maplayer serve` into your AI tool

Add the MCP server entry to your agent's config. See the Integrations section for tool-specific instructions.

# Example: .claude/settings.json
{
  "mcpServers": {
    "maplayer": {
      "command": "maplayer",
      "args": ["serve"]
    }
  }
}

MCP tools

Once maplayer serve is running, these tools are available to your agent. All results include a freshness field (fresh / stale / missing) so the agent knows whether the index reflects the current file on disk.

Tool	Description
`search_symbols`	Find functions, classes, and types by name or keyword
`find_by_intent`	FTS5 full-text search over file summaries and symbol names
`trace_dependencies`	List imports and dependents for a file
`find_callers`	Find all call sites of a function
`find_callees`	Find all functions called by a function
`get_symbol_body`	Read a symbol's exact source (policy-gated)
`get_file_slice`	Read a specific line range from a file (policy-gated)
`get_file_summary`	Return a cached file summary with freshness metadata
`describe_module`	Return a file's purpose, exports, and key behaviors
`list_changed_files`	List files changed since last index or a given commit

Integrations

Add maplayer serve as an MCP server in your AI tool's config.

Claude Code

Add to your project's .claude/settings.json:

{
  "mcpServers": {
    "maplayer": {
      "command": "maplayer",
      "args": ["serve"]
    }
  }
}

Codex

Add to .codex/config.toml in your repo:

[mcp_servers.maplayer]
command = "maplayer"
args = ["serve"]
startup_timeout_sec = 30

Gemini CLI

Add to .gemini/settings.json in your repo (or ~/.gemini/settings.json for all projects):

{
  "mcpServers": {
    "maplayer": {
      "command": "maplayer",
      "args": ["serve"]
    }
  }
}

Note: settings.json at repo root is also supported.

Cursor

In Cursor settings, open the MCP section and add a new server:

Command:  maplayer
Args:     serve

Continue.dev

Add to .continue/config.yaml in your repo (or ~/.continue/config.yaml for all projects):

mcpServers:
  - name: maplayer
    type: stdio
    command: maplayer
    args:
      - serve

Note: MCP tools are only available in agent mode in Continue.

Roo Code

Add to .roo/mcp.json in your repo (or via the global MCP settings in VS Code):

{
  "mcpServers": {
    "maplayer": {
      "command": "maplayer",
      "args": ["serve"]
    }
  }
}

Policy & audit

Control what gets indexed and what agents can retrieve. Every tool call is logged.

Policy

maplayer init creates .maplayer/policy.yaml — commit this file. It controls indexing scope and agent retrieval limits.

exclude:
  paths:
    - ".env*"
    - "secrets/**"
    - "**/*.pem"

retrieval:
  allow_raw_file_slice: true
  max_slice_lines: 120
  stale_summary_mode: "flag"

Test any path:

maplayer policy check .env
# excluded  tool=index  path=.env

maplayer policy check src/main.ts
# allowed   tool=index  path=src/main.ts

Audit log

Every tool call is appended to .maplayer/audit.log (gitignored). Inspect it with the built-in commands.

# last 20 entries
maplayer audit show

# filter by tool
maplayer audit show --tool get_symbol_body

# JSON output
maplayer audit show --json

# live stream
maplayer audit tail

Exits non-zero for excluded paths — usable in CI:

maplayer policy check .env || exit 1

Git timeline

maplayer timeline launches a local browser view of your repository's git lineage — file events, symbol lifecycle, rename chains, and commit diffs, all backed by the indexed lineage tables.

# default (port 4312)
maplayer timeline

# filter by date range
maplayer timeline --from 2025-01-01 --to 2025-06-01

# filter by author
maplayer timeline --author alice

# filter by event type
maplayer timeline --event added,renamed,deleted

# filter by file path
maplayer timeline --file src/auth

# filter by symbol name
maplayer timeline --symbol authenticate

Requires lineage data: run maplayer index with full history enabled before launching the timeline view.

File event feed —added, modified, deleted, renamed, copied
Symbol lifecycle —introduced, changed, moved, removed
Rename chain — canonical file identity across moves
Per-commit file and symbol breakdown
Inline diff view for any commit + file
Filter by date, author, event type, file, or symbol
URL filters — share a scoped view as a link

Options

`--port`	HTTP port (default `4312`)
`--host`	Bind address (default `127.0.0.1`)
`--from`	Start date `YYYY-MM-DD`
`--to`	End date `YYYY-MM-DD`
`--author`	Author name or email (substring)
`--event`	Comma-separated event types
`--file`	File path substring filter
`--symbol`	Symbol name filter

Graph visualizer

Launch a local, interactive visualization of your indexed symbol graph.

# default
maplayer visualize

# with limits
maplayer visualize --port 4311 \
  --max-nodes 1200 \
  --max-edges 4000

Force-directed graph layout
Pan, zoom, node metadata on hover
Search filter to highlight symbols
Minimap for navigating large graphs
Paginated loading for large repos (Load More Graph)

Gitignore

maplayer init adds the correct entries automatically. To add manually:

# .gitignore
.maplayer/index.db
.maplayer/index.db-shm
.maplayer/index.db-wal
.maplayer/vectors.db
.maplayer/vectors.db-shm
.maplayer/vectors.db-wal
.maplayer/summaries/
.maplayer/audit.log

policy.yaml and config.yaml should be committed.

Requirements

Node.js 22+ and a repository with one of the supported languages.

Supported

Languages

TypeScript · JavaScript · Java · Kotlin · Python · C# · Swift · YAML