ki-manager 2.2.0__tar.gz → 2.3.0.dev1__tar.gz

ki_manager-2.3.0.dev1/CHANGELOG.md

@@ -0,0 +1,116 @@
+# Changelog
+
+All notable changes to the `ki-manager` project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+<!-- Note: This changelog is intended for end-users and AI agents. It must always be maintained in English and focus on user-facing features, behavior changes, and bug fixes rather than internal implementation details. -->
+
+## [Unreleased]
+
+## [2.3.0.dev1] — 2026-10-05
+
+### Added
+- `--tool-mode full|compact` CLI option and `KI_TOOL_MODE` environment variable: compact facade mode reducing `tools/list` from 33 schemas to 6 essential tools (`ki_instructions`, `ki_search`, `ki_read`, `ki_tools`, `ki_call`, `ki_mutate`), drastically reducing context token usage for MCP clients.
+- `ki_search` MCP tool & search engine: BM25 ranking across Knowledge Items and ADRs without external embedding dependencies, featuring bilingual RU/EN stemming, weighted fields (Title x5, Headers x3, Path x2, Body x1), and contextual snippets.
+- `ki_read` MCP tool: token-efficient reader for KI and ADR markdown files with section filtering and character limit truncation.
+- `ki_tools` MCP tool: grouped catalog of all available tools and on-demand JSON schema inspector.
+- `ki_call` and `ki_mutate` facade dispatchers: safe routing with schema validation and enforcement of `readOnlyHint` (read-only queries in `ki_call`, mutations in `ki_mutate`).
+- Dynamic instructions & template directives: workflows and server rules dynamically adapt tool call examples and `allowed-tools` frontmatter to active `--tool-mode` (`full` vs `compact`) via HTML comment directives (`<!-- if-compact -->`), maintaining a single source of truth without content divergence.
+- Dedicated Agent Skill `ki-manager-workflows`: guide in `.agent/skills/ki-manager-workflows/` for authoring and maintaining dual-mode workflow instructions.
+- CLI `install-skills` mode option: `ki-manager install-skills` supports `--tool-mode full|compact` to render installed skill markdown for the intended client environment.
+- `add_ki_to_config` MCP tool and CLI helper: safely register or update Knowledge Items in `doc_config.json` with sandbox checks and atomic file updates.
+- `edit_doc_config` MCP tool: granular and safe modifications (`set`, `append`, `delete`) to service sections (`tracked_modules`, `artifacts`, `coverage_settings`) of `doc_config.json`.
+- `sync_agents_md` MCP tool and script: synchronize Knowledge Items and ADR tables in `AGENTS.md` using the single source of truth from `doc_config.json` and `decisions/`.
+- Per-project configurable agent instructions sync: `sync_agents_md` can be disabled via `"sync_agents_md": false` in `ki_config.json` to prevent context pollution in large projects.
+- `create_adr` MCP tool: create new Architecture Decision Records (ADR) with auto-incremented sequential ID prefix (`XXX`), standardized metadata, registration in `doc_config.json`, and automatic `AGENTS.md` sync.
+- Structured ADR table parser and enhanced `ki://adr-list.md` virtual resource displaying ID, Title, Status, Date, and File links.
+- Automatic IDE MCP tool schema generation (`<tool>.json`) for Antigravity, Cursor, and Windsurf on startup.
+- Comprehensive positive and negative test suite for configuration tools, ADR creation, synchronization rules, and sandbox enforcement.
+- Flexible configuration discovery: `ki_config.json` can now reside in project root, `.config/`, `config/`, `.ki-base/`, or `.know/`.
+- Fileless project registration: `ki_register_project` now supports registering projects directly via `workspace` and `inline_config` in `~/.ki_base/registry.json` without requiring configuration files on disk.
+- First-class custom knowledge root support: `paths.knowledge_root` is dynamically resolved and respected across all tools, engines, and scripts without chicken-and-egg discovery issues.
+- Configurable scaffolding: `ki_init_project` now accepts `knowledge_root` and `config_location` (`root` or `knowledge_dir`) parameters.
+- Dynamic workflow paths: workflow instructions dynamically substitute `{{KI_DIR}}` with the active project's knowledge folder name.
+- Unit and negative test coverage for flexible discovery, custom roots, and registry validation errors.
+
+### Changed
+- `scaffold.migrate_project` now preserves existing `AGENTS.md` files instead of forcibly deleting them.
+- Neutralized MCP tool descriptions and server prompt schemas, replacing hardcoded `.ki-base/` with dynamic references.
+
+
+### Fixed
+- Fixed an issue where `write_know_file` could permanently delete the contents of a file (leaving 0 bytes) if an encoding error occurred during saving.
+- Fixed server crashes and communication failures on Windows when handling text with emojis or special Unicode characters.
+- Fixed `edit_know_file` frequently failing to find and replace text blocks on Windows due to invisible line-ending mismatches (CRLF vs LF).
+- Fixed the `update_last_verified` tool being completely unusable due to a "missing script" error.
+- Fixed `git_checkpoint` failing to create backups when the project contained `.gitignore`'d files.
+- Fixed incorrect schema definitions that prevented AI agents from successfully calling parameterless tools.
+- Fixed outdated workflow instructions that were causing AI agents to fail by using the deprecated `ki_call` syntax.
+
+## [2.2.0] — 2026-09-24
+
+### Added
+- `ki_graph_visualize` MCP tool: on-the-fly Mermaid architecture diagrams visualizing dependencies and file clusters across Knowledge Items.
+- Cross-platform CI matrix workflow testing both Ubuntu and Windows environments on Python 3.10, 3.11, and 3.12.
+- End-to-end MCP integration test suite validating real JSON-RPC stdio subprocess communication, handshake, and tool execution.
+- Automated pre-flight release verification gate ensuring zero broken packages before release tagging.
+
+### Fixed
+- Proper exit codes and help formatting for `ki-manager-skills` CLI flags (`--help`, `-h`, `--version`).
+
+## [2.1.4] — 2026-09-22
+
+### Added
+- Unified file and directory exclusion engine supporting glob patterns (`*`, `?`) across configuration files (`config.json`, `doc_config.json`, `ki_config.json`).
+- Official project changelog following the Keep a Changelog standard.
+
+### Changed
+- Knowledge audit tools (`audit_coverage`, `find_unmapped_files`, `generate_dir_index`, `analyze_dependencies`) now consistently respect all configured exclusion rules.
+
+### Fixed
+- UTF-8 encoding crashes when running MCP tool scripts in Windows environments.
+
+## [2.1.3] — 2026-08-12
+
+### Added
+- `ki_finalize_scaffolds` MCP tool for bulk finalizing generated Knowledge Item drafts.
+- Bundled `scaffold-knowledge` workflow for AI coding assistants.
+- Installation hint for `ki-manager-skills install-skills` displayed during server startup.
+
+### Changed
+- Synchronized Smithery catalog manifest with updated schemas for all 25 MCP tools.
+
+## [2.1.2] — 2026-08-11
+
+### Fixed
+- Test suite verification during automated package build and release.
+
+## [2.1.1] — 2026-08-11
+
+### Fixed
+- Workspace path resolution compliance with the updated MCP protocol specification.
+
+## [2.1.0] — 2026-08-11
+
+### Added
+- Support for `server/discover` handshake and workspace folder detection under MCP 2026-07-28 protocol.
+- `ki-manager-skills` CLI command to easily install bundled workflows into IDE skill directories.
+- Automated release workflow for publishing packages to PyPI and Smithery Registry.
+
+## [2.0.0] — 2026-07-24
+
+### Added
+- Initial 2.0 release of the `ki-manager` MCP server for project knowledge base management.
+
+[Unreleased]: https://github.com/Laeryid/KI-base/compare/v2.3.0.dev1...HEAD
+[2.3.0.dev1]: https://github.com/Laeryid/KI-base/compare/v2.2.1...v2.3.0.dev1
+[2.2.1]: https://github.com/Laeryid/KI-base/compare/v2.2.0...v2.2.1
+[2.2.0]: https://github.com/Laeryid/KI-base/compare/v2.1.4...v2.2.0
+[2.1.4]: https://github.com/Laeryid/KI-base/compare/v2.1.3...v2.1.4
+[2.1.3]: https://github.com/Laeryid/KI-base/compare/v2.1.2...v2.1.3
+[2.1.2]: https://github.com/Laeryid/KI-base/compare/v2.1.1...v2.1.2
+[2.1.1]: https://github.com/Laeryid/KI-base/compare/v2.1.0...v2.1.1
+[2.1.0]: https://github.com/Laeryid/KI-base/compare/v2.0.37...v2.1.0
+[2.0.0]: https://github.com/Laeryid/KI-base/releases/tag/v2.0.0

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ki-manager
-Version: 2.2.0
+Version: 2.3.0.dev1
 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
