ki-manager 2.3.0.dev1__tar.gz → 2.3.0.dev2__tar.gz

{ki_manager-2.3.0.dev1 → ki_manager-2.3.0.dev2}/CHANGELOG.md

@@ -9,6 +9,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.3.0.dev2] — 2026-10-06
+
+### Added
+- `ki_search` output summarization & pagination: compact Markdown list formatting by default (saving up to 60% of context tokens and preventing MCP client disk dumping), reduced default result limit from 10 to 5, and added `offset` parameter for seamless result pagination.
+- `ki_search` format option: added `format: "markdown"|"json"` allowing clients to choose between compact human/LLM-readable lists or raw JSON.
+- `ki_read` and `read_know_file` character offset: added optional `offset` parameter enabling targeted reading from specific character positions without requiring repeated full reads.
+
+### Changed
+- `ki_read` path resolution: resilient cascade resolving paths relative to knowledge root (`.ki-base` by default), project root, subfolder prefixes, or filename basenames across KI and ADR documents.
+- `ki_instructions` tool schema: aligned document list with active workflows (`scaffold-knowledge`, `expand-knowledge`, `sync-knowledge`, `create-adr`), removing deprecated `update-knowledge`.
+
+### Fixed
+- Fixed `KeyError: 'know_root'` in `ki_status` tool when checking active project status.
+
 ## [2.3.0.dev1] — 2026-10-05
 
 ### Added

