mcp-kb 0.3.0__py3-none-any.whl → 0.3.2__py3-none-any.whl

mcp_kb/security/path_validation.py

@@ -0,0 +1,108 @@
+"""Path validation utilities to protect the knowledge base filesystem.
+
+This module implements reusable helpers that ensure every file operation stays
+inside the configured knowledge base root. The checks defend against directory
+traversal attempts (".." components), accidental absolute paths, and writes
+that target the reserved documentation folder. The helper functions are written
+so they can be reused both by the server runtime and by unit tests to keep the
+security rules consistent.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Iterable
+from pydantic import BaseModel
+
+from mcp_kb.config import DATA_FOLDER_NAME, DELETE_SENTINEL
+
+
+class PathValidationError(ValueError):
+    """Error raised when a path fails validation rules.
+
+    The server treats any instance of this exception as a client error: callers
+    attempted to access a disallowed path. Raising a dedicated subclass of
+    ``ValueError`` enables precise error handling and cleaner unit tests.
+    """
+
+
+class PathRules(BaseModel):
+    """Container for server-specific path constraints.
+
+    Attributes
+    ----------
+    root:
+        Absolute path that represents the root of the knowledge base. All file
+        operations must remain inside this directory tree.
+    protected_folders:
+        Iterable of folder names that are protected against mutations. The
+        server uses this to forbid modifications to the documentation folder
+        while still allowing read operations.
+    """
+    root: Path
+    protected_folders: Iterable[str]
+
+
+def normalize_path(candidate: Union[str, Path], rules: PathRules) -> Path:
+    """Normalize a relative path and ensure it stays inside the root.
+
+    Parameters
+    ----------
+    candidate:
+        The user-provided path, typically originating from an MCP tool request.
+    rules:
+        The active ``PathRules`` instance describing allowed operations.
+
+    Returns
+    -------
+    Path
+        A fully-resolved path that is guaranteed to be inside the root
+        directory.
+
+    Raises
+    ------
+    PathValidationError
+        If the candidate path is absolute, attempts traversal outside the root,
+        or resolves to a location that is not within the permitted tree.
+    """
+
+    path_obj = Path(candidate)
+    if path_obj.is_absolute():
+        raise PathValidationError(
+            "Absolute paths are not permitted inside the knowledge base"
+        )
+
+    normalized = (rules.root / path_obj).resolve()
+    try:
+        normalized.relative_to(rules.root)
+    except ValueError as exc:
+        raise PathValidationError(
+            "Path resolves outside the knowledge base root"
+        ) from exc
+
+    if DELETE_SENTINEL in normalized.name:
+        raise PathValidationError("Operations on soft-deleted files are not permitted")
+
+    return normalized
+
+
+def ensure_write_allowed(path: Path, rules: PathRules) -> None:
+    """Validate that a path resides outside protected folders before writing.
+
+    The function raises a ``PathValidationError`` when the path is located
+    inside one of the configured protected folders. Read operations can still
+    access those directories by skipping this check.
+
+    Parameters
+    ----------
+    path:
+        The already-normalized absolute path that will be used for writing.
+    rules:
+        The active ``PathRules`` instance describing allowed operations.
+    """
+
+    relative_parts = path.relative_to(rules.root).parts
+    if relative_parts and relative_parts[0] in set(rules.protected_folders):
+        raise PathValidationError(
+            f"Writes are not allowed inside the protected folder '{relative_parts[0]}'"
+        )

mcp_kb/server/__init__.py

@@ -0,0 +1 @@
+"""Server subpackage powering the FastMCP-based knowledge base server."""

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 typing import Iterable, List
+from pydantic import BaseModel
+
+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
+
+
+class ReadFileResult(BaseModel):
+    """Structured output for the ``kb.read_file`` tool."""
+
+    path: str
+    start_line: int
+    end_line: int
+    content: str
+
+
+class RegexReplaceResult(BaseModel):
+    """Structured output describing the number of replacements performed."""
+
+    replacements: int
+
+
+
+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 text-based knowledge base. Use the provided "
+            "tools to create, inspect, and organize content and search the knowledgebase for information.\n"
+            "Call the documentation tool first to get the latest documentation."
+        ),
+        **fastmcp_kwargs,
+    )
+
+    # Attach the knowledge base to the FastMCP instance for reuse by
+    # auxiliary servers (e.g., the human UI HTTP server). FastMCP does not
+    # expose a public extension API for storing arbitrary state, but keeping a
+    # direct attribute is harmless and enables tight coupling where needed.
+    # Downstream code should treat this as best-effort and feature-gated.
+    setattr(mcp, "kb", kb)  # type: ignore[attr-defined]
+
+    @mcp.tool(name="create_file", title="Create File")
+    def create_file(path: str, content: str) -> str:
+        """Create or overwrite a text 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 text file returning metadata about the extracted segment. 
+        start_line and end_line are 0-based line numbers.
+        """
+
+        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[FileSegment]:
+        """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,
+        )[0]
+
+        for match in matches:
+            match.assert_path(kb.rules)
+        return 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/ui/__init__.py

@@ -0,0 +1,17 @@
+"""Human-accessible UI for browsing and editing the knowledge base.
+
+This package exposes a tiny HTTP server using Python's standard library so we
+avoid introducing new runtime dependencies. The server mounts a minimal web UI
+with a menu bar and a "Browse" view that renders a file tree and a simple text
+editor. Changes are persisted via the same :class:`~mcp_kb.knowledge.store.KnowledgeBase`
+instance as the MCP server, ensuring that all registered listeners and
+triggers execute uniformly regardless of the entry point.
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "start_ui_server",
+]
+
+from .server import start_ui_server