mcp-kb 0.1.0__py3-none-any.whl

mcp_kb/__init__.py

@@ -0,0 +1 @@
+"""Top-level package for the MCP knowledge base server implementation."""

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,153 @@
+"""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.
+"""
+from __future__ import annotations
+
+import os
+from argparse import ArgumentParser, Namespace
+from pathlib import Path
+from typing import Optional
+
+from mcp_kb.ingest.chroma import SUPPORTED_CLIENTS, ChromaConfiguration, ChromaIngestor
+
+
+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``.
+
+    Environment variables are used as defaults where available so that
+    deployments can configure ingestion without repeating flags.
+    """
+
+    default_chroma_client = os.getenv("MCP_KB_CHROMA_CLIENT", "persistent").lower()
+    default_collection = os.getenv("MCP_KB_CHROMA_COLLECTION", "knowledge-base")
+    default_embedding = os.getenv("MCP_KB_CHROMA_EMBEDDING", "default")
+    default_data_dir = os.getenv("MCP_KB_CHROMA_DATA_DIR")
+    default_host = os.getenv("MCP_KB_CHROMA_HOST")
+    default_port_env = os.getenv("MCP_KB_CHROMA_PORT")
+    default_port = int(default_port_env) if default_port_env else None
+    default_ssl = parse_bool(os.getenv("MCP_KB_CHROMA_SSL", "true"))
+    default_tenant = os.getenv("MCP_KB_CHROMA_TENANT")
+    default_database = os.getenv("MCP_KB_CHROMA_DATABASE")
+    default_api_key = os.getenv("MCP_KB_CHROMA_API_KEY")
+    default_custom_auth = os.getenv("MCP_KB_CHROMA_CUSTOM_AUTH")
+    default_id_prefix = os.getenv("MCP_KB_CHROMA_ID_PREFIX")
+
+    parser.add_argument(
+        "--chroma-client",
+        dest="chroma_client",
+        choices=SUPPORTED_CLIENTS,
+        default=default_chroma_client,
+        help="Client implementation for mirroring data to ChromaDB (default: persistent).",
+    )
+    parser.add_argument(
+        "--chroma-collection",
+        dest="chroma_collection",
+        default=default_collection,
+        help="Chroma collection name used to store documents.",
+    )
+    parser.add_argument(
+        "--chroma-embedding",
+        dest="chroma_embedding",
+        default=default_embedding,
+        help="Embedding function name registered with chromadb.utils.embedding_functions.",
+    )
+    parser.add_argument(
+        "--chroma-data-dir",
+        dest="chroma_data_dir",
+        default=default_data_dir,
+        help="Storage directory for the persistent Chroma client.",
+    )
+    parser.add_argument(
+        "--chroma-host",
+        dest="chroma_host",
+        default=default_host,
+        help="Target host for HTTP or cloud Chroma clients.",
+    )
+    parser.add_argument(
+        "--chroma-port",
+        dest="chroma_port",
+        type=int,
+        default=default_port,
+        help="Port for the HTTP Chroma client.",
+    )
+    parser.add_argument(
+        "--chroma-ssl",
+        dest="chroma_ssl",
+        type=parse_bool,
+        default=default_ssl,
+        help="Toggle SSL for the HTTP Chroma client (default: true).",
+    )
+    parser.add_argument(
+        "--chroma-tenant",
+        dest="chroma_tenant",
+        default=default_tenant,
+        help="Tenant identifier for Chroma Cloud deployments.",
+    )
+    parser.add_argument(
+        "--chroma-database",
+        dest="chroma_database",
+        default=default_database,
+        help="Database name for Chroma Cloud deployments.",
+    )
+    parser.add_argument(
+        "--chroma-api-key",
+        dest="chroma_api_key",
+        default=default_api_key,
+        help="API key used to authenticate against Chroma Cloud.",
+    )
+    parser.add_argument(
+        "--chroma-custom-auth",
+        dest="chroma_custom_auth",
+        default=default_custom_auth,
+        help="Optional custom auth credentials for self-hosted HTTP deployments.",
+    )
+    parser.add_argument(
+        "--chroma-id-prefix",
+        dest="chroma_id_prefix",
+        default=default_id_prefix,
+        help="Prefix applied to document IDs stored in Chroma (default: kb::).",
+    )
+
+
+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``.
+    """
+
+    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,
+    )
+    if not configuration.enabled:
+        return None
+    return ChromaIngestor(configuration)
+

mcp_kb/cli/main.py

