javdet/nib-kb repository overview

⁠NIB — knowledge base (MCP server)

Knowledge-base server for NIB (Neuro Infrastructure Builder), speaking the Model Context Protocol. It stores your infrastructure documentation in PostgreSQL with pgvector, embeds it through an OpenAI-compatible /embeddings endpoint, and answers semantic search queries from any MCP client — the NIB agent, or your own.

The point is specificity. A planning agent that knows the general shape of Kubernetes still cannot tell you which cluster your staging ingress lives on, which registry your images come from, or why that one service is pinned to an old node pool. This is where that knowledge goes, and how the agent retrieves it while planning.

It is one of four images: nib-kb (this one), nib-backend⁠ (API and agent orchestrator), nib-frontend⁠ (web UI) and nib-agent⁠ (the coding-agent runner).

⁠The MCP interface

The server exposes one tool:

knowledge_search — embeds a natural-language query and returns the closest kb_chunks rows from the named collection, by cosine similarity in pgvector.

Two transports:

• streamable HTTP — -transport http -http-addr :8081 -http-path /mcp (the image default), for clients that connect over the network. Add -http-stateless to run without session tracking.
• stdio — -transport stdio, for a client that spawns the binary as a child process.

Inside NIB the agent reaches this over the internal network at http://kb-mcp:8081/mcp, registered as an MCP server in data/mcp.json. Alongside search, NIB agents read the current source document with get_kb_document and write a collection back with update_kb (those tools live in the backend); the build-knowledge-base skill drives the whole round trip — hand it a project name and a list of repositories and it fills the shipped skeleton in from what the repositories actually say, rather than from what someone remembered to write down last year.

⁠Quick start

docker run -d --name nib-kb \
  -p 8081:8081 \
  -e DATABASE_URL='postgres://nib:nib@postgres:5432/nib?sslmode=disable' \
  -e OPENROUTER_API_KEY="$LLM_API_KEY" \
  -e EMBEDDINGS_BASE_URL=https://api.openai.com/v1 \
  javdet/nib-kb:latest

MCP endpoint: http://<host>:8081/mcp. The database must have the pgvector extension available; the NIB backend creates and migrates the schema.

The whole stack comes up together with the repository's Compose file or Helm chart — see nib-backend⁠.

⁠Configuration

⁠Environment

Despite the name, -provider openrouter is the CLI's label for any OpenAI-compatible /embeddings client — OpenAI itself, OpenRouter, or a self-hosted gateway. Point EMBEDDINGS_BASE_URL wherever you like. -provider google selects the Generative Language API instead.

⁠kb serve-mcp flags

The image's default command is:

kb serve-mcp -transport http -http-addr :8081 -http-path /mcp

Override it with command: in Compose or args: in Kubernetes.

⁠Ingesting documents

The same binary ingests. It chunks the input, embeds each chunk in batches, and writes kb_collections / kb_chunks:

docker run --rm -i \
  -e DATABASE_URL='postgres://nib:nib@postgres:5432/nib?sslmode=disable' \
  -e OPENROUTER_API_KEY="$LLM_API_KEY" \
  -e EMBEDDINGS_BASE_URL=https://api.openai.com/v1 \
  --entrypoint kb javdet/nib-kb:latest \
  ingest -collection myproject -model text-embedding-3-small -replace < runbook.md

Files are passed as arguments, or the text is piped on stdin. In normal NIB use you do not run this by hand: the UI and the build-knowledge-base skill drive ingestion for you.

⁠Image contents

• A single static Go binary (CGO_ENABLED=0) on gcr.io/distroless/static-debian12:nonroot.
• Runs as nonroot:nonroot. No shell, no package manager, no busybox — the attack surface is the binary and nothing else. Worth knowing before you plan to docker exec into it: you cannot.
• Ships CA certificates (HTTPS to the embedding provider), tzdata and a nonroot passwd entry.
• Cross-compiled natively per target architecture, so the arm64 image is built without QEMU.
• Exposes port 8081. No healthcheck is baked in — the MCP endpoint expects a protocol handshake rather than a plain GET, so probe it at the TCP level (a Kubernetes tcpSocket probe on 8081).

⁠Tags and platforms

latest · vX.Y.Z (release, matching the repository's VERSION file) · <git-sha> (exact commit). Built for linux/amd64 and linux/arm64.

Pin vX.Y.Z in production and keep backend, frontend and kb on the same tag — they are released together from one repository and share the database schema.

⁠Links and licence

• Source, documentation and issues: https://github.com/javdet/nib⁠
• Knowledge-base documentation: docs/knowledgebase/ in the repository
• Licence: Nib Non-Commercial License 1.0 (MIT-based, with attribution and a non-commercial-use restriction). Read LICENSE before deploying this in a commercial setting.