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

{mcp_kb-0.2.1.dist-info → mcp_kb-0.3.1.dist-info}/METADATA

@@ -1,16 +1,21 @@
 Metadata-Version: 2.4
 Name: mcp-kb
-Version: 0.2.1
+Version: 0.3.1
 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"
+Provides-Extra: sentence-transformer
+Requires-Dist: mcp-kb[vector]; extra == "sentence-transformer"
+Requires-Dist: sentence-transformers>=5.1.1; extra == "sentence-transformer"
 
 # MCP Knowledge Base Server
 

mcp_kb-0.3.1.dist-info/RECORD

@@ -0,0 +1,7 @@
+mcp_kb/__init__.py,sha256=Ry7qODhfFQF6u6p2m3bwGWhB0-BdWTQcHDJB7NBYAio,74
+mcp_kb/config.py,sha256=NUpzjDH4PQw4FyjGgYUcMsGMeenNiZTMrQj4U62xKlk,2530
+mcp_kb-0.3.1.dist-info/METADATA,sha256=PChkcVS-WUUnKFSHxIkpDn7PtJlOmQFvHIjkus7xBRU,5389
+mcp_kb-0.3.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+mcp_kb-0.3.1.dist-info/entry_points.txt,sha256=PdX1utY9cbvU_NQcKqUrWnMa4r3jGl448T7HUF9Gjqw,126
+mcp_kb-0.3.1.dist-info/top_level.txt,sha256=IBiz3TNE3FF3TwkbCZpC1kkk6ohTwtBQNSPJNV3-qGA,7
+mcp_kb-0.3.1.dist-info/RECORD,,

{mcp_kb-0.2.1.dist-info → mcp_kb-0.3.1.dist-info}/entry_points.txt

@@ -1,3 +1,4 @@
 [console_scripts]
+mcp-kb = mcp_kb.cli.main:main
 mcp-kb-reindex = mcp_kb.cli.reindex:main
 mcp-kb-server = mcp_kb.cli.main:main

mcp_kb/cli/__init__.py

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

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/cli/main.py

@@ -1,123 +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/cli/reindex.py

@@ -1,93 +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/data/KNOWLEDBASE_DOC.md

