Metadata-Version: 2.4
Name: kb-agent-mcp
Version: 0.1.2
Summary: A zero-config MCP server that turns any folder of documents into a queryable multi-agent knowledge base
Author: KnowledgeBase Agent Contributors
License-Expression: MIT
Keywords: mcp,ai,knowledge-base,rag,agents,llm
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: chromadb>=0.5.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: numpy>=1.26.0
Requires-Dist: scikit-learn>=1.4.0
Requires-Dist: watchdog>=4.0.0
Requires-Dist: pypdf>=4.0.0
Requires-Dist: python-pptx>=1.0.0
Requires-Dist: openpyxl>=3.1.0
Requires-Dist: python-docx>=1.1.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: sentence-transformers>=3.0.0
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.30.0; extra == "anthropic"
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: pytest-mock>=3.14.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"

# 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

```bash
# 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

```bash
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 all ChromaDB indexes |
| `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")
```

---

## Configuration

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

```env
# 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:

```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):
```env
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:

```yaml
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-generate flags

```bash
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

```bash
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`:

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

---

## 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:

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

---

## 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

```bash
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.

---

## License

MIT
