Skip to main content
Glama

sangkar

A read-only MCP server over one repository's call graph, and the sangkar command that serves the same seven tools from a shell. It indexes the tree into a SQLite database and answers what changed, who calls what, what a change reaches, and what the index could not cover. The repository is bound at startup, so no tool takes a project argument.

Install

Bun 1.4.4 or newer. The app is a Bun program — bun:sqlite, bun build, Bun.spawn — so Node cannot run it.

bun add -g sangkar-mcp@beta   # or: npm i -g sangkar-mcp@beta

0.1.0-beta.0 publishes under the beta tag. Pin it explicitly — latest on the registry is a moving target: when npm first claimed this name it created a 0.0.0-stage holding version that took latest, and the real version took it over on publish, so an untagged install happens to get the prerelease today. That is a property of the registry's staged-publish flow, not of this package, and it stops being true as soon as a non-prerelease ships. sangkar-mcp@beta is the stable address.

The package ships TypeScript, so the sangkar binary runs under Bun through its shebang; the Bun prerequisite is not optional. Installing creates no database and writes nothing outside Bun's global directory.

From a checkout

bun install
bun link            # puts `sangkar` on PATH

bun link is the only global step: it registers bin/sangkar.ts as sangkar and touches nothing else. Skip it and invoke the entry point directly, which is the same program:

bun run bin/sangkar.ts status

Installing creates no database and writes nothing outside node_modules.

Related MCP server: repopedia

First run

sangkar index is the bootstrap: the one command that builds the graph by itself, with no client attached and no file change needed to start it.

cd /path/to/repo
sangkar index        # index the tree into <repo>/.sangkar/graph.db

It is the same work as the MCP index tool, with identical arguments. Until it has published once there is no store for a tool call to answer from, so every other command answers bootstrapping and exits 1. status is the one exception: it prints the single line naming the missing database and exits 0, because "no index yet" is the fact it exists to report. Once the graph exists, any tool answers:

sangkar status

The repository is found by walking up from the current directory: the nearest ancestor holding .sangkar, else the nearest holding .git, else the current directory itself. --repo-root states it explicitly, which is what a script should do:

sangkar status --repo-root /path/to/repo

CLI usage

sangkar <tool> [arguments] [global flags] — the name comes first

Example

What it does

sangkar status

The five human lines described below.

sangkar status --json

The same answer as the envelope.

sangkar search 'handleRequest'

Symbols matching a keyword.

sangkar trace 'db.write' --depth 1 --direction out

Callees of one symbol, one hop.

sangkar impact

What the working-tree diff reaches.

sangkar index --mode fast --force

Force a fast re-index.

sangkar trace --help

trace's own usage, exit 0.

Output:

  • status prints five human lines — the status line, then project, database, graph and health. On a tree with no index yet it prints the one-line reason instead, and exits 0.

  • Every other tool prints one JSON envelope.

  • --json is accepted by any tool and is the default output for all of them; it is status alone that swaps the envelope for human lines when the flag is absent.

  • --repo-root <path> and --data-dir <path> are globals: they follow the tool name and may sit anywhere among that tool's own arguments, in --flag value or --flag=value form; --json and --help are globals in the same sense. The name comes first — a global written before it is read as the tool name and refused with exit 2.

  • --help exits 0 with that tool's usage block, or, on a verb, the verb's own usage line: sangkar mcp --help, sangkar index --help, sangkar worker --help. It is answered before any argument is checked, so it works with a required argument still missing.

  • sangkar index streams progress as JSON log lines on stderr and exits 0 once it publishes. Nothing else reaches stdout.

Exit codes, from the envelope's status: 0 for ok, ambiguous and not_found — a negative answer is still an answer — 1 for error and bootstrapping, and 2 for a usage refusal (unknown tool, unknown option, missing value, bad type). sangkar index has two of its own, because it is the worker rather than a tool call: 2 when nothing changed and there was nothing to publish, and 75 when another indexer holds the lock.

