# MCP Knowledge Base Server

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that
gives AI assistants — Claude Desktop, Cursor, or any MCP client — searchable,
structured access to a company's **internal knowledge base** of Markdown
documents.

Ask your assistant *"how do I deploy to production?"* or *"how many vacation
days do I get?"* and it will search the knowledge base, read the relevant
articles, and answer with citations — instead of hallucinating your internal
processes.

## Features

- **6 tools** — keyword search with snippets, full-document fetch, filtered
  listing, tag browsing, hot reload, and stats
- **2 resource types** — browse the whole index or any document directly
  (`kb://index`, `kb://documents/{doc_id}`)
- **1 prompt template** — `answer_from_knowledge_base` grounds answers in
  search results and forces citations
- **Zero-infrastructure** — the knowledge base is just a folder of `.md`
  files with optional frontmatter; works great backed by a Git repo
- **Two transports** — stdio for local clients, HTTP for shared/remote setups
- **Dependency-light** — FastMCP + a small built-in TF-IDF-style index; no
  database, no embeddings service required

## Architecture

```
┌─────────────────┐   stdio / HTTP (JSON-RPC)   ┌──────────────────────────┐
│  MCP client     │ ───────────────────────────▶ │  FastMCP server          │
│  (Claude, …)    │ ◀─────────────────────────── │  ├─ tools (search, get…) │
└─────────────────┘                              │  ├─ resources (kb://…)   │
                                                 │  └─ prompts (answer…)   │
                                                 │          │             │
                                                 │  KnowledgeBaseIndex    │
                                                 │  (tokenize → TF-IDF)   │
                                                 └──────────┬─────────────┘
                                                            │ scans
                                                 ┌──────────▼─────────────┐
                                                 │ knowledge_base/        │
                                                 │  engineering/*.md      │
                                                 │  hr/*.md  product/*.md │
                                                 └────────────────────────┘
```

## Quickstart

```bash
git clone <your-repo-url> mcp-knowledge-base-server
cd mcp-knowledge-base-server
pip install .
```

Point the server at your own docs (or use the included sample corpus):

```bash
export KB_DIR=/path/to/your/markdown/docs
```

### Run the demo

```bash
pip install fastmcp          # only dependency the demo needs
python examples/demo_client.py
```

The demo spawns the server over stdio and exercises every capability —
search, document fetch, listing, resources, and the grounded-answer prompt —
printing the exact JSON-RPC payloads a real client would see.

### Connect Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "knowledge-base": {
      "command": "python",
      "args": ["-m", "mcp_knowledge_base.server"],
      "env": {
        "PYTHONPATH": "/absolute/path/to/mcp-knowledge-base-server/src",
        "KB_DIR": "/absolute/path/to/mcp-knowledge-base-server/knowledge_base"
      }
    }
  }
}
```

Restart Claude Desktop, then ask: *"Search our knowledge base — what's the
rollback procedure if a deploy goes wrong?"*

### Run over HTTP (shared/remote setups)

```bash
KB_DIR=/path/to/docs mcp-knowledge-base --transport http --port 8000
# → streamable HTTP endpoint at http://127.0.0.1:8000/mcp
```

## Document format

Any folder of `.md` files works. Optional frontmatter enriches results:

```markdown
---
title: Deploying to Production
tags: [deploy, production, runbook]
department: engineering
updated: 2025-11-02
---

# Deploying to Production
…
```

The document `doc_id` is its path relative to `KB_DIR` without the extension
(e.g. `engineering/deploy-guide`). Title falls back to the first `#` heading,
then the filename.

## API reference

### Tools

| Tool | Description |
|------|-------------|
| `search_knowledge_base(query, limit=5, tag=None)` | Ranked keyword search; returns doc_id, title, tags, snippet, score |
| `get_document(doc_id)` | Full Markdown content + metadata of one article |
| `list_documents(tag=None, department=None)` | List all articles, optionally filtered |
| `list_tags()` | All tags with document counts |
| `reload_knowledge_base()` | Re-scan `KB_DIR` to pick up edits |
| `stats()` | Document count, tag count, index age |

### Resources

| URI | Description |
|-----|-------------|
| `kb://index` | Human-readable index of every document |
| `kb://documents/{doc_id}` | Full content of one document |

### Prompts

| Prompt | Description |
|--------|-------------|
| `answer_from_knowledge_base(question)` | Searches the KB, then instructs the model to answer only from the excerpts and cite doc_ids |

### Environment variables

| Variable | Default | Description |
|----------|---------|-------------|
| `KB_DIR` | `./knowledge_base` | Root folder of Markdown documents |
| `KB_NAME` | `Company Knowledge Base` | Server name shown to MCP clients |

## Project structure

```
├── knowledge_base/            # sample corpus (replace with your own)
│   ├── engineering/*.md
│   ├── hr/*.md
│   └── product/*.md
├── src/mcp_knowledge_base/
│   ├── server.py              # FastMCP server: tools, resources, prompts
│   └── index.py               # document loading + TF-IDF-style search
├── examples/
│   └── demo_client.py         # end-to-end demo over stdio
└── pyproject.toml
```

## Extending it

- **Better search**: swap `KnowledgeBaseIndex` for embeddings + a vector DB
  (the tool interface stays identical).
- **Other sources**: index Confluence/Notion exports — anything that ends up
  as Markdown works unchanged.
- **Freshness**: run `reload_knowledge_base` on a schedule, or watch `KB_DIR`
  with a filesystem watcher.

## License

MIT — see [LICENSE](LICENSE).