mcp-kb 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

mcp_kb/cli/main.py

@@ -8,7 +8,7 @@ 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.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
@@ -79,7 +79,7 @@ def run_server(arguments: Iterable[str] | None = None) -> None:
     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,))
+    rules = PathRules(root=root_path, protected_folders=(DATA_FOLDER_NAME,))
     install_default_documentation(root_path)
     listeners: List[ChromaIngestor] = []
     try:

mcp_kb/cli/reindex.py

@@ -12,7 +12,7 @@ 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.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
@@ -58,7 +58,7 @@ def run_reindex(arguments: Iterable[str] | None = None) -> int:
     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,))
+    rules = PathRules(root=root_path, protected_folders=(DATA_FOLDER_NAME,))
     kb = KnowledgeBase(rules)
 
     listeners: List[KnowledgeBaseReindexListener] = []
@@ -71,6 +71,7 @@ def run_reindex(arguments: Iterable[str] | None = None) -> int:
 
     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

mcp_kb/config.py

@@ -16,7 +16,7 @@ import os
 DEFAULT_KNOWLEDGE_BASE_DIR = ".knowledgebase"
 """str: Default relative directory for persisting knowledge base documents."""
 
-DOCS_FOLDER_NAME = ".docs"
+DATA_FOLDER_NAME = ".data"
 """str: Name of the documentation folder inside the knowledge base tree."""
 
 DOC_FILENAME = "KNOWLEDBASE_DOC.md"

mcp_kb/data/KNOWLEDBASE_DOC.md

@@ -8,7 +8,7 @@ operational practices.
 ## Structure
 
 - All knowledge content lives beneath the `.knowledgebase/` root.
-- Documentation resides under `.docs/` and is read-only from the MCP tools.
+- 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

mcp_kb/ingest/chroma.py

@@ -6,7 +6,9 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, Dict, List, Mapping, Optional, Set, Tuple, Type, TYPE_CHECKING
 from langchain_text_splitters import TokenTextSplitter
+from tqdm import tqdm
 