MCP

The command a client registers as its stdio server:

sangkar mcp --repo-root /path/to/repo

--data-dir /path/to/dir is the optional second flag. stdout carries the MCP protocol and nothing else; diagnostics are JSON lines on stderr, one record per event.

The seven tools

Tool

What it answers

status

The generation being served, how stale the tree is, per-path coverage and the language census. Call it before saying something does not exist.

summary

The situation in a few hundred tokens: the working-tree diff (default), the whole repo, or one area, with risk, blast radius and test gaps.

trace

Callers, callees, implementers, importers and tests for one query, grouped by edge and tier; several matches come back as candidates, not a guess.

search

Symbols by keyword (BM25) with file:line and in/out degree — locations and shape, not source.

impact

What a change set reaches: dependents, affected entry points, the tests that cover them, and a risk score; defaults to the working-tree diff.

expand

More detail for one item from an earlier answer — members, edges, short source, or coverage.

index

Force a full or fast re-index, or repair a graph the watcher could not fix. Not for normal use.

Registered names are exactly these seven, in this order: no _tool suffix, no aliases, and no eighth name. MCP and the sangkar command publish the same surface; the instructions tell an agent to call index only when status reports a broken graph.

Six of the seven take an optional budget in tokens, defaulted per tool (status 800, summary 1200, trace 3200, search 2000, impact 2500, expand 2500); index has none, because a repair call has no payload worth paging. Above 32000 the call is refused with budget_too_large; so is a budget below the smallest size an answer can take, with a hint naming that floor — one refusal instead of a payload several times what you asked for.

.sangkar

One directory per working tree, beside the code it describes:

<repo>/.sangkar/graph.db          the graph
<repo>/.sangkar/graph.db-wal      WAL sidecars, never committed
<repo>/.sangkar/graph.db-shm
<repo>/.sangkar/write.lock        single-writer flock, outside the database
<repo>/.sangkar/.gitignore        a single `*`, written on first index

The data dir carries its own .gitignore holding one *, so git ignores everything inside without the repository's tracked .gitignore being edited. .sangkar is excluded from discovery the way .git is — otherwise each index would index the previous database. One database belongs to one working tree, including a linked git worktree; the database answering the session is always reported at status.payload.project.db_path.

Moving the data directory

--data-dir is the only override; a relative value resolves against the repository root. It exists because the checkout is not always somewhere you can write:

  • read-only mounts. A source tree mounted read-only, an image layer, or a CI checkout cannot hold .sangkar/ at all. Indexing into a writable directory leaves the tree byte-for-byte untouched.

  • network filesystems. SQLite needs working locks and a local filesystem for WAL; NFS, SMB, most FUSE mounts and synced folders do not provide that, and a half-checkpointed graph.db-wal is a corrupt graph. Keep the database on local disk and serve the tree over the mount.

A data dir holding an index of a different tree is refused rather than answered from, so a mis-pointed override is an error, not a quietly wrong answer.

Environment

Two settings remain, and both are read from the environment rather than a flag:

Variable

Default

Meaning

SANGKAR_CURSOR_KEY

empty

HMAC key for pagination cursors, 32 bytes or more; when unset the process generates its own key, so cursors do not survive across invocations — set it to share cursors between processes

SANGKAR_NO_WATCH

unset

any value stops the watcher; set by tests

Distribution

The order is TECH-SPEC.md §15's, and it is deliberate:

  1. Ship the Bun package first. A #!/usr/bin/env bun entry point is a small artifact, needs no rebuild per platform, and only requires Bun on the user's machine (102 MB itself). This is the route the seven tools are exercised through today.

  2. Add the compiled binary once the grammar set is fixed. bun build --compile produces a single file with no Bun prerequisite, but it is large and must be rebuilt per platform: 104 MB measured for a hello-world on Bun 1.4.4, 105.1 MB for this app (393 modules), and roughly 1–3 MB per embedded WASM grammar — an estimated 130–160 MB for the 12-language v1 set. Compiling grammars in is what makes the artifact big, so it waits until the language list stops moving.

