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

mcp_kb/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI subpackage exposing entry points for running the server."""

mcp_kb/cli/args.py

@@ -0,0 +1,175 @@
+"""Shared CLI argument wiring for knowledge base utilities.
+
+This module centralizes the definition of common command-line options and
+helpers so that multiple entry points (e.g., server and reindex commands) can
+remain small and focused while sharing consistent behavior. The helpers are
+careful to avoid embedding environment defaults directly into the argparse
+objects so that downstream consumers can layer persisted runtime configuration
+in between CLI flags and built-in defaults.
+"""
+
+from __future__ import annotations
+
+import argparse
+from argparse import ArgumentParser, Namespace
+from pathlib import Path
+from typing import Optional
+
+try:
+    from mcp_kb.ingest.chroma import SUPPORTED_CLIENTS, ChromaConfiguration, ChromaIngestor
+    W_CHROMA = True
+except ImportError:
+    W_CHROMA = False
+
+def parse_bool(value: str | bool | None) -> bool:
+    """Return ``True`` when ``value`` represents an affirmative boolean string.
+
+    The function accepts case-insensitive variants such as "true", "t",
+    "yes", and "1". ``None`` yields ``False``.
+    """
+
+    if isinstance(value, bool):
+        return value
+    if value is None:
+        return False
+    return value.lower() in {"1", "true", "t", "yes", "y"}
+
+
+def add_chroma_arguments(parser: ArgumentParser) -> None:
+    """Register Chroma ingestion arguments on ``parser``.
+
+    The parser intentionally suppresses defaults for all options so that the
+    calling code can merge CLI flags, environment variables, and persisted
+    runtime configuration explicitly. This keeps precedence handling in a
+    single location rather than scattering logic across the argument
+    registrations themselves.
+    """
+    if not W_CHROMA:
+        return None
+
+    parser.add_argument(
+        "--chroma-client",
+        dest="chroma_client",
+        choices=SUPPORTED_CLIENTS,
+        default=argparse.SUPPRESS,
+        help="Client implementation for mirroring data to ChromaDB (default: persistent).",
+    )
+    parser.add_argument(
+        "--chroma-collection",
+        dest="chroma_collection",
+        default=argparse.SUPPRESS,
+        help="Chroma collection name used to store documents.",
+    )
+    parser.add_argument(
+        "--chroma-embedding",
+        dest="chroma_embedding",
+        default=argparse.SUPPRESS,
+        help="Embedding function name registered with chromadb.utils.embedding_functions.",
+    )
+    parser.add_argument(
+        "--chroma-data-dir",
+        dest="chroma_data_dir",
+        default=argparse.SUPPRESS,
+        help="Storage directory for the persistent Chroma client.",
+    )
+    parser.add_argument(
+        "--chroma-host",
+        dest="chroma_host",
+        default=argparse.SUPPRESS,
+        help="Target host for HTTP or cloud Chroma clients.",
+    )
+    parser.add_argument(
+        "--chroma-port",
+        dest="chroma_port",
+        type=int,
+        default=argparse.SUPPRESS,
+        help="Port for the HTTP Chroma client.",
+    )
+    parser.add_argument(
+        "--chroma-ssl",
+        dest="chroma_ssl",
+        type=parse_bool,
+        default=argparse.SUPPRESS,
+        help="Toggle SSL for the HTTP Chroma client (default: true).",
+    )
+    parser.add_argument(
+        "--chroma-tenant",
+        dest="chroma_tenant",
+        default=argparse.SUPPRESS,
+        help="Tenant identifier for Chroma Cloud deployments.",
+    )
+    parser.add_argument(
+        "--chroma-database",
+        dest="chroma_database",
+        default=argparse.SUPPRESS,
+        help="Database name for Chroma Cloud deployments.",
+    )
+    parser.add_argument(
+        "--chroma-api-key",
+        dest="chroma_api_key",
+        default=argparse.SUPPRESS,
+        help="API key used to authenticate against Chroma Cloud.",
+    )
+    parser.add_argument(
+        "--chroma-custom-auth",
+        dest="chroma_custom_auth",
+        default=argparse.SUPPRESS,
+        help="Optional custom auth credentials for self-hosted HTTP deployments.",
+    )
+    parser.add_argument(
+        "--chroma-id-prefix",
+        dest="chroma_id_prefix",
+        default=argparse.SUPPRESS,
+        help="Prefix applied to document IDs stored in Chroma (default: kb::).",
+    )
+    parser.add_argument(
+        "--chroma-sentence-transformer",
+        dest="chroma_sentence_transformer",
+        default=argparse.SUPPRESS,
+        help="Sentence transformer model name.",
+    )
+    parser.add_argument(
+        "--chroma-chunk-size",
+        dest="chroma_chunk_size",
+        type=int,
+        default=argparse.SUPPRESS,
+        help="Chunk size for the sentence transformer model.",
+    )
+    parser.add_argument(
+        "--chroma-chunk-overlap",
+        dest="chroma_chunk_overlap",
+        type=int,
+        default=argparse.SUPPRESS,
+        help="Chunk overlap for the sentence transformer model.",
+    )
+
+
+def build_chroma_listener(options: Namespace, root: Path) -> Optional[ChromaIngestor]:
+    """Construct a Chroma listener from parsed CLI options when enabled.
+
+    Returns ``None`` when the configured client type is ``off``.
+    """
+    if not W_CHROMA:
+        return None
+
+    configuration = ChromaConfiguration.from_options(
+        root=root,
+        client_type=options.chroma_client,
+        collection_name=options.chroma_collection,
+        embedding=options.chroma_embedding,
+        data_directory=options.chroma_data_dir,
+        host=options.chroma_host,
+        port=options.chroma_port,
+        ssl=options.chroma_ssl,
+        tenant=options.chroma_tenant,
+        database=options.chroma_database,
+        api_key=options.chroma_api_key,
+        custom_auth_credentials=options.chroma_custom_auth,
+        id_prefix=options.chroma_id_prefix,
+        sentence_transformer=options.chroma_sentence_transformer,
+        chunk_size=options.chroma_chunk_size,
+        chunk_overlap=options.chroma_chunk_overlap,
+    )
+    if not configuration.enabled:
+        return None
+    return ChromaIngestor(configuration)

mcp_kb/cli/main.py

@@ -0,0 +1,181 @@
+"""Command line interface for running the MCP knowledge base server."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import logging
+from typing import Iterable, List
+
+from mcp_kb.config import DATA_FOLDER_NAME, resolve_knowledge_base_root
+from mcp_kb.cli.args import add_chroma_arguments, build_chroma_listener
+from mcp_kb.cli.runtime_config import (
+    apply_cli_runtime_configuration,
+    load_runtime_configuration,
+    persist_runtime_configuration,
+)
+try:
+    from mcp_kb.ingest.chroma import ChromaIngestor
+    W_CHROMA = True
+except ImportError:
+    if TYPE_CHECKING:
+        ChromaIngestor = None
+    W_CHROMA = False
+from mcp_kb.knowledge.bootstrap import install_default_documentation
+from mcp_kb.security.path_validation import PathRules
+from mcp_kb.server.app import create_fastmcp_app
+from mcp.server.fastmcp import FastMCP
+from mcp_kb.ui import start_ui_server
+
+logging.basicConfig(level=logging.INFO)
+
+logger = logging.getLogger(__name__)
+
+
+def _build_argument_parser() -> argparse.ArgumentParser:
+    """Create and return the argument parser used by ``main``."""
+
+    parser = argparse.ArgumentParser(
+        description="Run the MCP knowledge base server", allow_abbrev=False
+    )
+    parser.add_argument(
+        "--root",
+        dest="root",
+        default=argparse.SUPPRESS,
+        help="Optional path to the knowledge base root (defaults to environment configuration)",
+    )
+    parser.add_argument(
+        "--transport",
+        dest="transports",
+        action="append",
+        choices=["stdio", "sse", "http"],
+        default=argparse.SUPPRESS,
+        help="Transport protocol to enable (repeatable). Defaults to stdio only.",
+    )
+    parser.add_argument(
+        "--host",
+        dest="host",
+        default=argparse.SUPPRESS,
+        help="Host interface for HTTP/SSE transports (default 127.0.0.1).",
+    )
+    parser.add_argument(
+        "--port",
+        dest="port",
+        type=int,
+        default=argparse.SUPPRESS,
+        help="Port for HTTP/SSE transports (default 8000).",
+    )
+    parser.add_argument(
+        "--ui-port",
+        dest="ui_port",
+        type=int,
+        default=argparse.SUPPRESS,
+        help=(
+            "Starting port for the human UI (default 8765). If occupied, the UI "
+            "server increments the port by 1 until a free one is found."
+        ),
+    )
+    parser.add_argument(
+        "--no-ui",
+        dest="no_ui",
+        action="store_true",
+        help=(
+            "Disable the human UI entirely, even when HTTP/SSE transports are active."
+        ),
+    )
+
+    if W_CHROMA:
+        add_chroma_arguments(parser)
+    return parser
+
+
+async def _run_transports(server: FastMCP, transports: List[str]) -> None:
+    """Run all selected transport protocols concurrently."""
+
+    coroutines = []
+    for name in transports:
+        if name == "stdio":
+            coroutines.append(server.run_stdio_async())
+        elif name == "sse":
+            coroutines.append(server.run_sse_async())
+        elif name == "http":
+            coroutines.append(server.run_streamable_http_async())
+        else:  # pragma: no cover - argparse restricts values
+            raise ValueError(f"Unsupported transport: {name}")
+
+    await asyncio.gather(*coroutines)
+
+
+def run_server(arguments: Iterable[str] | None = None) -> None:
+    """Entry point used by both CLI invocations and unit tests.
+
+    Besides orchestrating the server lifecycle, the function resolves
+    configuration values by layering command-line arguments over environment
+    variables and any persisted defaults stored in the knowledge base data
+    directory. The resolved mapping is written back to disk so that future runs
+    inherit the same defaults unless explicitly overridden.
+    """
+
+    parser = _build_argument_parser()
+    options = parser.parse_args(arguments)
+    root_path = resolve_knowledge_base_root(getattr(options, "root", None))
+
+    persisted_config = load_runtime_configuration(root_path)
+    resolved_config = apply_cli_runtime_configuration(
+        options,
+        root=root_path,
+        persisted=persisted_config,
+    )
+    rules = PathRules(root=root_path, protected_folders=(DATA_FOLDER_NAME,))
+    install_default_documentation(root_path)
+    listeners: List[ChromaIngestor] = []
+    try:
+        listener = build_chroma_listener(options, root_path)
+    except Exception as exc:  # pragma: no cover - configuration errors
+        logger.exception(exc)
+        raise SystemExit(f"Failed to configure Chroma ingestion: {exc}") from exc
+    if listener is not None:
+        listeners.append(listener)
+        logger.info(
+            "Chroma ingestion enabled (client=%s, collection=%s)",
+            options.chroma_client,
+            options.chroma_collection,
+        )
+    server = create_fastmcp_app(
+        rules,
+        host=options.host,
+        port=options.port,
+        listeners=listeners,
+    )
+    transports = options.transports or ["stdio"]
+    options.transports = transports
+    resolved_config["transports"] = transports
+    logger.info(
+        f"Running server on {options.host}:{options.port} with transports {transports}"
+    )
+    logger.info(f"Data root is {root_path}")
+    
+    # Start the human-accessible UI when an HTTP-capable transport is active.
+    if not options.no_ui and any(t in ("http", "sse") for t in transports):
+        kb = getattr(server, "kb", None)
+        if kb is not None:
+            ui = start_ui_server(
+                kb,
+                host=options.host or "127.0.0.1",
+                port=options.ui_port,
+            )
+            logger.info("UI available at http://%s:%d", ui.host, ui.port)
+
+    persist_runtime_configuration(root_path, resolved_config)
+
+    asyncio.run(_run_transports(server, transports))
+
+
+def main() -> None:
+    """CLI hook that executes :func:`run_server`."""
+
+    run_server()
+
+
+if __name__ == "__main__":
+    main()

