mcp-kb 0.1.0__py3-none-any.whl

mcp_kb/server/app.py

@@ -0,0 +1,201 @@
+"""FastMCP application that exposes knowledge base management tools.
+
+The module builds a :class:`FastMCP` server configured with the knowledge base
+operations defined elsewhere in the package. Using FastMCP drastically reduces
+protocol boilerplate because the framework introspects type hints and
+Docstrings to generate MCP-compatible tool schemas automatically.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterable, List
+
+from mcp.server.fastmcp import FastMCP
+
+from mcp_kb.config import DOC_FILENAME
+from mcp_kb.knowledge.events import (
+    KnowledgeBaseListener,
+    KnowledgeBaseSearchListener,
+)
+from mcp_kb.knowledge.search import build_tree_overview, read_documentation, search_text
+from mcp_kb.knowledge.store import FileSegment, KnowledgeBase
+from mcp_kb.security.path_validation import PathRules, PathValidationError
+
+
+@dataclass
+class ReadFileResult:
+    """Structured output for the ``kb.read_file`` tool."""
+
+    path: str
+    start_line: int
+    end_line: int
+    content: str
+
+
+@dataclass
+class RegexReplaceResult:
+    """Structured output describing the number of replacements performed."""
+
+    replacements: int
+
+
+@dataclass
+class SearchMatchResult:
+    """Structured representation of a search result with contextual lines."""
+
+    path: str
+    line: int
+    context: List[str]
+
+
+def create_fastmcp_app(
+    rules: PathRules,
+    *,
+    host: str | None = None,
+    port: int | None = None,
+    listeners: Iterable[KnowledgeBaseListener] | None = None,
+) -> FastMCP:
+    """Build and return a configured :class:`FastMCP` server instance.
+
+    Parameters
+    ----------
+    rules:
+        Sanitised filesystem rules that restrict all knowledge base operations to
+        a designated root.
+    host:
+        Optional host interface for HTTP/SSE transports. ``None`` uses FastMCP's
+        defaults.
+    port:
+        Optional TCP port for HTTP/SSE transports. ``None`` uses FastMCP's defaults.
+    listeners:
+        Optional iterable of :class:`KnowledgeBaseListener` implementations that
+        should receive change notifications. The iterable is passed directly to
+        :class:`~mcp_kb.knowledge.store.KnowledgeBase` so that integrations such
+        as Chroma ingestion can react to file lifecycle events.
+    """
+
+    kb = KnowledgeBase(rules, listeners=listeners)
+    search_providers: List[KnowledgeBaseSearchListener] = []
+    if listeners is not None:
+        for listener in listeners:
+            if isinstance(listener, KnowledgeBaseSearchListener):
+                search_providers.append(listener)
+    fastmcp_kwargs: dict[str, object] = {}
+    if host is not None:
+        fastmcp_kwargs["host"] = host
+    if port is not None:
+        fastmcp_kwargs["port"] = port
+
+    mcp = FastMCP(
+        "mcp-knowledge-base",
+        instructions=(
+            "You are connected to a local markdown knowledge base. Use the provided "
+            "tools to create, inspect, and organize content while respecting the "
+            "soft deletion semantics and the protected documentation folder."
+        ),
+        **fastmcp_kwargs,
+    )
+
+    @mcp.tool(name="create_file", title="Create File")
+    def create_file(path: str, content: str) -> str:
+        """Create or overwrite a markdown file at ``path`` with ``content``."""
+
+        try:
+            created = kb.create_file(path, content)
+        except PathValidationError as exc:
+            raise ValueError(str(exc)) from exc
+        return f"Created {created}"
+
+    @mcp.tool(name="read_file", title="Read File", structured_output=True)
+    def read_file(path: str, start_line: int | None = None, end_line: int | None = None) -> ReadFileResult:
+        """Read a markdown file returning metadata about the extracted segment."""
+
+        try:
+            segment: FileSegment = kb.read_file(path, start_line=start_line, end_line=end_line)
+        except PathValidationError as exc:
+            raise ValueError(str(exc)) from exc
+        except FileNotFoundError as exc:
+            raise ValueError(str(exc)) from exc
+        return ReadFileResult(
+            path=str(segment.path),
+            start_line=segment.start_line,
+            end_line=segment.end_line,
+            content=segment.content,
+        )
+
+    @mcp.tool(name="append_file", title="Append File")
+    def append_file(path: str, content: str) -> str:
+        """Append ``content`` to the file specified by ``path``."""
+
+        try:
+            target = kb.append_file(path, content)
+        except PathValidationError as exc:
+            raise ValueError(str(exc)) from exc
+        return f"Appended to {target}"
+
+    @mcp.tool(name="regex_replace", title="Regex Replace", structured_output=True)
+    def regex_replace(path: str, pattern: str, replacement: str) -> RegexReplaceResult:
+        """Perform a regex-based replacement across the full file."""
+
+        try:
+            replacements = kb.regex_replace(path, pattern, replacement)
+        except PathValidationError as exc:
+            raise ValueError(str(exc)) from exc
+        return RegexReplaceResult(replacements=replacements)
+
+    @mcp.tool(name="delete", title="Soft Delete")
+    def delete(path: str) -> str:
+        """Soft delete the file at ``path`` by appending the configured sentinel."""
+
+        try:
+            deleted = kb.soft_delete(path)
+        except PathValidationError as exc:
+            raise ValueError(str(exc)) from exc
+        except FileNotFoundError as exc:
+            raise ValueError(str(exc)) from exc
+        return f"Marked {deleted.name} as deleted"
+
+    @mcp.tool(name="search", title="Search", structured_output=True)
+    def search(query: str, limit: int = 5) -> List[SearchMatchResult]:
+        """Search for ``query`` across the knowledge base with semantic ranking.
+
+        Registered listeners that implement the optional search interface are
+        queried first (e.g., the Chroma ingestor). When no listener returns a
+        result the tool falls back to streaming the markdown files directly so
+        callers always receive deterministic text snippets.
+        """
+
+        if limit <= 0:
+            raise ValueError("limit must be greater than zero")
+
+        matches = search_text(
+            kb,
+            query,
+            providers=search_providers,
+            n_results=limit,
+        )
+        return [
+            SearchMatchResult(
+                path=str(match.path),
+                line=match.line_number,
+                context=match.context,
+            )
+            for match in matches
+        ]
+
+    @mcp.tool(name="overview", title="Overview")
+    def overview() -> str:
+        """Return a textual tree describing the knowledge base structure."""
+
+        return build_tree_overview(kb)
+
+    @mcp.tool(name="documentation", title="Documentation")
+    def documentation() -> str:
+        """Read the knowledge base documentation if ``%s`` exists.""" % DOC_FILENAME
+
+        text = read_documentation(kb)
+        if not text:
+            return "Documentation is not available."
+        return text
+
+    return mcp

mcp_kb/utils/__init__.py

@@ -0,0 +1 @@
+"""Utility helpers shared across the knowledge base server modules."""

mcp_kb/utils/filesystem.py

@@ -0,0 +1,83 @@
+"""Filesystem helpers wrapping Python's standard library primitives.
+
+The knowledge base server performs numerous file operations. Consolidating the
+logic in this module keeps the rest of the code focused on business semantics
+such as validating incoming requests and shaping responses. Each helper function
+is intentionally small so that callers can compose them for different workflows
+without duplicating the low-level boilerplate.
+"""
+from __future__ import annotations
+
+from contextlib import contextmanager
+from pathlib import Path
+from threading import Lock
+from typing import Dict, Iterator
+
+
+class FileLockRegistry:
+    """In-memory lock registry to serialize write operations per file.
+
+    Using per-path locks prevents concurrent writes from interleaving content
+    and potentially corrupting files. The registry lazily creates locks when a
+    path is first encountered. We reuse locks for subsequent operations to avoid
+    unbounded memory usage.
+    """
+
+    def __init__(self) -> None:
+        """Initialize the registry with an empty dictionary."""
+
+        self._locks: Dict[Path, Lock] = {}
+        self._global_lock = Lock()
+
+    @contextmanager
+    def acquire(self, path: Path) -> Iterator[None]:
+        """Context manager that acquires a lock for the supplied path.
+
+        The helper nests two locks: a global mutex to retrieve or create the
+        per-path lock, and the per-path lock itself for the duration of the
+        caller's critical section.
+
+        Parameters
+        ----------
+        path:
+            Absolute path indicating which file should be protected.
+        """
+
+        with self._global_lock:
+            lock = self._locks.setdefault(path, Lock())
+        lock.acquire()
+        try:
+            yield
+        finally:
+            lock.release()
+
+
+def write_text(path: Path, content: str) -> None:
+    """Write text content to ``path`` using UTF-8 encoding."""
+
+    path.write_text(content, encoding="utf-8")
+
+
+def append_text(path: Path, content: str) -> None:
+    """Append text content to ``path`` using UTF-8 encoding."""
+
+    with path.open("a", encoding="utf-8") as handle:
+        handle.write(content)
+
+
+def read_text(path: Path) -> str:
+    """Read UTF-8 text content from ``path`` and return it."""
+
+    return path.read_text(encoding="utf-8")
+
+
+def ensure_parent_directory(path: Path) -> None:
+    """Ensure the parent directory of ``path`` exists by creating it."""
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+
+def rename(path: Path, target: Path) -> None:
+    """Rename ``path`` to ``target`` using ``Path.rename`` semantics."""
+
+    path.rename(target)

mcp_kb-0.1.0.dist-info/METADATA

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: mcp-kb
+Version: 0.1.0
+Summary: MCP server exposing a local markdown knowledge base
+Author: LLM Maintainer
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: chromadb>=1.1.0
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: mcp[cli]>=1.15.0
+Provides-Extra: vector
+Requires-Dist: tiktoken>=0.11.0; extra == "vector"
+Requires-Dist: langchain-text-splitters>=0.3.11; extra == "vector"
+
+# 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
+`.docs/` 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.1.0.dist-info/RECORD

@@ -0,0 +1,26 @@
+mcp_kb/__init__.py,sha256=Ry7qODhfFQF6u6p2m3bwGWhB0-BdWTQcHDJB7NBYAio,74
+mcp_kb/config.py,sha256=snbGzbeUf-YXah_F4h2IzHzL_wII966Pf3LZWLKZ-uU,2506
+mcp_kb/cli/__init__.py,sha256=dEIRWFycAfPkha1S1Bj_Y6zkvEZv4eF0qtbF9t74r60,67
+mcp_kb/cli/args.py,sha256=0yU5lwjjUkgk91ksocqOdpqO_u5JU6xuCaayiOJ-5pQ,5371
+mcp_kb/cli/main.py,sha256=07pxHS4FRfhNO4EXWe_9psF7PV6axrY92U7kpZZHkA0,3864
+mcp_kb/cli/reindex.py,sha256=WxGCTX35ngXO2AjCXSP4TAUJDGcbCzEOIVl6NIFwVu8,2963
+mcp_kb/data/KNOWLEDBASE_DOC.md,sha256=jrjNdkXNZUIOBZYy9X9ZnRcRWoARJwCKh2pmpiI0oNw,1639
+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=P3IrPZW3SK3HVayTzyR3KNe_e8aPGiLDfpZswaLmMbE,21849
+mcp_kb/knowledge/__init__.py,sha256=W_dtRbtnQlrDJ_425vWR8BcoZGJ8gC5-wg1De1E654s,76
+mcp_kb/knowledge/bootstrap.py,sha256=DitA1x7i4ZMb9IZyWyw1oPh78iHz9VkHe03sBF9042U,1202
+mcp_kb/knowledge/events.py,sha256=A7CfD7U5bxo6mCCIic83yE7VPixAN05ssw_HKRF2zxw,3549
+mcp_kb/knowledge/search.py,sha256=_hfN89GPoJn-Y1TEEfnYawkgOGxOn_3-f7-lzdAqbMA,5901
+mcp_kb/knowledge/store.py,sha256=JP8_vGMzm6HYxg2Y2LUB1fnguIWYokuO1yCRh2pLym4,9598
+mcp_kb/security/__init__.py,sha256=lF8_XAjzpwhAFresuskXMo0u9v7KFiTJId88wqOAM4Y,62
+mcp_kb/security/path_validation.py,sha256=lhyL1WUVCb4ypxmJx8drGmR7y_b7nNohz_JFRWJ25MQ,3617
+mcp_kb/server/__init__.py,sha256=j9TmxW_WLCoibyQvCsDT1MIuUqSL8sRh2h4u0M4eU0c,74
+mcp_kb/server/app.py,sha256=GnI2z_6C0wwbJd1r-GheQMn1nc4xj71A51_xKLyCUoU,7070
+mcp_kb/utils/__init__.py,sha256=lKhRsjgnbhye1sSlch1_wsAI3eWKE1M6RVIiNlnsvLI,71
+mcp_kb/utils/filesystem.py,sha256=Uyo_lHXF35qRxNXsyDkCs6NC0pDqwDt-D6dw0xtYZQE,2632
+mcp_kb-0.1.0.dist-info/METADATA,sha256=KCfsCIxMSzOzsE7HXtvSmb9d8ouK7ILbab4XNqZjP2Y,5103
+mcp_kb-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+mcp_kb-0.1.0.dist-info/entry_points.txt,sha256=qwJkR3vV7ZeydfS_IYMiDwLv4BdTkrOf4-5neWj25g0,96
+mcp_kb-0.1.0.dist-info/top_level.txt,sha256=IBiz3TNE3FF3TwkbCZpC1kkk6ohTwtBQNSPJNV3-qGA,7
+mcp_kb-0.1.0.dist-info/RECORD,,

mcp_kb-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mcp_kb-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+mcp-kb-reindex = mcp_kb.cli.reindex:main
+mcp-kb-server = mcp_kb.cli.main:main

mcp_kb-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+mcp_kb