Knowledge Base MCP Server

This MCP server provides tools for listing and retrieving content from different knowledge bases.

Demo

Real output, no mock data: the capture drives the kb CLI against a small knowledge base seeded from this repo's own docs/, indexed with the default Ollama embedding model. Regenerate it with docs/assets/record-demo.sh.

<a href="https://glama.ai/mcp/servers/n0p6v0o0a4">

</a>

Setup Instructions

These instructions assume you have Node.js (version 20 or higher) and npm installed on your system.

Install (one command)

npx -y @jeanibarz/knowledge-base-mcp-server@latest

npx fetches the package from npm and launches the stdio server. Point your MCP client at npx -y @jeanibarz/knowledge-base-mcp-server@latest and configure the environment variables documented below. See docs/clients.md for copy-pasteable snippets (Claude Desktop, Codex CLI, Cursor, Continue, Cline).

> Pin @latest, not the unversioned spec. npx -y @jeanibarz/knowledge-base-mcp-server (no version) caches the resolved version in ~/.npm/_npx/ indefinitely — subsequent client launches reuse that cached version even after a new release ships. The @latest form hashes to a different cache key and re-resolves on every launch, so new fixes arrive on the next client restart instead of requiring a manual ~/.npm/_npx/ clear. See RFC 012 §2.4.

Install (CLI alongside the MCP server, RFC 012)

For an interactive shell or AI-agent shell-tool flow, install globally and use the kb bin directly. The OS resolves the binary on every invocation, so npm i -g …@latest is picked up without restarting any AI client that has the MCP server loaded:

