Symbol extraction: classes/interfaces/traits/enums (PHP), structs/
interfaces/type aliases (Go), classes/interfaces/enums/type aliases
and const arrow-function components (TS/JS, incl. TSX/JSX), methods,
properties (incl. constructor promotion and parameter properties),
constants, functions, doc comments.
Code map & call-graph MCP server for AI agents. Tree-sitter + SQLite index of PHP/Go/TS code with type-inference enrichment — semantic search, callers, implementations in milliseconds.
스타
2
도구
—
가동 시간
—
Reference edges resolved at extraction time with file-local
knowledge: instantiations, static and instance calls ($this->,
self::, parent::, typed properties and parameters, one hop
through struct fields in Go), constant access, type hints,
instanceof, attributes, inheritance and trait/embedding facts.
JSX component renders become call edges; TS imports resolve through
relative paths and workspace package names (package.json).
Incremental indexing into SQLite + FTS5: stat fast path
(mtime+size), sha256 as the source of truth, so branch switches
reindex only real diffs. Vendor code is indexed shallow
(declarations + hierarchy, no call graph).
MCP server (stdio) with graph query tools; hierarchy-aware callers
via recursive CTEs.
Optional enrichment layer (kartograf enrich): full type inference
on top of the file-local AST heuristics.
Per-branch handoff note (get_task_context / put_task_context):
what was done, key files, decisions, and what is left, stored in the
git common dir. The agent writes it when work pauses, so a new chat
days later can resume the task. Up to 4 KiB.
Quick install (let your AI agent do it)
Prebuilt binaries for macOS (Intel/Apple Silicon) and Linux
(amd64/arm64) are attached to every
release.
Step-by-step instructions for AI agents live in
docs/install-prompt.md — paste this into
Claude Code (or any agent with shell access) inside the project you
want indexed:
Fetch https://raw.githubusercontent.com/dev-manul/kartograf/master/docs/install-prompt.md
and follow the instructions to install the kartograf MCP server for
this project.
Building from source
The build requires the sqlite_fts5 build tag (FTS5 support in
mattn/go-sqlite3); without it compilation fails on purpose with a
readable error. Use the Makefile:
make install # go install -tags sqlite_fts5 ./cmd/kartograf
make check # vet + test + fmt + build
kartograf index [root] # build/update the index
kartograf index --rebuild # from scratch
kartograf serve [root] # MCP server on stdio (updates the index on start)
kartograf outline path/to/File.php # symbols of one file
kartograf outline --json path/to/File.php # full FileIndex as JSON
kartograf install claude|cursor [root] # register the MCP server for a client
kartograf install codex [root] # Codex UserPromptSubmit and Stop hooks
kartograf install hook [root] # Claude Code prompt hook: mentions of indexed
# symbols nudge the agent to query the graph
kartograf self-update # update to the latest release
kartograf stats [root] # local tool-call counts and a token estimate
Each GitHub release lists the commits since the previous tag, one
English subject line each.
Registering in Claude Code:
claude mcp add kartograf -- kartograf serve /path/to/project
For Cursor and other stdio MCP clients (note the required
"type": "stdio") see docs/cursor.md.
The index lives in the user cache dir
(~/Library/Caches/kartograf/<project>-<hash>/index.db on macOS,
~/.cache/... on Linux) — a derived artifact, never committed. On a
schema version change the database is silently rebuilt.
Reference numbers on a PHP monolith (~79k files incl. vendor, ~885k
symbols): cold index ~19s (bulk mode: batched inserts, indexes and FTS
built once after the load), warm run ~1.5s.
MCP tools
Tool
What it does
search_symbols
FTS over names/FQNs/docblocks (camelCase-aware), kind and path-prefix filters
get_symbol
Declaration by FQN (or name suffix): signature, doc, members, source
find_references
Every reference to a symbol: calls, new, type hints, instanceof, constants
get_callers
Who calls a method/function; class hierarchy is taken into account
get_callees
What a symbol calls or instantiates
class_hierarchy
Transitive ancestors and descendants (interface implementations)
Blast radius: transitive callers by depth + affected test files
search_code
Full-text search over file contents: string literals, SQL, config keys
project_map
Routes, commands and SQL strings written in source, without running PHP
get_task_context
Handoff note for a branch (skip when <kartograf_task> for it is already in the chat)
put_task_context
Write that handoff when work pauses, so a later chat can resume it (4 KiB; a blank body deletes it)
list_task_contexts
Other branches that have a handoff
find_task
Branches whose names match a task id, including nested repositories
branch_changes
Files and symbols a branch changed since the default branch, for work that has no handoff
Edges with resolved=false are heuristic (calls via parent::,
inferred receiver types, global function fallback); exact edges follow
the language's name-resolution rules using the file's import map and
namespace. TypeScript export { Name } from and export * from are
followed for a few hops, so a call imported through an index.ts
barrel joins the file that defines the name. Every edge carries
source: ast (file-local extraction), phpstan or go-types
(enrichment layer).
What works without the enrichment layer:
Tool
AST only
with enrich
search_symbols, file_outline, get_symbol
✅
✅
class_hierarchy
✅ PHP/TS; Go lacks implements
✅
find_references
⚠️ partial for dynamic calls
✅
get_callees
⚠️ low resolved % in untyped PHP
✅
get_callers (PHP interface/DI call sites)
❌ mostly heuristic
✅
For PHP projects kartograf enrich php is effectively required for
call-graph queries, not an optional nicety — serve warns when it is
missing, and get_callers, get_callees, find_references and
explore say so in notice instead of returning a quiet empty list.
Task context
A handoff note per git branch lets a new chat resume work days later:
what the task was, what changed (key files and symbols), which
decisions were made and why, what is left, and how to verify. The
agent writes it when work pauses, not on every turn. One note is at
most 4 KiB. Paths named in the note that were committed afterwards
come back as staleFiles, so a later chat can see the code has moved.
Notes live under the repository's common git directory
(<git-common-dir>/kartograf/context/), outside the working tree and
outside the index database, so git checkout and index --rebuild
leave them in place. Notes stay local to the clone; linked worktrees
of the same repository share them.
Call get_task_context only when no <kartograf_task> block for that
branch is already in the conversation. Follow-ups often arrive on a
new branch: list_task_contexts (and the <kartograf_tasks> list the
Claude Code hook adds on the first prompt of a session) names the
older notes. When the user names a task id instead of a branch,
find_task locates the branch; a nested repository comes back as
repo and is passed through to the other task tools. Each repository
can set task.branch in .kartograf.yml (see below); otherwise the
branch name only has to contain the id. A detached HEAD is stored as HEAD@<sha>. The Claude
Code hook and, after kartograf install cursor, Cursor's
beforeSubmitPrompt hook inject the current branch's note once per
session and do not repeat it. Checking out another branch in that
same chat shows the new branch's note once. The Claude Code Stop hook, and the same hook after
kartograf install codex, asks for the note once, at the end of a
turn, when the branch has moved and the note is missing or stale.
Codex must trust the new hook (/hooks) and have features.hooks
enabled.
Enrichment layer
kartograf enrich adds edges from full type-inference tools. They are
stored in .kartograf/enrich.<source>.jsonl at the project root
(commit it or gitignore it — your choice) and are re-imported
automatically by index/serve whenever the file changes; deleting
the file retires its edges.
The indexed root may be a workspace of many repositories (kartograf serve ~/projects): every nested <repo>/.kartograf/enrich.*.jsonl is
discovered and imported too, with tool-reported paths resolved
relative to the repository that owns the file — two Go services with an
identical internal/config/config.go never get mixed up. Run enrich
inside each repository as usual; the workspace index picks the files
up on its next refresh. In a workspace, the first path segment of every
result is the repository directory, and pathPrefix (on
search_symbols, search_code and the graph tools) narrows a query to
one repository.
kartograf enrich go — in-process go/packages + go/types pass:
exact calls (interface calls, fields typed in other files) and
structural implements edges (Go interface hierarchy is impossible
to derive from single-file AST).
kartograf enrich php — scaffolds a PHPStan rule into
.kartograf/phpstan/ and runs vendor/bin/phpstan with the
project's own config. Edges travel as pseudo-errors with the
identifier kartograf.edge through the JSON output, so PHPStan's
result cache makes repeat runs incremental. Resolves calls through
untyped properties (types inferred from constructors). If PHP is not
available locally, run phpstan wherever it works and import with
kartograf enrich import <file> --source phpstan (container paths
are mapped automatically).
Enrich in Docker / CI
If PHP only runs in a container, generate the config locally, run
PHPStan where PHP lives, and import the result:
Container paths in the JSONL are mapped onto indexed files
automatically (longest-suffix match).
Re-runs are incremental for free: edges ride PHPStan's result cache,
so only changed files are re-analysed (~20s warm on a 79k-file
monolith vs minutes cold). The JSONL is rewritten wholesale on each
run — replace semantics, no merging.
Commit the JSONL to share resolved call graphs with the whole team
(and CI agents), or gitignore .kartograf/ and re-run enrich after
big changes — both work, index/serve auto-import on file change
either way. The file starts with the commit it was built from. Graph
tools then say when the checkout has moved on, so a call list is not
silently from another revision.
Performance expectations
grep wins on raw text; kartograf wins on graph semantics:
Task
grep/rg
kartograf
text search
~0.06s
~ms (search_symbols, warm)
find usages of a class
hundreds of noisy text matches
typed edges with kind + resolution
who calls this method
impractical
get_callers ~ms (PHP needs enrich)
first response after MCP start
—
<1s on an 80k-file repo (index refresh runs in background)
Project config — .kartograf.yml (optional)
include: [] # directories to index (default: the whole root)
exclude: [] # extra gitignore-style patterns
vendor: index # index (default, flagged as vendor) | skip
task:
branch: "feature/{id}-" # optional; how a task id sits in branch names.
# empty = the branch name contains the id
enrich:
url: "https://example.com/kartograf/{commit}/enrich.phpstan.jsonl"
# optional; download a PHPStan graph built in CI
# when this checkout has none for its commit
stats:
dollars_per_million: 3 # optional; price used by `kartograf stats`
The project's .gitignore is respected; vendor/node_modules are
indexed bypassing gitignore and flagged as vendor.
Architecture
internal/core/model — language-agnostic model: Symbol, Import,
Ref, FileIndex. Symbol IDs are global and deterministic:
php:App\Service\Foo::bar(), go:module/pkg.Type.Method(),
ts:src/api/client#ApiClient.get() (module = file path).
internal/core/lang — language adapter contract + registry.
internal/core/indexer — gitignore-aware walk, worker pool,
change detection.
kartograf parse-tree file.php # raw tree-sitter CST (hidden command)
K
Kartograf
dev-manul·스타 2개·
Code map & call-graph MCP server for AI agents. Tree-sitter + SQLite index of PHP/Go/TS code with type-inference enrichment — semantic search, callers, implementations in milliseconds.
이 페이지에서 Cursor, Claude Desktop, Claude Code 또는 VS Code용 stdio 설정을 복사합니다. PlugMCP 프록시가 아니라 게시자의 설치 방식을 사용합니다.
Kartograf에 API 키가 필요한가요?
이 레코드에는 필수 환경 변수가 등록되어 있지 않습니다.
Kartograf은(는) 어떤 전송 방식을 사용하나요?
Kartograf은(는) stdio를 통해 로컬에서 실행됩니다.
Kartograf은(는) 마지막으로 언제 확인되었나요?
마지막 확인: 2026-10-28. Code map & call-graph MCP server for AI agents. Tree-sitter + SQLite index of PHP/Go/TS code with type-inference enrichment — semantic search, callers, implementations in milliseconds.