Two facts about the standalone artifact today:

  • Migrations must be embedded. The migration runner reads .sql files from import.meta.dir/migrations; inside a compiled binary that directory is the virtual /$bunfs/root, which holds only what the build put there. Without --asset the binary ships zero migrations, computes a shipped schema version of 0, and refuses every existing index with schema_too_new. The working build command is:

    bun build --compile bin/sangkar.ts \
      --asset "$PWD/src/shared/store/migrations" \
      --outfile dist/sangkar

    bun run build passes exactly this flag, so dist/sangkar can read and serve an index. dist/sangkar mcp --repo-root /path/to/repo is the same command line the Bun install answers, with the binary in place of sangkar, and dist/sangkar status --repo-root /path/to/repo answers from it too. tests/binary-smoke.test.ts builds and drives that artifact, which is the evidence the flag is required rather than merely tidy.

  • Grammar WASM is not embedded. Grammars load lazily from web-tree-sitter and tree-sitter-wasms in node_modules at index time, never at startup, so a compiled binary serves an index with no node_modules beside it but cannot build one. Until the grammars are compiled in, indexing stays with the Bun install and the binary serves the graph it produced.

Publishing to npm

bun run release:beta          # npm publish --tag beta

Two traps, both hit on 2026-11-18 and both proven with npm publish --dry-run:

  • --tag beta is not optional. publishConfig.tag is ignored by npm 11 (it only suppresses the "you must specify a tag" guard for prereleases): without the flag on the command line the publish goes to latest anyway, which is the one tag a 0.1.0-beta.0 must never take.

  • The bin warning is cosmetic. npm prints bin[sangkar] script name bin/sangkar.ts was invalid and removed when it rewrites the field to strip a leading ./; the entry survives as bin/sangkar.ts. npm pkg fix shows the same result, so the canonical form is written in package.json and the warning no longer appears.

Publishing then needs two-factor authentication: either --otp <code> from an authenticator app, or a granular access token with 2FA bypass in ~/.npmrc. Without one the registry answers E403 ... Two-factor authentication or granular access token with bypass 2fa enabled is required, and nothing is published.

Checks

bun test                            # fixtures plus temp dirs; no network, no writes into the repo
bun run typecheck                   # tsc --noEmit, strict
bun run lint                        # biome check src tests bin
bun test tests/binary-smoke.test.ts  # builds the standalone artifact and drives one tools/call

License

MIT — see LICENSE. The grant covers the package as published, including the migration SQL it ships; tree-sitter-wasms, web-tree-sitter, drizzle-orm and the MCP SDK keep their own licenses.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Serves an AI coding agent a searchable index of a codebase's existing capabilities and past incidents, so it can find and reuse what already exists before writing new code. Also exposes blast-radius analysis for shared code and lets the agent reindex the knowledge base, all via local retrieval with no model calls or API keys.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Serves a repository's code knowledge graph over stdio (MCP) so coding agents can look up symbols, trace callers and callees, compute blast radius, list file symbols, run hybrid lexical-plus-graph search, and get citation-grounded answers from file:line evidence instead of guessing from text chunks. All tools work offline straight from the graph, with prose synthesis only when an OpenAI-compatible LLM endpoint is configured.
      17
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents and reviewers to query a deterministic code dependency graph for callers, routes, pages, tables, and config with file:line evidence instead of grepping. One server can serve many indexed graphs, supporting cross-repository impact analysis.
      329 PyPI
      4
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Serves AI coding agents focused context from a project-local SQLite graph of source entities and Git relationships, so they can retrieve relevant code, trace callers/callees and impact, and carry recorded mistakes into later sessions without reading whole files. Queries render bounded, token-estimated packets while all indexing stays on the local machine.
      24 npm
      MIT