knowledge-base-mcp-server: Instructions file for Claude Code

knowledge-base-mcp-server — Agent Instructions

Local-first knowledge-base MCP server and kb CLI backed by embedded FAISS indexes and pluggable embedding providers (HuggingFace, Ollama, or OpenAI).

Working on this repo

Build / test / run

npm install
npm run build          # tsc → build/index.js (chmod +x, stdio-executable)
npm test               # build + test:parallel (--maxWorkers=4) + test:serial (--runInBand) — must stay green
npm run dev            # node --watch --import tsx src/index.ts for iteration
node build/index.js    # runs the server over stdio (clients launch it this way)

Key architecture

• Transport: src/KnowledgeBaseServer.ts starts stdio by default and can opt into SSE or streamable HTTP via MCP_TRANSPORT. HTTP/SSE mode requires MCP_AUTH_TOKEN and defaults to loopback.
• MCP tool surface: tools are registered in KnowledgeBaseServer.registerTools(). Current tools include list_knowledge_bases, retrieve_knowledge, ask_knowledge, list_models, kb_stats, diff_index, find_related, list_facets, recommend_knowledge_base, export_citations, add_document, delete_document, and reindex_knowledge_base.
• CLI surface: src/cli.ts is the kb dispatcher. Command-specific behavior lives in src/cli-*.ts; shared command-independent logic belongs in *-core.ts helpers.
• Embeddings: FaissIndexManager is constructed for a concrete (provider, modelName) pair. Provider defaults come from EMBEDDING_PROVIDER plus provider-specific model env vars.
• Index layout: $FAISS_INDEX_PATH/active.txt selects a model id. Each model stores metadata and versioned FAISS data under $FAISS_INDEX_PATH/models/<model_id>/. See model-storage-layout.ts (paths, sentinel) and model-resolution.ts (active-model resolution) — they decide and enforce this layout, so read them before changing any index path.
• Indexing strategy: per-file SHA256 hashes and chunk manifests in <kb>/.index/ let a refresh skip content that has not changed, so re-indexing costs embedding calls only for what moved. To stop concurrent writers from corrupting an index, mutating refreshes take a per-model write lock and save new index versions atomically.
• Logging: logger.ts writes only to stderr (and optionally LOG_FILE). Writing to stdout corrupts the JSON-RPC stream — this is a landed bug, never reintroduce console.log inside the server process.