osnova
OfficialSummary: Osnova is a read-only, deterministic code-map MCP server that indexes a repository into a symbol and call graph and answers structural questions about it.
Search definitions (
osnova_ground): keyword/identifier search returning exactfile:line, kind, span and signature, with optional inlined source; also resolves framework routes likeGET /usersto their handler.Text search (
osnova_thread): regex or literal matches grouped by enclosing definition and ranked by how many dependents it has.File outline (
osnova_outline): definitions of one file with signatures and line spans, instead of reading the whole file.Call graph (
osnova_warp): who calls a symbol or what it calls, direct or transitive (depth 2), with exact call-sitefile:line.Repository map (
osnova_groundwork): directory clusters, hubs and hotspots for an unfamiliar codebase.Task context (
osnova_footing): seed definitions, their callers/callees and related test files for a multi-file change or review.Change impact (
osnova_settle): symbols a diff touches and their indexed dependents; can index a base ref for comparison.Claim checking (
osnova_plumb): verifies an agent's claimed call sites as confirmed, name-only, no-call, or missing dependents.Tests lookup (
osnova_tests): test files with resolved edges to given symbols (plus import-only leads), or symbols one test file reaches.Unreferenced candidates (
osnova_unreferenced): definitions with no indexed callers, each with same-name leads and mention counts.
All tools are read-only and offline, return exact file:line evidence with omission counts, and explicitly treat empty results as "not found", never as proof of absence.
Indexes C++ codebases to provide symbol search, call graph navigation, and change impact analysis.
Indexes Dart codebases to provide symbol search, call graph navigation, and change impact analysis.
Indexes Elixir codebases to provide symbol search, call graph navigation, and change impact analysis.
Indexes JavaScript codebases to provide symbol search, call graph navigation, and change impact analysis.
Indexes Kotlin codebases to provide symbol search, call graph navigation, and change impact analysis.
Indexes OCaml codebases to provide symbol search, call graph navigation, and change impact analysis.
Indexes PHP codebases to provide symbol search, call graph navigation, and change impact analysis.
Indexes Python codebases to provide symbol search, call graph navigation, and change impact analysis.
Indexes Ruby codebases to provide symbol search, call graph navigation, and change impact analysis.
Indexes Rust codebases to provide symbol search, call graph navigation, and change impact analysis.
Indexes Scala codebases to provide symbol search, call graph navigation, and change impact analysis.
Indexes Swift codebases to provide symbol search, call graph navigation, and change impact analysis.
Indexes TypeScript codebases to provide symbol search, call graph navigation, and change impact analysis.
Indexes Zig codebases to provide symbol search, call graph navigation, and change impact analysis.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@osnova where do we validate tokens?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Osnova
A deterministic code map for AI coding agents. Osnova indexes a repository into a symbol and call graph with tree-sitter, then serves it to any MCP client or from the command line. Same input, same output, byte for byte. No embeddings, no telemetry, and no network connection unless you type osnova update-check. Twenty languages, seven of them (TypeScript, JavaScript, Python, Go, Rust, Java, C#) with deep adapters.
Osnova is the Slavic word for base or foundation. That is the job: give an agent solid ground to stand on before it edits code.
Quick start
Node.js 22.13 or newer. Serve a repository to any MCP client:
npx -y @getdomovoi/osnova mcp --workspace /path/to/repoAfter npm install -g @getdomovoi/osnova, one command per kind of agent: claude wires Claude Code (MCP entry, session, prompt and stop hooks, and the skill); agents wires every installed harness that reads AGENTS.md (Codex, OpenCode, Kilo, Pi, Cursor), each with its hooks, plugin or extension, plus one shared skill in ~/.agents/skills/. Each previews its changes; --apply writes them, backing up every file it changes.
osnova setup claude --apply
osnova setup agents --applyOr add the MCP entry by hand; replace osnova with npx -y @getdomovoi/osnova when there is no global install.
{ "mcpServers": { "osnova": { "command": "osnova", "args": ["mcp"] } } }Related MCP server: ThingForce Graph Studio
What you get back
osnova warp src/api.ts#refreshWorkspace on this repository, cut to twelve lines (test/docs-readme-warp.test.ts fails when the first two no longer reproduce):
function src/api.ts#refreshWorkspace: 83 indexed edges
reach: d1 callers 83 in 14 files (3 dirs); d2 +16 in 2 files; unresolved same-name 10; tests 18
d1 calls src/cli/cli.ts#ensureIndex:78 [import-binding]
d1 calls src/cli/hook.ts#runHook:191,203,225,240 [import-binding]
d1 calls src/mcp/server.ts#createOsnovaMcpServer.refresh:297 [import-binding]
d1 calls test/verification-fastpath.test.ts#<module>:37,47,48,51,53,57,58,64,68,74,78,85,110,114,132,145,154,166,171,197 [re-export-binding]
via src/index.ts:65 refreshWorkspace -> src/api.ts (export refreshWorkspace)
This does not prove absence of callers or that deletion is safe.
unresolved evidence (10); not confirmed relationships
candidates for refreshWorkspace (2, unverified): src/api.ts#refreshWorkspace, test/mcp-watch.test.ts#refreshWorkspace
d1 calls refreshWorkspace test/artifact-format9.test.ts:78,85,104,120,140 [binding-blocked]
d1 calls refreshWorkspace scripts/perf.mjs:485,486,491 [import-target-unresolved]Each confirmed line names the caller, its lines and the evidence that tied the call to this definition: an import binding, a same-file definition, a re-export chain with its hop, or an identified receiver. Calls the index could not tie to a definition are listed apart as unresolved evidence, with the same-name candidates it found and the reason it stopped, so a name match is never mistaken for a caller. The reach line gives exact counts, not scores, and when the list outgrows its budget a capped: line and an omitted: footer count what was left out.
How much of the graph is exact
A call site counts as resolved when the index ties it to one definition through evidence it can name; everything else stays unresolved with a reason. These are the shares on the pinned checkouts under benchmarks/corpora/, recorded in benchmarks/results/resolution-coverage-2026-09-21b.json; the last column leaves out calls through packages outside the repository and calls to builtins, which can never resolve locally, and the reference defines every column.
Corpus | Languages | Call sites | Resolved | Share | Excluding externals |
click | all | 6593 | 2903 | 44.0% | 62.4% |
cobra | all | 4374 | 1980 | 45.3% | 88.9% |
gson | all | 23382 | 8473 | 36.2% | 56.7% |
humanizer | all | 30517 | 7798 | 25.6% | 51.3% |
pyright | all | 58578 | 30070 | 51.3% | 74.5% |
ripgrep | all | 13387 | 6121 | 45.7% | 71.6% |
zod | all | 53417 | 21630 | 40.5% | 73.2% |
Per-language rows are in the reference. osnova coverage reports the same numbers for your own repository, per language and per reason.
Resolved is not the same as right, so the call edges are also scored against each language's type checker or compiler. Every call site in six pinned checkouts was sent to the checker for the callee's declarations, and each osnova edge was marked true when the definition it names contains that declaration and false when it does not. Measured at 0.12.0:
Corpus | Checker | Decided edges | False | False-edge rate | In-repo sites covered |
click | pyright 1.1.414 | 2883 | 0 | 0% | 90.4% |
zod | TypeScript 5.9.3 | 21593 | 4 | 0.02% | 78.2% |
cobra | go/types, Go 1.27.1 | 1980 | 0 | 0% | 87.5% |
ripgrep | rust-analyzer 1.98.1 | 6066 | 29 | 0.48% | 85.8% |
humanizer | Roslyn 5.9.0 | 7363 | 3 | 0.04% | 62.2% |
gson | javac 27 | 8133 | 4 | 0.05% | 72.3% |
Java and C# overloads share one symbol in the index, so a call edge names the overload it binds only when the written argument count fits exactly one declaration of the type, its partial parts and its declared base classes; when it fits several or none, the edge keeps the method and names no declaration, and the oracle leaves it out of both rates (2526 edges on gson, 602 on humanizer). 0.11.0 named the last overload declared for every call, recorded a call at the first line of its call expression, and lost the rest of a C# file after a primary constructor or a raw string; it measured gson 2045 false edges (24.75%), humanizer 617 (8.25%) and ripgrep 112 (2.06%). Of the 29 left on ripgrep, 11 are functions declared once per #[cfg] branch, 6 are a test module's function named like its parent's, and 5 are calls to a local closure or parameter named like a function elsewhere. A call whose target has one declaration that fits keeps it even when a base type is outside the index, where an unseen base overload could be the one the compiler binds; this limit is kept because withdrawing those edges cost 10 recall points on humanizer for one fewer false edge. Every false edge is classified by cause in benchmarks/results/type-checker-oracle-2026-09-30.json with the method and its limits. The scripts that produce these numbers are in benchmarks/oracle/.
Grep versus the graph
The reason to keep a call graph instead of running a text search is not speed. It is that the first regex a person types is wrong more often than it looks, and nobody notices. Nine call-site sets in six languages were verified line by line; each cell shows sites found (precision / recall), and the method lists what each side got wrong.
Corpus | Target | Verified sites | Text search | Resolved graph |
click |
| 13 | 12 (0.92 / 0.85) | 12 (1.00 / 0.92) |
pyright |
| 28 | 5 (0.80 / 0.14) | 28 (1.00 / 1.00) |
cobra |
| 30 | 30 (1.00 / 1.00) | 30 (1.00 / 1.00) |
cobra |
| 12 | 13 (0.92 / 1.00) | 12 (1.00 / 1.00) |
humanizer |
| 18 | 19 (0.74 / 0.78) | 18 (1.00 / 1.00) |
ripgrep |
| 12 | 32 (0.38 / 1.00) | 12 (1.00 / 1.00) |
ripgrep |
| 26 | 26 (1.00 / 1.00) | 26 (1.00 / 1.00) |
gson |
| 10 | 29 (0.34 / 1.00) | 10 (1.00 / 1.00) |
gson |
| 27 | 43 (0.63 / 1.00) | 27 (1.00 / 1.00) |
The graph never returned a site that was not a call of the target. The record is benchmarks/results/grep-vs-graph-2026-09-21.json.
The ten tools
The names play on the foundation image. The CLI uses the same names without the prefix: osnova ground and osnova_ground are the same query.
Tool | Meaning | Does |
| the ground you stand on | Keyword search: ranked definitions with exact |
| the thread you follow through the cloth | Text search: regex or literal matches grouped by symbol |
| the outline of one part | Signatures and line spans for one file |
| the threads that hold the weave | Call graph: callers and callees, direct or transitive |
| the groundwork under everything | Repository map: directory clusters, hubs and hotspots |
| the footing you build on | Task context: definitions, relationships and candidate tests around a question |
| how the ground settles after a change | Change impact: the symbols a diff touches and their indexed dependents |
| the plumb line dropped straight through | Check claims: which listed call sites the index confirms, and which dependents were left out |
| the cloth pulled to see what holds | Tests: the test files that reference a symbol, or the symbols one test file reaches |
| threads left loose at the edge | Definitions with no indexed caller, each with its leads; candidates, never proof |
Every MCP response opens with its index generation, says when the index is partial, and counts what its budget left out; the budgets, and which CLI subcommands carry the generation, are in the reference.
Hooks and clients
One global install serves every repository and every client: one entry in each client's global config, nothing per project, nothing written inside your repository. osnova setup claude and osnova setup agents show the diff and write nothing until --apply; agents skips a harness whose config folder is missing, --only codex,pi narrows it, and a skill or plugin file you edited is kept and reported. --uninstall reverses either family the same way, previewing first. The table lists the per-client form, for one piece at a time. What each hook prints, when it stays quiet, and what the trials measured are in the reference.
Client | How to wire | What it adds |
Claude Code |
| MCP entry plus session, prompt and stop hooks; |
Claude Code, as a plugin |
| The same MCP entry, hooks and skill, run through |
Codex |
| MCP entry plus the same three hooks; trust them in |
Cursor |
| MCP entry plus the stop hook as a follow-up message; |
OpenCode |
| MCP entry plus a plugin that appends starting points to each message; the tool guidance comes from the MCP instructions; |
Kilo |
| MCP entry plus the same plugin; |
Pi |
| MCP entry through |
The search gate is opt-in: add --gate to osnova setup claude or osnova setup agents, or to the per-client form. It denies a grep, rg, find or search-tool call that reaches code osnova indexes until an osnova tool, or the osnova CLI, has run in the current turn; the deny names the tools to use instead. A search of data, prose or configuration files, of a path outside the repository, or of a command's output after | always runs. Codex and Pi may not report an osnova call to the gate, so there it denies once per turn until it has seen one, then holds as on the other clients. OSNOVA_GATE=off switches it off for a session.
In CI
The action runs osnova settle --base-ref against the pull request base and lists every indexed dependent of the symbols the pull request changed; the report is indexed structural evidence only, so a missing dependent is not proof that nothing depends on the change.
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: getdomovoi/osnova@v0.12.1
with:
depth: "2"Inputs and the local form are in the reference.
What osnova does not do
No type inference and no dynamic dispatch. Edges come from syntax: direct calls, imports, name references, declared heritage (a written superclass or interface name) and framework routes (a registration whose receiver binds to a listed framework import, with the verb and the literal path written at the site), with lexical binding and receiver hints for TypeScript, JavaScript and Python. Resolution is heuristic and says so.
No route table. A
routesedge is one registration site tied to one handler; prefixes from mounts, blueprints and controllers are recorded on their own edges and never composed into a full path, a computed path records no path, and an inline closure or a wrapped handler records the route with no target. Express, NestJS, Flask and FastAPI are read; gin, axum, Django, Spring, ASP.NET, Rails and file-based routers are not.That boundary has a measured price. Scored against a type checker on two pinned corpora, the calls osnova does not resolve are mostly calls whose receiver type is never written down: 2945 of 6359 missed sites on zod and 164 of 307 on click are a plain name carrying no annotation, and another 1478 on zod are a call result or a property chain. Only 349 missed sites on zod and 10 on click have a type written at the receiver's declaration, and 248 of those 349 are a single library idiom. Resolving every one of them would move recall from 76.9% to 78.2% on zod and from 90.4% to 90.7% on click, so the boundary costs roughly one recall point rather than ten. The full census is in
benchmarks/results/receiver-boundary-census-2026-09-21.json.No semantic search.
osnova_groundis fielded lexical ranking over definitions. It is fast, deterministic and explainable, and it will not match a paraphrase.No proof of safety. An empty caller list means the index found no caller, not that none exists.
No cost claims. Agent trials so far show correctness parity with and without the graph on small tasks. A benchmark that separates the two is in progress.
How it stays honest
Every query refreshes the index from the working tree first, uncommitted edits included, and reports its generation.
Every clipped output says how much was clipped. Every ranked list says how many candidates it dropped. Partial indexes say so on every response.
Every hit carries a
file:linespan, a source hash and an index generation, so you can check what the agent cites.Every benchmark result in
benchmarks/results/is frozen with its corpus fingerprint, and rejected experiments stay on record next to accepted ones.The cache verifies a SHA-256 over the structural core before parsing it and hash-checks each source text on read. Nothing is written outside it.
CLI
Every tool is a subcommand: osnova build <root>, osnova warp <symbol>, osnova settle --base-ref <ref>, plus coverage, check, doctor, setup and mcp. The full list is in the reference.
Library
import { buildIndex, ask, callersDetailed, renderMapCard } from "@getdomovoi/osnova". The structured APIs return complete results with omission counts; the text budgets apply to CLI and MCP presentation only. Every export is in the reference.
Contributing
Bug reports, language adapters, benchmark corpora and agent trials are all welcome. Read CONTRIBUTING.md for the gates a change must pass: lint, typecheck, tests, build, perf budgets and package smoke.
pnpm install
pnpm lint && pnpm typecheck && pnpm test && pnpm build && pnpm perfDeterminism is the core invariant. A change that makes incremental refresh differ from a full rebuild by one byte is a bug.
License
Apache-2.0
Privacy: PRIVACY.md. Security policy and reporting: SECURITY.md.
Available Tools
10 toolsosnova_footingARead-onlyIdempotent
Task context: for one task, the seed definitions (inlined when 40 lines or shorter), the callers and callees that connect them, and the test files that touch them, under 4096 code units with exact omission counts. Use once at the start of a change or review that spans more than one file; for a single known symbol use ground or warp instead.
Inputs: in, task, depth, kinds, +3 more.
osnova_groundARead-onlyIdempotent
Search: find definitions by keyword or identifier. Each hit gives exact file:line, kind, definition span and signature, without source lines. Pass lean=false to inline the whole definition when it is 40 lines or shorter and an 8-line excerpt otherwise, or full=true to inline whole definitions. Start here when you do not know where code lives. A verb and path (GET /users) finds the route registration and its handler for Express, NestJS, Flask and FastAPI.
Inputs: question (required), in, full, lean, +1 more.
osnova_groundworkARead-onlyIdempotent
Repository map: directory clusters, hubs and hotspots in under 2048 code units. Use once when the repository is unfamiliar; do not follow it with an outline of every directory.
Inputs: maxDirs.
osnova_outlineARead-onlyIdempotent
Outline: the definitions of one file with signature and line span, selected by connectivity to fit 4096 code units, with an exact count of any omitted. Use instead of reading a whole file to learn its shape; read only the span you need afterwards.
Inputs: file (required).
osnova_plumbARead-onlyIdempotent
Check claims: given a symbol and a list of path:line call sites an agent believes depend on it, says which are confirmed by the index, which are name matches only, which have no call, and which indexed dependents were left out. Use before declaring a caller list complete. Confirmed means an indexed resolved edge, not runtime proof.
Inputs: sites (required), symbol (required), depth, direction.
osnova_settleARead-onlyIdempotent
Change impact: given the output of git diff, the symbols the diff touches and their indexed dependents to the requested depth (default 1), under 4096 code units with exact omission counts. Use once after editing, before declaring done, to find callers the tests do not cover; with no arguments it checks every uncommitted change against HEAD. A diff alone compares against the current index only, so deleted symbols are not visible; with baseRef (a git commit or ref) it indexes that commit's tree under the cache and compares it with the current index, computing the diff with git when none is given.
Inputs: diff, depth, baseRef.
osnova_testsARead-onlyIdempotent
Tests: given symbols, the indexed test files for each one in two separate tiers with separate counts: files with a resolved call or reference edge to the symbol (exact file:line and resolution basis), then files that only import the symbol's file and contain no indexed call or reference to it. An empty resolved tier is stated on its own line; import-only files are leads, not tests of the symbol. Given one test file, the non-test symbols it calls and the files it imports. Exactly one of symbols or file. Use before editing to find the tests to run. No indexed test is not proof of no test, and a listed test is not coverage.
Inputs: file, limit, symbols, includeImportOnly.
osnova_threadARead-onlyIdempotent
Text search: regex or literal matches over indexed text, grouped by the enclosing definition and ranked by how much else depends on it. Shows up to 10 matches per group and 50 groups by default (limit raises the group cap); totals and omission counts are exact, so you know what was left out.
Inputs: pattern (required), in, fixed, limit, +1 more.
osnova_unreferencedARead-onlyIdempotent
Unreferenced candidates: definitions with no resolved call or reference edge from outside their own body in a non-test file, sorted by file and line, each with the count of unresolved same-name call sites (leads that may reach it), test-file sites and identifier mentions in non-test files. Entry points (main, default exports, index.* files, package.json bin files, test files, constructors, Python dunders) are never listed; exported definitions are listed only with includeExported. Candidates only: no indexed caller is not proof of no caller.
Inputs: kinds, limit, scope, includeExported.
osnova_warpARead-onlyIdempotent
Call graph: who calls a symbol (direction=in, default) or what it calls (direction=out), with exact call-site file:line. Accepts file#Class.method, Class.method or a bare name. Use before changing a signature or deleting code. An empty list means no indexed caller, not proof that none exists.
Inputs: symbol (required), full, depth, direction.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Each tool has a clearly distinct purpose: repository overview, file outline, symbol search, text search, call graph, task context, change impact, claim checking, test discovery, and unreferenced audit. No two tools overlap in function or output, so an agent can select the right tool without confusion.
All names are a single lowercase word with the osnova_ prefix, which is consistent and readable. However, the terms are metaphorical and domain-specific rather than predictable verb_noun patterns, making them less immediately intuitive than standard naming conventions.
Ten tools is well-scoped for a code intelligence server, covering discovery, navigation, analysis, and validation without redundancy. Each tool earns its place by addressing a distinct code-understanding need.
The set covers a broad range of code intelligence tasks from exploration to change validation, with strong attention to edge cases. It lacks direct tools for editing code or generating diffs, but those may be outside the server's scope.
Maintenance
Related MCP Connectors
Ask a codebase what calls what: search, blast radius, paths between symbols, and diffs.
Ask who calls a route, what a change breaks or who reads a field, across a system's repos.
Persistent memory, hybrid search and a goal graph for AI agents, over stdio or remote HTTP.
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceServes a repo-indexing engine over stdio with tools for scanning, graph analysis, symbol extraction, caller lookup, and grep.1,543 npm1MIT
- AlicenseNot gradedqualityCmaintenanceEnables people and AI agents to query local code repositories as graphs through stdio MCP tools for project listing, search, dependency tracing, impact analysis, bridge detection, node inspection, bounded code reading, and optional LSP definition/reference lookups.MIT
- AlicenseNot gradedqualityBmaintenanceServes 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.16MIT
- AlicenseNot gradedqualityBmaintenanceEnables agents and tools to read and write a repo-local graph datastore over stdio, query it with datalog, and manage nodes such as todos, gaps, rules, and notes.26 npm1MIT