sqlite-kb-mcp 0.1.0__py3-none-any.whl

mcp_knowledge_base/__init__.py

@@ -0,0 +1,3 @@
+"""mcp-knowledge-base: a Model Context Protocol server backed by SQLite full-text search."""
+
+__version__ = "0.1.0"

mcp_knowledge_base/db.py

@@ -0,0 +1,164 @@
+"""Data layer: SQLite + FTS5. Knows nothing about MCP."""
+
+from __future__ import annotations
+
+import os
+import sqlite3
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+def _default_db_path() -> Path:
+    """User-writable DB path. Override with the KB_DB_PATH env var.
+
+    Never stored inside the installed package (site-packages may be read-only).
+    """
+    override = os.environ.get("KB_DB_PATH")
+    if override:
+        return Path(override)
+    if os.name == "nt":
+        base = Path(os.environ.get("LOCALAPPDATA", Path.home() / "AppData" / "Local"))
+    else:
+        base = Path(os.environ.get("XDG_DATA_HOME", Path.home() / ".local" / "share"))
+    data_dir = base / "sqlite-kb-mcp"
+    data_dir.mkdir(parents=True, exist_ok=True)
+    return data_dir / "knowledge.db"
+
+
+DB_PATH = _default_db_path()
+
+
+def _now() -> str:
+    """Current UTC time as ISO-8601 text."""
+    return datetime.now(timezone.utc).isoformat()
+
+
+def get_connection(db_path: Path | str = DB_PATH) -> sqlite3.Connection:
+    """Open a connection with rows accessible by column name."""
+    conn = sqlite3.connect(db_path)
+    conn.row_factory = sqlite3.Row  # rows behave like dicts
+    conn.execute("PRAGMA foreign_keys = ON")
+    return conn
+
+
+def init_db(conn: sqlite3.Connection) -> None:
+    """Create the documents table and its FTS5 search index."""
+    conn.executescript(
+        """
+        CREATE TABLE IF NOT EXISTS documents (
+            id         INTEGER PRIMARY KEY AUTOINCREMENT,
+            title      TEXT NOT NULL,
+            content    TEXT NOT NULL,
+            tags       TEXT NOT NULL DEFAULT '',
+            created_at TEXT NOT NULL,
+            updated_at TEXT NOT NULL
+        );
+
+        -- FTS5 index mirrors the searchable columns of `documents`.
+        CREATE VIRTUAL TABLE IF NOT EXISTS documents_fts USING fts5(
+            title, content, tags,
+            content='documents',
+            content_rowid='id'
+        );
+
+        -- Triggers keep the FTS index in sync with the table.
+        CREATE TRIGGER IF NOT EXISTS documents_ai AFTER INSERT ON documents BEGIN
+            INSERT INTO documents_fts(rowid, title, content, tags)
+            VALUES (new.id, new.title, new.content, new.tags);
+        END;
+
+        CREATE TRIGGER IF NOT EXISTS documents_ad AFTER DELETE ON documents BEGIN
+            INSERT INTO documents_fts(documents_fts, rowid, title, content, tags)
+            VALUES ('delete', old.id, old.title, old.content, old.tags);
+        END;
+
+        CREATE TRIGGER IF NOT EXISTS documents_au AFTER UPDATE ON documents BEGIN
+            INSERT INTO documents_fts(documents_fts, rowid, title, content, tags)
+            VALUES ('delete', old.id, old.title, old.content, old.tags);
+            INSERT INTO documents_fts(rowid, title, content, tags)
+            VALUES (new.id, new.title, new.content, new.tags);
+        END;
+        """
+    )
+    conn.commit()
+
+
+def add_document(
+    conn: sqlite3.Connection, title: str, content: str, tags: str = ""
+) -> int:
+    """Insert a document and return its new id."""
+    now = _now()
+    cur = conn.execute(
+        "INSERT INTO documents (title, content, tags, created_at, updated_at) "
+        "VALUES (?, ?, ?, ?, ?)",
+        (title, content, tags, now, now),
+    )
+    conn.commit()
+    return int(cur.lastrowid)
+
+
+def get_document(conn: sqlite3.Connection, doc_id: int) -> dict | None:
+    """Fetch one document by id, or None if missing."""
+    row = conn.execute(
+        "SELECT * FROM documents WHERE id = ?", (doc_id,)
+    ).fetchone()
+    return dict(row) if row else None
+
+
+def list_documents(conn: sqlite3.Connection) -> list[dict]:
+    """Return all documents, newest first."""
+    rows = conn.execute(
+        "SELECT * FROM documents ORDER BY created_at DESC, id DESC"
+    ).fetchall()
+    return [dict(r) for r in rows]
+
+
+def search_documents(
+    conn: sqlite3.Connection, query: str, limit: int = 10
+) -> list[dict]:
+    """Full-text search, ranked by relevance (BM25)."""
+    rows = conn.execute(
+        """
+        SELECT d.*, bm25(documents_fts) AS score
+        FROM documents_fts
+        JOIN documents d ON d.id = documents_fts.rowid
+        WHERE documents_fts MATCH ?
+        ORDER BY score
+        LIMIT ?
+        """,
+        (query, limit),
+    ).fetchall()
+    return [dict(r) for r in rows]
+
+
+def update_document(
+    conn: sqlite3.Connection,
+    doc_id: int,
+    title: str | None = None,
+    content: str | None = None,
+    tags: str | None = None,
+) -> bool:
+    """Update provided fields of a document. Returns True if it existed."""
+    existing = get_document(conn, doc_id)
+    if existing is None:
+        return False
+    conn.execute(
+        "UPDATE documents SET title = ?, content = ?, tags = ?, updated_at = ? "
+        "WHERE id = ?",
+        (
+            title if title is not None else existing["title"],
+            content if content is not None else existing["content"],
+            tags if tags is not None else existing["tags"],
+            _now(),
+            doc_id,
+        ),
+    )
+    conn.commit()
+    return True
+
+
+def delete_document(conn: sqlite3.Connection, doc_id: int) -> bool:
+    """Delete a document. Returns True if a row was removed."""
+    cur = conn.execute("DELETE FROM documents WHERE id = ?", (doc_id,))
+    conn.commit()
+    return cur.rowcount > 0

