kb-agent-mcp 0.1.3

A zero-config MCP server that turns any folder of documents into a queryable multi-agent knowledge base

kb-agent-mcp

A zero-config pip-installable MCP server that turns any folder of documents into a queryable, multi-agent knowledge base.

Connect it to Claude Desktop, Bob, Cursor, or any MCP-compatible AI tool — then ask questions in natural language.

---

Features

• Zero configuration — point at a folder, run one command, start asking questions
• Multi-domain routing — automatically routes questions to the right knowledge domain
• README-first RAG — uses compact AUTO-INDEX blocks for fast answers; falls back to full-document search for complex/data questions
• Passthrough mode — works with no local LLM; your AI tool answers using retrieved context
• Supports all major document types — PDF, DOCX, XLSX (with streaming aggregation for large files), PPTX, MD, TXT, CSV, BoxNote
• ChromaDB vector search — persistent, hash-based change detection (only re-indexes changed files)
• Multi-session memory — per-session conversation history with configurable timeout
• Hot-reload — kb-agent-watch keeps indexes in sync as you add/modify files
• LLM providers — Ollama (local), OpenAI, Anthropic, any OpenAI-compatible endpoint

---

Quick Start

# Install
pip install kb-agent-mcp

# Run the setup wizard
cd /path/to/your/documents
kb-agent-setup

# Or manually: generate indexes and domain configs
kb-agent-generate

# Start the MCP server (stdio — for Claude Desktop / Bob)
kb-agent-serve

# Or HTTP/SSE
kb-agent-serve --transport http --port 8765

---

Installation

Build tools required on macOS and Linux. chromadb compiles native C++ bindings at install time. Without the right tools the pip install will fail with a cryptic compiler error.

• macOS: xcode-select --install
• Linux (Debian/Ubuntu): sudo apt install build-essential python3-dev
• Windows: No extra steps needed.

pip install kb-agent-mcp

# With OpenAI embeddings
pip install "kb-agent-mcp[openai]"

# With Anthropic
pip install "kb-agent-mcp[anthropic]"

# For development
pip install "kb-agent-mcp[dev]"

Requires Python 3.10+.

---

MCP Tools

Once the server is running, the following tools are available:

Tool	Description
ask(question, format?, session_id?)	Query all relevant domains and return a markdown answer
list_domains()	List indexed knowledge domains with descriptions
reindex()	Re-scan KB_ROOT and rebuild ChromaDB indexes. Note: New domain folders with no domain_config.yaml will not become queryable — run kb-agent-generate from the CLI first.
clear_memory(session_id?)	Clear conversation history for a session
show_memory(session_id?)	Show current session state and recent history

ask examples

ask("What is IBM ACE?")
ask("What is our Q3 revenue by product?", format="table")
ask("Explain the architecture of CP4I", format="bullets")
ask("How many deals closed last quarter?", session_id="my-session")

Session isolation: Omitting session_id uses the shared "default" session. All callers on the same server share this session — earlier questions affect later answers. For isolated conversations (multiple users, multiple windows), always pass a unique session_id per user or conversation thread.

---

Configuration

All configuration is via environment variables (or a .env file):

# Required
KB_ROOT=/path/to/your/KnowledgeBase

# LLM provider (default: ollama)
KB_LLM_PROVIDER=ollama          # ollama | openai | anthropic | custom | passthrough
KB_LLM_BASE_URL=http://localhost:11434
KB_MODEL=qwen3:14b
KB_API_KEY=                     # required for openai/anthropic/custom

# Embeddings
KB_EMBED_MODEL=                 # auto-detected from provider; or set explicitly

# Context budgets (chars, ~4 chars = 1 token)
KB_BUDGET_TOTAL=24000
KB_BUDGET_INDEX=8000
KB_BUDGET_FULL_README=24000
KB_BUDGET_RAG_FILE=4000

# Session memory
KB_SESSION_TIMEOUT_HOURS=2
KB_SESSION_MAX_TURNS=20
KB_SESSION_MAX_ANSWER_CHARS=400

# Ignore these top-level folders
KB_IGNORE_FOLDERS=archive,tmp

Passthrough mode

When KB_LLM_PROVIDER=passthrough (or when Ollama is unreachable and KB_PASSTHROUGH_FALLBACK is not false), the server automatically detects that no local LLM is available and returns the retrieved document context as clean markdown:

> **No local LLM detected.** Retrieved context is provided below —
> use it to answer the question.

### BizOps Agent
*Source: BizOps/Revenue.xlsx*

Q1 revenue: $1.2M
Q2 revenue: $1.5M

The calling AI tool (Claude, Bob, Cursor) receives this directly from the ask tool and can answer the question from the context — no special parsing or configuration needed on the client side.

To disable the automatic fallback (hard-fail instead):

KB_PASSTHROUGH_FALLBACK=false

This is the recommended mode for most users — no local model required.

---

Folder Structure

Each top-level folder under KB_ROOT becomes a knowledge domain:

~/KnowledgeBase/
  ACE Docs/          ← domain "ACE Docs"
    Installation.pdf
    API Reference.md
    domain_config.yaml   ← generated by kb-agent-generate
  BizOps/            ← domain "BizOps"
    Revenue.xlsx
    Won Deals.xlsx
    domain_config.yaml
  .kb_index/         ← ChromaDB + session memory (auto-created)
    chroma/
    session_memory/