@@ -0,0 +1,116 @@
+"""Command line interface for running the MCP knowledge base server."""
+from __future__ import annotations
+
+import argparse
+import asyncio
+import logging
+import os
+from pathlib import Path
+from typing import Iterable, List, Optional
+
+from mcp_kb.config import DOCS_FOLDER_NAME, resolve_knowledge_base_root
+from mcp_kb.cli.args import add_chroma_arguments, build_chroma_listener, parse_bool
+from mcp_kb.ingest.chroma import ChromaIngestor
+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
+
+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")
+    parser.add_argument(
+        "--root",
+        dest="root",
+        default=None,
+        help="Optional path to the knowledge base root (defaults to environment configuration)",
+    )
+    parser.add_argument(
+        "--transport",
+        dest="transports",
+        action="append",
+        choices=["stdio", "sse", "http"],
+        help="Transport protocol to enable (repeatable). Defaults to stdio only.",
+    )
+    parser.add_argument(
+        "--host",
+        dest="host",
+        default=None,
+        help="Host interface for HTTP/SSE transports (default 127.0.0.1).",
+    )
+    parser.add_argument(
+        "--port",
+        dest="port",
+        type=int,
+        default=None,
+        help="Port for HTTP/SSE transports (default 8000).",
+    )
+
+    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."""
+
+    parser = _build_argument_parser()
+    options = parser.parse_args(arguments)
+    root_path = resolve_knowledge_base_root(options.root)
+    rules = PathRules(root=root_path, protected_folders=(DOCS_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
+        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"]
+    logger.info(f"Running server on {options.host}:{options.port} with transports {transports}")
+    logger.info(f"Data root is {root_path}")
+    print("--------------------------------",root_path,"--------------------------------")
+    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,90 @@
+"""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.config import DOCS_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")
+    parser.add_argument(
+        "--root",
+        dest="root",
+        default=None,
+        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.
+
+    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(options.root)
+    rules = PathRules(root=root_path, protected_folders=(DOCS_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
+        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:
+        count = listener.reindex(kb)
+        logger.info("Reindexed %d documents via %s", count, listener.__class__.__name__)
+        total += count
+
+    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()
+

mcp_kb/config.py

@@ -0,0 +1,69 @@
+"""Configuration helpers for the MCP Knowledge Base server.
+
+This module centralizes configuration lookups so that the rest of the codebase
+only interacts with well-defined helper functions rather than environment
+variables or default literals. Keeping configuration isolated makes the server
+logic more reusable across different deployment environments because callers can
+swap configurations programmatically or via environment variables without
+modifying the core modules.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+import os
+
+
+DEFAULT_KNOWLEDGE_BASE_DIR = ".knowledgebase"
+"""str: Default relative directory for persisting knowledge base documents."""
+
+DOCS_FOLDER_NAME = ".docs"
+"""str: Name of the documentation folder inside the knowledge base tree."""
+
+DOC_FILENAME = "KNOWLEDBASE_DOC.md"
+"""str: Name of the canonical documentation file advertised in the PRD."""
+
+DELETE_SENTINEL = "_DELETE_"
+"""str: Marker appended to filenames to implement soft deletion semantics."""
+
+ENV_ROOT_KEY = "MCP_KB_ROOT"
+"""str: Environment variable that overrides the knowledge base root path."""
+
+
+def resolve_knowledge_base_root(provided_path: str | None = None) -> Path:
+    """Return the absolute knowledge base root directory for the server.
+
+    The function applies the following precedence order when choosing a
+    directory:
+
+    1. An explicit ``provided_path`` argument, if supplied by the caller.
+    2. The ``MCP_KB_ROOT`` environment variable supplied by the host process.
+    3. The default relative ``.knowledgebase`` directory.
+
+    The returned path is always absolute and resolved, which makes subsequent
+    filesystem operations robust against relative path confusion. The function
+    also ensures that the directory exists by calling ``mkdir`` with
+    ``parents=True`` and ``exist_ok=True`` so that repeated initializations are
+    idempotent.
+
+    Parameters
+    ----------
+    provided_path:
+        A string path explicitly supplied by the caller. ``None`` indicates
+        that the caller prefers environment or default resolution.
+
+    Returns
+    -------
+    Path
+        The resolved absolute path that should be used as the knowledge base
+        root directory.
+    """
+
+
+    candidate = provided_path or os.getenv(ENV_ROOT_KEY) or Path(
+        os.getenv('WORKSPACE_FOLDER_PATHS') or Path.cwd()
+    )/DEFAULT_KNOWLEDGE_BASE_DIR
+    root_path = Path(candidate).expanduser().resolve()
+    root_path.mkdir(parents=True, exist_ok=True)
+
+   
+    return root_path

mcp_kb/data/KNOWLEDBASE_DOC.md

@@ -0,0 +1,36 @@
+# Knowledge Base Usage Guide
+
+Welcome to the MCP-managed knowledge base. This document is automatically
+installed the first time the server starts to ensure every deployment ships with
+baseline documentation. Customize it to describe project-specific conventions or
+operational practices.
+
+## Structure
+
+- All knowledge content lives beneath the `.knowledgebase/` root.
+- Documentation resides under `.docs/` and is read-only from the MCP tools.
+- Soft-deleted files are suffixed with `_DELETE_` and ignored by search/overview.
+
+## Recommended Practices
+
+1. Organize content into topic-based folders (e.g., `architecture/`, `ops/`).
+2. Keep document titles within the first heading so search results show context.
+3. Use relative markdown links to connect related documents inside the knowledge
+   base.
+4. Periodically review `_DELETE_` files and clean up as necessary via direct
+   filesystem operations.
+
+## Default Tools
+
+| Tool            | Purpose                                   |
+| --------------- | ----------------------------------------- |
+| `create_file`   | Create or overwrite markdown documents    |
+| `read_file`     | Read entire files or specific line ranges |
+| `append_file`   | Append additional content to a file       |
+| `regex_replace` | Run regex-based replacements              |
+| `search`        | Search text across active documents       |
+| `overview`      | Display a tree overview of the knowledge  |
+| `documentation` | Read this documentation file              |
+| `delete`        | Soft-delete files safely                  |
+
+Update this document to reflect your team's workflows after deployment.

mcp_kb/data/__init__.py

@@ -0,0 +1 @@
+"""Embedded data files shipped with the MCP knowledge base server."""

mcp_kb/ingest/__init__.py

@@ -0,0 +1 @@
+"""Pluggable ingestion adapters for synchronizing knowledge base content."""