+from mcp_kb.config import DATA_FOLDER_NAME
 from mcp_kb.knowledge.events import (
     FileDeleteEvent,
     FileUpsertEvent,
@@ -104,7 +106,7 @@ class ChromaConfiguration:
         if data_directory:
             resolved_directory = Path(data_directory).expanduser().resolve()
         elif normalized_type == "persistent":
-            resolved_directory = (root / "chroma").resolve()
+            resolved_directory = (root/DATA_FOLDER_NAME / "chroma").resolve()
         else:
             resolved_directory = None
 
@@ -419,6 +421,7 @@ class ChromaIngestor(KnowledgeBaseListener, KnowledgeBaseReindexListener):
             d.metadata['chunk_number'] = i
             d.metadata['startline'] = len(content[:d.metadata['start_index']].splitlines())
             d.metadata['endline'] =  d.metadata['startline']  + len(d.page_content.splitlines())-1
+            
 
         self._collection.add(
             documents=[d.page_content for d in split_docs],
@@ -451,19 +454,21 @@ class ChromaIngestor(KnowledgeBaseListener, KnowledgeBaseReindexListener):
 
         count = 0
         root = kb.rules.root
-        for path in kb.iter_active_files(include_docs=False):
-            try:
-                content = path.read_text(encoding="utf-8")
-            except FileNotFoundError:  # pragma: no cover - race with external edits
-                continue
-
-            relative = str(path.relative_to(root))
-            document_id = f"{self.configuration.id_prefix}{relative}"
-            metadata = {
-                "relative_path": relative,
-            }
-            self._reindex_document(document_id, content, metadata)
-            count += 1
+        with tqdm(kb.iter_active_files(include_docs=False), desc="Reindexing Chroma",total=kb.total_active_files(include_docs=False)) as pbar:
+            for path in pbar:
+                pbar.set_description(f"Reindexing Chroma {path.name}")
+                try:
+                    content = path.read_text(encoding="utf-8")
+                except FileNotFoundError:  # pragma: no cover - race with external edits
+                    continue
+
+                relative = str(path.relative_to(root))
+                document_id = f"{self.configuration.id_prefix}{relative}"
+                metadata = {
+                    "relative_path": relative,
+                }
+                self._reindex_document(document_id, content, metadata)
+                count += 1
 
         return count
 

mcp_kb/knowledge/bootstrap.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 import importlib.resources as resources
 from pathlib import Path
 
-from mcp_kb.config import DOCS_FOLDER_NAME, DOC_FILENAME
+from mcp_kb.config import DATA_FOLDER_NAME, DOC_FILENAME
 
 
 def install_default_documentation(root: Path) -> Path:
@@ -26,7 +26,7 @@ def install_default_documentation(root: Path) -> Path:
         Path to the documentation file inside the knowledge base tree.
     """
 
-    docs_dir = root / DOCS_FOLDER_NAME
+    docs_dir = root / DATA_FOLDER_NAME
     doc_path = docs_dir / DOC_FILENAME
     if doc_path.exists():
         return doc_path

mcp_kb/knowledge/search.py

@@ -11,7 +11,7 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Dict, Iterable, List, Optional
 
-from mcp_kb.config import DOCS_FOLDER_NAME, DOC_FILENAME
+from mcp_kb.config import DATA_FOLDER_NAME, DOC_FILENAME
 from mcp_kb.knowledge.events import KnowledgeBaseSearchListener
 from mcp_kb.knowledge.store import KnowledgeBase
 
@@ -141,7 +141,7 @@ def read_documentation(kb: KnowledgeBase) -> str:
     folder.
     """
 
-    doc_path = kb.rules.root / DOCS_FOLDER_NAME / DOC_FILENAME
+    doc_path = kb.rules.root / DATA_FOLDER_NAME / DOC_FILENAME
     if not doc_path.exists():
         return ""
     return doc_path.read_text(encoding="utf-8")

mcp_kb/knowledge/store.py

@@ -2,7 +2,7 @@
 
 This module exposes the ``KnowledgeBase`` class, which orchestrates validated
 filesystem operations for the MCP server. The class encapsulates logic for
-creating, reading, appending, and modifying markdown files while respecting the
+creating, reading, appending, and modifying text files while respecting the
 security constraints defined in the PRD. Each method returns plain Python data
 structures so that higher-level layers (e.g., JSON-RPC handlers) can focus on
 protocol serialization rather than filesystem minutiae.
@@ -14,7 +14,7 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Iterable, Optional
 
-from mcp_kb.config import DELETE_SENTINEL, DOCS_FOLDER_NAME
+from mcp_kb.config import DELETE_SENTINEL, DATA_FOLDER_NAME
 from mcp_kb.knowledge.events import FileDeleteEvent, FileUpsertEvent, KnowledgeBaseListener
 from mcp_kb.security.path_validation import (
     PathRules,
@@ -79,7 +79,7 @@ class KnowledgeBase:
         self.listeners = tuple(listeners or ())
 
     def create_file(self, relative_path: str, content: str) -> Path:
-        """Create or overwrite a markdown file at ``relative_path``.
+        """Create or overwrite a text file at ``relative_path``.
 
         The method validates the path, ensures that the parent directory exists,
         and writes the provided content as UTF-8 text. Existing files are
@@ -185,9 +185,14 @@ class KnowledgeBase:
         original_relative = self._relative_path(normalized)
         self._notify_delete(target, original_relative)
         return target
+    
+    def total_active_files(self, include_docs: bool = False) -> int:
+        """Return the total number of non-deleted UTF-8 text files under the root directory.
+        """
+        return sum(1 for _ in self.iter_active_files(include_docs=include_docs))
 
     def iter_active_files(self, include_docs: bool = False) -> Iterable[Path]:
-        """Yield non-deleted markdown files under the root directory.
+        """Yield non-deleted UTF-8 text files under the root directory.
 
         Parameters
         ----------
@@ -197,13 +202,18 @@ class KnowledgeBase:
             the search and overview requirements from the PRD.
         """
 
-        for path in self.rules.root.rglob("*.md"):
+        from mcp_kb.utils.filesystem import is_text_file
+
+        for path in self.rules.root.rglob("*"):
+            if not path.is_file():
+                continue
             if DELETE_SENTINEL in path.name:
                 continue
             parts = path.relative_to(self.rules.root).parts
-            if parts and parts[0] == DOCS_FOLDER_NAME and not include_docs:
+            if parts and parts[0] == DATA_FOLDER_NAME and not include_docs:
                 continue
-            yield path
+            if is_text_file(path):
+                yield path
 
     def _relative_path(self, absolute: Path) -> str:
         """Return ``absolute`` rewritten relative to the knowledge base root."""
@@ -218,7 +228,7 @@ class KnowledgeBase:
         absolute:
             Fully resolved path that was modified on disk.
         content:
-            Markdown payload that should be provided to subscribers.
+            Text payload that should be provided to subscribers.
         """
 
         if not self.listeners:

mcp_kb/security/path_validation.py

@@ -13,7 +13,7 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Iterable
 
-from mcp_kb.config import DOCS_FOLDER_NAME, DELETE_SENTINEL
+from mcp_kb.config import DATA_FOLDER_NAME, DELETE_SENTINEL
 
 
 class PathValidationError(ValueError):

mcp_kb/server/app.py

@@ -89,7 +89,7 @@ def create_fastmcp_app(
     mcp = FastMCP(
         "mcp-knowledge-base",
         instructions=(
-            "You are connected to a local markdown knowledge base. Use the provided "
+            "You are connected to a local text-based knowledge base. Use the provided "
             "tools to create, inspect, and organize content while respecting the "
             "soft deletion semantics and the protected documentation folder."
         ),
@@ -98,7 +98,7 @@ def create_fastmcp_app(
 
     @mcp.tool(name="create_file", title="Create File")
     def create_file(path: str, content: str) -> str:
-        """Create or overwrite a markdown file at ``path`` with ``content``."""
+        """Create or overwrite a text file at ``path`` with ``content``."""
 
         try:
             created = kb.create_file(path, content)
@@ -108,7 +108,7 @@ def create_fastmcp_app(
 
     @mcp.tool(name="read_file", title="Read File", structured_output=True)
     def read_file(path: str, start_line: int | None = None, end_line: int | None = None) -> ReadFileResult:
-        """Read a markdown file returning metadata about the extracted segment."""
+        """Read a text file returning metadata about the extracted segment."""
 
         try:
             segment: FileSegment = kb.read_file(path, start_line=start_line, end_line=end_line)

mcp_kb/utils/filesystem.py

@@ -81,3 +81,47 @@ def rename(path: Path, target: Path) -> None:
     """Rename ``path`` to ``target`` using ``Path.rename`` semantics."""
 
     path.rename(target)
+
+
+def is_text_file(path: Path, max_bytes: int = 2048) -> bool:
+    """Heuristically determine whether ``path`` contains UTF-8 text.
+
+    The check is designed to be fast and conservative for use when iterating
+    a directory tree. It reads at most ``max_bytes`` from the file in binary
+    mode and applies two filters:
+
+    - Reject files that contain NUL bytes, which are extremely uncommon in
+      textual formats and a strong indicator of binary content.
+    - Attempt to decode the sampled bytes as UTF-8. If decoding fails, the
+      file is treated as binary.
+
+    Parameters
+    ----------
+    path:
+        Absolute path to the file on disk.
+    max_bytes:
+        Upper bound on the number of bytes to sample from the head of the
+        file. A small sample keeps directory scans fast while remaining
+        accurate for typical text formats such as ``.md``, ``.txt``, ``.xml``,
+        and source files.
+
+    Returns
+    -------
+    bool
+        ``True`` if the file appears to be UTF-8 text; ``False`` otherwise.
+    """
+
+    try:
+        with path.open("rb") as handle:
+            sample = handle.read(max_bytes)
+    except (FileNotFoundError, PermissionError):  # pragma: no cover - defensive
+        return False
+
+    if b"\x00" in sample:
+        return False
+
+    try:
+        sample.decode("utf-8")
+        return True
+    except UnicodeDecodeError:
+        return False

{mcp_kb-0.1.0.dist-info → mcp_kb-0.2.0.dist-info}/METADATA

@@ -1,14 +1,14 @@
 Metadata-Version: 2.4
 Name: mcp-kb
-Version: 0.1.0
+Version: 0.2.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: chromadb>=1.1.0; extra == "vector"
 Requires-Dist: tiktoken>=0.11.0; extra == "vector"
 Requires-Dist: langchain-text-splitters>=0.3.11; extra == "vector"
 
@@ -36,7 +36,7 @@ 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
+`.data/` directory if it is missing so that every deployment starts with a
 baseline usage guide.
 
 ## Optional ChromaDB Mirroring

mcp_kb-0.2.0.dist-info/RECORD

@@ -0,0 +1,26 @@
+mcp_kb/__init__.py,sha256=Ry7qODhfFQF6u6p2m3bwGWhB0-BdWTQcHDJB7NBYAio,74
+mcp_kb/config.py,sha256=VallCc3_Bjcm2FPElthupvXdbMuXvDkiTkQKj0f4dkQ,2506
+mcp_kb/cli/__init__.py,sha256=dEIRWFycAfPkha1S1Bj_Y6zkvEZv4eF0qtbF9t74r60,67
+mcp_kb/cli/args.py,sha256=0yU5lwjjUkgk91ksocqOdpqO_u5JU6xuCaayiOJ-5pQ,5371
+mcp_kb/cli/main.py,sha256=FMsnWcXmEsXXfETyvPMP2il9jREGFWmR8t23-6QfhMo,3864
+mcp_kb/cli/reindex.py,sha256=UBBN7_u9rcgGXel5FKnnA3yd7a-AQMwHMwQjt7ZFrSs,3033
+mcp_kb/data/KNOWLEDBASE_DOC.md,sha256=bkSpdK1W3F0KR6d3q4V_23fnY8Kw2IBjXPvTTRv06AI,1663
+mcp_kb/data/__init__.py,sha256=UYYuO_n2ikjpwkPSykgleiifYvC0V8_O-atUaRBQUm4,70
+mcp_kb/ingest/__init__.py,sha256=8obrvfa8nLNLYPbi1MHlFUqfoFHgK9YfdryPzAXQ6kU,77
+mcp_kb/ingest/chroma.py,sha256=3Kt7or1Z9ng-wBeXeuOPhrVIfjokwkF25jKHdAeYSH8,22170
+mcp_kb/knowledge/__init__.py,sha256=W_dtRbtnQlrDJ_425vWR8BcoZGJ8gC5-wg1De1E654s,76
+mcp_kb/knowledge/bootstrap.py,sha256=WlbJUXhxglyWjlvwhUdT20oijLNLaZOePQ6nYwfBCxk,1202
+mcp_kb/knowledge/events.py,sha256=A7CfD7U5bxo6mCCIic83yE7VPixAN05ssw_HKRF2zxw,3549
+mcp_kb/knowledge/search.py,sha256=AKsyNipsA8bfRxIJb49tdsU4ICzbHeFrA1Ikvlk1u7w,5901
+mcp_kb/knowledge/store.py,sha256=urZaLrSRjgqxb_hLC6RQjDeNw8Id14ripQH_6HdWb3o,10002
+mcp_kb/security/__init__.py,sha256=lF8_XAjzpwhAFresuskXMo0u9v7KFiTJId88wqOAM4Y,62
+mcp_kb/security/path_validation.py,sha256=21bfKdxjHY-ywDYw0DcGCeXDnvdXDILWVuueUsuuZUM,3617
+mcp_kb/server/__init__.py,sha256=j9TmxW_WLCoibyQvCsDT1MIuUqSL8sRh2h4u0M4eU0c,74
+mcp_kb/server/app.py,sha256=7s10UJWFopJ4CZPqZ4briTKsfjDiRo44ZbLAeWb6Lj8,7064
+mcp_kb/utils/__init__.py,sha256=lKhRsjgnbhye1sSlch1_wsAI3eWKE1M6RVIiNlnsvLI,71
+mcp_kb/utils/filesystem.py,sha256=0M-Waf2vfqhp8UL__2Emfpwpoqxshti3M7XLjXnpjJw,4026
+mcp_kb-0.2.0.dist-info/METADATA,sha256=AjAH4xcztes0PzJkjW3J9qyes0VDXS7jfsJFQMq2s1g,5122
+mcp_kb-0.2.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+mcp_kb-0.2.0.dist-info/entry_points.txt,sha256=qwJkR3vV7ZeydfS_IYMiDwLv4BdTkrOf4-5neWj25g0,96
+mcp_kb-0.2.0.dist-info/top_level.txt,sha256=IBiz3TNE3FF3TwkbCZpC1kkk6ohTwtBQNSPJNV3-qGA,7
+mcp_kb-0.2.0.dist-info/RECORD,,

mcp_kb-0.1.0.dist-info/RECORD

@@ -1,26 +0,0 @@
-mcp_kb/__init__.py,sha256=Ry7qODhfFQF6u6p2m3bwGWhB0-BdWTQcHDJB7NBYAio,74
-mcp_kb/config.py,sha256=snbGzbeUf-YXah_F4h2IzHzL_wII966Pf3LZWLKZ-uU,2506
-mcp_kb/cli/__init__.py,sha256=dEIRWFycAfPkha1S1Bj_Y6zkvEZv4eF0qtbF9t74r60,67
-mcp_kb/cli/args.py,sha256=0yU5lwjjUkgk91ksocqOdpqO_u5JU6xuCaayiOJ-5pQ,5371
-mcp_kb/cli/main.py,sha256=07pxHS4FRfhNO4EXWe_9psF7PV6axrY92U7kpZZHkA0,3864
-mcp_kb/cli/reindex.py,sha256=WxGCTX35ngXO2AjCXSP4TAUJDGcbCzEOIVl6NIFwVu8,2963
-mcp_kb/data/KNOWLEDBASE_DOC.md,sha256=jrjNdkXNZUIOBZYy9X9ZnRcRWoARJwCKh2pmpiI0oNw,1639
-mcp_kb/data/__init__.py,sha256=UYYuO_n2ikjpwkPSykgleiifYvC0V8_O-atUaRBQUm4,70
-mcp_kb/ingest/__init__.py,sha256=8obrvfa8nLNLYPbi1MHlFUqfoFHgK9YfdryPzAXQ6kU,77
-mcp_kb/ingest/chroma.py,sha256=P3IrPZW3SK3HVayTzyR3KNe_e8aPGiLDfpZswaLmMbE,21849
-mcp_kb/knowledge/__init__.py,sha256=W_dtRbtnQlrDJ_425vWR8BcoZGJ8gC5-wg1De1E654s,76
-mcp_kb/knowledge/bootstrap.py,sha256=DitA1x7i4ZMb9IZyWyw1oPh78iHz9VkHe03sBF9042U,1202
-mcp_kb/knowledge/events.py,sha256=A7CfD7U5bxo6mCCIic83yE7VPixAN05ssw_HKRF2zxw,3549
-mcp_kb/knowledge/search.py,sha256=_hfN89GPoJn-Y1TEEfnYawkgOGxOn_3-f7-lzdAqbMA,5901
-mcp_kb/knowledge/store.py,sha256=JP8_vGMzm6HYxg2Y2LUB1fnguIWYokuO1yCRh2pLym4,9598
-mcp_kb/security/__init__.py,sha256=lF8_XAjzpwhAFresuskXMo0u9v7KFiTJId88wqOAM4Y,62
-mcp_kb/security/path_validation.py,sha256=lhyL1WUVCb4ypxmJx8drGmR7y_b7nNohz_JFRWJ25MQ,3617
-mcp_kb/server/__init__.py,sha256=j9TmxW_WLCoibyQvCsDT1MIuUqSL8sRh2h4u0M4eU0c,74
-mcp_kb/server/app.py,sha256=GnI2z_6C0wwbJd1r-GheQMn1nc4xj71A51_xKLyCUoU,7070
-mcp_kb/utils/__init__.py,sha256=lKhRsjgnbhye1sSlch1_wsAI3eWKE1M6RVIiNlnsvLI,71
-mcp_kb/utils/filesystem.py,sha256=Uyo_lHXF35qRxNXsyDkCs6NC0pDqwDt-D6dw0xtYZQE,2632
-mcp_kb-0.1.0.dist-info/METADATA,sha256=KCfsCIxMSzOzsE7HXtvSmb9d8ouK7ILbab4XNqZjP2Y,5103
-mcp_kb-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-mcp_kb-0.1.0.dist-info/entry_points.txt,sha256=qwJkR3vV7ZeydfS_IYMiDwLv4BdTkrOf4-5neWj25g0,96
-mcp_kb-0.1.0.dist-info/top_level.txt,sha256=IBiz3TNE3FF3TwkbCZpC1kkk6ohTwtBQNSPJNV3-qGA,7
-mcp_kb-0.1.0.dist-info/RECORD,,