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

mcp_kb/server/app.py

@@ -1,201 +0,0 @@
-"""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 text-based 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 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."""
-
-        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

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

mcp_kb/utils/filesystem.py

@@ -1,127 +0,0 @@
-"""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)
-
-
-def is_text_file(path: Path, max_bytes: int = 2048) -> bool:
-    """Heuristically determine whether ``path`` contains UTF-8 text.
-
-    The check is designed to be fast and conservative for use when iterating
-    a directory tree. It reads at most ``max_bytes`` from the file in binary
-    mode and applies two filters:
-
-    - Reject files that contain NUL bytes, which are extremely uncommon in
-      textual formats and a strong indicator of binary content.
-    - Attempt to decode the sampled bytes as UTF-8. If decoding fails, the
-      file is treated as binary.
-
-    Parameters
-    ----------
-    path:
-        Absolute path to the file on disk.
-    max_bytes:
-        Upper bound on the number of bytes to sample from the head of the
-        file. A small sample keeps directory scans fast while remaining
-        accurate for typical text formats such as ``.md``, ``.txt``, ``.xml``,
-        and source files.
-
-    Returns
-    -------
-    bool
-        ``True`` if the file appears to be UTF-8 text; ``False`` otherwise.
-    """
-
-    try:
-        with path.open("rb") as handle:
-            sample = handle.read(max_bytes)
-    except (FileNotFoundError, PermissionError):  # pragma: no cover - defensive
-        return False
-
-    if b"\x00" in sample:
-        return False
-
-    try:
-        sample.decode("utf-8")
-        return True
-    except UnicodeDecodeError:
-        return False

mcp_kb-0.2.0.dist-info/RECORD

@@ -1,26 +0,0 @@
-mcp_kb/__init__.py,sha256=Ry7qODhfFQF6u6p2m3bwGWhB0-BdWTQcHDJB7NBYAio,74
-mcp_kb/config.py,sha256=VallCc3_Bjcm2FPElthupvXdbMuXvDkiTkQKj0f4dkQ,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=FMsnWcXmEsXXfETyvPMP2il9jREGFWmR8t23-6QfhMo,3864
-mcp_kb/cli/reindex.py,sha256=UBBN7_u9rcgGXel5FKnnA3yd7a-AQMwHMwQjt7ZFrSs,3033
-mcp_kb/data/KNOWLEDBASE_DOC.md,sha256=bkSpdK1W3F0KR6d3q4V_23fnY8Kw2IBjXPvTTRv06AI,1663
-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=3Kt7or1Z9ng-wBeXeuOPhrVIfjokwkF25jKHdAeYSH8,22170
-mcp_kb/knowledge/__init__.py,sha256=W_dtRbtnQlrDJ_425vWR8BcoZGJ8gC5-wg1De1E654s,76
-mcp_kb/knowledge/bootstrap.py,sha256=WlbJUXhxglyWjlvwhUdT20oijLNLaZOePQ6nYwfBCxk,1202
-mcp_kb/knowledge/events.py,sha256=A7CfD7U5bxo6mCCIic83yE7VPixAN05ssw_HKRF2zxw,3549
-mcp_kb/knowledge/search.py,sha256=AKsyNipsA8bfRxIJb49tdsU4ICzbHeFrA1Ikvlk1u7w,5901
-mcp_kb/knowledge/store.py,sha256=urZaLrSRjgqxb_hLC6RQjDeNw8Id14ripQH_6HdWb3o,10002
-mcp_kb/security/__init__.py,sha256=lF8_XAjzpwhAFresuskXMo0u9v7KFiTJId88wqOAM4Y,62
-mcp_kb/security/path_validation.py,sha256=21bfKdxjHY-ywDYw0DcGCeXDnvdXDILWVuueUsuuZUM,3617
-mcp_kb/server/__init__.py,sha256=j9TmxW_WLCoibyQvCsDT1MIuUqSL8sRh2h4u0M4eU0c,74
-mcp_kb/server/app.py,sha256=7s10UJWFopJ4CZPqZ4briTKsfjDiRo44ZbLAeWb6Lj8,7064
-mcp_kb/utils/__init__.py,sha256=lKhRsjgnbhye1sSlch1_wsAI3eWKE1M6RVIiNlnsvLI,71
-mcp_kb/utils/filesystem.py,sha256=0M-Waf2vfqhp8UL__2Emfpwpoqxshti3M7XLjXnpjJw,4026
-mcp_kb-0.2.0.dist-info/METADATA,sha256=AjAH4xcztes0PzJkjW3J9qyes0VDXS7jfsJFQMq2s1g,5122
-mcp_kb-0.2.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-mcp_kb-0.2.0.dist-info/entry_points.txt,sha256=qwJkR3vV7ZeydfS_IYMiDwLv4BdTkrOf4-5neWj25g0,96
-mcp_kb-0.2.0.dist-info/top_level.txt,sha256=IBiz3TNE3FF3TwkbCZpC1kkk6ohTwtBQNSPJNV3-qGA,7
-mcp_kb-0.2.0.dist-info/RECORD,,