Files in nested subfolders are indexed into their parent domain.

---

domain_config.yaml

Generated by kb-agent-generate, one per domain folder. Edit manually to tune the agent:

folder_name: BizOps
agent_name: BizOps Agent
description: Business operations — CP4I and ACE revenue, won deals, renewals
keywords:
  - revenue
  - quota
  - attainment
  - ACE
  - CP4I
top_n: 5
max_chars: 8000
system_prompt: |
  You are the BizOps Agent, a specialist in IBM APC region business data.
  CRITICAL: For revenue questions use only Revenue Report files (Rev Act @ PC column).
  Be concise, accurate, and cite the source file.
retrieval_rules:
  pin_files:
    - "*Revenue*.xlsx"      # always included for data questions
  boost_keywords:
    - revenue               # ranked to top of results
  question_classifier:
    data_patterns:
      - "\\brevenue\\b"     # regex → bypass README-first, use raw file content
    complex_patterns: []

---

CLI Commands

Command	Description
kb-agent-setup	Interactive setup wizard
kb-agent-generate	Build ChromaDB indexes + generate domain_config.yaml
kb-agent-serve	Start the MCP server
kb-agent-watch	Watch for file changes and auto-update indexes
kb-agent-doctor	Run a health checklist to diagnose problems

kb-agent-generate flags

kb-agent-generate               # incremental — skip unchanged
kb-agent-generate --force       # regenerate all domain_config.yaml files
kb-agent-generate --no-llm      # index only, use minimal YAML defaults
kb-agent-generate --domain Foo  # only process the "Foo" folder

kb-agent-serve flags

kb-agent-serve                           # stdio (Claude Desktop / Bob)
kb-agent-serve --transport http          # HTTP/SSE on port 8765
kb-agent-serve --transport http --port 9000
kb-agent-serve --version

---

Connecting to Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "knowledge-base": {
      "command": "kb-agent-serve",
      "env": {
        "KB_ROOT": "/path/to/your/KnowledgeBase"
      }
    }
  }
}

⚠ Two common gotchas:

1. KB_ROOT is required in the "env" block. Omitting it causes the server to index the wrong directory and return empty results for every query.
2. venv PATH: If kb-agent-serve is not found, replace "command": "kb-agent-serve" with the absolute path — run which kb-agent-serve or check the setup wizard output. See Troubleshooting for details.

---

Connecting to Bob

After running kb-agent-generate, a SKILL.md is auto-installed at:

~/.bob/skills/knowledgebase-agent/SKILL.md

Bob will automatically load it. Configure the server in your Bob MCP settings with:

{
  "command": "kb-agent-serve",
  "env": { "KB_ROOT": "/path/to/your/KnowledgeBase" }
}

⚠ Two common gotchas:

1. KB_ROOT is required in the "env" block. Omitting it causes the server to index the wrong directory and return empty results for every query.
2. venv PATH: If kb-agent-serve is not found, replace "command": "kb-agent-serve" with the absolute path — run which kb-agent-serve or check the setup wizard output. See Troubleshooting for details.

---

Backward Compatibility

This package (kb-agent-mcp) is built alongside the original agents/ and scripts/ system. Nothing in the existing codebase is modified. Both systems can run independently from the same KB_ROOT.

---

Development

git clone <this-repo>
cd KnowledgeBase
pip install -e ".[dev]"
pytest tests/ -q

---

Releasing

Merging to main triggers the CI/CD pipeline, which automatically:

1. Bumps the patch version in pyproject.toml (e.g. 0.1.0 → 0.1.1)
2. Commits the bump back to main with [skip ci] to prevent re-triggering
3. Builds the wheel + source distribution
4. Publishes to PyPI as kb-agent-mcp

For a minor or major version bump (e.g. 0.2.0 or 1.0.0), manually edit version in pyproject.toml in your PR before merging — CI will auto-bump the patch on top of it.

---

Troubleshooting

If something isn't working, run:

kb-agent-doctor

This command checks everything and prints a ✓ / ✗ report:

Check	What it verifies
Python version	3.10 or later
KB_ROOT set	env var present and directory exists
Domain folders	at least one non-ignored subfolder under KB_ROOT
domain_config.yaml	present per domain
ChromaDB index	non-empty collection per domain
Embedding model	all-MiniLM-L6-v2 cached on disk
LLM reachable	Ollama/OpenAI/Anthropic endpoint responds
kb-agent-serve on PATH	absolute path shown if in venv
Bob skill installed	~/.bob/skills/knowledgebase-agent/SKILL.md

Each failing item shows a one-line fix hint. Exit code 0 = healthy, 1 = fix needed.

Common issues

KB_ROOT not set — Add it to your MCP host config env block:

"env": { "KB_ROOT": "/absolute/path/to/your/KnowledgeBase" }

kb-agent-serve not found — If installed in a venv, use the absolute path:

which kb-agent-serve   # or: python -m kb_agent_mcp.server

Empty answers / no domains — Re-run kb-agent-generate after adding documents.

Stale index warning in answers — You've added files since the last index. Run:

kb-agent-generate

After upgrading (pip install -U kb-agent-mcp) — If queries fail or ChromaDB throws an error after an upgrade, the index format may be incompatible. Delete the index and rebuild:

rm -rf /path/to/your/KnowledgeBase/.kb_index
kb-agent-generate

---

License

MIT