Skip to main content
Glama
MCP Knowledge Server

MCP Knowledge Server

by nitishfound
README.md
# MCP Knowledge Server

A **Model Context Protocol (MCP) server** that gives AI assistants (Claude Desktop, Claude Code, or any MCP client) a personal notes knowledge base: full-text search with BM25 ranking, read, create, update and delete notes, plus resources and prompt templates.
Built with the official MCP Python SDK (v2, `MCPServer`) and SQLite FTS5.

```text
$ python examples/demo_client.py
tools: search_notes, get_note, list_tags, add_note, update_note, delete_note
  [2] RAG chunking notes  score=0.926  **Chunk** by heading, ~800 chars with 150 overlap. Embed heading + text.

notes://recent ->
- [3] Hiking checklist (personal)
- [2] RAG chunking notes (ai, rag)
- [1] Postgres connection pooling (databases, work)

get_note(999) -> Error executing tool get_note: note 999 not found (is_error = True )
```

## What is MCP?

MCP is an open standard for connecting AI apps to tools and data. Instead of writing a custom integration for every app, you write **one server**, and any MCP client can use it. The server describes what it offers:

| MCP concept | Who decides to use it | This server |
|---|---|---|
| **Tools** (actions with JSON-schema inputs) | the model | `search_notes`, `get_note`, `list_tags`, `add_note`, `update_note`, `delete_note` |
| **Resources** (read-only data addressed by URI) | the app / user | `notes://recent`, `notes://{note_id}` |
| **Prompts** (reusable prompt templates) | the user | `summarize_tag`, `find_connections` |

```mermaid
sequenceDiagram
    participant U as User
    participant H as AI app (MCP client)
    participant S as notes MCP server
    participant DB as SQLite + FTS5
    H->>S: initialize, tools/list
    S-->>H: tool names, descriptions, JSON schemas, annotations
    U->>H: "what did I write about connection pools?"
    H->>S: tools/call search_notes {"query": "connection pool"}
    S->>DB: MATCH '"connection" OR "pool"' ORDER BY bm25
    DB-->>S: ranked rows + snippets
    S-->>H: structured result [{id, title, snippet, score}]
    H->>S: tools/call get_note {"note_id": 1}
    S-->>H: full note
    H-->>U: answer citing note 1
```

## Features

- **Full-text search** with SQLite FTS5: Porter stemming, BM25 ranking (title matches weigh 5x, tags 2x), highlighted snippets, optional tag filter. The index is kept in sync by triggers.
- **Structured outputs**: tools return Pydantic models, so clients get a JSON schema for results, not just text.
- **Tool annotations** tell the client which tools are read-only and which are destructive (`delete_note`), so the app can ask the user before running them.
- **Least privilege**: `--read-only` mode does not even register the write tools.
- **Injection-safe**: all SQL is parameterised, and free-text search is converted into a quoted FTS5 query, so FTS operators (`NEAR`, `*`, column filters, unbalanced quotes) can't break or bend the search.
- **Input limits**: title/content length, max 10 tags, tag format validated. Errors use `ToolError` so the model gets a clear message ("note 999 not found") while unexpected crashes are hidden.
- **Prompt-injection hygiene**: server instructions and prompts say note content is data, not instructions.
- **Two transports**: stdio (local apps) and Streamable HTTP (bound to 127.0.0.1 by default).
- Logs go to **stderr**, because on stdio, stdout carries the protocol and a stray `print` would corrupt it.

## Quick start

```bash
git clone https://github.com/nitishfound/mcp-knowledge-server.git
cd mcp-knowledge-server
pip install -r requirements.txt
pytest -q
python examples/demo_client.py
```

### Use it from Claude Code

```bash
claude mcp add notes -- python -m notes_mcp --db ~/.mcp-notes/notes.db
```

### Use it from Claude Desktop

Add to `claude_desktop_config.json` (use the full path to the Python you installed the requirements into):

```json
{
  "mcpServers": {
    "notes": {
      "command": "python",
      "args": ["-m", "notes_mcp", "--db", "/home/you/.mcp-notes/notes.db"],
      "cwd": "/path/to/mcp-knowledge-server"
    }
  }
}
```

Add `"--read-only"` to the args to give the assistant search and read access only.

### HTTP mode

```bash
python -m notes_mcp --http --port 8000        # Streamable HTTP at http://127.0.0.1:8000/mcp
```

## Project structure

```
notes_mcp/
  store.py     SQLite + FTS5 store: add/get/update/delete/search/tags, safe FTS queries
  server.py    MCP server: tools, resources, prompts, read-only mode, CLI
examples/demo_client.py   launches the server over stdio and calls it
tests/        21 tests: store, injection attempts, MCP protocol in-process, real stdio subprocess
```

## Testing approach

- `test_store.py`: ranking, stemming, tag filter, update re-indexing, validation, and five injection strings (`'); DROP TABLE notes; --`, `NEAR(a b)`, unbalanced quotes...).
- `test_server.py`: talks real MCP to the server in-process (`mcp.Client(server)`): tool listing and annotations, read-only mode, structured outputs, error messages, resources, prompts.
- `test_stdio.py`: starts `python -m notes_mcp` as a subprocess and talks over stdin/stdout, exactly like Claude Desktop.

## License

MIT