MCP Server¶

CodeNib serves a pre-built repository manifest to coding agents over Model Context Protocol stdio. Index construction and query serving are separate: build or update a repository once, then reuse that manifest across agent sessions.

Install And Index¶

For Codex or Claude Code, the recommended 0.2.3 path prepares the graph index and native client configuration together:

python -m pip install "codenib[graph,mcp]==0.2.3"
codenib codegraph init /path/to/repository

This keeps the checkout clean, uses each client CLI instead of editing its configuration directly, and enables explore_context, dependency_subgraph, BM25, regex, static definitions/references, and verified source reads. See Agent-ready CodeGraph for the complete one-command lifecycle.

For a custom MCP client or a retrieval-only setup, build and launch the server manually. The smaller no-model fallback is:

python -m pip install "codenib[mcp]==0.2.3"
codenib index /path/to/repository --preset fast

Add static navigation and dependency tools without an embedding download:

python -m pip install "codenib[graph,mcp]==0.2.3"
codenib toolchain install /path/to/repository --scope graph
codenib index /path/to/repository --preset graph

Each build writes a manifest below $CODENIB_HOME/repositories/<repo>-<id>/indexes (default ~/.codenib/repositories/...) and prints its exact path. A failed optional view is recorded in the manifest without invalidating successful independent views.

Run The Server¶

codenib mcp /path/to/repository

The command also accepts the manifest path directly:

codenib mcp ~/.codenib/repositories/<repo>-<id>/indexes/repo_manifest.json

Load a Published Artifact¶

A Pages publishing run can produce the same query-serving views once and reuse them in MCP at the indexed commit:

codenib artifact fetch owner/repository --repo /path/to/repository
codenib artifact mcp-config \
  ~/.codenib/artifacts/owner/repository/<full-commit> \
  --repo /path/to/repository \
  --host codex

artifact fetch derives the full commit from the checkout unless --commit is provided. It requires GH_TOKEN with Actions read access. The MCP process rechecks artifact hashes, repository identity, commit, and the filtered source fingerprint on every start; it does not rebuild or silently substitute a stale view. See Publish With GitHub Pages for the trust boundary and Claude/generic configuration options.

Transport is stdio and logs go to stderr. A typical client configuration is:

{
  "mcpServers": {
    "codenib": {
      "command": "codenib",
      "args": ["mcp", "/absolute/path/to/repository"]
    }
  }
}

Use an absolute repository path because the client may launch the server from a different working directory.

Tool Surfaces¶

The default --tool-surface full preserves the complete, compatible tool list and accepts existing calls unchanged. The bounded exploration surface is selected explicitly:

codenib mcp /path/to/repository --tool-surface explore

With --tool-surface explore, the server lists and accepts only explore_context; direct calls to tools hidden by that surface are rejected. Each stdio connection has its own runtime state, so reconnecting starts a fresh exploration ledger.

MCP Registry¶

CodeNib publishes its local stdio server as ai.codenib/codenib in the official MCP Registry. Registry clients request one required value: the absolute path to a repository previously indexed with codenib index. The declared launch is equivalent to:

uvx --with "codenib[mcp]==0.2.3" \
  "codenib==0.2.3" mcp /absolute/path/to/repository

The Registry path is intentionally query-only and model-free. It can always serve the persisted BM25 view without downloading an embedding model. Use the normal client configuration above from an environment with semantic or graph installed when those richer persisted views are required.

Tools¶

Only tools whose backing views are fresh and available can return results.

Tool	Backing view	Granularity	Use for
`explore_context`	available retrieval, LSP route, `symbol_graph`, and verified checkout	grouped source windows	Bounded retrieval, navigation, dependencies, and source in one call
`search_context`	available `bm25`, `vector`, and `symbol_graph` views	file/symbol	Recommended planned ranked search; reports the selected route and source identity
`search_semantic`	`vector`	file/symbol (L0/L2)	Natural-language or conceptual queries
`search_bm25`	`bm25`	symbol	Exact names and keyword lookups
`search_regex`	`symbol_graph`	file / symbol	Structural pattern matching
`search_zoekt`	`zoekt`	file	Fast substring or regex search over files
`dependency_subgraph`	`symbol_graph`	call graph	Caller impact, callee dependencies, or a one-hop neighborhood
`lsp_definition`	runtime LSP provider or `symbol_graph` fallback	location	Static go-to-definition-shaped lookup
`lsp_references`	runtime LSP provider or `symbol_graph` fallback	locations	Static find-references-shaped lookup
`lsp_route`	runtime LSP provider or `symbol_graph` fallback	locations	Compact route anchors from symbol seeds or a bounded query fallback
`read_source`	verified checkout	source window	Read an exact 1-based span after retrieval or navigation
`get_manifest`	manifest	repository	Repository identity, languages, view states, and capabilities