@@ -1,151 +0,0 @@
-# LLM Operating Manual — MCP Knowledge Base (`mcp-kb`)
-
-You are connected to a **local, text-only knowledge base**. Your job is to **search, read, create, update, and soft-delete** UTF‑8 text files under a single root directory while respecting safety rules below. Use the provided MCP tools exactly as specified.
-
----
-
-## Ground Rules (enforced by the server)
-
-- **Paths are relative only.** Absolute paths are rejected. No `..` traversal.
-- **Protected folder:** `.data/` is read‑only. Do not write there.  
-- **Soft delete sentinel:** Files marked with `_DELETE_` in the name are considered deleted. Do not read/write them.
-- **Text files only.** Binary-ish files are ignored by scans. Treat this KB as UTF‑8 text storage.
-- **Concurrency:** Writes are serialized per file; still prefer read‑verify‑write sequences.
-
-Constants (baked into the server):
-- Protected folder: `.data`
-- Documentation file name: `KNOWLEDBASE_DOC.md`
-- Delete sentinel: `_DELETE_`
-
----
-
-## Tools You Can Call
-
-All tool names and parameter contracts are stable. Stick to these shapes.
-
-### `create_file(path: str, content: str) -> str`
-- Create or **overwrite** a text file at `path` with `content`.
-- `path` must be **relative** and **outside** `.data/`.
-
-### `read_file(path: str, start_line?: int, end_line?: int) -> { path, start_line, end_line, content }`
-- Read full file or a 1‑based inclusive slice.  
-- If both bounds omitted ⇒ full file. If one bound omitted ⇒ server fills it.
-
-### `append_file(path: str, content: str) -> str`
-- Append text. If file is missing, it will be **created**.
-
-### `regex_replace(path: str, pattern: str, replacement: str) -> { replacements: int }`
-- Multiline regex (`re.MULTILINE`). Returns count. Always `read_file` afterwards to verify.
-
-### `delete(path: str) -> str`
-- **Soft delete**: renames `name.ext` to `name_DELETE_.ext`. Use when content is obsolete.
-
-### `search(query: str, limit: int = 5) -> [{ path, line, context: string[] }]`
-- Returns up to `limit` matches with short context.
-- If Chroma mirroring is active, results are **semantic** first; otherwise plain scan.
-- `limit` must be **> 0**.
-
-### `overview() -> str`
-- A deterministic `tree`-like view of active files under root (skips deleted and binaries).
-
-### `documentation() -> str`
-- Human usage guide (not this manual). For you, prefer this manual.
-
----
-
-## How to Work Effectively
-
-### 1) Discover
-- Call `overview()` to understand the tree.
-- If you need conventions or human guidelines, read `documentation()` (optional).
-
-### 2) Locate Content
-- Prefer `search("keywords", limit=5)` to find candidate files/snippets.
-  - Examine each `{path, line, context}`. The `context` is a short window around the hit.
-  - If results look thin, **increase `limit`** (e.g., 10–20) before broadening the query.
-
-### 3) Read Precisely
-- Use `read_file(path)` for the full file when structure matters.
-- If the file is large but you know the region, use `read_file(path, start_line, end_line)` to minimize tokens.
-
-### 4) Create New Knowledge
-- Pick a **descriptive relative path** (folders based on topic, kebab‑case names).
-  - Example: `architecture/decision-records/adr-2025-10-06-edge-cache.md`
-- Call `create_file(path, content)`.
-- Keep the **title as the first Markdown heading** so search has context.
-- Link related files with **relative Markdown links**.
-
-### 5) Update Safely
-- For small edits:  
-  1) `read_file(...)` to confirm current state.  
-  2) `regex_replace(path, pattern, replacement)` for targeted changes.  
-  3) `read_file(...)` again to verify.
-- For additive changes: `append_file(path, "\n...")`.
-
-### 6) Deletion Policy
-- Use `delete(path)` to **soft-delete**. Do not operate on files that already include `_DELETE_` in their name.
-
----
-
-## Search Semantics (important)
-
-- When Chroma ingestion is **enabled**, `search()` uses semantic ranking first and returns the **best slice per file** (the ingestor extracts one representative match per document chunk/file). If no obvious line match is found, you may get a **top-of-file preview** — then call `read_file()` to confirm.
-- When Chroma is **not** enabled, `search()` scans files literally and returns all matches up to `limit`.
-- Always **validate** by fetching the file segment with `read_file()` before making edits.
-
----
-
-## Parameter Contracts and Gotchas
-
-- `path` must be **relative** (e.g., `notes/today.md`). Absolute paths are rejected.
-- Do **not** write into `.data/` (protected). Reads are allowed there.
-- Line numbers in `read_file` are **1‑based** and the interval is **inclusive**.
-- `regex_replace` uses Python’s `re.MULTILINE`. Validate your pattern; avoid overly broad substitutions.
-- `append_file` will create a file if missing (useful for logs/progress notes).
-
----
-
-## Typical Recipes
-
-**Find → Read → Edit**
-1. `search("beta feature toggle", limit=10)`
-2. Pick a result: `read_file("features/toggles.md", 40, 80)`
-3. Adjust: `regex_replace("features/toggles.md", "^Status:.*$", "Status: Enabled")`
-4. Verify: `read_file("features/toggles.md")` (check the `Status:` header)
-
-**Add a new doc**
-1. `create_file("ops/runbooks/cache-invalidation.md", "# Cache Invalidation\n\n…")`
-2. Optionally link it from an index: `append_file("ops/README.md", "\n- [Cache Invalidation](runbooks/cache-invalidation.md)")`
-
-**Soft delete an obsolete note**
-1. `delete("notes/old-incident.md")`
-
----
-
-## Error Recovery
-
-- **"Absolute paths are not permitted"** → Use a **relative** path.
-- **"Writes are not allowed inside the protected folder '.data'"** → Choose a different folder (e.g., `docs/`).
-- **"File 'X' does not exist"** on delete → Confirm with `overview()` or `search()`. Only existing non‑deleted files can be soft‑deleted.
-- **No search hits** → Widen keywords, increase `limit`, or pivot to `overview()` to eyeball likely locations.
-
----
-
-## Things You Should Not Do
-
-- Do not fabricate file contents or paths. Always confirm with `overview()`, `search()`, and `read_file()`.
-- Do not operate on files that include `_DELETE_` in their name.
-- Do not attempt to talk directly to Chroma; you only use `search()`. Indexing is handled automatically after writes.
-- Do not write binary or non‑UTF‑8 content.
-
----
-
-## Performance Hints
-
-- Prefer `search()` + targeted `read_file()` slices over reading entire large files.
-- Keep `limit` modest (5–10) unless you must broaden the search.
-- Batch edits in one file using a single `regex_replace` when safe (then verify).
-
----
-
-You now have the minimal contract to operate this KB safely and efficiently.

mcp_kb/data/__init__.py

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

mcp_kb/ingest/__init__.py

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