Osnova

What osnova does

The osnova MCP server turns a repository into a local code map containing symbols and call relationships. It uses tree-sitter to parse source files, then makes the resulting index available through MCP or the command line. Its output is deterministic: the same input produces the same output byte for byte.

Queries can identify callers and related call edges with exact file and line references. Results distinguish relationships that were resolved through evidence such as import bindings, same-file definitions, re-exports, or identified receivers from same-name matches that could not be confirmed. The output can also report reach counts, tests, unresolved evidence, candidates, and omitted results when a response exceeds its budget.

How it works

The index is built from a local repository and read from a local cache. Tree-sitter supplies the parsed source structure, while language adapters resolve symbols and calls where the available evidence permits. Seven languages have deep adapters: TypeScript, JavaScript, Python, Go, Rust, Java, and C#. The project states support for 20 languages overall.

The osnova MCP server does not use embeddings or telemetry. It does not require a network connection during normal operation; the README identifies osnova update-check as the command that makes a network request. Resolution is intentionally explicit: unresolved calls remain separate from confirmed relationships rather than being presented as definite callers.

Setup and configuration

Node.js 22.13 or newer is required. Install the package globally with npm, or run it without a global installation through npx:

npx -y @getdomovoi/osnova mcp --workspace /path/to/repo

A manually configured MCP entry can invoke osnova mcp; when the package is not installed globally, use the equivalent npx -y @getdomovoi/osnova command. The workspace path selects the repository to index.

The project also provides setup commands for Claude Code and agent harnesses that read AGENTS.md. Setup previews file changes, and --apply writes them while backing up changed files.

Tools and capabilities

The osnova MCP server provides repository indexing and code-graph access over MCP. The documented command-line capabilities include:

• osnova warp for tracing callers and call reachability from a symbol such as src/api.ts#refreshWorkspace.
• osnova plumb for checking candidate call sites against indexed relationships and reporting confirmed, name-only, and unrelated matches.
• osnova coverage for reporting resolution results by language and reason.
• osnova mcp for serving the repository index to an MCP client.

The README describes the project as having ten tools over MCP and CLI, but the supplied material names only these capabilities directly.

Limitations and notes

A resolved edge is not a guarantee that no other callers exist, and the README warns that a result does not prove deletion is safe. Calls to external packages and built-ins cannot be resolved locally. Java and C# overloads share one indexed symbol; overload selection is reported only when the written argument count identifies one declaration under the stated type, partial-class, and base-class rules.

Coverage varies by repository and language. The published benchmark data shows that resolved call sites are a subset of all call sites, so unresolved evidence should be reviewed rather than treated as a confirmed relationship. The osnova MCP server is therefore best suited to deterministic repository navigation and evidence-based call-graph queries, not as a complete proof of program behavior.