jarvis

# jarvis

<!-- mcp-name: io.github.phuongddx/jarvis -->

[![CI](https://github.com/phuongddx/jarvis/actions/workflows/test.yml/badge.svg)](https://github.com/phuongddx/jarvis/actions/workflows/test.yml)
[![PyPI](https://img.shields.io/pypi/v/jarvis-mcp.svg)](https://pypi.org/project/jarvis-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/jarvis-mcp.svg)](https://pypi.org/project/jarvis-mcp/)
[![Platforms](https://img.shields.io/badge/platform-macOS%20%20%2F%20%20Linux-lightgrey)](https://pypi.org/project/jarvis-mcp/)
[![License: MIT](https://img.shields.io/pypi/l/jarvis-mcp.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-server-2e5aa8)](https://modelcontextprotocol.io)

**Local-first code intelligence for coding agents.** Precomputed SCIP navigation
(go-to-definition, find-references, call/type hierarchy, document symbols), Zoekt
lexical search, natural-language semantic search, and cross-repo blast radius —
exposed as ten MCP tools for Claude Code, Cursor, or any MCP client.

One indexing CLI writes up, one stdio runtime reads down — the storage seam in
`~/.jarvis` is the only contract between them. **No server, no auth, no network,
nothing leaves your machine.**

[What is it?](#what-is-it) · [How it works](#how-it-works) · [Quick start](#quick-start) · [MCP tools](#mcp-tools) · [Requirements and limits](#requirements-and-limits) · [Indexing](#indexing-a-repo) · [Configuration](#configuration) · [Documentation](#documentation)

## What is it?

**Without jarvis**, asking your agent *"where is `AuthService` used?"* means
grepping for the string, re-reading whole files to filter false positives, and
guessing at call sites — burning context window on **search** instead of
**reasoning**.

**With jarvis**, the agent calls `findReferences` and gets exact file-and-range
occurrences from a precomputed SCIP index, `callHierarchy` for the call graph,
and `semanticSearch` for questions like *"where is token refresh handled?"* in
plain language.

Think of it as `grep`, but matching **symbols, definitions, and references** —
indexed once per repo, answered in milliseconds.

- **Declaration-level navigation without any indexer** — a Tree-sitter syntax
  baseline (17 languages) is built on every `jarvis index` run from pip-installed
  grammars, no compiler or build system required — on top of a precomputed
  [SCIP](https://scip-code.org/) index for full precise navigation
  (TypeScript/TSX, Python, Java/Kotlin, Swift), Zoekt lexical search, and
  optional vector search, all from local SQLite/LanceDB files.
- **Read-only by design.** jarvis never edits code; it is the retrieval half.
  If you want an agent that performs semantic renames and refactors, you want
  [Serena](https://github.com/oraios/serena) — the two are complementary.

jarvis is deliberately narrow: one language per repo, macOS/Linux only, and
indexing is an explicit step — see [Requirements and limits](#requirements-and-limits)
before installing.

## How it works

<p align="center">
  <img
    src="https://raw.githubusercontent.com/phuongddx/jarvis/main/docs/assets/jarvis-architecture.png"
    width="880"
    alt="jarvis architecture: a writer CLI and an MCP reader inside the jarvis system boundary, both talking to four stores in the local data dir — the immutable SCIP index, Zoekt shards, LanceDB vectors, and the registry — plus the git repo and a lazily spawned zoekt-webserver">
1. **Index.** `jarvis index /repo` builds a Tree-sitter syntax baseline for every
   supported file first, then optionally runs the language's SCIP indexer and
   converts the result to SQLite, builds Zoekt shards (plus optional
   embeddings), and publishes everything **atomically** into `~/.jarvis` as one
   immutable snapshot selected by a single `current` pointer. SCIP tooling
   missing or failing degrades the run to exit-0 — the baseline still publishes.
2. **Serve.** `jarvis-server` speaks MCP over stdio and exposes ten tools,
   backed by lazy singletons; a `zoekt-webserver` is spawned on first search
   and shared across processes via pidfile.
3. **Ask.** Your agent calls tools. Every query opens the published
   `index-<sha>-<generation>.db` read-only (`mode=ro&immutable=1`) — the
   runtime path never writes.

**Storage is the seam.** The runtime half only ever reads down into it; the
indexing half only ever writes up into it; the two share no other contract.
Three load-bearing consequences:

- **The runtime path never writes.** Index files are never mutated in place.
- **Publishing is atomic.** A reindex writes a new versioned `.db`, populates
  the package graph, and runs `zoekt-index` — only once *all* of that succeeds
  does `os.replace` (POSIX `rename(2)`) flip the small `current` pointer. A
  query already reading the old file keeps working; there is no downtime
  window, and a failure anywhere leaves the previously published index live.
- **The package graph is rebuilt, not accumulated.** Each reindex clears that
  repo's own outgoing edges before recomputing them, so `blastRadius` always
  reflects each repo's *last* index run.

Layer-by-layer detail, the full index pipeline, and the semantic path are in
[`docs/system-architecture.md`](docs/system-architecture.md). Core query/search
logic is ported from an internal reference implementation; the enterprise shell
(FastAPI, Postgres, hosted-git auth, Cloud Build) is dropped in favor of a
single stdio process reading local SQLite files.

## Quick start

**1. Install the external indexer binaries** (only needed for optional SCIP
navigation and Zoekt search — the Tree-sitter syntax baseline ships inside the
pip package and needs no external binary): scip, zoekt, per-language indexers:

```bash
curl -fsSL https://raw.githubusercontent.com/jarvis-intelligence/jarvis-index/main/setup.sh | sh
```

**2. Install jarvis:**

```bash
uv tool install jarvis-mcp
```

**3. Index a repo** (slug defaults to the directory name):

```bash
jarvis index /path/to/your/repo
```

**4. Register the MCP server.** Using Claude Code, install the plugin and it
registers itself:

```
/plugin marketplace add jarvis-intelligence/jarvis-index
/plugin install jarvis@jarvis
```

Any other MCP client (or Claude Code without the plugin) registers manually:

```bash
claude mcp add jarvis --scope user -- jarvis-server
```

That's it — ask your agent *"find all references to `AuthService`"* and it will
call `findReferences` instead of grepping.

<details>
<summary>Other MCP clients (Cursor, Claude Desktop, any stdio client)</summary>

```json
{
  "mcpServers": {
    "jarvis": {
      "command": "jarvis-server"
    }
  }
}
```

If your client can't find `jarvis-server` on `PATH` (GUI apps often don't
inherit your shell's), use the absolute path from `which jarvis-server`.
</details>

<details>
<summary>Running from a clone instead</summary>

```bash
git clone https://github.com/phuongddx/jarvis && cd jarvis
uv sync
claude mcp add jarvis --scope user -- uv --directory "$(pwd)" run jarvis-server
```
</details>

<details>
<summary>Optional extras</summary>

```bash
uv tool install "jarvis-mcp[watch]"      # + watchdog, for `jarvis watch`
uv tool install "jarvis-mcp[semantic]"   # + lancedb/sentence-transformers, for semanticSearch
```
</details>

## MCP tools

| `goToDefinition` | Resolve a symbol to its defining file and range — SCIP when the file has SCIP definition coverage, otherwise the syntax baseline's declaration; each location carries `source` (`"scip"` or `"tree-sitter"`) and `positionEncoding` |
| `findReferences` | Every occurrence of a symbol across the indexed repo — **SCIP-only**: without usable SCIP occurrence data it returns `requiredCapability`/`reason`/`recovery`, never an empty list |
| `callHierarchy` | Incoming/outgoing calls for a symbol — **SCIP-only** (same contract as `findReferences`) |
| `typeHierarchy` | Supertypes/subtypes — **SCIP-only**; needs an index built with the bundled `scip`, see [limitations](#known-upstream-limitations) |
| `documentSymbols` | Outline of every symbol defined in one file — routed per file: the SCIP outline when usable, otherwise Tree-sitter declarations; a syntax-served response carries a `coverage` object (parsed/partial/failed counts and reason) |
| `searchCode` | Zoekt lexical/regex search, optionally filtered to one repo |
| `semanticSearch` | Natural-language search — vector hits fused with Zoekt lexical hits and SCIP symbol-definition matches via reciprocal rank fusion |
| `blastRadius` | Which *other* indexed repos depend on a package, up to 2 hops |
| `getIndexStatus` | Published commit, freshness, staleness vs. a working tree; `capabilities.tools` reports per-tool providers, `capabilities.syntax` reports extraction counts, and freshness names the snapshot `generation` |
| `indexRepo` | Build an index for a git repo at `path` so the other tools have something to read. Returns immediately; poll `getIndexStatus`. `semantic` defaults to false. |

`documentSymbols`/`goToDefinition` are **per-file provider routed**: a file with
usable SCIP coverage is answered by SCIP (full identifiers, references,
hierarchies); a file without it is answered by the syntax baseline's real
Tree-sitter declarations, whose opaque `syntax:` identifiers round-trip through
`goToDefinition`. Bare or qualified names search both providers, so an
ambiguous name returns combined candidates from both.

Every nav tool takes `repo` (the slug from `jarvis index`) plus a
tool-specific `symbol` or `path`. All tools report failure the same way — a
`{"error": "..."}` payload rather than a transport-level error, so a query bug
never kills the stdio server.

## Requirements and limits

Read this before installing — jarvis is deliberately narrow.

- **macOS and Linux only.** Windows is not supported.
- **One language per repo.** Language is detected by extension plurality across
  git-tracked files; a polyglot monorepo gets indexed as whichever language has
  the most files. Multi-language merge is out of scope. Override with