ki-manager 2.2.1__tar.gz → 2.3.0.dev2__tar.gz

ki_manager-2.3.0.dev2/CHANGELOG.md

@@ -0,0 +1,130 @@
+# 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.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
+- `--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.1 → ki_manager-2.3.0.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ki-manager
-Version: 2.2.1
+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
@@ -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.1 → ki_manager-2.3.0.dev2}/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.1 → ki_manager-2.3.0.dev2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ki-manager"
-version = "2.2.1"
+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.2.1 → 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.2.1"
+__version__ = "2.3.0.dev2"

{ki_manager-2.2.1 → ki_manager-2.3.0.dev2}/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.dev2/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.1 → ki_manager-2.3.0.dev2}/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)