mcp-kb 0.1.0__tar.gz

mcp_kb-0.1.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: mcp-kb
+Version: 0.1.0
+Summary: MCP server exposing a local markdown knowledge base
+Author: LLM Maintainer
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: chromadb>=1.1.0
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: mcp[cli]>=1.15.0
+Provides-Extra: vector
+Requires-Dist: tiktoken>=0.11.0; extra == "vector"
+Requires-Dist: langchain-text-splitters>=0.3.11; extra == "vector"
+
+# MCP Knowledge Base Server
+
+This project implements a Model Context Protocol (MCP) server that manages a local markdown knowledge base. It provides tools for creating, reading, updating, searching, and organizing documents stored beneath a configurable root directory. The server uses `FastMCP` for transport and schema generation, so the Python tool functions double as the canonical source of truth for MCP metadata.
+
+## Running the server
+
+```bash
+uv run mcp-kb-server --root /path/to/knowledgebase
+```
+
+To expose multiple transports, pass `--transport` flags (supported values: `stdio`,
+`sse`, `http`):
+
+```bash
+uv run mcp-kb-server --transport stdio --transport http
+```
+
+Use `--host` and `--port` to bind HTTP/SSE transports to specific interfaces:
+
+```bash
+uv run mcp-kb-server --transport http --host 0.0.0.0 --port 9000
+```
+
+On first launch the server copies a bundled `KNOWLEDBASE_DOC.md` into the
+`.docs/` directory if it is missing so that every deployment starts with a
+baseline usage guide.
+
+## Optional ChromaDB Mirroring
+
+The CLI can mirror knowledge base changes into a Chroma collection without
+exposing raw Chroma operations as MCP tools. Mirroring is enabled by default via
+the `persistent` client, which stores data under `<root>/chroma`. Choose a
+different backend with `--chroma-client` (choices: `ephemeral`, `persistent`,
+`http`, `cloud`). Example:
+
+```bash
+uv run mcp-kb-server \
+  --root /path/to/knowledgebase \
+  --chroma-client ephemeral \
+  --chroma-collection local-kb \
+  --chroma-embedding default
+```
+
+Persistent and remote clients accept additional flags:
+
+- `--chroma-data-dir`: storage directory for the persistent client (defaults to
+  `<root>/chroma` when not supplied).
+- `--chroma-host`, `--chroma-port`, `--chroma-ssl`, `--chroma-custom-auth`:
+  options for a self-hosted HTTP server.
+- `--chroma-tenant`, `--chroma-database`, `--chroma-api-key`: credentials for
+  Chroma Cloud deployments.
+- `--chroma-id-prefix`: custom document ID prefix (`kb::` by default).
+
+Every flag has a matching environment variable (`MCP_KB_CHROMA_*`), so the
+following snippet enables an HTTP client without modifying CLI commands:
+
+```bash
+export MCP_KB_CHROMA_CLIENT=http
+export MCP_KB_CHROMA_HOST=chroma.internal
+export MCP_KB_CHROMA_PORT=8001
+export MCP_KB_CHROMA_CUSTOM_AUTH="username:password"
+uv run mcp-kb-server --transport http
+```
+
+When enabled, any file creation, update, or soft deletion is synchronously
+propagated to the configured Chroma collection, ensuring semantic search stays
+in lockstep with the markdown knowledge base.
+
+The `kb.search` MCP tool automatically queries Chroma when mirroring is active,
+falling back to direct filesystem scans if the semantic index returns no hits.
+
+## Reindexing
+
+Use the standalone CLI to rebuild external indexes (e.g., Chroma) from the
+current knowledge base. This command is not exposed as an MCP tool.
+
+```bash
+uv run mcp-kb-reindex --root /path/to/knowledgebase \
+  --chroma-client persistent \
+  --chroma-data-dir /path/to/chroma \
+  --chroma-collection knowledge-base \
+  --chroma-embedding default
+```
+
+- Honors the same `--chroma-*` flags and `MCP_KB_CHROMA_*` environment
+  variables as the server.
+- Processes all non-deleted `*.md` files under the root and prints a summary:
+  `Reindexed N documents`.
+
+## Testing
+
+```bash
+uv run pytest
+```
+
+## LLM Client Configuration
+
+Below are sample configurations for popular MCP-capable LLM clients. All
+examples assume this repository is cloned locally and that `uv` is installed.
+
+### Claude Desktop
+
+Add the following block to your Claude Desktop `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "local-kb": {
+      "server-name": "kb-server",
+      "command": "uv",
+      "args": [
+        "run",
+        "mcp-kb-server",
+        "--root",
+        "/absolute/path/to/.knowledgebase"
+      ]
+    }
+  }
+}
+```
+
+### Cursor AI
+
+In Cursor's `cursor-settings.json`, register the server as a custom tool:
+
+```json
+{
+  "mcpServers": {
+    "local_knowledge_base": {
+      "id": "local-kb",
+      "title": "Local Knowledge Base",
+      "command": "uvx",
+      "args": [
+        " --from",
+        "~/cursor_projects/local_knowledge_base",
+        "mcp-kb-server"
+      ]
+    }
+  }
+}
+```
+
+### VS Code (Claude MCP Extension)
+
+For the `Claude MCP` extension, add an entry to `settings.json`:
+
+```json
+{
+  "claudeMcp.servers": {
+    "local-kb": {
+      "command": "uv",
+      "args": ["run", "mcp-kb-server"],
+      "env": {
+        "MCP_KB_ROOT": "/absolute/path/to/.knowledgebase"
+      }
+    }
+  }
+}
+```
+
+Adjust the `--root` flag or `MCP_KB_ROOT` environment variable to point at the
+desired knowledge base directory for each client.