@@ -43,6 +43,10 @@ Classifier: Topic :: Software Development :: Documentation
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Laeryid/KI-base/main/ki_manager_logo.png" width="150" alt="ki-manager Logo">
+</p>
+
 # ki-manager — Knowledge Item MCP Server
 
 > AI-powered knowledge management for software projects.  
@@ -122,6 +126,23 @@ On Windows:
 }
 ```
 
+### Compact Mode (Token Saver)
+
+By default, `ki-manager` runs in `full` mode and exposes all tools directly. For AI clients that inject tool definitions into the context window, you can enable compact facade mode to expose only 6 essential tools (`ki_instructions`, `ki_search`, `ki_read`, `ki_tools`, `ki_call`, `ki_mutate`):
+
+```json
+{
+  "mcpServers": {
+    "ki-manager": {
+      "command": "ki-manager",
+      "args": ["--tool-mode", "compact"]
+    }
+  }
+}
+```
+
+Alternatively, set the environment variable `KI_TOOL_MODE=compact`.
+
 ---
 
 ## Quickstart
@@ -164,6 +185,10 @@ Use the available tools or slash commands:
 | `ki_scaffold` | Create stub KI files for uncovered modules |
 | `ki_scaffold_status` | Show pending vs enriched scaffold KIs |
 | `ki_finalize_scaffolds` | Strip scaffold markers, update doc_config summaries |
+| `add_ki_to_config` | Register or update Knowledge Item in `doc_config.json` |
+| `edit_doc_config` | Safely modify `doc_config.json` (`tracked_modules`, `artifacts`, `coverage_settings`) |
+| `sync_agents_md` | Sync Knowledge Items and ADR tables in `AGENTS.md` (can be disabled via `sync_agents_md: false` in `ki_config.json`) |
+| `create_adr` | Create structured ADR with sequential ID, template, and auto-registration |
 | `analyze_all_dependencies` | Update "Related KIs" links across all KIs |
 | `git_checkpoint` | Save knowledge snapshot to git |
 | `/scaffold-knowledge` | Bootstrap KI stubs → AI enrichment → finalize |

{ki_manager-2.2.0 → ki_manager-2.3.0.dev1}/README.md

@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Laeryid/KI-base/main/ki_manager_logo.png" width="150" alt="ki-manager Logo">
+</p>
+
 # ki-manager — Knowledge Item MCP Server
 
 > AI-powered knowledge management for software projects.  
@@ -77,6 +81,23 @@ On Windows:
 }
 ```
 