mcp_kb/cli/reindex.py

@@ -0,0 +1,113 @@
+"""CLI command to reindex the knowledge base into configured ingestors.
+
+This command does not expose an MCP tool. Instead, it builds the configured
+ingestors and calls their ``reindex`` method when available, allowing operators
+to trigger a full rebuild of external indexes (e.g., Chroma) from the current
+filesystem state.
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+from typing import Iterable, List
+
+from mcp_kb.cli.args import add_chroma_arguments, build_chroma_listener
+from mcp_kb.cli.runtime_config import (
+    apply_cli_runtime_configuration,
+    load_runtime_configuration,
+    persist_runtime_configuration,
+)
+from mcp_kb.config import DATA_FOLDER_NAME, resolve_knowledge_base_root
+from mcp_kb.knowledge.events import KnowledgeBaseReindexListener
+from mcp_kb.knowledge.store import KnowledgeBase
+from mcp_kb.security.path_validation import PathRules
+
+
+logger = logging.getLogger(__name__)
+
+
+def _build_argument_parser() -> argparse.ArgumentParser:
+    """Return the argument parser for the reindex command."""
+
+    parser = argparse.ArgumentParser(
+        description="Reindex the knowledge base into configured backends",
+        allow_abbrev=False,
+    )
+    parser.add_argument(
+        "--root",
+        dest="root",
+        default=argparse.SUPPRESS,
+        help="Optional path to the knowledge base root (defaults to environment configuration)",
+    )
+    add_chroma_arguments(parser)
+    return parser
+
+
+def run_reindex(arguments: Iterable[str] | None = None) -> int:
+    """Execute a reindex run across all registered ingestors.
+
+    The function constructs a :class:`~mcp_kb.knowledge.store.KnowledgeBase`
+    using the same root resolution logic as the server, builds any enabled
+    ingestion listeners from CLI options, and invokes ``reindex`` on those that
+    implement the optional protocol. Configuration precedence mirrors the main
+    server: command-line arguments override environment variables, which in
+    turn override the last persisted configuration snapshot. The resolved
+    mapping is written back to disk so the next invocation inherits the same
+    defaults.
+
+    Parameters
+    ----------
+    arguments:
+        Optional iterable of command-line arguments, primarily used by tests.
+
+    Returns
+    -------
+    int
+        The total number of documents processed across all reindex-capable
+        listeners.
+    """
+
+    parser = _build_argument_parser()
+    options = parser.parse_args(arguments)
+    root_path = resolve_knowledge_base_root(getattr(options, "root", None))
+
+    persisted_config = load_runtime_configuration(root_path)
+    resolved_config = apply_cli_runtime_configuration(
+        options,
+        root=root_path,
+        persisted=persisted_config,
+    )
+    rules = PathRules(root=root_path, protected_folders=(DATA_FOLDER_NAME,))
+    kb = KnowledgeBase(rules)
+
+    listeners: List[KnowledgeBaseReindexListener] = []
+    try:
+        chroma = build_chroma_listener(options, root_path)
+    except Exception as exc:  # pragma: no cover - configuration errors
+        logger.exception(exc)
+        raise SystemExit(f"Failed to configure Chroma ingestion: {exc}") from exc
+    if chroma is not None and isinstance(chroma, KnowledgeBaseReindexListener):
+        listeners.append(chroma)
+
+    total = 0
+    for listener in listeners:
+        logger.info("Reindexing via %s", listener.__class__.__name__)
+        count = listener.reindex(kb)
+        logger.info("Reindexed %d documents via %s", count, listener.__class__.__name__)
+        total += count
+
+    persist_runtime_configuration(root_path, resolved_config)
+
+    return total
+
+
+def main() -> None:
+    """CLI hook that executes :func:`run_reindex` and prints a summary."""
+
+    total = run_reindex()
+    print(f"Reindexed {total} documents")
+
+
+if __name__ == "__main__":
+    main()