# 🧠 MCP Knowledge Base Server

A **Personal Knowledge Base** built as an MCP (Model Context Protocol) server in Python. Connect it to Claude Desktop, Claude Code, VS Code Copilot, Cursor, or any MCP-compatible client — and let your AI assistant manage your notes, tasks, and ideas.

This project teaches you the **three core MCP primitives** through a practical, useful application:

| Primitive | What It Is | Examples in This Project |
|-----------|-----------|------------------------|
| **Tools** | Functions the LLM can call | `add_note`, `search_notes`, `add_task`, `update_task`, `get_stats` |
| **Resources** | Data the LLM can browse | `kb://notes`, `kb://tasks`, `kb://stats` |
| **Prompts** | Reusable templates | `daily_review`, `weekly_planning`, `capture_learning` |

## Architecture

```
┌─────────────────────┐         stdio / SSE          ┌──────────────────────┐
│   MCP Client        │◄────────────────────────────►│  Knowledge Base      │
│   (Claude Desktop,  │    JSON-RPC 2.0 messages     │  MCP Server          │
│    Claude Code,     │                               │                      │
│    Cursor, etc.)    │                               │  ┌──────────────┐   │
│                     │    tools/call ──────────────►  │  │  12 Tools    │   │
│                     │    resources/read ──────────►  │  │  4 Resources │   │
│                     │    prompts/get ─────────────►  │  │  4 Prompts   │   │
└─────────────────────┘                               │  └──────┬───────┘   │
                                                      │         │           │
                                                      │  ┌──────▼───────┐   │
                                                      │  │   SQLite DB  │   │
                                                      │  │  + FTS5 idx  │   │
                                                      │  └──────────────┘   │
                                                      └──────────────────────┘
```

## Quick Start

### Prerequisites

- **Python 3.11+**
- **[uv](https://docs.astral.sh/uv/getting-started/installation/)** (modern Python package manager)

```bash
# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh
```

### 1. Clone & Install

```bash
cd mcp-knowledge-base

# Create virtual environment and install dependencies
uv venv
source .venv/bin/activate   # On Windows: .venv\Scripts\activate
uv sync
```

### 2. Verify It Works

```bash
uv run test_server.py
```

You should see all tests pass — tools, resources, and prompts all registering correctly.

### 3. Connect to an MCP Client

#### Option A: Claude Desktop

Edit your Claude Desktop config file:

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "knowledge-base": {
      "command": "uv",
      "args": [
        "--directory", "/FULL/PATH/TO/mcp-knowledge-base",
        "run", "server.py"
      ]
    }
  }
}
```

> ⚠️ Replace `/FULL/PATH/TO/mcp-knowledge-base` with the actual absolute path.

Restart Claude Desktop. You should see a 🔨 hammer icon in the chat input — click it to see all 12 tools.

#### Option B: Claude Code

```bash
# From the project directory
claude mcp add knowledge-base -- uv run server.py

# Or globally
claude mcp add --scope user knowledge-base -- uv --directory /FULL/PATH/TO/mcp-knowledge-base run server.py
```

Then in Claude Code, your knowledge base tools are available automatically.

#### Option C: Cursor / VS Code

Add to your `.cursor/mcp.json` or VS Code MCP settings:

```json
{
  "mcpServers": {
    "knowledge-base": {
      "command": "uv",
      "args": ["--directory", "/FULL/PATH/TO/mcp-knowledge-base", "run", "server.py"]
    }
  }
}
```

## What You Can Do

Once connected, try these conversations with Claude:

### Notes

> "Save a note about what I learned about MCP today — it uses JSON-RPC 2.0, has three primitives (tools, resources, prompts), and the Python SDK uses FastMCP for the high-level API."

> "Search my notes for anything about Python"

> "Show me all my notes tagged with 'learning'"

### Tasks

> "Add a task: Build a multi-agent system with CrewAI, high priority, due next Friday"

> "What are my urgent tasks?"

> "Mark task #3 as done"

### Prompts (Workflows)

> "Run my daily review" — triggers the `daily_review` prompt

> "Help me plan my week" — triggers `weekly_planning`

> "I want to capture what I learned about Docker" — triggers `capture_learning`

### Stats

> "Give me an overview of my knowledge base"

## Project Structure

```
mcp-knowledge-base/
├── server.py          # The MCP server — all tools, resources, prompts
├── test_server.py     # Test client to verify everything works
├── pyproject.toml     # Project config and dependencies
└── README.md          # You are here
```

Data is stored in `~/.mcp-knowledge-base/knowledge.db` (SQLite with FTS5 full-text search).

## Key Concepts You'll Learn

### 1. Tools (the most important primitive)

Tools are Python functions decorated with `@mcp.tool()`. The MCP SDK automatically generates the JSON schema from your type hints and docstrings:

```python
@mcp.tool()
def add_note(title: str, content: str, tags: list[str] | None = None) -> dict:
    """Create a new note in the knowledge base."""
    ...
```

The LLM sees this as a callable function with typed parameters. Good docstrings = better tool use.

### 2. Resources (browsable data)

Resources are URIs the LLM can read, like a file system:

```python
@mcp.resource("kb://notes/{note_id}")
def resource_single_note(note_id: int) -> str:
    """Full content of a specific note."""
    ...
```

### 3. Prompts (workflow templates)

Prompts are pre-written instructions that guide the LLM through multi-step workflows:

```python
@mcp.prompt()
def daily_review() -> str:
    """Generate a daily review of all open tasks and recent notes."""
    return "Please review my current tasks and recent notes..."
```

### 4. Full-Text Search with FTS5

SQLite's FTS5 extension gives you fast, relevance-ranked search across all your notes — no external search engine needed.

### 5. Transport Modes

- **stdio** (default): The client spawns the server as a subprocess. Used by Claude Desktop, Claude Code, Cursor.
- **SSE**: Server runs as an HTTP endpoint. Used by web-based clients.

## Extending This Project

Here are ideas to keep building:

1. **Add a `web_clip` tool** — save content from URLs as notes (use `httpx` + `BeautifulSoup`)
2. **Add reminders** — tasks with due dates that surface automatically
3. **Add note linking** — `[[wiki-style]]` links between notes
4. **Add export tools** — export notes as Markdown files or a PDF
5. **Add an embedding-based search** — use OpenAI/Anthropic embeddings for semantic search alongside FTS5
6. **Add OAuth** — protect your server when running over SSE (the June 2025 MCP spec update covers this)
7. **Deploy to the cloud** — run on Cloudflare Workers, Fly.io, or Railway with Streamable HTTP transport

## Troubleshooting

| Issue | Fix |
|-------|-----|
| Claude Desktop doesn't show tools | Restart Claude Desktop after editing config. Check the config path is correct. |
| `ModuleNotFoundError: mcp` | Run `uv sync` to install dependencies |
| Server crashes on startup | Check Python version: `python --version` (need 3.11+) |
| FTS search returns nothing | FTS index only covers notes added *after* the table was created |
| Database locked errors | Make sure only one instance of the server is running |

## Resources

- [MCP Official Docs](https://modelcontextprotocol.io/)
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
- [FastMCP](https://github.com/jlowin/fastmcp) — the high-level API (v1 is built into the official SDK)
- [MCP Server Registry](https://registry.modelcontextprotocol.io/) — discover community servers
- [MCP Specification (Nov 2025)](https://spec.modelcontextprotocol.io/) — the full protocol spec

## License

MIT — use this however you want. Build on it, learn from it, ship it.