Knowledge Base Mcp Server

Knowledge Base MCP Server

[](https://github.com/jeanibarz/knowledge-base-mcp-server/actions/workflows/test.yml) [](https://www.npmjs.com/package/@jeanibarz/knowledge-base-mcp-server) [](./UNLICENSE) [](./package.json)

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](docs/assets/record-demo.sh).

[](https://smithery.ai/server/@jeanibarz/knowledge-base-mcp-server)

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](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 "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 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=     # read canonical request logs by id (#397)
kb logs recent --limit=20 --format=json  # most recent canonical log entries
kb diagnose --request-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](docs/feature-flags.md). kb stats [--kb=] [--format=md|json] 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, 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](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= penalizes candidates close to a negative query but only among positively supported candidates; --plus= and --minus= 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.

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](docs/cli-json-contracts.md#kb-research); 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](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](docs/operations/local-services.md). For active incidents, start with the symptom-keyed [incident response runbook](docs/operations/incident-response.md).

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= / --task-context-file= 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) |

Note: KB_RERANK_DEVICE (e.g. cuda, cpu) is an external ONNX Runtime / Transformers.js runtime knob — set it in the shell environment when you want GPU acceleration, but it is not a KB config option and is not validated by kb config validate.

kb search --format=vimgrep prints one quickfix-compatible line per result: path:line:col:preview. JSON results include a stable chunk_id such as alpha/docs/deploy.md#L42-L78 when chunk metadata has a KB, path, and line range; chunks without line metadata fall back to #chunk-N. Set KB_EDITOR_URI=vscode, cursor, or file to add opt-in absolute-path editor_uri fields and markdown Open links. The default KB_EDITOR_URI=none omits local absolute paths. kb open resolves any of those pointers back to the absolute source path, validated against the KB root; it is read-only and prints the path (add --json for the cited line range and an editorUri). kb related retrieves an indexed seed chunk from that handle, runs dense search with the seed text, and excludes the seed chunk unless --include-self is passed.

kb remember is a conservative CLI write path for agent shells. --suggest lists likely existing targets from note filenames/headings, does not read stdin or write notes, and may update a small .index heading cache. Creates and appends require both --stdin and --yes; create uses a slugified .md filename and refuses overwrites, while append accepts only existing KB-relative paths. Plain EOF appends and kb capture --append serialize per target and commit through a temp-file fsync plus atomic rename. kb capture redacts common credentials from captured stdout and the displayed command line by default; pass --no-redact only when raw output is required. Add --refresh to re-index the affected KB after a successful write. For machine-readable command shapes, see [docs/cli-json-contracts.md](docs/cli-json-contracts.md).

kb import-url --kb= snapshots a web page or PDF into one new KB note while preserving provenance. It fetches the URL over http(s), routes HTML and PDF responses through the same loaders the indexer uses, and writes a note whose YAML frontmatter records source_url, fetched_at, content_sha256, content_type, http_status, and byte_count. The fetch is guarded: only http/https schemes are allowed, redirects are followed manually and re-validated per hop (--max-redirects, default 5), responses are size-capped (--max-bytes, default 8 MiB) and time-bounded (--timeout, default 30000 ms), and private/loopback/link-local addresses are refused unless --allow-local-network is passed (SSRF guard). The note path defaults to a slug of the page title; pass --note= to choose it, --title to override the title, and --refresh to re-index afterwards. It refuses to overwrite an existing note.

kb superseded --kb= is a read-only active-forgetting review. It scans markdown frontmatter for explicit contradiction, deprecated/dormant lifecycle status, stale verification dates, and low-confidence active notes, then uses the existing semantic index to add conservative newer-neighbor evidence when available. Use --format=json for agent workflows and --include-clean when you need a full inventory.

kb feedback add --kb= --query="" --source= --verdict=relevant|irrelevant|stale|misleading [--relevance=0..3] [--chunk-id=] appends a relevance judgment to the per-KB ledger (/.index/relevance-feedback.jsonl). kb feedback list --kb= reviews recent entries, and `kb feedback promote --kb=

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jeanibarz
• Source: jeanibarz/knowledge-base-mcp-server
• License: Unlicense

Install and usage instructions live in the source repository linked above.