mcp_knowledge_base/server.py

@@ -0,0 +1,144 @@
+"""MCP server: thin tool layer over the db.py knowledge base."""
+
+import json
+from typing import Annotated, Optional
+
+from mcp.server.fastmcp import FastMCP
+from pydantic import Field
+
+from mcp_knowledge_base import db
+
+mcp = FastMCP("knowledge-base")
+
+# create tables once on load (idempotent)
+with db.get_connection() as _conn:
+    db.init_db(_conn)
+
+
+@mcp.tool()
+def add_document(
+    title: Annotated[str, Field(min_length=1, description="Document title")],
+    content: Annotated[str, Field(min_length=1, description="Document body")],
+    tags: Annotated[str, Field(description="Comma-separated tags")] = "",
+) -> dict:
+    """Add a document to the knowledge base. Returns the new document."""
+    with db.get_connection() as conn:
+        doc_id = db.add_document(conn, title, content, tags)
+        return db.get_document(conn, doc_id)
+
+
+@mcp.tool()
+def search_documents(
+    query: Annotated[str, Field(min_length=1, description="Full-text search query")],
+    limit: Annotated[int, Field(ge=1, le=50, description="Max results")] = 10,
+) -> list[dict] | str:
+    """Full-text search the knowledge base, ranked by relevance."""
+    with db.get_connection() as conn:
+        results = db.search_documents(conn, query, limit)
+    if not results:
+        return f"No documents matched '{query}'."
+    return results
+
+
+@mcp.tool()
+def get_document(
+    doc_id: Annotated[int, Field(ge=1, description="Document id")],
+) -> dict | str:
+    """Fetch a single document by its id."""
+    with db.get_connection() as conn:
+        doc = db.get_document(conn, doc_id)
+    return doc if doc else f"No document found with id {doc_id}."
+
+
+@mcp.tool()
+def list_documents() -> list[dict] | str:
+    """List all documents, newest first."""
+    with db.get_connection() as conn:
+        docs = db.list_documents(conn)
+    return docs if docs else "The knowledge base is empty."
+
+
+@mcp.tool()
+def update_document(
+    doc_id: Annotated[int, Field(ge=1, description="Document id to update")],
+    title: Annotated[str | None, Field(min_length=1)] = None,
+    content: Annotated[str | None, Field(min_length=1)] = None,
+    tags: str | None = None,
+) -> dict | str:
+    """Update a document's fields. Only provided fields change."""
+    with db.get_connection() as conn:
+        ok = db.update_document(conn, doc_id, title, content, tags)
+        if not ok:
+            return f"No document found with id {doc_id}."
+        return db.get_document(conn, doc_id)
+
+
+@mcp.tool()
+def delete_document(
+    doc_id: Annotated[int, Field(ge=1, description="Document id to delete")],
+) -> str:
+    """Delete a document by its id."""
+    with db.get_connection() as conn:
+        ok = db.delete_document(conn, doc_id)
+    return f"Deleted document {doc_id}." if ok else f"No document found with id {doc_id}."
+
+
+# --- Resources: read-only data addressed by URI (app/user-controlled) ---
+
+
+@mcp.resource("kb://documents")
+def all_documents() -> str:
+    """All documents in the knowledge base, as JSON."""
+    with db.get_connection() as conn:
+        docs = db.list_documents(conn)
+    return json.dumps(docs, indent=2)
+
+
+@mcp.resource("kb://documents/{doc_id}")
+def one_document(doc_id: str) -> str:
+    """A single document by id, as JSON. (URI params arrive as strings.)"""
+    with db.get_connection() as conn:
+        doc = db.get_document(conn, int(doc_id))
+    if doc is None:
+        return json.dumps({"error": f"No document found with id {doc_id}"})
+    return json.dumps(doc, indent=2)
+
+
+# --- Prompts: reusable instruction templates (user-controlled) ---
+
+
+@mcp.prompt()
+def summarize_search(
+    query: Annotated[str, Field(min_length=1, description="Topic to search for")],
+    limit: Annotated[int, Field(ge=1, le=20, description="How many results")] = 5,
+) -> str:
+    """Search the KB and ask the model to summarize the results (data embedded)."""
+    with db.get_connection() as conn:
+        results = db.search_documents(conn, query, limit)
+    if not results:
+        return f"No documents matched '{query}'. Tell the user nothing was found."
+    body = json.dumps(results, indent=2)
+    return (
+        f"Summarize these knowledge base results for '{query}'. "
+        f"Group related points and note any gaps.\n\n{body}"
+    )
+
+
+@mcp.prompt()
+def find_related(
+    topic: Annotated[str, Field(min_length=1, description="Subject to explore")],
+) -> str:
+    """Instruct the model to find related documents using the search tool."""
+    return (
+        f"Use the search_documents tool to find documents related to '{topic}'. "
+        "Then explain how they connect and suggest what to read first."
+    )
+
+
+def main() -> None:
+    """Console entry point. Runs the server over stdio."""
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

