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

mcp_kb/knowledge/events.py

@@ -1,100 +0,0 @@
-"""Change event types and listener contracts for knowledge base updates.
-
-The knowledge base emits high-level events whenever a markdown document is
-created, updated, or soft deleted. Downstream components can subscribe to these
-notifications to implement side effects such as vector database ingestion without
-coupling the core filesystem logic to specific backends. Each event captures both
-absolute and knowledge-base-relative paths so that listeners can decide which
-identifier best fits their storage requirements.
-"""
-from __future__ import annotations
-
-from dataclasses import dataclass
-from pathlib import Path
-from typing import Optional, Protocol, runtime_checkable, TYPE_CHECKING
-
-if TYPE_CHECKING:  # pragma: no cover - type hints only
-    from typing import List
-
-    from mcp_kb.knowledge.search import SearchMatch
-    from mcp_kb.knowledge.store import KnowledgeBase
-
-
-@dataclass(frozen=True)
-class FileUpsertEvent:
-    """Describes a document that was created or updated inside the knowledge base.
-
-    Attributes
-    ----------
-    absolute_path:
-        Fully resolved path to the document on disk. Listeners that need direct
-        filesystem access can rely on this value to open the file again.
-    relative_path:
-        Path relative to the configured knowledge base root. This identifier is
-        stable across restarts and makes for concise IDs in downstream systems.
-    content:
-        Full markdown content of the updated document at the time the event was
-        emitted. Listeners can avoid re-reading the file when they only need the
-        text payload.
-    """
-
-    absolute_path: Path
-    relative_path: str
-    content: str
-
-
-@dataclass(frozen=True)
-class FileDeleteEvent:
-    """Signals that a document has been soft deleted according to PRD semantics.
-
-    Attributes
-    ----------
-    absolute_path:
-        Fully resolved path that now contains the soft-deleted file. The path
-        may include the configured delete sentinel in its name.
-    relative_path:
-        Original knowledge-base-relative path before soft deletion. Downstream
-        systems should remove entries keyed by this relative path to stay in
-        sync with the knowledge base state.
-    """
-
-    absolute_path: Path
-    relative_path: str
-
-
-class KnowledgeBaseListener(Protocol):
-    """Interface for components that react to knowledge base change events."""
-
-    def handle_upsert(self, event: FileUpsertEvent) -> None:
-        """Persist changes triggered by a document creation or update event."""
-
-    def handle_delete(self, event: FileDeleteEvent) -> None:
-        """Process the removal of a previously ingested document."""
-
-
-@runtime_checkable
-class KnowledgeBaseSearchListener(Protocol):
-    """Optional extension that allows listeners to service search requests."""
-
-    def search(
-        self,
-        kb: "KnowledgeBase",
-        query: str,
-        *,
-        context_lines: int = 2,
-        limit: Optional[int] = None,
-    ) -> "List[SearchMatch]":
-        """Return semantic search matches for ``query`` or an empty list."""
-
-
-@runtime_checkable
-class KnowledgeBaseReindexListener(Protocol):
-    """Optional extension that allows listeners to perform full reindexing.
-
-    Implementations can expose a ``reindex`` method to rebuild any external
-    indexes from the current state of the knowledge base. The method should be
-    idempotent and safe to run multiple times.
-    """
-
-    def reindex(self, kb: "KnowledgeBase") -> int:
-        """Rebuild indexes, returning the number of documents processed."""

mcp_kb/knowledge/search.py