+### Compact Mode (Token Saver)
+
+By default, `ki-manager` runs in `full` mode and exposes all tools directly. For AI clients that inject tool definitions into the context window, you can enable compact facade mode to expose only 6 essential tools (`ki_instructions`, `ki_search`, `ki_read`, `ki_tools`, `ki_call`, `ki_mutate`):
+
+```json
+{
+  "mcpServers": {
+    "ki-manager": {
+      "command": "ki-manager",
+      "args": ["--tool-mode", "compact"]
+    }
+  }
+}
+```
+
+Alternatively, set the environment variable `KI_TOOL_MODE=compact`.
+
 ---
 
 ## Quickstart
@@ -119,6 +140,10 @@ Use the available tools or slash commands:
 | `ki_scaffold` | Create stub KI files for uncovered modules |
 | `ki_scaffold_status` | Show pending vs enriched scaffold KIs |
 | `ki_finalize_scaffolds` | Strip scaffold markers, update doc_config summaries |
+| `add_ki_to_config` | Register or update Knowledge Item in `doc_config.json` |
+| `edit_doc_config` | Safely modify `doc_config.json` (`tracked_modules`, `artifacts`, `coverage_settings`) |
+| `sync_agents_md` | Sync Knowledge Items and ADR tables in `AGENTS.md` (can be disabled via `sync_agents_md: false` in `ki_config.json`) |
+| `create_adr` | Create structured ADR with sequential ID, template, and auto-registration |
 | `analyze_all_dependencies` | Update "Related KIs" links across all KIs |
 | `git_checkpoint` | Save knowledge snapshot to git |
 | `/scaffold-knowledge` | Bootstrap KI stubs → AI enrichment → finalize |

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

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

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

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

