mcp-kb 0.2.0__tar.gz → 0.3.0__tar.gz

{mcp_kb-0.2.0 → mcp_kb-0.3.0}/PKG-INFO

@@ -1,16 +1,18 @@
 Metadata-Version: 2.4
 Name: mcp-kb
-Version: 0.2.0
+Version: 0.3.0
 Summary: MCP server exposing a local markdown knowledge base
 Author: LLM Maintainer
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 Requires-Dist: httpx>=0.28.1
 Requires-Dist: mcp[cli]>=1.15.0
+Requires-Dist: pydantic>=2.11.9
 Provides-Extra: vector
 Requires-Dist: chromadb>=1.1.0; extra == "vector"
 Requires-Dist: tiktoken>=0.11.0; extra == "vector"
 Requires-Dist: langchain-text-splitters>=0.3.11; extra == "vector"
+Requires-Dist: umap-learn>=0.5.9.post2; extra == "vector"
 
 # MCP Knowledge Base Server
 

{mcp_kb-0.2.0 → mcp_kb-0.3.0}/mcp_kb/config.py

@@ -7,6 +7,7 @@ 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
@@ -58,12 +59,13 @@ def resolve_knowledge_base_root(provided_path: str | None = None) -> Path:
         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
+    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-0.2.0 → mcp_kb-0.3.0}/mcp_kb.egg-info/PKG-INFO

@@ -1,16 +1,18 @@
 Metadata-Version: 2.4
 Name: mcp-kb
-Version: 0.2.0
+Version: 0.3.0
 Summary: MCP server exposing a local markdown knowledge base
 Author: LLM Maintainer
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 Requires-Dist: httpx>=0.28.1
 Requires-Dist: mcp[cli]>=1.15.0
+Requires-Dist: pydantic>=2.11.9
 Provides-Extra: vector
 Requires-Dist: chromadb>=1.1.0; extra == "vector"
 Requires-Dist: tiktoken>=0.11.0; extra == "vector"
 Requires-Dist: langchain-text-splitters>=0.3.11; extra == "vector"
+Requires-Dist: umap-learn>=0.5.9.post2; extra == "vector"
 
 # MCP Knowledge Base Server
 

mcp_kb-0.3.0/mcp_kb.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+mcp_kb/__init__.py
+mcp_kb/config.py
+mcp_kb.egg-info/PKG-INFO
+mcp_kb.egg-info/SOURCES.txt
+mcp_kb.egg-info/dependency_links.txt
+mcp_kb.egg-info/entry_points.txt
+mcp_kb.egg-info/requires.txt
+mcp_kb.egg-info/top_level.txt

{mcp_kb-0.2.0 → mcp_kb-0.3.0}/mcp_kb.egg-info/requires.txt

@@ -1,7 +1,9 @@
 httpx>=0.28.1
 mcp[cli]>=1.15.0
+pydantic>=2.11.9
 
 [vector]
 chromadb>=1.1.0
 tiktoken>=0.11.0
 langchain-text-splitters>=0.3.11
+umap-learn>=0.5.9.post2

{mcp_kb-0.2.0 → mcp_kb-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mcp-kb"
-version = "0.2.0"
+version = "0.3.0"
 description = "MCP server exposing a local markdown knowledge base"
 readme = "README.md"
 authors = [{ name = "LLM Maintainer" }]
@@ -8,6 +8,7 @@ requires-python = ">=3.11"
 dependencies = [
     "httpx>=0.28.1",
     "mcp[cli]>=1.15.0",
+    "pydantic>=2.11.9",
 ]
 
 [project.scripts]
@@ -19,7 +20,7 @@ vector = [
     "chromadb>=1.1.0",
     "tiktoken>=0.11.0",
     "langchain-text-splitters>=0.3.11",
-
+    "umap-learn>=0.5.9.post2",
 ]
 
 [build-system]
@@ -28,9 +29,15 @@ build-backend = "setuptools.build_meta"
 
 [tool.setuptools.package-data]
 "mcp_kb.data" = ["KNOWLEDBASE_DOC.md"]
+"mcp_kb.ui.assets" = ["index.html", "assets/**"]
+
+[tool.setuptools]
+packages = ["mcp_kb"]
+include-package-data = true
 
 [tool.uv]
 package = true
 dev-dependencies = [
     "pytest>=8.4.2",
+    "markitdown[all]>=0.1.3",
 ]

mcp_kb-0.2.0/mcp_kb/cli/__init__.py

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

mcp_kb-0.2.0/mcp_kb/cli/args.py

@@ -1,153 +0,0 @@
-"""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-0.2.0/mcp_kb/cli/main.py

@@ -1,116 +0,0 @@
-"""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 DATA_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=(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
-        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-0.2.0/mcp_kb/cli/reindex.py

@@ -1,91 +0,0 @@
-"""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 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")
-    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=(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
-        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
-
-    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-0.2.0/mcp_kb/data/KNOWLEDBASE_DOC.md

@@ -1,36 +0,0 @@
-# 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 and other non knowledge resides under `.data/` 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-0.2.0/mcp_kb/data/__init__.py

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

mcp_kb-0.2.0/mcp_kb/ingest/__init__.py

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