mcp-kb 0.3.1__py3-none-any.whl → 0.3.3__py3-none-any.whl

mcp_kb-0.3.3.dist-info/METADATA

@@ -0,0 +1,338 @@
+Metadata-Version: 2.4
+Name: mcp-kb
+Version: 0.3.3
+Summary: MCP server exposing a local markdown knowledge base
+Author: LLM Maintainer
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: mcp[cli]>=1.15.0
+Requires-Dist: pydantic>=2.11.9
+Provides-Extra: vector
+Requires-Dist: chromadb>=1.1.0; extra == "vector"
+Requires-Dist: tiktoken>=0.11.0; extra == "vector"
+Requires-Dist: langchain-text-splitters>=0.3.11; extra == "vector"
+Requires-Dist: umap-learn>=0.5.9.post2; extra == "vector"
+Provides-Extra: sentence-transformer
+Requires-Dist: mcp-kb[vector]; extra == "sentence-transformer"
+Requires-Dist: sentence-transformers>=5.1.1; extra == "sentence-transformer"
+
+# MCP Knowledge Base Server
+
+A local, text‑only knowledge base exposed as an MCP server with optional HTTP/SSE transports and a built‑in web UI. Supports creating, reading, updating, searching, and soft‑deleting UTF‑8 text files. Optionally mirrors content to Chroma for semantic search and 2D/3D vector visualization.
+
+## Highlights
+
+- **MCP tools** for file lifecycle + search
+- **HTTP/SSE transports** and a minimal **built‑in UI**
+- **Deterministic path validation** and **soft deletes**
+- **Optional Chroma mirroring** for semantic search and vector plotting
+- **No lock‑in**: works with any Python toolchain (pip/pipx/Poetry/PDM/Rye/etc.)
+
+---
+
+## Table of contents
+
+- [Quick start](#quick-start)
+- [How it works](#how-it-works)
+- [CLI usage](#cli-usage)
+- [MCP tools](#mcp-tools)
+- [Human UI](#human-ui)
+- [UI HTTP API](#ui-http-api)
+- [Optional: ChromaDB mirroring](#optional-chromadb-mirroring)
+- [Reindexing CLI](#reindexing-cli)
+- [Persistent CLI defaults](#persistent-cli-defaults)
+- [Path rules & safety](#path-rules--safety)
+- [Testing](#testing)
+- [Integrating with LLM clients](#integrating-with-llm-clients)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## Quick start
+
+**Prereqs:** Python 3.11+ is required. :contentReference[oaicite:1]{index=1}
+
+**Install (choose one):**
+
+- From PyPI:
+
+  ```bash
+  python -m pip install mcp-kb
+  ```
+
+**Run the server (HTTP transport + UI):**
+
+```bash
+mcp-kb-server --root /path/to/knowledgebase --transport http
+# Alternative if entry points aren't on PATH:
+python -m mcp_kb.cli.main --root /path/to/knowledgebase --transport http
+```
+
+On first launch, a documentation file is installed at `.data/KNOWLEDBASE_DOC.md`. The UI binds to port **8765** by default and increments until free, logging a URL like:
+
+```
+UI available at http://127.0.0.1:8765
+```
+
+> **Note:** The server defaults to `stdio` only. Add `--transport sse` and/or `--transport http` to enable network transports.
+
+---
+
+## How it works
+
+- **KnowledgeBase**: safe, validated file operations (create/read/append/regex/soft‑delete).
+- **MCP server**: exposes the operations as MCP tools over chosen transports.
+- **Human UI**: small web UI for browsing, editing, and searching files.
+- **Optional vector layer**: if Chroma is configured, semantic search and a 3D scatter of embeddings appear in the UI.
+
+---
+
+## CLI usage
+
+The package exposes these entry points: `mcp-kb` / `mcp-kb-server` (run server) and `mcp-kb-reindex` (offline reindex).
+
+Common flags (server):
+
+- `--root <path>`: KB root directory (relative paths are enforced internally)
+- `--transport {stdio|sse|http}` (repeatable; default: `stdio`)
+- `--host <ip>` / `--port <int>`: apply to HTTP/SSE transports
+- `--ui-port <int>`: starting port for UI (default 8765; auto‑increments if busy)
+- `--no-ui`: disable the UI even if HTTP/SSE is active
+
+Examples:
+
+```bash
+# stdio only (default):
+mcp-kb-server --root /path/to/kb
+
+# HTTP + SSE + stdio:
+mcp-kb-server --root /path/to/kb \
+  --transport stdio --transport sse --transport http \
+  --host 0.0.0.0 --port 9000
+```
+
+---
+
+## MCP tools
+
+All tools operate on **relative** paths inside the KB root and respect soft‑deletes.
+
+- `create_file(path, content) -> str`
+- `read_file(path, start_line?, end_line?) -> {path, start_line, end_line, content}`
+- `append_file(path, content) -> str`
+- `regex_replace(path, pattern, replacement) -> {replacements}`
+- `delete(path) -> str` _(soft delete; renames file with sentinel)_
+- `search(query, limit=5) -> [FileSegment...]` _(semantic first if Chroma is on; otherwise literal scan)_
+- `overview() -> str`
+- `documentation() -> str`
+
+`read_file` and `search` return **FileSegment** objects with `start_line`, `end_line`, and `content`. Line indices are **0‑based inclusive** in the JSON the server emits.
+
+---
+
+## Human UI
+
+- Menu: **Browse** (always) and **Vectors** (when a vector store is available).
+- Browse: left tree, right editor, Save/Cancel/Delete, and **New File**.
+- Search: sidebar search filters the tree; clicking a result opens the file and highlights the matched lines. When vectors are available, the plot highlights results and the query point.
+
+---
+
+## UI HTTP API
+
+Base path is the UI origin.
+
+- `GET /api/tree` → file tree (nested `{name, path, type, children}`)
+- `GET /api/file?path=<rel>` → `{path, start_line, end_line, content}`
+- `PUT /api/file` (JSON `{path, content}`) → `204` on success
+- `DELETE /api/file?path=<rel>` → `204` on success
+- `GET /api/search?query=<text>&limit=<int>` →
+
+  ```json
+  {
+    "results": [
+      { "path": "notes/a.md", "start_line": 10, "end_line": 12, "content": "..." }
+    ],
+    "meta": {
+      "query_embeddings": [ ... ],
+      "query_embeddings_umap2d": [x, y],
+      "query_embeddings_umap3d": [x, y, z]
+    }
+  }
+  ```
+
+  _(Meta fields appear when Chroma is enabled.)_
+
+**Vector endpoints** (visible when Chroma is configured):
+
+- `GET /api/vector/status` → `{ "available": bool, "dimensions": int|null, "count": int|null }`
+- `GET /api/vector/embeddings?limit=<int>&offset=<int>&path=<rel?>` → `[ { id, document_id, path, chunk, embedding, umap2d?, umap3d? } ]`
+- `GET /api/vector/query_embedding?query=<text>` → `{ embedding: number[], used_model: string|null }`
+- `POST /api/vector/reindex` → `{ status: "queued"|"running"|"unavailable"|"error" }`
+- `POST /api/vector/refit` → `{ status: "queued"|"unavailable"|"error" }`
+
+---
+
+## Optional: ChromaDB mirroring
+
+Install the vector extras (pick what you need):
+
+```bash
+# core vector support (Chroma, UMAP integration, splitters)
+python -m pip install 'mcp-kb[vector]'
+
+# add Sentence Transformers embedding support
+python -m pip install 'mcp-kb[sentence-transformer]'
+```
+
+Enable via CLI flags (examples):
+
+```bash
+mcp-kb-server \
+  --root /path/to/kb \
+  --transport http \
+  --chroma-client ephemeral \
+  --chroma-collection local-kb \
+  --chroma-embedding default
+```
+
+Supported clients: `off`, `ephemeral`, `persistent`, `http`, `cloud`. All `--chroma-*` flags have `MCP_KB_CHROMA_*` env var equivalents (e.g., `MCP_KB_CHROMA_CLIENT=http`, `MCP_KB_CHROMA_HOST=...`). Chunking can be tuned with `--chroma-chunk-size` and `--chroma-chunk-overlap`.
+
+---
+
+## Reindexing CLI
+
+Rebuild the Chroma index from disk without running the MCP transports:
+
+```bash
+mcp-kb-reindex --root /path/to/kb \
+  --chroma-client persistent \
+  --chroma-data-dir /path/to/chroma \
+  --chroma-collection knowledge-base \
+  --chroma-embedding default
+```
+
+This processes all active text files and updates the collection; some tests assert the reindex path mirrors content exactly.
+
+---
+
+## Persistent CLI defaults
+
+Resolved CLI/environment settings are persisted per KB root at:
+
+```
+<root>/.data/cli-config.json
+```
+
+Future runs inherit these defaults unless overridden by new flags or env vars. Delete or edit the file to reset.
+
+---
+
+## Path rules & safety
+
+- **Relative paths only.** Absolute paths and `..` traversal are rejected.
+- **`.data/` is read‑only** for writes (reads allowed).
+- **Soft delete**: files renamed with a sentinel; hidden from listing/search.
+- Writes are serialized with per‑file locks to avoid corruption.
+
+These rules are enforced in the validation and filesystem helpers.
+
+---
+
+## Testing
+
+Install test deps and run:
+
+```bash
+python -m pip install pytest
+pytest -q
+```
+
+Vector‑related tests are skipped if Chroma isn’t installed. To run them:
+
+```bash
+python -m pip install 'mcp-kb[vector]'
+pytest -q
+```
+
+The suite exercises the real HTTP UI, vector endpoints, CLI config persistence, and FastMCP flows.
+
+---
+
+## Integrating with LLM clients
+
+Provide the server command your client can execute. Two portable options:
+
+- **Executable** (preferred if on PATH):
+
+  ```json
+  {
+    "command": "mcp-kb-server",
+    "args": ["--root", "/absolute/path/.knowledgebase", "--transport", "stdio"]
+  }
+  ```
+
+- **Python module** (works even without entry points on PATH):
+
+  ```json
+  {
+    "command": "python",
+    "args": [
+      "-m",
+      "mcp_kb.cli.main",
+      "--root",
+      "/absolute/path/.knowledgebase",
+      "--transport",
+      "stdio"
+    ]
+  }
+  ```
+
+Examples:
+
+- **Claude Desktop** (`claude_desktop_config.json`):
+
+  ```json
+  {
+    "mcpServers": {
+      "local-kb": {
+        "command": "mcp-kb-server",
+        "args": [
+          "--root",
+          "/absolute/path/.knowledgebase",
+          "--transport",
+          "stdio"
+        ]
+      }
+    }
+  }
+  ```
+
+- **VS Code (Claude MCP Extension)** (`settings.json`):
+
+  ```json
+  {
+    "claudeMcp.servers": {
+      "local-kb": {
+        "command": "mcp-kb-server",
+        "args": [
+          "--root",
+          "/absolute/path/.knowledgebase",
+          "--transport",
+          "stdio"
+        ],
+        "env": { "MCP_KB_ROOT": "/absolute/path/.knowledgebase" }
+      }
+    }
+  }
+  ```
+
+---
+
+## Troubleshooting
+
+- **“Absolute paths are not permitted”** → Use a **relative** path in tools and UI.
+- **“Writes are not allowed inside the protected folder '.data'”** → Choose a different directory (e.g., `docs/`).
+- **Vector endpoints missing** → You didn’t install/enable the vector extras or a Chroma client.
+- **UI port in use** → Set `--ui-port` to another number; it auto‑increments if busy.

mcp_kb-0.3.3.dist-info/RECORD

@@ -0,0 +1,32 @@
+mcp_kb/__init__.py,sha256=Ry7qODhfFQF6u6p2m3bwGWhB0-BdWTQcHDJB7NBYAio,74
+mcp_kb/config.py,sha256=NUpzjDH4PQw4FyjGgYUcMsGMeenNiZTMrQj4U62xKlk,2530
+mcp_kb/cli/__init__.py,sha256=dEIRWFycAfPkha1S1Bj_Y6zkvEZv4eF0qtbF9t74r60,67
+mcp_kb/cli/args.py,sha256=NaAcxW6WzRZeDLEASKx6tPu3RDeJLX0cDkn2yeLSNZc,5904
+mcp_kb/cli/main.py,sha256=t8zDokpVjRPkkhYBO4UGhHRHJifp4jAuxxbFQP4lQLE,5910
+mcp_kb/cli/reindex.py,sha256=JxukrYWWurEk2DlyIEUNF6PzGbNSSwsw_XJ6-ABwIvs,3829
+mcp_kb/cli/runtime_config.py,sha256=Lwb5IIINCQeidqP6Ev5JO_uqwhLpPsTokerQA8yIfPE,13077
+mcp_kb/data/KNOWLEDBASE_DOC.md,sha256=xnLUJIK8WvdLxqm-rkjL00brpb3hvZHeNVpuqf_3w4E,6704
+mcp_kb/data/__init__.py,sha256=UYYuO_n2ikjpwkPSykgleiifYvC0V8_O-atUaRBQUm4,70
+mcp_kb/ingest/__init__.py,sha256=8obrvfa8nLNLYPbi1MHlFUqfoFHgK9YfdryPzAXQ6kU,77
+mcp_kb/ingest/chroma.py,sha256=gsR1Y4PsE4v18NJQYCkV6xt5P3iRgLb6wb_JY90OGu4,47422
+mcp_kb/knowledge/__init__.py,sha256=W_dtRbtnQlrDJ_425vWR8BcoZGJ8gC5-wg1De1E654s,76
+mcp_kb/knowledge/bootstrap.py,sha256=Og72GvxeJX7PLe_vHVMzRqnXIS06JswSrIdKcz776_8,1237
+mcp_kb/knowledge/events.py,sha256=4pYC7gP6k-_O6hIdc0w69SkcoMq639f9TIJg6PikMgs,3624
+mcp_kb/knowledge/search.py,sha256=G38AEKL38sA2SaVvuGSmy0TdR17Sx8n12GA8E4i9JvE,6003
+mcp_kb/knowledge/store.py,sha256=SNkD-6I3J8xvHQdt-Z9xdoZdlQ8rSxj1nuqckNtNmak,10932
+mcp_kb/security/__init__.py,sha256=lF8_XAjzpwhAFresuskXMo0u9v7KFiTJId88wqOAM4Y,62
+mcp_kb/security/path_validation.py,sha256=yqSPb6_WFJF3ZwwyOtzvJIhM9pNYmCVpseQdXPkb1gM,3658
+mcp_kb/server/__init__.py,sha256=j9TmxW_WLCoibyQvCsDT1MIuUqSL8sRh2h4u0M4eU0c,74
+mcp_kb/server/app.py,sha256=Ol3usBD9Rr4fjRYBGChWQOR5GkYinR0zfh_DDVuF8Fk,7336
+mcp_kb/ui/__init__.py,sha256=vQMh9koOAjJO35WRd0LlUvvadZZ5gZ74C4Rs_XVmH9k,639
+mcp_kb/ui/api.py,sha256=kKEIqcHi-OAuY8NfYKAMuNSFcHSM-yqV7SKUIuCnqmk,13078
+mcp_kb/ui/server.py,sha256=miJXMYpfbcxpIvawkFsLvJtKHLCur0Ze10hJaD8X2ZA,13321
+mcp_kb/ui/assets/index.html,sha256=4oPfhGAYhxrtwNj31JVfLgtrTyHEdoIirOTDPhMBh7g,2452
+mcp_kb/ui/assets/assets/index.css,sha256=0ijQKJMsklOMXKKMdFhx7cQUV-ksgJX1pT7XSX0XSyg,3923
+mcp_kb/utils/__init__.py,sha256=lKhRsjgnbhye1sSlch1_wsAI3eWKE1M6RVIiNlnsvLI,71
+mcp_kb/utils/filesystem.py,sha256=1Jr9cxIimV-o91DJMh5lR9GLFE3BDknoGquVBFQ-fd4,4027
+mcp_kb-0.3.3.dist-info/METADATA,sha256=kMzKsM-pcL_EE0ah6FkLyIyNBkR5LOH83otv2DW7JzM,9944
+mcp_kb-0.3.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+mcp_kb-0.3.3.dist-info/entry_points.txt,sha256=PdX1utY9cbvU_NQcKqUrWnMa4r3jGl448T7HUF9Gjqw,126
+mcp_kb-0.3.3.dist-info/top_level.txt,sha256=IBiz3TNE3FF3TwkbCZpC1kkk6ohTwtBQNSPJNV3-qGA,7
+mcp_kb-0.3.3.dist-info/RECORD,,

mcp_kb-0.3.1.dist-info/METADATA

@@ -1,181 +0,0 @@
-Metadata-Version: 2.4
-Name: mcp-kb
-Version: 0.3.1
-Summary: MCP server exposing a local markdown knowledge base
-Author: LLM Maintainer
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-Requires-Dist: httpx>=0.28.1
-Requires-Dist: mcp[cli]>=1.15.0
-Requires-Dist: pydantic>=2.11.9
-Provides-Extra: vector
-Requires-Dist: chromadb>=1.1.0; extra == "vector"
-Requires-Dist: tiktoken>=0.11.0; extra == "vector"
-Requires-Dist: langchain-text-splitters>=0.3.11; extra == "vector"
-Requires-Dist: umap-learn>=0.5.9.post2; extra == "vector"
-Provides-Extra: sentence-transformer
-Requires-Dist: mcp-kb[vector]; extra == "sentence-transformer"
-Requires-Dist: sentence-transformers>=5.1.1; extra == "sentence-transformer"
-
-# MCP Knowledge Base Server
-
-This project implements a Model Context Protocol (MCP) server that manages a local markdown knowledge base. It provides tools for creating, reading, updating, searching, and organizing documents stored beneath a configurable root directory. The server uses `FastMCP` for transport and schema generation, so the Python tool functions double as the canonical source of truth for MCP metadata.
-
-## Running the server
-
-```bash
-uv run mcp-kb-server --root /path/to/knowledgebase
-```
-
-To expose multiple transports, pass `--transport` flags (supported values: `stdio`,
-`sse`, `http`):
-
-```bash
-uv run mcp-kb-server --transport stdio --transport http
-```
-
-Use `--host` and `--port` to bind HTTP/SSE transports to specific interfaces:
-
-```bash
-uv run mcp-kb-server --transport http --host 0.0.0.0 --port 9000
-```
-
-On first launch the server copies a bundled `KNOWLEDBASE_DOC.md` into the
-`.data/` directory if it is missing so that every deployment starts with a
-baseline usage guide.
-
-## Optional ChromaDB Mirroring
-
-The CLI can mirror knowledge base changes into a Chroma collection without
-exposing raw Chroma operations as MCP tools. Mirroring is enabled by default via
-the `persistent` client, which stores data under `<root>/chroma`. Choose a
-different backend with `--chroma-client` (choices: `ephemeral`, `persistent`,
-`http`, `cloud`). Example:
-
-```bash
-uv run mcp-kb-server \
-  --root /path/to/knowledgebase \
-  --chroma-client ephemeral \
-  --chroma-collection local-kb \
-  --chroma-embedding default
-```
-
-Persistent and remote clients accept additional flags:
-
-- `--chroma-data-dir`: storage directory for the persistent client (defaults to
-  `<root>/chroma` when not supplied).
-- `--chroma-host`, `--chroma-port`, `--chroma-ssl`, `--chroma-custom-auth`:
-  options for a self-hosted HTTP server.
-- `--chroma-tenant`, `--chroma-database`, `--chroma-api-key`: credentials for
-  Chroma Cloud deployments.
-- `--chroma-id-prefix`: custom document ID prefix (`kb::` by default).
-
-Every flag has a matching environment variable (`MCP_KB_CHROMA_*`), so the
-following snippet enables an HTTP client without modifying CLI commands:
-
-```bash
-export MCP_KB_CHROMA_CLIENT=http
-export MCP_KB_CHROMA_HOST=chroma.internal
-export MCP_KB_CHROMA_PORT=8001
-export MCP_KB_CHROMA_CUSTOM_AUTH="username:password"
-uv run mcp-kb-server --transport http
-```
-
-When enabled, any file creation, update, or soft deletion is synchronously
-propagated to the configured Chroma collection, ensuring semantic search stays
-in lockstep with the markdown knowledge base.
-
-The `kb.search` MCP tool automatically queries Chroma when mirroring is active,
-falling back to direct filesystem scans if the semantic index returns no hits.
-
-## Reindexing
-
-Use the standalone CLI to rebuild external indexes (e.g., Chroma) from the
-current knowledge base. This command is not exposed as an MCP tool.
-
-```bash
-uv run mcp-kb-reindex --root /path/to/knowledgebase \
-  --chroma-client persistent \
-  --chroma-data-dir /path/to/chroma \
-  --chroma-collection knowledge-base \
-  --chroma-embedding default
-```
-
-- Honors the same `--chroma-*` flags and `MCP_KB_CHROMA_*` environment
-  variables as the server.
-- Processes all non-deleted `*.md` files under the root and prints a summary:
-  `Reindexed N documents`.
-
-## Testing
-
-```bash
-uv run pytest
-```
-
-## LLM Client Configuration
-
-Below are sample configurations for popular MCP-capable LLM clients. All
-examples assume this repository is cloned locally and that `uv` is installed.
-
-### Claude Desktop
-
-Add the following block to your Claude Desktop `claude_desktop_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "local-kb": {
-      "server-name": "kb-server",
-      "command": "uv",
-      "args": [
-        "run",
-        "mcp-kb-server",
-        "--root",
-        "/absolute/path/to/.knowledgebase"
-      ]
-    }
-  }
-}
-```
-
-### Cursor AI
-
-In Cursor's `cursor-settings.json`, register the server as a custom tool:
-
-```json
-{
-  "mcpServers": {
-    "local_knowledge_base": {
-      "id": "local-kb",
-      "title": "Local Knowledge Base",
-      "command": "uvx",
-      "args": [
-        " --from",
-        "~/cursor_projects/local_knowledge_base",
-        "mcp-kb-server"
-      ]
-    }
-  }
-}
-```
-
-### VS Code (Claude MCP Extension)
-
-For the `Claude MCP` extension, add an entry to `settings.json`:
-
-```json
-{
-  "claudeMcp.servers": {
-    "local-kb": {
-      "command": "uv",
-      "args": ["run", "mcp-kb-server"],
-      "env": {
-        "MCP_KB_ROOT": "/absolute/path/to/.knowledgebase"
-      }
-    }
-  }
-}
-```
-
-Adjust the `--root` flag or `MCP_KB_ROOT` environment variable to point at the
-desired knowledge base directory for each client.

mcp_kb-0.3.1.dist-info/RECORD

@@ -1,7 +0,0 @@
-mcp_kb/__init__.py,sha256=Ry7qODhfFQF6u6p2m3bwGWhB0-BdWTQcHDJB7NBYAio,74
-mcp_kb/config.py,sha256=NUpzjDH4PQw4FyjGgYUcMsGMeenNiZTMrQj4U62xKlk,2530
-mcp_kb-0.3.1.dist-info/METADATA,sha256=PChkcVS-WUUnKFSHxIkpDn7PtJlOmQFvHIjkus7xBRU,5389
-mcp_kb-0.3.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-mcp_kb-0.3.1.dist-info/entry_points.txt,sha256=PdX1utY9cbvU_NQcKqUrWnMa4r3jGl448T7HUF9Gjqw,126
-mcp_kb-0.3.1.dist-info/top_level.txt,sha256=IBiz3TNE3FF3TwkbCZpC1kkk6ohTwtBQNSPJNV3-qGA,7
-mcp_kb-0.3.1.dist-info/RECORD,,