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

mcp_kb/knowledge/__init__.py

@@ -0,0 +1 @@
+"""Knowledge layer that encapsulates content storage and search helpers."""

mcp_kb/knowledge/bootstrap.py

@@ -0,0 +1,44 @@
+"""Bootstrap helpers executed during server startup."""
+
+from __future__ import annotations
+
+import importlib.resources as resources
+from pathlib import Path
+
+from mcp_kb.config import DATA_FOLDER_NAME, DOC_FILENAME
+
+
+def install_default_documentation(root: Path) -> Path:
+    """Ensure the default documentation file exists under ``root``.
+
+    The function creates the documentation directory if necessary and copies the
+    packaged ``KNOWLEDBASE_DOC.md`` file into place. Existing documentation is
+    preserved so that operators can customize the file without losing changes on
+    subsequent startups.
+
+    Parameters
+    ----------
+    root:
+        Absolute path representing the knowledge base root directory.
+
+    Returns
+    -------
+    Path
+        Path to the documentation file inside the knowledge base tree.
+    """
+
+    docs_dir = root / DATA_FOLDER_NAME
+    doc_path = docs_dir / DOC_FILENAME
+    if doc_path.exists():
+        return doc_path
+
+    docs_dir.mkdir(parents=True, exist_ok=True)
+
+    with (
+        resources.files("mcp_kb.data")
+        .joinpath("KNOWLEDBASE_DOC.md")
+        .open("r", encoding="utf-8") as source
+    ):
+        doc_path.write_text(source.read(), encoding="utf-8")
+
+    return doc_path

mcp_kb/knowledge/events.py

@@ -0,0 +1,105 @@
+"""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 ast import Tuple
+from pathlib import Path
+from typing import Optional, Protocol, runtime_checkable, TYPE_CHECKING, Dict, Any
+from pydantic import BaseModel, model_validator
+
+if TYPE_CHECKING:  # pragma: no cover - type hints only
+    from typing import List
+
+    from mcp_kb.knowledge.store import KnowledgeBase
+
+
+class FileUpsertEvent(BaseModel):
+    """Describes a document that was created or updated inside the knowledge base.
+
+    Attributes
+    ----------
+    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.
+    """
+    path: str
+    content: str
+
+    # make sure path is a string
+    @model_validator(mode="before")
+    @classmethod
+    def check_path(cls, values: dict) -> dict:
+        if isinstance(values["path"], Path):
+            values["path"] = str(values["path"])
+        return values
+
+
+class FileDeleteEvent(BaseModel):
+    """Signals that a document has been soft deleted according to PRD semantics.
+
+    Attributes
+    ----------
+    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.
+    """
+    path: str
+
+    # make sure path is a string
+    @model_validator(mode="before")
+    @classmethod
+    def check_path(cls, values: dict) -> dict:
+        if isinstance(values["path"], Path):
+            values["path"] = str(values["path"])
+        return values
+
+
+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,
+    ) -> "Tuple[List[FileSegment], Dict[str, Any]]":
+        """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

