kula MCP

Why "kula"?

In the Trobriand Islands, the kula ring is a circuit of gifts. Shell necklaces travel one way around the islands and armbands travel the other. Nobody keeps them. Their value is the history of hands they have passed through. A commit works the same way: a sign whose meaning is its lineage. In Peirce's terms the code is the sign, the graph is its object, and your notes are the interpretant. Kula puts all three in one place, with the map drawn before you touch the code.

The mark is a K drawn inside the kula ring. Every stroke lies on the hexagon's own geometry: the stem is a chord, the arms are two of its radii, and the junction is the centre node. The letter is literally a subgraph of the circuit.

Related MCP server: 50 First Tapes MCP Server

Where Kula fits

Developer tooling around git splits into camps, and each leaves a gap:

Kula collapses these into one MIT-licensed binary. The same graph powers your git client, your reviews and your AI agent. Three things are unusual:

1. Architectural review. graph-diff and the Contrast view show what a branch does to the structure (symbols gained, lost and rewritten, call edges added and cut), not just which lines moved.

2. Review that works offline. Proposals, issues and notes are git objects on refs/kula/meta, so they work on a plane and sync through any remote.

3. Triage built in. The Overview ranks open proposals by risk and surfaces hotspots (files with high churn and high centrality) without a separate SaaS product.

Install

Kula is a single static binary (about 11 MB) with the web UI embedded. Its only runtime dependency is git.

curl -fsSL https://a12n4v.github.io/kula/kula.gpg | sudo tee /usr/share/keyrings/kula.gpg >/dev/null
echo "deb [signed-by=/usr/share/keyrings/kula.gpg] https://a12n4v.github.io/kula/apt stable main" \
  | sudo tee /etc/apt/sources.list.d/kula.list
sudo apt update && sudo apt install kula

Why not plain brew install kula or apt install kula? Those names resolve only in the distributions' own repositories. Homebrew core admits self-submitted projects once they are at least 30 days old with 225 stars (or 90 forks or watchers); a source-built formula is ready in packaging/homebrew/kula-core.rb for that day. Debian and Ubuntu need a sponsored package with every Rust dependency packaged first. Until then, the tap and the signed apt repository are one line each.

Sixty seconds

cd your-repo
kula index                 # build the knowledge graph  → .kula/graph.db
kula view                  # open the graph + git UI    → http://localhost:7420
kula impact parseConfig    # what breaks if I change this?
kula compare main feat/x   # graph-aware branch diff
kula graph-diff main WORKTREE  # what my uncommitted work does to the architecture
kula commit -am "ship it"  # …and it's still just git

The UI

kula view serves a local app at localhost:7420. It binds to 127.0.0.1 only and is protected by a per-session token.

Also included:

• Notes on the repo, a file, a symbol or a commit, with [[symbol]] links.

• Flows: execution paths traced from entry points.

• Symbol history: the owners and commits behind any function (git log -L), in the inspector.

• Git console: any non-interactive git command, in the browser, under a slowly turning dithered portrait of the repo.

• One palette (⌘K) for everything. Prefix # for issues and proposals, @ for branches, > for commands.

• Navigation: number keys 1–9, 0 switch views; [ ] go back and forward through inspected symbols; ? shows every shortcut.

• Shareable deep links such as #graph/<id>/impact, #graph/contrast/main/feat%2Fx and #issues/3.

• Always-fresh graph: kula view reindexes in the background whenever HEAD moves.

• Settings (,): colour the graph by directory, cluster, kind or 90-day churn; pick any directory's colour; set directory depth, hub share, label density, import edges and curved edges; light, dark or system theme; compact or comfortable density.

• Resizable panels: drag any panel edge (lists, inspector, legend, contrast panel, the before/after divider, settings) to size it; double-click an edge to reset. Sizes are remembered per browser, and arrow keys work on a focused edge.

Design principles

1. Triage first, then the map. You land on what needs you; every item opens straight into the graph, the diff or the thread.

2. One variable per channel. Hue is the variable you choose (directory by default). Size is degree. Shape marks hubs. The ground behind the nodes is the directory. Nothing glows for decoration.

3. Keyboard first. Everything is reachable through ⌘K, and every view has a number key.

4. Honest status. The top bar always says whether the graph matches HEAD.