@@ -1,178 +0,0 @@
-"""Search utilities that operate on the knowledge base filesystem.
-
-The functions in this module are separate from ``KnowledgeBase`` so that they
-can evolve independently. Search often benefits from dedicated caching or
-indexing strategies; keeping it in its own module means the server can swap the
-implementation later without changing the core file lifecycle API.
-"""
-from __future__ import annotations
-
-from dataclasses import dataclass
-from pathlib import Path
-from typing import Dict, Iterable, List, Optional
-
-from mcp_kb.config import DATA_FOLDER_NAME, DOC_FILENAME
-from mcp_kb.knowledge.events import KnowledgeBaseSearchListener
-from mcp_kb.knowledge.store import KnowledgeBase
-
-
-@dataclass
-class SearchMatch:
-    """Represents a search hit with surrounding context."""
-
-    path: Path
-    line_number: int
-    context: List[str]
-
-
-def search_text(
-    kb: KnowledgeBase,
-    query: str,
-    context_lines: int = 2,
-    *,
-    providers: Iterable[KnowledgeBaseSearchListener] | None = None,
-    n_results: Optional[int] = None,
-) -> List[SearchMatch]:
-    """Search for ``query`` in all non-deleted knowledge base files.
-
-    Parameters
-    ----------
-    kb:
-        Active knowledge base instance used to iterate over files.
-    query:
-        Literal string that should be located within the files. The helper does
-        not treat the query as a regular expression to avoid surprising matches
-        when characters such as ``*`` appear in user input.
-    context_lines:
-        Number of lines to include before and after each match. Defaults to two
-        lines, aligning with the PRD's requirement for contextual snippets.
-    providers:
-        Optional iterable of listeners capable of serving semantic search
-        results. Providers are consulted in order and the first non-empty
-        response is returned to the caller. When no provider produces results the
-        function falls back to a filesystem scan.
-    n_results:
-        Maximum number of matches to return. ``None`` keeps the legacy behaviour
-        of returning every match discovered on disk.
-
-    Returns
-    -------
-    list[SearchMatch]
-        Ordered list of matches. Each match contains the absolute path, the
-        one-based line number where the query was found, and the extracted
-        context lines.
-    """
-
-    for provider in providers or ():
-        try:
-            matches = provider.search(
-                kb,
-                query,
-                context_lines=context_lines,
-                limit=n_results,
-            )
-        except Exception as exc:  # pragma: no cover - defensive path
-            raise RuntimeError(f"Search provider {provider!r} failed: {exc}") from exc
-        if matches:
-            return matches
-
-    return _search_by_scanning(kb, query, context_lines, n_results)
-
-
-def _search_by_scanning(
-    kb: KnowledgeBase,
-    query: str,
-    context_lines: int,
-    n_results: Optional[int],
-) -> List[SearchMatch]:
-    """Return search matches by scanning files on disk."""
-
-    matches: List[SearchMatch] = []
-    for path in kb.iter_active_files():
-        matches.extend(_extract_matches_for_path(path, query, context_lines))
-        if n_results is not None and len(matches) >= n_results:
-            return matches[:n_results]
-    return matches
-
-
-def _build_tree(paths: List[List[str]]) -> Dict[str, Dict]:
-    """Construct a nested dictionary representing the directory tree."""
-
-    tree: Dict[str, Dict] = {}
-    for parts in paths:
-        current = tree
-        for part in parts:
-            current = current.setdefault(part, {})
-    return tree
-
-
-def _flatten_tree(tree: Dict[str, Dict], prefix: str = "  ") -> List[str]:
-    """Convert a nested dictionary tree into indented lines."""
-
-    lines: List[str] = []
-    for name in sorted(tree.keys()):
-        lines.append(f"{prefix}- {name}")
-        lines.extend(_flatten_tree(tree[name], prefix + "  "))
-    return lines
-
-
-def build_tree_overview(kb: KnowledgeBase) -> str:
-    """Produce a textual tree showing the structure of the knowledge base.
-
-    The output intentionally mirrors a simplified ``tree`` command but remains
-    deterministic across operating systems by controlling ordering and
-    indentation.
-    """
-
-    relative_paths = [
-        list(path.relative_to(kb.rules.root).parts) for path in kb.iter_active_files()
-    ]
-    tree = _build_tree(relative_paths)
-    lines = [f"{kb.rules.root.name}/"] if kb.rules.root.name else ["./"]
-    lines.extend(_flatten_tree(tree))
-    return "\n".join(lines)
-
-
-def read_documentation(kb: KnowledgeBase) -> str:
-    """Return documentation content if the canonical file exists.
-
-    The helper intentionally performs no access control checks because read
-    operations are always permitted, even for the protected documentation
-    folder.
-    """
-
-    doc_path = kb.rules.root / DATA_FOLDER_NAME / DOC_FILENAME
-    if not doc_path.exists():
-        return ""
-    return doc_path.read_text(encoding="utf-8")
-
-
-def _extract_matches_for_path(path: Path, query: str, context_lines: int) -> List[SearchMatch]:
-    """Read ``path`` and return every match that contains ``query``."""
-
-    lines = path.read_text(encoding="utf-8").splitlines()
-    return _extract_matches_from_lines(path, lines, query, context_lines)
-
-
-def _extract_matches_from_lines(
-    path: Path,
-    lines: List[str],
-    query: str,
-    context_lines: int,
-) -> List[SearchMatch]:
-    """Return matches using the provided ``lines`` buffer."""
-
-    matches: List[SearchMatch] = []
-    for index, line in enumerate(lines, start=1):
-        if query in line:
-            start = max(0, index - context_lines - 1)
-            end = min(len(lines), index + context_lines)
-            context = lines[start:end]
-            matches.append(SearchMatch(path=path, line_number=index, context=context))
-    return matches
-
-
-__all__ = [
-    "SearchMatch",
-    "search_text",
-]

mcp_kb/knowledge/store.py