{ki_manager-2.3.0.dev1 → ki_manager-2.3.0.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ki-manager
-Version: 2.3.0.dev1
+Version: 2.3.0.dev2
 Summary: Knowledge Item (KI) management MCP server for AI-assisted development
 Project-URL: Homepage, https://github.com/Laeryid/KI-base
 Project-URL: Repository, https://github.com/Laeryid/KI-base

{ki_manager-2.3.0.dev1 → ki_manager-2.3.0.dev2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ki-manager"
-version = "2.3.0.dev1"
+version = "2.3.0.dev2"
 description = "Knowledge Item (KI) management MCP server for AI-assisted development"
 readme = "README.md"
 license = { file = "LICENSE" }

{ki_manager-2.3.0.dev1 → ki_manager-2.3.0.dev2}/src/ki_manager/__init__.py

@@ -1,3 +1,3 @@
 
 """ki-manager — Knowledge Item MCP server for AI-assisted development."""
-__version__ = "2.3.0.dev1"
+__version__ = "2.3.0.dev2"

{ki_manager-2.3.0.dev1 → ki_manager-2.3.0.dev2}/src/ki_manager/scripts/ki_search.py

@@ -196,7 +196,8 @@ def search_knowledge(
     query: str,
     project_root: Optional[str] = None,
     scope: str = "all",
-    limit: int = 10,
+    limit: int = 5,
+    offset: int = 0,
     k1: float = 1.5,
     b: float = 0.75,
 ) -> Dict[str, Any]:
@@ -206,7 +207,8 @@ def search_knowledge(
     :param query: Search string (e.g. "workspace detection" or "управление зависимостями")
     :param project_root: Root path of the project. If None, resolved via ki_utils.
     :param scope: "all", "ki", or "adr".
-    :param limit: Max number of results to return.
+    :param limit: Max number of results to return (default: 5).
+    :param offset: Offset index for pagination (default: 0).
     :param k1: BM25 k1 parameter.
     :param b: BM25 b parameter.
     """
@@ -296,10 +298,45 @@ def search_knowledge(
             })
 
     scored_results.sort(key=lambda x: x["score"], reverse=True)
-    final_results = scored_results[:limit]
+    safe_offset = max(0, offset)
+    final_results = scored_results[safe_offset : safe_offset + limit]
 
     return {
         "query": query,
         "total": len(scored_results),
+        "offset": safe_offset,
+        "limit": limit,
         "results": final_results,
     }
+
+
+def format_search_markdown(search_dict: Dict[str, Any]) -> str:
+    """Formats search results into a clean, compact Markdown summary."""
+    query = search_dict.get("query", "")
+    total = search_dict.get("total", 0)
+    results = search_dict.get("results", [])
+    offset = search_dict.get("offset", 0)
+    limit = search_dict.get("limit", 5)
+
+    if total == 0 or not results:
+        return f'No documentation matching "{query}" found.'
+
+    start_idx = offset + 1
+    end_idx = offset + len(results)
+    out = [f'Found {total} result(s) for "{query}" (showing {start_idx}-{end_idx}):\n']
+
+    for i, r in enumerate(results, start=start_idx):
+        doc_type = r.get("type", "ki").upper()
+        title = r.get("title", "")
+        path = r.get("path", "")
+        score = r.get("score", 0.0)
+        snippet = r.get("snippet", "").strip()
+
+        out.append(f"{i}. [{doc_type}] **{title}** (`{path}`, score: {score})")
+        if snippet:
+            out.append(f"   > {snippet}")
+
+    if end_idx < total:
+        out.append(f"\n*Showing {end_idx} of {total} results. Call ki_search(query='{query}', offset={end_idx}) to view more.*")
+
+    return "\n".join(out)

{ki_manager-2.3.0.dev1 → ki_manager-2.3.0.dev2}/src/ki_manager/server.py

@@ -204,8 +204,8 @@ MCP_TOOLS = [
             "- 'knowledge-items' \u2014 table of registered KI files\n"
             "- 'create-adr' \u2014 workflow: document architectural decisions\n"
             "- 'expand-knowledge' \u2014 workflow: deep enrichment of KI files\n"
+            "- 'scaffold-knowledge' \u2014 workflow: bulk scaffold of uncovered modules\n"
             "- 'sync-knowledge' \u2014 workflow: sync KI after code changes\n"
-            "- 'update-knowledge' \u2014 workflow: update KI files\n"
             "Call this before starting any documentation workflow task."
         ),
         "inputSchema": {
@@ -679,7 +679,11 @@ MCP_TOOLS = [
         ),
         "inputSchema": {
             "type": "object",
-            "properties": {"rel_path": {"type": "string", "description": "Path relative to knowledge root/"}},
+            "properties": {
+                "rel_path": {"type": "string", "description": "Path relative to knowledge root/"},
+                "max_chars": {"type": "integer", "description": "Optional maximum number of characters to return"},
+                "offset": {"type": "integer", "default": 0, "description": "Optional character offset to start reading from"},
+            },
             "required": ["rel_path"],
         },
         "annotations": {
@@ -1198,35 +1202,76 @@ def tool_read_file(args: dict) -> Any:
     jail = get_jail_dir()
 
     target = None
-    # 1. Try resolving within jail (knowledge root)
+    norm = ki_utils.normalize_path(rel_path, make_absolute=False)
+    base_name = os.path.basename(norm)
+
+    # 1. Try resolving within jail (knowledge root from config, default .ki-base)
     if jail:
+        # 1a. Direct path inside jail
         try:
-            cand = validate_path(rel_path)
-            if os.path.exists(cand):
+            cand = validate_path(norm)
+            if os.path.exists(cand) and os.path.isfile(cand):
                 target = cand
         except Exception:
             target = None
 
+        # 1b. Try inside jail/knowledge/ (standard structure: <jail>/knowledge/<file>)
+        if not target:
+            try:
+                cand = validate_path(os.path.join("knowledge", norm))
+                if os.path.exists(cand) and os.path.isfile(cand):
+                    target = cand
+            except Exception:
+                target = None
+
+        # 1c. If rel_path starts with the knowledge_root folder name itself (e.g. '.ki-base/...' or 'knowledge/...'),
+        # strip the prefix and resolve inside jail
+        if not target and project_root:
+            rel_to_proj = os.path.relpath(jail, project_root).replace("\\", "/")
+            if norm.startswith(rel_to_proj + "/"):
+                sub_path = norm[len(rel_to_proj) + 1:]
+                try:
+                    cand = validate_path(sub_path)
+                    if os.path.exists(cand) and os.path.isfile(cand):
+                        target = cand
+                except Exception:
+                    pass
+                if not target:
+                    try:
+                        cand = validate_path(os.path.join("knowledge", sub_path))
+                        if os.path.exists(cand) and os.path.isfile(cand):
+                            target = cand
+                    except Exception:
+                        pass
+
     # 2. Try resolving ADR or path relative to project_root
     if not target and project_root:
-        norm = ki_utils.normalize_path(rel_path, make_absolute=False)
         candidates = ki_utils.get_decisions_dirs(project_root, jail)
         # Check by basename in decisions dirs
         for d in candidates:
-            cand_p = os.path.abspath(os.path.join(d, os.path.basename(norm)))
-            if os.path.exists(cand_p) and cand_p.endswith(".md"):
+            cand_p = os.path.abspath(os.path.join(d, base_name))
+            if os.path.exists(cand_p) and cand_p.endswith(".md") and os.path.isfile(cand_p):
                 target = cand_p
                 break
         if not target:
             # Check relative to project root, ensuring it is within decisions or jail
             cand_p = os.path.abspath(os.path.join(project_root, norm))
-            if os.path.exists(cand_p) and cand_p.endswith(".md"):
+            if os.path.exists(cand_p) and cand_p.endswith(".md") and os.path.isfile(cand_p):
                 valid_prefixes = candidates + ([jail] if jail else [])
                 for vp in valid_prefixes:
                     if os.path.normcase(cand_p).startswith(os.path.normcase(vp)):
                         target = cand_p
                         break
 
+    # 3. Fallback: Search by basename in jail (knowledge root) and its subfolders
+    if not target and jail and os.path.exists(jail):
+        for root, _, files in os.walk(jail):
+            if base_name in files:
+                cand_p = os.path.abspath(os.path.join(root, base_name))
+                if cand_p.endswith(".md") and os.path.isfile(cand_p):
+                    target = cand_p
+                    break
+
     if not target or not os.path.exists(target):
         return f"File not found: '{rel_path}'."
 
@@ -1243,14 +1288,31 @@ def tool_read_file(args: dict) -> Any:
             return f"Section '{section}' not found in '{rel_path}'."
         content = sec_content
 
+    offset = 0
+    if args.get("offset") is not None:
+        try:
+            offset = max(0, int(args["offset"]))
+        except (ValueError, TypeError):
+            offset = 0
+
     max_chars = args.get("max_chars")
     if max_chars is not None:
         try:
             mc = int(max_chars)
-            if mc > 0 and len(content) > mc:
-                content = content[:mc] + f"\n\n... [truncated to {mc} characters]"
+            if mc > 0:
+                total_len = len(content)
+                chunk = content[offset : offset + mc]
+                if offset + mc < total_len:
+                    content = chunk + f"\n\n... [truncated to {mc} characters, offset {offset} of {total_len}]"
+                else:
+                    content = chunk
+            elif offset > 0:
+                content = content[offset:]
         except (ValueError, TypeError):
-            pass
+            if offset > 0:
+                content = content[offset:]
+    elif offset > 0:
+        content = content[offset:]
 
     return content
 
@@ -1302,8 +1364,10 @@ def handle_tool_call(name: str, args: dict) -> Any:
             return "\n".join(f"- {v['name']}: {k}" for k, v in reg["projects"].items())
         if name == "ki_status":
             match = ki_utils.find_project_by_cwd(args.get("path"))
-            return (f"Active: {match['name']} at {match['know_root']}" if match
-                    else "No project active for current workspace.")
+            if match:
+                loc = get_jail_dir() or match.get("workspace", "")
+                return f"Active: {match['name']} at {loc}"
+            return "No project active for current workspace."
         if name == "ki_prune_registry":
             reg = ki_utils.load_registry()
             before = len(reg["projects"])
@@ -1401,7 +1465,28 @@ def handle_tool_call(name: str, args: dict) -> Any:
         # ─── File Ops ───
         if name == "read_know_file":
             with open(validate_path(args["rel_path"]), "r", encoding="utf-8") as f:
-                return f.read()
+                content = f.read()
+            offset = 0
+            if args.get("offset") is not None:
+                try:
+                    offset = max(0, int(args["offset"]))
+                except (ValueError, TypeError):
+                    offset = 0
+            max_chars = args.get("max_chars")
+            if max_chars is not None:
+                try:
+                    mc = int(max_chars)
+                    if mc > 0:
+                        total_len = len(content)
+                        chunk = content[offset : offset + mc]
+                        if offset + mc < total_len:
+                            return chunk + f"\n\n... [truncated to {mc} characters, offset {offset} of {total_len}]"
+                        return chunk
+                except (ValueError, TypeError):
+                    pass
+            if offset > 0:
+                return content[offset:]
+            return content
         if name == "write_know_file":
             p = validate_path(args["rel_path"], is_write=True)
             os.makedirs(os.path.dirname(p), exist_ok=True)
@@ -1454,9 +1539,13 @@ def handle_tool_call(name: str, args: dict) -> Any:
         if name == "ki_search":
             query = args.get("query", "").strip()
             scope = args.get("scope", "all")
-            limit = int(args.get("limit", 10))
-            res = ki_search.search_knowledge(query, project_root=get_project_root(), scope=scope, limit=limit)
-            return json.dumps(res, ensure_ascii=False, indent=2)
+            limit = int(args.get("limit", 5))
+            offset = int(args.get("offset", 0))
+            fmt = args.get("format", "markdown")
+            res = ki_search.search_knowledge(query, project_root=get_project_root(), scope=scope, limit=limit, offset=offset)
+            if fmt == "json":
+                return json.dumps(res, ensure_ascii=False, indent=2)
+            return ki_search.format_search_markdown(res)
 
         if name == "ki_read":
             return tool_read_file(args)

{ki_manager-2.3.0.dev1 → ki_manager-2.3.0.dev2}/src/ki_manager/tools/facade.py

@@ -87,8 +87,19 @@ KI_SEARCH_TOOL = {
             },
             "limit": {
                 "type": "integer",
-                "default": 10,
-                "description": "Maximum number of results to return (default: 10).",
+                "default": 5,
+                "description": "Maximum number of results to return (default: 5).",
+            },
+            "offset": {
+                "type": "integer",
+                "default": 0,
+                "description": "Result offset for pagination (default: 0).",
+            },
+            "format": {
+                "type": "string",
+                "enum": ["markdown", "json"],
+                "default": "markdown",
+                "description": "Output format: 'markdown' (compact list, default) or 'json'.",
             },
         },
         "required": ["query"],
@@ -105,14 +116,14 @@ KI_READ_TOOL = {
     "name": "ki_read",
     "description": (
         "Read a Knowledge Item (KI) or ADR markdown file. "
-        "Supports optional section filtering (by markdown header) and character limits to save tokens."
+        "Supports optional section filtering (by markdown header), character limits, and offset."
     ),
     "inputSchema": {
         "type": "object",
         "properties": {
             "rel_path": {
                 "type": "string",
-                "description": "Relative path to file from knowledge root or project root (e.g. '_OVERVIEW.ki.md' or 'decisions/0001_some.md').",
+                "description": "Path or filename of the Knowledge Item or ADR (e.g. 'KI_architecture.md', 'knowledge/KI_architecture.md', or '001_some.md').",
             },
             "section": {
                 "type": "string",
@@ -122,6 +133,11 @@ KI_READ_TOOL = {
                 "type": "integer",
                 "description": "Optional maximum number of characters to return (truncates if exceeded).",
             },
+            "offset": {
+                "type": "integer",
+                "default": 0,
+                "description": "Optional character offset to start reading from (default: 0).",
+            },
         },
         "required": ["rel_path"],
     },