{ki_manager-2.2.0 → ki_manager-2.3.0.dev1}/src/ki_manager/cli.py

@@ -11,6 +11,7 @@ Usage:
 """
 
 import sys
+import os
 import argparse
 from pathlib import Path
 
@@ -61,6 +62,13 @@ def install_skills(argv=None):
         default=None,
         help="Target skills directory (default: current working directory)",
     )
+    parser.add_argument(
+        "--tool-mode",
+        type=str,
+        choices=["full", "compact"],
+        default=None,
+        help="Format for skill instructions (default: full, or KI_TOOL_MODE env var)",
+    )
     args = parser.parse_args(argv)
 
     target = Path(args.path).resolve() if args.path else Path.cwd()
@@ -77,9 +85,17 @@ def install_skills(argv=None):
     installed = []
     skipped = []
 
+    # Import facade renderer
+    sys.path.insert(0, str(_PACKAGE_DIR / "tools"))
+    from facade import render_instruction
+    target_mode = (args.tool_mode or os.environ.get("KI_TOOL_MODE", "full")).lower()
+    if target_mode not in ("full", "compact"):
+        target_mode = "full"
+
     for wf_file in workflow_files:
-        content = wf_file.read_text(encoding="utf-8")
-        meta, _ = _parse_frontmatter(content)
+        raw_content = wf_file.read_text(encoding="utf-8")
+        rendered_content = render_instruction(raw_content, tool_mode=target_mode)
+        meta, _ = _parse_frontmatter(rendered_content)
         
         skill_name = meta.get("name") or f"ki-manager-{wf_file.stem}"
         skill_dir = target / skill_name
@@ -90,7 +106,7 @@ def install_skills(argv=None):
             continue
         
         skill_dir.mkdir(parents=True, exist_ok=True)
-        skill_md.write_text(content, encoding="utf-8")
+        skill_md.write_text(rendered_content, encoding="utf-8")
         installed.append(skill_name)
 
     print(f"Installed: {len(installed)} skill(s)")

ki_manager-2.3.0.dev1/src/ki_manager/scripts/add_ki_to_config.py

@@ -0,0 +1,80 @@
+"""
+add_ki_to_config.py
+
+CLI helper and module function to register or update a Knowledge Item in doc_config.json.
+"""
+
+import sys
+import os
+import json
+import argparse
+from typing import List, Optional
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import ki_utils
+
+
+def add_ki(
+    ki_name: str,
+    description: str,
+    covers: Optional[List[str]] = None,
+    depends_on: Optional[List[str]] = None,
+    summary: Optional[str] = None
+) -> str:
+    """
+    Registers or updates a Knowledge Item in doc_config.json.
+    """
+    if not ki_name:
+        raise ValueError("ki_name is required.")
+
+    covers = covers if covers is not None else []
+    depends_on = depends_on if depends_on is not None else []
+
+    config = ki_utils.get_doc_config()
+    if not config and not ki_utils.get_doc_config_path():
+        raise PermissionError("No active workspace detected or doc_config.json not found.")
+
+    if "knowledge_items" not in config:
+        config["knowledge_items"] = {}
+
+    existing = config["knowledge_items"].get(ki_name, {})
+    entry = {
+        "description": description if description else existing.get("description", ""),
+        "covers": covers,
+        "depends_on": depends_on,
+    }
+    
+    if summary:
+        entry["summary"] = summary
+    elif "summary" in existing:
+        entry["summary"] = existing["summary"]
+    elif description:
+        entry["summary"] = description
+
+    config["knowledge_items"][ki_name] = entry
+    ki_utils.save_doc_config(config)
+    return f"Knowledge Item '{ki_name}' successfully registered in doc_config.json"
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Add or update a Knowledge Item in doc_config.json")
+    parser.add_argument("ki_name", type=str, help="Knowledge Item filename")
+    parser.add_argument("description", type=str, help="KI description")
+    parser.add_argument("--covers", type=str, default="[]", help="JSON array of covered modules")
+    parser.add_argument("--depends-on", type=str, default="[]", help="JSON array of dependencies")
+    parser.add_argument("--summary", type=str, default=None, help="Optional summary text")
+
+    args = parser.parse_args()
+    try:
+        covers = json.loads(args.covers)
+        depends_on = json.loads(args.depends_on)
+    except json.JSONDecodeError as e:
+        print(f"Error decoding JSON arguments: {e}")
+        sys.exit(1)
+
+    result = add_ki(args.ki_name, args.description, covers, depends_on, args.summary)
+    print(result)
+
+
+if __name__ == "__main__":
+    main()

{ki_manager-2.2.0 → ki_manager-2.3.0.dev1}/src/ki_manager/scripts/generate_dir_index.py

@@ -94,7 +94,7 @@ def build_tree(root: str, knowledge_root_name: str,
 def generate_dir_index(output_path: str, max_depth: int = 3) -> None:
     project_root = get_project_root()
     knowledge_root = get_knowledge_root()
-    knowledge_root_name = os.path.basename(knowledge_root) if knowledge_root else ".know"
+    knowledge_root_name = os.path.basename(knowledge_root) if knowledge_root else ".ki-base"
     now = datetime.now(timezone.utc).strftime("%Y-%m-%d")
     project_name = os.path.basename(os.path.abspath(project_root))
     total_files = count_files_in_dir(project_root)

{ki_manager-2.2.0 → ki_manager-2.3.0.dev1}/src/ki_manager/scripts/ki_graph_visualize.py

@@ -14,6 +14,7 @@ import os
 import sys
 import re
 import argparse
+import textwrap
 from pathlib import Path
 from typing import Dict, List, Optional, Set, Tuple, Any
 
@@ -45,16 +46,31 @@ def clean_label(text: str) -> str:
     return text.replace('"', "'").replace("\n", " ").strip()
 
 
+def wrap_label(text: str, width: int = 35) -> str:
+    """Wraps long labels with <br/> for compact Mermaid node rendering."""
+    cleaned = clean_label(text)
+    if len(cleaned) <= width:
+        return cleaned
+    parts = textwrap.wrap(cleaned, width=width)
+    return "<br/>".join(parts)
+
+
 def build_mermaid_graph(
     mode: str = "semantic",
     ki_filter: Optional[str] = None,
-    direction: str = "TD",
+    direction: Optional[str] = None,
     max_unmapped: int = 15,
+    max_files_per_ki: int = 10,
 ) -> str:
     """
     Generates Mermaid graph markdown based on doc_config.json and dependency analysis.
     """
-    direction = direction.upper() if direction.upper() in ("TD", "LR", "TB", "RL", "BT") else "TD"
+    # Adaptive direction: LR (horizontal) for focused single-KI subgraphs, TD (top-down) for global overviews
+    if not direction:
+        direction = "LR" if ki_filter else "TD"
+    else:
+        direction = direction.upper() if direction.upper() in ("TD", "LR", "TB", "RL", "BT") else "TD"
+
     doc_config = ki_utils.get_doc_config()
     knowledge_items: Dict[str, Any] = doc_config.get("knowledge_items", {}) if doc_config else {}
 
@@ -113,7 +129,7 @@ def build_mermaid_graph(
             files_count = len(info.get("depends_on", []))
             ki_id = sanitize_id(ki_name, prefix="ki")
             display_title = info.get("summary") or os.path.splitext(ki_name)[0]
-            lines.append(f'  {ki_id}["{clean_label(display_title)}<br/>({files_count} files)"]')
+            lines.append(f'  {ki_id}["{wrap_label(display_title, width=32)}<br/>({files_count} files)"]')
 
         for src, dst in sorted(edges):
             if src in visible_kis and dst in visible_kis:
@@ -127,12 +143,29 @@ def build_mermaid_graph(
             subgraph_id = sanitize_id(ki_name, prefix="sg")
             display_title = info.get("summary") or os.path.splitext(ki_name)[0]
 
-            lines.append(f'  subgraph {subgraph_id} ["{clean_label(display_title)}"]')
+            lines.append(f'  subgraph {subgraph_id} ["{wrap_label(display_title, width=40)}"]')
             if depends_on:
-                for file_path in sorted(depends_on):
-                    fid = sanitize_id(f"{ki_name}_{file_path}", prefix="f")
-                    basename = os.path.basename(file_path)
-                    lines.append(f'    {fid}["{clean_label(basename)}"]')
+                # If global semantic mode (no filter), limit files per KI to prevent visual spaghetti
+                files_to_render = depends_on
+                overflow_count = 0
+                if not ki_filter and len(depends_on) > max_files_per_ki:
+                    files_to_render = depends_on[:max_files_per_ki]
+                    overflow_count = len(depends_on) - max_files_per_ki
+
+                for file_path in sorted(files_to_render):
+                    is_dir = file_path.endswith(("/", "\\"))
+                    clean_path = file_path.rstrip("/\\")
+                    if not is_dir and analyzer and (analyzer.project_root / clean_path).is_dir():
+                        is_dir = True
+
+                    fid = sanitize_id(f"{ki_name}_{clean_path}", prefix="f")
+                    basename = os.path.basename(clean_path) or clean_path
+                    icon = "📁 " if is_dir else ""
+                    lines.append(f'    {fid}["{icon}{clean_label(basename)}"]')
+
+                if overflow_count > 0:
+                    more_id = sanitize_id(f"more_{ki_name}", prefix="f")
+                    lines.append(f'    {more_id}["... and {overflow_count} more files"]')
             else:
                 placeholder_id = sanitize_id(f"empty_{ki_name}", prefix="node")
                 lines.append(f'    {placeholder_id}["(no tracked files)"]')
@@ -188,8 +221,8 @@ def main():
     parser.add_argument(
         "--direction",
         choices=["TD", "LR", "TB", "RL", "BT"],
-        default="TD",
-        help="Mermaid flowchart direction (default: TD)",
+        default=None,
+        help="Mermaid flowchart direction (default: LR for focused --ki, TD for global)",
     )
     args = parser.parse_args()