Metadata-Version: 2.4
Name: sqlite-kb-mcp
Version: 0.1.0
Summary: A Model Context Protocol server for a SQLite-backed knowledge base with full-text search.
Keywords: mcp,model-context-protocol,sqlite,fts5,knowledge-base,llm
Author: Hammad
Author-email: Hammad <mhd-Hammad@users.noreply.github.com>
License-Expression: MIT
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 :: Software Development :: Libraries
Requires-Dist: mcp[cli]>=1.0,<2
Requires-Python: >=3.10
Project-URL: Homepage, https://github.com/mhd-Hammad/mcp-knowledge-base
Project-URL: Repository, https://github.com/mhd-Hammad/mcp-knowledge-base
Project-URL: Issues, https://github.com/mhd-Hammad/mcp-knowledge-base/issues
Description-Content-Type: text/markdown

# mcp-knowledge-base

A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that gives an
AI assistant a searchable, persistent knowledge base. Documents are stored in SQLite and
searched with FTS5 full-text search ranked by relevance.

It is a **self-contained** MCP server: it owns its own data and logic rather than wrapping
an external API. The SQLite database *is* the application; MCP is the interface an AI host
(Kiro, Claude Desktop, any MCP client) talks to it through.

## Features

- **Tools** — add, search, get, list, update, and delete documents.
- **Resources** — read documents by URI (`kb://documents`, `kb://documents/{id}`).
- **Prompts** — reusable templates (`summarize_search`, `find_related`).
- **Full-text search** — SQLite FTS5 with BM25 relevance ranking, not naive `LIKE`.
- **Input validation** — Pydantic field constraints surfaced in the generated tool schemas.

## Installation

Once published, add the server to your MCP host's config. No clone, no paths:

```json
{
  "mcpServers": {
    "knowledge-base": {
      "command": "uvx",
      "args": ["sqlite-kb-mcp"]
    }
  }
}
```

- **Kiro** — put this in `.kiro/settings/mcp.json` (workspace) or `~/.kiro/settings/mcp.json` (user).
- **Claude Desktop** — put this in `claude_desktop_config.json`.

`uvx` downloads and runs the published package on demand, so users never touch the source.

> `autoApprove` is intentionally omitted here: auto-approving tool calls is a personal trust
> decision. Add it in your own config if you want read-only tools to run without a prompt.

## What it exposes

### Tools

| Tool | Description |
|------|-------------|
| `add_document(title, content, tags="")` | Add a document. |
| `search_documents(query, limit=10)` | Full-text search, ranked by relevance. |
| `get_document(doc_id)` | Fetch one document by id. |
| `list_documents()` | List all documents, newest first. |
| `update_document(doc_id, ...)` | Update provided fields. |
| `delete_document(doc_id)` | Delete a document. |

### Resources

| URI | Description |
|-----|-------------|
| `kb://documents` | All documents, as JSON. |
| `kb://documents/{doc_id}` | One document, as JSON. |

### Prompts

| Prompt | Description |
|--------|-------------|
| `summarize_search(query, limit=5)` | Searches the KB and asks the model to summarize (data embedded). |
| `find_related(topic)` | Instructs the model to find related documents using the search tool. |

## Architecture

```
MCP host  ──stdio──►  server.py  ──►  db.py  ──►  knowledge.db
(Kiro/Claude)         (MCP layer)     (logic)     (SQLite + FTS5)
```

- **`server.py`** — the MCP interface. Each tool/resource/prompt is a thin wrapper that
  validates input and delegates to `db.py`. No business logic lives here.
- **`db.py`** — pure data-access logic. Knows nothing about MCP, so it is independently
  testable. Opens a connection per call to avoid SQLite threading issues.
- **SQLite + FTS5** — a `documents` table plus a `documents_fts` external-content virtual
  table. Triggers keep the search index in sync automatically, so CRUD touches only the
  main table.

This separation of concerns means the whole data layer is tested without any MCP machinery.

## Development

```bash
# clone, then:
uv sync                 # install deps (incl. dev group)
uv run pytest           # run the test suite
uv run mcp dev src/mcp_knowledge_base/server.py   # open the MCP Inspector
```

To run the server directly over stdio:

```bash
uv run sqlite-kb-mcp
```

## Notes and future work

- **Transport** — currently stdio (local subprocess). Streamable HTTP would make it
  deployable as a remote service; FastMCP supports it with a small change.
- **Search** — FTS5 matches whole tokens (`index` != `indexes`). Prefix queries (`index*`)
  work today; a Porter stemmer could be enabled for automatic stem matching.
- **Not implemented (by design)** — client-side primitives (sampling, elicitation, roots)
  and OAuth authorization, which are relevant mainly to remote/HTTP deployments.

## License

MIT
