NCI
Agent Integration

Drop NCI into the loop

An agent loop is small: think, call a tool, read the result, respond. NCI is the tool you wire in for type-aware questions about the user’s actual installed packages. The MCP server (nci-mcp) exposes exactly two tools — nci_query and nci_sql — and three resources.

A single tick of the loop

ThoughtI need the shape of zod's ZodObject

The user asked for an object schema. I should look up ZodObject in their installed version of zod before I write a snippet — and pin the exact package_version.

The model deliberates for a tick, calls nci_query with a discriminated subcommand, reads the JSON envelope, then keeps going. NCI’s job is to make that one structured call return a useful answer fast.

What the agent calls

There is no general-purpose “ask” tool. nci_query is a discriminated union — every shape is one CLI subcommand:

  • subcommand: "active_package" — resolve which installed version is live in the project tree.
  • subcommand: "evidence" — exact-name hits + FTS phrase fallback + batched signature / js_doc snippets, all in one round-trip.
  • subcommand: "find" | "symbol" — narrower fall-backs for a single anchor.
  • subcommand: "show" | "snippet" | "overloads" — drill in on a specific symbols.id.
  • subcommand: "packages" | "package_versions" | "package_deps" | "source_packages" | "symbols" — listings for orientation.

nci_sql is the escape hatch for read-only relational checks. Mutating SQL is rejected before it reaches the database.

The agent primer

nci-mcp advertises three resources. The first, nci://primer/agent, is the operating manual a fresh agent reads before its first call. You can read it directly at Agent primer.

Why this beats RAG for code

nci

That output is exact. There is no embedding, no nearest-neighbour, no top-k tradeoff: you asked for one symbol id, you got that symbol’s stored signature and js_doc. The full comparison is at Local index vs. RAG.

Wiring up