5. Motion explains cause. Selecting a symbol dims everything that isn't connected to it, and small dots run along its calls in the direction they go. prefers-reduced-motion is respected everywhere.

6. Three voices of type. Antonio, compressed, for titles and figures; JetBrains Mono (ligatures off, so code reads as written) for labels, paths and code; Geist for reading.

7. Density over decoration. Every number sits next to what it means: KPIs carry a sub-fact, hotspots show commits and edges, the hover card shows in, out, lines and churn.

Commands

Kula is a superset of git. Any command it doesn't recognise goes straight to git, so kula rebase -i, kula bisect and kula lfs pull all work.

Every graph command accepts --json, and -C <path> works like git's.

For AI agents (MCP)

kula mcp gives agents the graph as tools: query, context, impact, trace, compare, graph_diff, flows, notes, issues. Agents can check the blast radius before editing and read the notes your team left.

// Claude Code:  claude mcp add kula -- kula mcp
// Cursor / others (.mcp.json):
{ "mcpServers": { "kula": { "command": "kula", "args": ["mcp"] } } }

How it works

• Indexing. Files are walked in parallel (respecting .gitignore) and parsed with tree-sitter. Kula extracts definitions (functions, methods, classes, interfaces), call sites and imports. Imports are resolved per language (relative JS/TS paths, Python packages, Rust mod/use, Go packages). Calls are resolved by preferring the same file, then imported files, then an unambiguous global match. A stoplist keeps generic names like .get() and .map() from creating false edges.

• Contrast. Any revision's graph is built straight from git objects (git ls-tree plus a single git cat-file --batch), with no checkout, and cached per commit. Symbols are matched across revisions by kind, path, container and name, and compared by a hash of their source.

• Clusters. Weighted label propagation over calls, containment and imports. Each cluster is named after its dominant directory and its central class or file.

• Storage. .kula/graph.db is SQLite with FTS5. It is git-ignored automatically and rebuilt by kula index. A small codebase indexes in well under a second.

• Issues, proposals and notes live in one JSON document committed onto refs/kula/meta. Every change is a commit, so there is full history and nothing touches your branches. kula sync fetches, merges and pushes that ref through any git remote.

• Git itself is never reimplemented. Kula shells out to your git, so hooks, signing, credential helpers, LFS and your config all keep working.

• Security. The UI server listens on 127.0.0.1, rejects foreign Host headers (which blocks DNS rebinding), requires a random per-session token on every API call, and validates revisions so they can't be read as git options.

Language support today: TypeScript/TSX, JavaScript/JSX, Python, Rust, Go. Adding a language takes a grammar crate plus a few tree-sitter patterns in src/index/langs.rs.

Development

pnpm -C web install && pnpm -C web build   # UI → web/dist (embedded at compile time)
cargo run -- view                           # run against this repo
pnpm -C web dev                             # hot-reload UI, proxies /api to :7420 (start `KULA_TOKEN=dev kula view --no-open` first)
./scripts/test.sh                           # everything; --quick skips packaging

scripts/test.sh is the single entry point used by CI:

src/
  main.rs        CLI (clap) + git passthrough
  git.rs         thin wrapper over the git binary
  index/         tree-sitter indexer + language registry
  store.rs       SQLite graph store + FTS search
  graph.rs       clusters · context · impact · trace · flows · compare
  meta.rs        issues / proposals / notes on refs/kula/meta
  server.rs      axum HTTP API + embedded UI
  mcp.rs         MCP stdio server
web/src/         React UI (sigma.js graph, Geist type)
packaging/       npm launcher · Homebrew formula
scripts/         test.sh · install.sh

Releasing: push a vX.Y.Z tag. release.yml builds 5 targets and publishes the GitHub release, .deb packages, PyPI wheels, npm packages, the crates.io crate and the Homebrew formula.

Roadmap

• Incremental re-indexing on file change (kula view --watch)

• More languages: Java, C#, Kotlin, Swift, C/C++, Ruby, PHP

• Semantic search with optional local embeddings

• Two-way sync with GitHub and GitLab issues and PRs

• Time-travel graph: scrub through history and watch the architecture change

• Interactive rebase planner in the UI

License

MIT © 2026 Arnav Sharma. Kula is an independent, clean-room project and contains no code from other code-graph tools.