@@ -1,263 +0,0 @@
-"""Core knowledge base operations for file lifecycle management.
-
-This module exposes the ``KnowledgeBase`` class, which orchestrates validated
-filesystem operations for the MCP server. The class encapsulates logic for
-creating, reading, appending, and modifying text files while respecting the
-security constraints defined in the PRD. Each method returns plain Python data
-structures so that higher-level layers (e.g., JSON-RPC handlers) can focus on
-protocol serialization rather than filesystem minutiae.
-"""
-from __future__ import annotations
-
-import re
-from dataclasses import dataclass
-from pathlib import Path
-from typing import Iterable, Optional
-
-from mcp_kb.config import DELETE_SENTINEL, DATA_FOLDER_NAME
-from mcp_kb.knowledge.events import FileDeleteEvent, FileUpsertEvent, KnowledgeBaseListener
-from mcp_kb.security.path_validation import (
-    PathRules,
-    ensure_write_allowed,
-    normalize_path,
-)
-from mcp_kb.utils.filesystem import (
-    FileLockRegistry,
-    append_text,
-    ensure_parent_directory,
-    read_text,
-    rename,
-    write_text,
-)
-
-
-@dataclass
-class FileSegment:
-    """Represents a snippet of file content returned to MCP clients."""
-
-    path: Path
-    start_line: int
-    end_line: int
-    content: str
-
-
-class KnowledgeBase:
-    """High-level API that executes validated knowledge base operations.
-
-    The class is intentionally stateless aside from the path rules and lock
-    registry. Stateless methods make this component easy to reuse across tests
-    and potential future transports. Locking responsibilities are scoped to the
-    knowledge base to keep write safety consistent across entry points.
-    """
-
-    def __init__(
-        self,
-        rules: PathRules,
-        lock_registry: FileLockRegistry | None = None,
-        listeners: Iterable[KnowledgeBaseListener] | None = None,
-    ) -> None:
-        """Initialize the knowledge base with path rules and optional locks.
-
-        Parameters
-        ----------
-        rules:
-            Active path rules that govern which paths are safe to touch.
-        lock_registry:
-            Optional ``FileLockRegistry`` allowing tests to inject deterministic
-            locking behavior. A new registry is created when omitted.
-        listeners:
-            Optional iterable of callback objects that subscribe to change
-            events. Each listener must implement the
-            :class:`~mcp_kb.knowledge.events.KnowledgeBaseListener` protocol.
-            Events are dispatched synchronously after filesystem operations
-            succeed, which allows callers to maintain eventual consistency with
-            external systems such as vector databases.
-        """
-
-        self.rules = rules
-        self.locks = lock_registry or FileLockRegistry()
-        self.listeners = tuple(listeners or ())
-
-    def create_file(self, relative_path: str, content: str) -> Path:
-        """Create or overwrite a text file at ``relative_path``.
-
-        The method validates the path, ensures that the parent directory exists,
-        and writes the provided content as UTF-8 text. Existing files are
-        overwritten to match the PRD, which views creation as setting the file
-        contents.
-        """
-
-        normalized = normalize_path(relative_path, self.rules)
-        ensure_write_allowed(normalized, self.rules)
-        ensure_parent_directory(normalized)
-        with self.locks.acquire(normalized):
-            write_text(normalized, content)
-        self._notify_upsert(normalized, content)
-        return normalized
-
-    def read_file(
-        self,
-        relative_path: str,
-        start_line: Optional[int] = None,
-        end_line: Optional[int] = None,
-    ) -> FileSegment:
-        """Read content from ``relative_path`` optionally constraining lines.
-
-        Parameters
-        ----------
-        relative_path:
-            Target file path relative to the knowledge base root.
-        start_line:
-            One-based index for the first line to include. ``None`` means start
-            from the beginning of the file.
-        end_line:
-            One-based index signaling the last line to include. ``None`` means
-            include content through the end of the file.
-        """
-
-        normalized = normalize_path(relative_path, self.rules)
-        full_content = read_text(normalized)
-        lines = full_content.splitlines()
-
-        if start_line is None and end_line is None:
-            segment_content = full_content
-            actual_start = 1
-            actual_end = len(lines)
-        else:
-            actual_start = start_line or 1
-            actual_end = end_line or len(lines)
-            if actual_start < 1 or actual_end < actual_start:
-                raise ValueError("Invalid line interval requested")
-            selected = lines[actual_start - 1 : actual_end]
-            segment_content = "\n".join(selected)
-
-        return FileSegment(
-            path=normalized,
-            start_line=actual_start,
-            end_line=actual_end,
-            content=segment_content,
-        )
-
-    def append_file(self, relative_path: str, content: str) -> Path:
-        """Append ``content`` to the file located at ``relative_path``.
-
-        Missing files are created automatically so that append operations remain
-        idempotent for clients.
-        """
-
-        normalized = normalize_path(relative_path, self.rules)
-        ensure_write_allowed(normalized, self.rules)
-        ensure_parent_directory(normalized)
-        with self.locks.acquire(normalized):
-            if not normalized.exists():
-                write_text(normalized, content)
-            else:
-                append_text(normalized, content)
-        updated_text = read_text(normalized)
-        self._notify_upsert(normalized, updated_text)
-        return normalized
-
-    def regex_replace(self, relative_path: str, pattern: str, replacement: str) -> int:
-        """Perform regex replacement and return the number of substitutions."""
-
-        normalized = normalize_path(relative_path, self.rules)
-        ensure_write_allowed(normalized, self.rules)
-        with self.locks.acquire(normalized):
-            text = read_text(normalized)
-            new_text, count = re.subn(pattern, replacement, text, flags=re.MULTILINE)
-            write_text(normalized, new_text)
-        self._notify_upsert(normalized, new_text)
-        return count
-
-    def soft_delete(self, relative_path: str) -> Path:
-        """Apply soft deletion semantics by appending the deletion sentinel."""
-
-        normalized = normalize_path(relative_path, self.rules)
-        ensure_write_allowed(normalized, self.rules)
-        if not normalized.exists():
-            raise FileNotFoundError(f"File '{relative_path}' does not exist")
-
-        target_name = f"{normalized.stem}{DELETE_SENTINEL}{normalized.suffix}"
-        target = normalized.with_name(target_name)
-        ensure_write_allowed(target, self.rules)
-        with self.locks.acquire(normalized):
-            rename(normalized, target)
-        original_relative = self._relative_path(normalized)
-        self._notify_delete(target, original_relative)
-        return target
-    
-    def total_active_files(self, include_docs: bool = False) -> int:
-        """Return the total number of non-deleted UTF-8 text files under the root directory.
-        """
-        return sum(1 for _ in self.iter_active_files(include_docs=include_docs))
-
-    def iter_active_files(self, include_docs: bool = False) -> Iterable[Path]:
-        """Yield non-deleted UTF-8 text files under the root directory.
-
-        Parameters
-        ----------
-        include_docs:
-            When ``True`` the generator includes files located in the protected
-            documentation folder. By default those files are skipped to match
-            the search and overview requirements from the PRD.
-        """
-
-        from mcp_kb.utils.filesystem import is_text_file
-
-        for path in self.rules.root.rglob("*"):
-            if not path.is_file():
-                continue
-            if DELETE_SENTINEL in path.name:
-                continue
-            parts = path.relative_to(self.rules.root).parts
-            if parts and parts[0] == DATA_FOLDER_NAME and not include_docs:
-                continue
-            if is_text_file(path):
-                yield path
-
-    def _relative_path(self, absolute: Path) -> str:
-        """Return ``absolute`` rewritten relative to the knowledge base root."""
-
-        return str(absolute.relative_to(self.rules.root))
-
-    def _notify_upsert(self, absolute: Path, content: str) -> None:
-        """Dispatch an upsert event to registered listeners.
-
-        Parameters
-        ----------
-        absolute:
-            Fully resolved path that was modified on disk.
-        content:
-            Text payload that should be provided to subscribers.
-        """
-
-        if not self.listeners:
-            return
-
-        event = FileUpsertEvent(
-            absolute_path=absolute,
-            relative_path=self._relative_path(absolute),
-            content=content,
-        )
-        self._dispatch("handle_upsert", event)
-
-    def _notify_delete(self, absolute: Path, relative: str) -> None:
-        """Dispatch a delete event to registered listeners."""
-
-        if not self.listeners:
-            return
-
-        event = FileDeleteEvent(absolute_path=absolute, relative_path=relative)
-        self._dispatch("handle_delete", event)
-
-    def _dispatch(self, method_name: str, event: FileUpsertEvent | FileDeleteEvent) -> None:
-        """Call ``method_name`` on every listener and wrap failures for clarity."""
-
-        for listener in self.listeners:
-            handler = getattr(listener, method_name)
-            try:
-                handler(event)  # type: ignore[misc]
-            except Exception as exc:  # pragma: no cover - defensive logging path
-                raise RuntimeError(
-                    f"Knowledge base listener {listener!r} failed during {method_name}: {exc}"
-                ) from exc

mcp_kb/security/__init__.py

@@ -1 +0,0 @@
-"""Security-related helpers such as path validation rules."""

mcp_kb/security/path_validation.py

@@ -1,105 +0,0 @@
-"""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 dataclasses import dataclass
-from pathlib import Path
-from typing import Iterable
-
-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.
-    """
-
-
-@dataclass(frozen=True)
-class PathRules:
-    """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: str, 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

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