mcp_kb-0.1.0/README.md

@@ -0,0 +1,162 @@
+# MCP Knowledge Base Server
+
+This project implements a Model Context Protocol (MCP) server that manages a local markdown knowledge base. It provides tools for creating, reading, updating, searching, and organizing documents stored beneath a configurable root directory. The server uses `FastMCP` for transport and schema generation, so the Python tool functions double as the canonical source of truth for MCP metadata.
+
+## Running the server
+
+```bash
+uv run mcp-kb-server --root /path/to/knowledgebase
+```
+
+To expose multiple transports, pass `--transport` flags (supported values: `stdio`,
+`sse`, `http`):
+
+```bash
+uv run mcp-kb-server --transport stdio --transport http
+```
+
+Use `--host` and `--port` to bind HTTP/SSE transports to specific interfaces:
+
+```bash
+uv run mcp-kb-server --transport http --host 0.0.0.0 --port 9000
+```
+
+On first launch the server copies a bundled `KNOWLEDBASE_DOC.md` into the
+`.docs/` directory if it is missing so that every deployment starts with a
+baseline usage guide.
+
+## Optional ChromaDB Mirroring
+
+The CLI can mirror knowledge base changes into a Chroma collection without
+exposing raw Chroma operations as MCP tools. Mirroring is enabled by default via
+the `persistent` client, which stores data under `<root>/chroma`. Choose a
+different backend with `--chroma-client` (choices: `ephemeral`, `persistent`,
+`http`, `cloud`). Example:
+
+```bash
+uv run mcp-kb-server \
+  --root /path/to/knowledgebase \
+  --chroma-client ephemeral \
+  --chroma-collection local-kb \
+  --chroma-embedding default
+```
+
+Persistent and remote clients accept additional flags:
+
+- `--chroma-data-dir`: storage directory for the persistent client (defaults to
+  `<root>/chroma` when not supplied).
+- `--chroma-host`, `--chroma-port`, `--chroma-ssl`, `--chroma-custom-auth`:
+  options for a self-hosted HTTP server.
+- `--chroma-tenant`, `--chroma-database`, `--chroma-api-key`: credentials for
+  Chroma Cloud deployments.
+- `--chroma-id-prefix`: custom document ID prefix (`kb::` by default).
+
+Every flag has a matching environment variable (`MCP_KB_CHROMA_*`), so the
+following snippet enables an HTTP client without modifying CLI commands:
+
+```bash
+export MCP_KB_CHROMA_CLIENT=http
+export MCP_KB_CHROMA_HOST=chroma.internal
+export MCP_KB_CHROMA_PORT=8001
+export MCP_KB_CHROMA_CUSTOM_AUTH="username:password"
+uv run mcp-kb-server --transport http
+```
+
+When enabled, any file creation, update, or soft deletion is synchronously
+propagated to the configured Chroma collection, ensuring semantic search stays
+in lockstep with the markdown knowledge base.
+
+The `kb.search` MCP tool automatically queries Chroma when mirroring is active,
+falling back to direct filesystem scans if the semantic index returns no hits.
+
+## Reindexing
+
+Use the standalone CLI to rebuild external indexes (e.g., Chroma) from the
+current knowledge base. This command is not exposed as an MCP tool.
+
+```bash
+uv run mcp-kb-reindex --root /path/to/knowledgebase \
+  --chroma-client persistent \
+  --chroma-data-dir /path/to/chroma \
+  --chroma-collection knowledge-base \
+  --chroma-embedding default
+```
+
+- Honors the same `--chroma-*` flags and `MCP_KB_CHROMA_*` environment
+  variables as the server.
+- Processes all non-deleted `*.md` files under the root and prints a summary:
+  `Reindexed N documents`.
+
+## Testing
+
+```bash
+uv run pytest
+```
+
+## LLM Client Configuration
+
+Below are sample configurations for popular MCP-capable LLM clients. All
+examples assume this repository is cloned locally and that `uv` is installed.
+
+### Claude Desktop
+
+Add the following block to your Claude Desktop `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "local-kb": {
+      "server-name": "kb-server",
+      "command": "uv",
+      "args": [
+        "run",
+        "mcp-kb-server",
+        "--root",
+        "/absolute/path/to/.knowledgebase"
+      ]
+    }
+  }
+}
+```
+
+### Cursor AI
+
+In Cursor's `cursor-settings.json`, register the server as a custom tool:
+
+```json
+{
+  "mcpServers": {
+    "local_knowledge_base": {
+      "id": "local-kb",
+      "title": "Local Knowledge Base",
+      "command": "uvx",
+      "args": [
+        " --from",
+        "~/cursor_projects/local_knowledge_base",
+        "mcp-kb-server"
+      ]
+    }
+  }
+}
+```
+
+### VS Code (Claude MCP Extension)
+
+For the `Claude MCP` extension, add an entry to `settings.json`:
+
+```json
+{
+  "claudeMcp.servers": {
+    "local-kb": {
+      "command": "uv",
+      "args": ["run", "mcp-kb-server"],
+      "env": {
+        "MCP_KB_ROOT": "/absolute/path/to/.knowledgebase"
+      }
+    }
+  }
+}
+```
+
+Adjust the `--root` flag or `MCP_KB_ROOT` environment variable to point at the
+desired knowledge base directory for each client.

mcp_kb-0.1.0/mcp_kb/__init__.py

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

mcp_kb-0.1.0/mcp_kb/cli/__init__.py

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

mcp_kb-0.1.0/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-0.1.0/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-0.1.0/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()
+