All source locations returned by MCP use 1-based line numbers. Search tools reject blank query text, cap it at 16,000 characters, and accept top_k values from 1 through 100.

explore_context accepts a query, optional symbol seeds, a bounded top_k, a fast/balanced/thorough budget, dependency direction, and test/dependency filters. It combines ranked retrieval, the selected LSP route, dependency subgraphs, and verified live-source windows. The response identifies the route provider and source binding explicitly. Missing or failed retrieval, route, dependency, or source providers degrade independently and add bounded diagnostics; unverified indexed excerpts remain marked verified: false instead of being presented as checkout source.

Each complete serialized explore_context MCP CallToolResult has a hard 256 KiB (262,144-byte) ceiling. Accounting includes the structured and text forms, and payload projection reserves room for the result/protocol envelope. The limit therefore does not grant 256 KiB to source content alone.

Within each independent stdio connection, the runtime ledger remembers at most 160 verified source ranges. A repeated identical range may use a stable source_call pointer to the call that supplied its body; unverified indexed excerpts are not deduplicated. Response summaries expose current ledger usage, deduplication, and eviction counts.

Call lsp_route with symbols=[] and a non-blank query when no reliable symbol is known. This best-effort fallback examines at most 10,000 graph nodes, retains at most 256 query matches and 512 expanded candidates, and stops after 100 milliseconds.

In 0.2.2 every manifest-bound C/C++ checkout uses the verified persisted symbol graph. Project-local clangd .idx files often live below the default-excluded build/ tree and do not yet carry an authenticated generation receipt plus allowed-file proof, so the server does not reuse them directly. This is a fail-closed query-time boundary, not a removal of C/C++ graph indexing. LSP result rows identify the backend, fallback reason, capabilities, and snapshot when provider metadata is available; get_manifest.runtime.lsp_provider reports the same persisted-graph selection before a result is returned.

search_context accepts query, top_k (1-100), budget (fast, balanced, or thorough), dense level (l0 or l2), and filter_test. Its response separates the selected plan, indexed source (repository, commit, and source fingerprint), and ranked results. It never silently labels a sparse fallback as hybrid or graph-expanded execution. Across all search tools, ranked metadata is retained while source bodies share a 10,000-character response budget. Projected hits report original and returned character counts under content_projection. Path and symbol fields have separate limits and report pathological truncation under metadata_projection. read_source accepts a repository-relative POSIX path and a 1-based inclusive range of at most 200 lines; it returns at most 16,000 characters with commit and source-fingerprint provenance. Source reads remain disabled when startup cannot verify the checkout against its manifest or portable-artifact binding.

The codenib-guide prompt explains how to choose among available tools. Parameter and return schemas live in codenib/mcp/README.md.

Advanced Views¶

The full preset requests BM25, vectors, a symbol graph, and Zoekt:

python -m pip install "codenib[full]==0.2.3"
codenib toolchain install /path/to/repository --scope graph
codenib index /path/to/repository --preset full

This succeeds only with the default source selection, an immutable commit tree that exactly matches the authenticated checkout, and no tracked path rejected by the default policy. A non-empty custom exclusion set, or a tracked default-excluded path, makes the Zoekt build fail closed; see the CodeGraph source-surface boundary.

Graph and Zoekt construction also require external backend binaries. Check the repository's language-specific graph provider before building:

codenib doctor /path/to/repository --require graph

The doctor command does not currently diagnose Zoekt. Verify both Zoekt commands independently:

command -v zoekt-git-index
command -v zoekt-webserver

In 0.2.2 authenticated search_zoekt serving is Linux-only. The runtime keeps the verified shard generation open and gives zoekt-webserver a /proc descriptor path; macOS and Windows fail closed rather than reopen the mutable published directory.

See SCIP Indexing and Language Capabilities for backend-specific setup and support boundaries.