@@ -0,0 +1,177 @@
+"""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 pathlib import Path
+from typing import Dict, Iterable, List, Optional, Literal, Any, Tuple
+
+from mcp_kb.config import DATA_FOLDER_NAME, DOC_FILENAME
+from mcp_kb.knowledge.events import KnowledgeBaseSearchListener
+from mcp_kb.knowledge.store import KnowledgeBase, FileSegment
+from pydantic import BaseModel
+
+
+def search_text(
+    kb: KnowledgeBase,
+    query: str,
+    context_lines: int = 2,
+    *,
+    providers: Iterable[KnowledgeBaseSearchListener] | None = None,
+    n_results: Optional[int] = None,
+) -> Tuple[List[FileSegment], Dict[str, Any]]:
+    """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[FileSegment]
+        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.
+    """
+
+    all_matches: List[FileSegment] = []
+    all_meta: Dict[str, Any] = {}
+    for provider in providers or ():
+        try:
+            matches,meta = 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:
+            all_matches.extend(matches)
+            all_meta.update(meta)
+
+    all_matches.extend(_search_by_scanning(kb, query, context_lines, n_results))
+    for match in all_matches:
+        match.assert_path(kb.rules)
+    return all_matches,all_meta
+
+
+def _search_by_scanning(
+    kb: KnowledgeBase,
+    query: str,
+    context_lines: int,
+    n_results: Optional[int],
+) -> List[FileSegment]:
+    """Return search matches by scanning files on disk."""
+
+    matches: List[FileSegment] = []
+    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.
+    """
+
+    paths = [
+        list(path.relative_to(kb.rules.root).parts) for path in kb.iter_active_files()
+    ]
+    tree = _build_tree(paths)
+    lines =  []
+    lines.extend(_flatten_tree(tree,prefix=""))
+    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[FileSegment]:
+    """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[FileSegment]:
+    """Return matches using the provided ``lines`` buffer."""
+
+    matches: List[FileSegment] = []
+    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 = '\n'.join(lines[start:end])
+            matches.append(FileSegment(
+                path=path, start_line=start, end_line=end, content=context))
+    return matches
+
+__all__ = [
+    "search_text",
+]

mcp_kb/knowledge/store.py

@@ -0,0 +1,294 @@
+"""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 pathlib import Path
+from typing import Iterable, Optional, Union
+
+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,
+)
+
+
+from pydantic import BaseModel, model_validator
+
+
+class FileSegment(BaseModel):
+    """Represents a snippet of file content returned to MCP clients.
+
+    The model captures a ``path``  (relative to the knowledge base root) 
+    along with one-based ``start_line`` and ``end_line`` indices and the 
+    extracted text ``content``. Using a Pydantic model makes structured output and
+    validation consistent across API layers.
+    """
+
+    path: str
+    start_line: int
+    end_line: int
+    content: str
+
+    @model_validator(mode="before")
+    @classmethod
+    def check_path(cls, values: dict) -> dict:
+        if isinstance(values["path"], Path):
+            values["path"] = str(values["path"])
+        return values
+
+    def assert_path(self,rules: PathRules) -> None:
+        rel_path = Path(self.path)
+        if not rel_path.is_absolute():
+            abspath = rules.root / rel_path
+        else:
+            abspath = rel_path
+        # make sure the relative path is inside the knowledge base root
+        if not abspath.is_relative_to(rules.root):
+            raise ValueError(f"Relative path {rel_path} is not in the knowledge base root")
+        # make sure the relative path is not in the protected folders
+        self.path = str(abspath.relative_to(rules.root))
+
+
+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, path: Union[str, Path], content: str) -> Path:
+        """Create or overwrite a text file at ``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(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(self._path(normalized), content)
+        return normalized
+
+    def read_file(
+        self,
+        path: Union[str, Path],
+        start_line: Optional[int] = None,
+        end_line: Optional[int] = None,
+    ) -> FileSegment:
+        """Read content from ``path`` optionally constraining lines.
+
+        Parameters
+        ----------
+        path:
+            Target file path relative to the knowledge base root.
+        start_line:
+            Zero-   based index for the first line to include. ``None`` means start
+            from the beginning of the file.
+        end_line:
+            Zero-based index signaling the last line to include. ``None`` means
+            include content through the end of the file.
+        """
+
+        normalized = normalize_path(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 = 0
+            actual_end = len(lines)-1
+        else:
+            actual_start = start_line or 0
+            actual_end = end_line or len(lines)-1
+            if actual_start < 0 or actual_end < actual_start:
+                raise ValueError("Invalid line interval requested")
+            selected = lines[actual_start : actual_end + 1]
+            segment_content = "\n".join(selected)
+
+        return FileSegment(
+            path=normalized,
+            start_line=actual_start,
+            end_line=actual_end,
+            content=segment_content,
+        )
+
+    def append_file(self, path: Union[str, Path], content: str) -> Path:
+        """Append ``content`` to the file located at ``path``.
+
+        Missing files are created automatically so that append operations remain
+        idempotent for clients.
+        """
+
+        normalized = normalize_path(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(self._path(normalized), updated_text)
+        return normalized
+
+    def regex_replace(self, path: Union[str, Path], pattern: str, replacement: str) -> int:
+        """Perform regex replacement and return the number of substitutions."""
+
+        normalized = normalize_path(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(self._path(normalized), new_text)
+        return count
+
+    def soft_delete(self, path: Union[str, Path]) -> Path:
+        """Apply soft deletion semantics by appending the deletion sentinel."""
+
+        normalized = normalize_path(path, self.rules)
+        ensure_write_allowed(normalized, self.rules)
+        if not normalized.exists():
+            raise FileNotFoundError(f"File '{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._path(normalized)
+        self._notify_delete(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 _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, relative: str, 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(
+            path=relative,
+            content=content,
+        )
+        self._dispatch("handle_upsert", event)
+
+    def _notify_delete(self,relative: str) -> None:
+        """Dispatch a delete event to registered listeners."""
+
+        if not self.listeners:
+            return
+
+        event = FileDeleteEvent(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

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