npm install -g @jeanibarz/knowledge-base-mcp-server@latest
kb list                       # list available knowledge bases
kb stats                      # read-only index/corpus stats
kb search "your query"                       # read-only dense search
kb search "your query" --timing              # include retrieval-stage timings
kb search "your query" --format=compact      # one-line-per-hit operator table (#446)
printf '{"query":"q1"}\n{"query":"q2"}\n' | kb search --batch-jsonl  # batched JSONL stdin (#440)
kb search "query" --refresh                  # also re-scan KB files (write path)
kb search "query" --explain-empty            # opt-in deep diagnostics when results are empty (#328)
kb search "INDEX_NOT_INITIALIZED" --mode=lexical --refresh   # BM25 debug surface (#206 stage 1)
kb search "retrieval benchmarks" --mode=lexical --lexical-unit=source  # source-level BM25
kb search "INDEX_NOT_INITIALIZED" --mode=hybrid              # dense ⨁ BM25 fused via RRF (#206 stage 2)
kb search "src/cli-search.ts" --mode=auto    # opt-in heuristic: hybrid for code/path/error-shaped queries
kb search "runbook rollback" --context-window=1  # include adjacent chunks around dense hits
kb search "agent evidence" --diverse --format=json           # source-aware representative sampling
kb search "agent evidence" --anti-query="frontend styling"   # contrastive, positive-support constrained
kb search "queue debt" --plus="slow loop" --minus="UI layout" --format=json
kb open alpha/docs/deploy.md#L42-L78         # resolve a chunk id / kb:// URI / result path to its source file
kb related alpha/docs/deploy.md#L42-L78      # find dense neighbors from an existing result chunk
kb llm use-endpoint http://127.0.0.1:8080/v1/chat/completions --profile=local-research-agent
kb ask "what changed in the daemonization notes?" --timing   # retrieval + local LLM answer with timings
kb ask "why does src/cli.ts throw?" --mode=hybrid --rerank   # same dense|hybrid|lexical|auto modes + opt-in rerank as kb search
kb ask "what changed?" --kb=work --save-transcript --title="Ask - daemon changes" --yes
kb research plan "autonomous research agents and evals" --format=json
kb research collect "autonomous research agents and evals" --run-dir runs/agents --format=json
kb remember --suggest --kb=work --title="Quarterly plan"
printf '# Quarterly plan\n\n...' | kb remember --kb=work --title="Quarterly plan" --stdin --yes
printf '\nFollow-up note.\n' | kb remember --kb=work --append=quarterly-plan.md --stdin --yes
kb import-url --kb=research https://example.com/article   # snapshot a URL into a provenance-tagged note
kb superseded --kb=work       # read-only review for obsolete/contradicted notes
kb tags --kb=work             # read-only: list frontmatter facet values (tags/status/type) with counts
kb tags --facet=status --format=json  # discover the vocabulary for kb search --status filters
kb tag work/runbooks/deploy.md --add=verified  # dry-run; add --yes to apply the tag change
kb feedback add --kb=work --query="rollback procedure" --source=runbooks/deploy.md --verdict=relevant
kb feedback promote --kb=work --query="rollback procedure" --fixture=docs/testing/feedback-fixture.yml --yes  # promote ledger entries into an eval fixture
kb eval retrieval-eval.yml     # run fixture-driven retrieval checks
kb eval-gate docs/testing/fixtures/rfc-018-gate-eval/queries.yml  # RFC 018 gate validation harness
kb reindex --with-context     # rebuild the FAISS index with RFC 017 contextual prefaces
kb reindex status --format=json  # ledger of recent / in-flight reindex passes (#417)
kb logs show --request-id=<id>     # read canonical request logs by id (#397)
kb logs recent --limit=20 --format=json  # most recent canonical log entries
kb diagnose --request-id=<id> --repro-bundle=/tmp/kb-diag  # package redacted canonical log context
kb serve                      # start the loopback CLI daemon (warm reads); add --warm to pre-load active indexes
kb serve status               # daemon liveness + degraded-mode diagnostics (#420)
kb config validate            # static env-var schema validation before startup
kb doctor                     # availability snapshot (index, embedding backend, LLM)
kb doctor --endpoints         # focused MCP/daemon/Ollama/LLM endpoint preflight
kb doctor --locks             # write-lock owner and stale-lock diagnosis
kb doctor --kb-symlinks       # inventory KB-root symlinks and escaping targets
kb doctor --bug-report=/tmp   # write a redacted support bundle for issue reports
kb --help                     # top-level command list
kb help search                # per-command help (also: kb search --help)
kb completion bash|zsh|fish   # generate a shell completion script (bash, zsh, or fish)
kb cite alpha/docs/deploy.md  # export BibTeX or CSL-JSON from note frontmatter
kb cache list                 # inspect local cache surfaces
kb cache prune                # prune stale cache entries
kb explain "rollback procedure" --kb=work  # verbose single-query retrieval trace for debugging
kb verify                     # run slow integrity checks for persisted indexes and sidecars
kb where "observability stack" # recommend the best KB and file for a given topic
kb stale-check --kb=work      # scan markdown notes for path / URL references that no longer resolve
kb promote alpha/docs/deploy.md  # review and update lifecycle frontmatter on a KB note
kb quarantine list --kb=work  # inspect and manage per-file ingest quarantine entries

The kb bin shares the same env vars as the MCP server (KNOWLEDGE_BASES_ROOT_DIR, FAISS_INDEX_PATH, EMBEDDING_PROVIDER, OLLAMA_, OPENAI_, HUGGINGFACE_*). The consolidated operator matrix for retrieval flags, defaults, per-call overrides, rollout status, and validation commands lives in docs/feature-flags.md. kb stats [--kb=<name>] [--format=md|json|csv|tsv|ndjson|openmetrics] mirrors the MCP kb_stats payload for local shell use: per-KB file/chunk/byte counts, last indexed time, embedding model, index path, version context, filesystem enumeration failure diagnostics, process-lifetime chat-completion call/error/latency/token counters, bounded provider/coarse-model attribution, attempt/retry totals, workflow cache outcomes, answer impact, contextual-preface cache/failure counters (when RFC 017 ingest is enabled), and remote-transport request/auth/backoff counters (when the HTTP or SSE transport is active). It is read-only and does not refresh the index. kb search also defaults to read-only dense retrieval — it loads the existing FAISS index but does not re-scan KB files. Pass --refresh to re-index. Use --mode=hybrid for explicit dense+BM25 rank fusion, or --mode=auto to keep dense for prose queries while selecting hybrid for code, path, flag, error-code, and issue-reference shaped queries. Dense-only neighbor context flags (--context-before, --context-after, --context-window) attach adjacent chunks from the same source around each ranked semantic match; see docs/search-neighbor-context.md for examples, JSON shape, and tradeoffs. Exploration operators stay additive and read-only: --diverse reranks a bounded dense candidate pool for source-aware representative coverage; --anti-query=<text> penalizes candidates close to a negative query but only among positively supported candidates; --plus=<text> and --minus=<text> add vector-composition-style positive and negative query components. JSON output includes an advanced_retrieval explanation block with mode, constraints, query components, and per-result scoring signals. Add --timing to kb search or kb ask when you need per-stage elapsed milliseconds in either markdown or JSON output. --format=compact collapses each result to a single score|kb|path:line line for terse operator listings; --batch-jsonl reads {"query":"…","kb":"…","k":N} records from stdin and emits one JSON result envelope per line. Search output includes a freshness footer indicating whether the index is up-to-date relative to KB file mtimes.