sqlite_kb_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,134 @@
+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

sqlite_kb_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+mcp_knowledge_base/__init__.py,sha256=P9YXMrSkRUr76uLBoZZhV1MM7o-QdZOFF9togKRu-0s,116
+mcp_knowledge_base/db.py,sha256=Sl9_cm-UUt0sS_xO_USvUKCg-rXzDfQj9LfR1M7NnNQ,5327
+mcp_knowledge_base/server.py,sha256=kva3CFmTvlUIlqkkuajrIn2Gj6BzfZ1864J97bNF-ak,4738
+sqlite_kb_mcp-0.1.0.dist-info/WHEEL,sha256=si2p8vW03RnhyBnhWl4tj-ObJa78SpE-c9HsEtblGR0,80
+sqlite_kb_mcp-0.1.0.dist-info/entry_points.txt,sha256=r9o1fIoHPCsVgNF3SE7rC1dQeV5bT-PvR11o70y32Gk,66
+sqlite_kb_mcp-0.1.0.dist-info/METADATA,sha256=_2xW5C_crYqZxt4WU-FijjwJ0rec9dsziqdsFwlubsM,5201
+sqlite_kb_mcp-0.1.0.dist-info/RECORD,,

sqlite_kb_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.13.5
+Root-Is-Purelib: true
+Tag: py3-none-any

sqlite_kb_mcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+sqlite-kb-mcp = mcp_knowledge_base.server:main
+