kb config validate also checks static cross-variable constraints before startup. In particular, KB_CHUNK_OVERLAP must be strictly less than KB_CHUNK_SIZE; kb doctor reports the same configuration finding and exits non-zero when the pair is invalid.

Research evidence packets for agents

kb research is a read-only workflow for agent shells that need a broad evidence pass before writing an answer, RFC, eval plan, or issue. It does not call an LLM, trigger local-research-agent, refresh indexes, or write KB notes.

Run plan first to inspect the deterministic shelf/query plan, then run collect with a run directory:

kb research plan "synthesize an end-to-end approach for autonomous research agents and evals" --format=json
kb research collect "synthesize an end-to-end approach for autonomous research agents and evals" \
  --run-dir /tmp/kb-research-autonomous-agents-evals-20260521 \
  --format=json

After collect, read the generated evidence_packet.md and synthesize manually. The run directory also contains run.json, plan.json, ledger.json, and events.jsonl; ledger.json stays lossless for audit/debug use, while evidence_packet.md is the human-scannable packet. The JSON contract and stable artifact fields are documented in docs/cli-json-contracts.md; a longer operator walk-through (when to use it, how to read the packet, downstream kb ask + kb feedback plumbing) lives in docs/operations/research-workflow.md.

For local day-two operations with Ollama, llama-server, n8n, systemd user
units, remote MCP transports, or kb serve, see the
local service operations runbook. For
active incidents, start with the symptom-keyed
incident response runbook.

RFC 018 relevance gating is off by default. Enable it per process with KB_RELEVANCE_GATE=on, or per CLI call with kb search --gate; bypass an enabled process with --no-gate or MCP gate: "off". The judge uses --task-context=<text> / --task-context-file=<path> or MCP task_context, and reads KB_GATE_LLM_ENDPOINT / KB_GATE_LLM_MODEL (falling back to KB_LLM_ENDPOINT / KB_LLM_MODEL). Tuning env vars are KB_GATE_SCORE_FLOOR (default 0.95), KB_GATE_JUDGE_INPUT (default 10), KB_GATE_LLM_TIMEOUT_MS (default 8000), and KB_GATE_MIN_TASK_TOKENS (default 8). KB_GATE_EMPTY_VERDICT defaults to off; turn it on only when you are comfortable letting the gate return no retrieved context.

Cross-encoder reranking (RFC 019, off by default). After the initial dense (or hybrid) retrieval stage, an optional cross-encoder reranking pass reorders the top-N candidates using a more precise model. It improves precision at a small latency cost. Enable it with KB_RERANK=on. Tuning env vars:

| Env var | Description | Default |
| --- | --- | --- |
| KB_RERANK | Enable the cross-encoder reranking stage. | off |
| KB_RERANK_MODEL | Cross-encoder model id used for reranking. | (built-in default) |
| KB_RERANK_TOP_N | How many top candidates to feed into the reranker. | (built-in default) |
| KB_RERANK_SKIP_DOMAINS | Comma-separated KB domain names to skip reranking for. | (none) |