ki-manager 2.0.0__tar.gz

ki_manager-2.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bogdan Buliakov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ki_manager-2.0.0/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: ki-manager
+Version: 2.0.0
+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
+Project-URL: Issues, https://github.com/Laeryid/KI-base/issues
+License: MIT License
+        
+        Copyright (c) 2026 Bogdan Buliakov
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: ai,claude,cursor,documentation,knowledge,mcp,windsurf
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# ki-manager — Knowledge Item MCP Server
+
+> AI-powered knowledge management for software projects.  
+> Install once, use across all your projects.
+
+---
+
+## What is ki-manager?
+
+**ki-manager** is an MCP (Model Context Protocol) server that turns any project into a **self-documenting codebase** for AI agents (Claude, Antigravity, Cursor, Windsurf, etc.).
+
+It provides:
+- **Knowledge Items (KI)** — structured Markdown snapshots of each module, stored in `.ki-base/knowledge/`
+- **Coverage Audit** — measures how well your KI base covers your actual code
+- **Dependency Analysis** — auto-updates "Related KIs" by analyzing imports
+- **Git Snapshots** — versioned knowledge state (`git_checkpoint`, `git_restore`)
+- **Scaffolding** — one command creates the complete `.ki-base/` structure in any project
+
+---
+
+## Installation
+
+### Option A: uvx (recommended — no install needed)
+
+```json
+{
+  "mcpServers": {
+    "ki-manager": {
+      "command": "uvx",
+      "args": ["ki-manager"]
+    }
+  }
+}
+```
+
+> Requires [uv](https://docs.astral.sh/uv/) — install with: `curl -LsSf https://astral.sh/uv/install.sh | sh`
+
+### Option B: Smithery (Claude Desktop / Cursor / Windsurf GUI)
+
+Search for **ki-manager** in your IDE's MCP marketplace and click Install.
+
+### Option C: pip
+
+```bash
+pip install ki-manager
+ki-manager  # starts the MCP server
+```
+
+### Option D: Docker
+
+```bash
+docker run -i --rm -v "$(pwd):/workspace" ghcr.io/laeryid/ki-manager
+```
+
+---
+
+## Quickstart
+
+### 1. Add the MCP server to your IDE
+
+Pick one of the options above and add it to your MCP config.
+
+### 2. Initialize a project
+
+In your IDE chat, call the `ki_init_project` tool:
+
+```
+ki_init_project(project_path="/absolute/path/to/your-project")
+```
+
+This creates:
+
+```
+your-project/
+└── .ki-base/
+    ├── config.json          ← machine-specific (auto-added to .gitignore)
+    ├── ki_config.json       ← project settings (commit to git)
+    ├── doc_config.json      ← file→KI map (commit to git)
+    ├── AGENTS.md            ← agent instructions (commit to git)
+    ├── DIR_INDEX.md         ← directory index (commit to git)
+    └── knowledge/
+        └── _OVERVIEW.ki.md  ← starter Knowledge Item
+```
+
+### 3. Start documenting
+
+Use the available tools or slash commands:
+
+| Tool / Command | Action |
+|----------------|--------|
+| `audit_coverage` | Find documentation gaps |
+| `generate_dir_index` | Build directory index |
+| `sync_agents_md` | Sync KI table in AGENTS.md |
+| `git_checkpoint` | Save knowledge snapshot to git |
+| `/expand-knowledge` | Iteratively fill gaps (Antigravity) |
+| `/sync-knowledge` | Full sync workflow (Antigravity) |
+| `/create-adr` | Record architectural decision |
+
+---
+
+## What Goes Into Git?
+
+| Path | Git | Notes |
+|------|:---:|-------|
+| `.ki-base/knowledge/*.ki.md` | ✅ | Project knowledge |
+| `.ki-base/doc_config.json` | ✅ | Module manifest |
+| `.ki-base/ki_config.json` | ✅ | Project settings |
+| `.ki-base/AGENTS.md` | ✅ | Agent instructions |
+| `.ki-base/DIR_INDEX.md` | ✅ | Directory index |
+| `.ki-base/config.json` | ❌ | Machine-specific paths |
+| `.ki-base/doc_state.json` | ❌ | Hash cache |
+
+---
+
+## Security
+
+The MCP server operates in a **sandbox**:
+- All file access is restricted to the `.ki-base/` directory
+- Executable files (`.py`, `.exe`, `.sh`, etc.) cannot be modified via MCP
+- Critical config files are protected from direct overwrite
+
+---
+
+## Project Structure (this repo)
+
+```
+ki-manager/
+├── pyproject.toml            ← pip / uvx package config
+├── smithery.yaml             ← Smithery MCP marketplace config
+├── src/ki_manager/
+│   ├── server.py             ← MCP server entry point
+│   ├── tools/
+│   │   └── scaffold.py       ← ki_init_project implementation
+│   └── scripts/              ← bundled analysis scripts
+│       ├── ki_utils.py       ← shared utilities
+│       ├── audit_coverage.py
+│       ├── sync_agents_md.py
+│       ├── generate_dir_index.py
+│       ├── ki_dependency_analyzer.py
+│       └── ...
+├── knowledge/                ← KI documentation of this repo itself
+└── decisions/                ← Architecture Decision Records
+```
+
+---
+
+## License
+
+MIT — free to use, copy, and adapt.

ki_manager-2.0.0/README.md

@@ -0,0 +1,149 @@
+# ki-manager — Knowledge Item MCP Server
+
+> AI-powered knowledge management for software projects.  
+> Install once, use across all your projects.
+
+---
+
+## What is ki-manager?
+
+**ki-manager** is an MCP (Model Context Protocol) server that turns any project into a **self-documenting codebase** for AI agents (Claude, Antigravity, Cursor, Windsurf, etc.).
+
+It provides:
+- **Knowledge Items (KI)** — structured Markdown snapshots of each module, stored in `.ki-base/knowledge/`
+- **Coverage Audit** — measures how well your KI base covers your actual code
+- **Dependency Analysis** — auto-updates "Related KIs" by analyzing imports
+- **Git Snapshots** — versioned knowledge state (`git_checkpoint`, `git_restore`)
+- **Scaffolding** — one command creates the complete `.ki-base/` structure in any project
+
+---
+
+## Installation
+
+### Option A: uvx (recommended — no install needed)
+
+```json
+{
+  "mcpServers": {
+    "ki-manager": {
+      "command": "uvx",
+      "args": ["ki-manager"]
+    }
+  }
+}
+```
+
+> Requires [uv](https://docs.astral.sh/uv/) — install with: `curl -LsSf https://astral.sh/uv/install.sh | sh`
+
+### Option B: Smithery (Claude Desktop / Cursor / Windsurf GUI)
+
+Search for **ki-manager** in your IDE's MCP marketplace and click Install.
+
+### Option C: pip
+
+```bash
+pip install ki-manager
+ki-manager  # starts the MCP server
+```
+
+### Option D: Docker
+
+```bash
+docker run -i --rm -v "$(pwd):/workspace" ghcr.io/laeryid/ki-manager
+```
+
+---
+
+## Quickstart
+
+### 1. Add the MCP server to your IDE
+
+Pick one of the options above and add it to your MCP config.
+
+### 2. Initialize a project
+
+In your IDE chat, call the `ki_init_project` tool:
+
+```
+ki_init_project(project_path="/absolute/path/to/your-project")
+```
+
+This creates:
+
+```
+your-project/
+└── .ki-base/
+    ├── config.json          ← machine-specific (auto-added to .gitignore)
+    ├── ki_config.json       ← project settings (commit to git)
+    ├── doc_config.json      ← file→KI map (commit to git)
+    ├── AGENTS.md            ← agent instructions (commit to git)
+    ├── DIR_INDEX.md         ← directory index (commit to git)
+    └── knowledge/
+        └── _OVERVIEW.ki.md  ← starter Knowledge Item
+```
+
+### 3. Start documenting
+
+Use the available tools or slash commands:
+
+| Tool / Command | Action |
+|----------------|--------|
+| `audit_coverage` | Find documentation gaps |
+| `generate_dir_index` | Build directory index |
+| `sync_agents_md` | Sync KI table in AGENTS.md |
+| `git_checkpoint` | Save knowledge snapshot to git |
+| `/expand-knowledge` | Iteratively fill gaps (Antigravity) |
+| `/sync-knowledge` | Full sync workflow (Antigravity) |
+| `/create-adr` | Record architectural decision |
+
+---
+
+## What Goes Into Git?
+
+| Path | Git | Notes |
+|------|:---:|-------|
+| `.ki-base/knowledge/*.ki.md` | ✅ | Project knowledge |
+| `.ki-base/doc_config.json` | ✅ | Module manifest |
+| `.ki-base/ki_config.json` | ✅ | Project settings |
+| `.ki-base/AGENTS.md` | ✅ | Agent instructions |
+| `.ki-base/DIR_INDEX.md` | ✅ | Directory index |
+| `.ki-base/config.json` | ❌ | Machine-specific paths |
+| `.ki-base/doc_state.json` | ❌ | Hash cache |
+
+---
+
+## Security
+
+The MCP server operates in a **sandbox**:
+- All file access is restricted to the `.ki-base/` directory
+- Executable files (`.py`, `.exe`, `.sh`, etc.) cannot be modified via MCP
+- Critical config files are protected from direct overwrite
+
+---
+
+## Project Structure (this repo)
+
+```
+ki-manager/
+├── pyproject.toml            ← pip / uvx package config
+├── smithery.yaml             ← Smithery MCP marketplace config
+├── src/ki_manager/
+│   ├── server.py             ← MCP server entry point
+│   ├── tools/
+│   │   └── scaffold.py       ← ki_init_project implementation
+│   └── scripts/              ← bundled analysis scripts
+│       ├── ki_utils.py       ← shared utilities
+│       ├── audit_coverage.py
+│       ├── sync_agents_md.py
+│       ├── generate_dir_index.py
+│       ├── ki_dependency_analyzer.py
+│       └── ...
+├── knowledge/                ← KI documentation of this repo itself
+└── decisions/                ← Architecture Decision Records
+```
+
+---
+
+## License
+
+MIT — free to use, copy, and adapt.

ki_manager-2.0.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ki-manager"
+version = "2.0.0"
+description = "Knowledge Item (KI) management MCP server for AI-assisted development"
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.8"
+keywords = ["mcp", "knowledge", "ai", "documentation", "cursor", "windsurf", "claude"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Documentation",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+[project.scripts]
+ki-manager = "ki_manager.server:main"
+
+[project.urls]
+Homepage = "https://github.com/Laeryid/KI-base"
+Repository = "https://github.com/Laeryid/KI-base"
+Issues = "https://github.com/Laeryid/KI-base/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ki_manager"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/ki_manager/**", "README.md", "LICENSE"]

ki_manager-2.0.0/src/ki_manager/__init__.py

@@ -0,0 +1,2 @@
+"""ki-manager — Knowledge Item MCP server for AI-assisted development."""
+__version__ = "2.0.0"

ki_manager-2.0.0/src/ki_manager/scripts/add_ki_to_config.py

@@ -0,0 +1,57 @@
+"""
+add_ki_to_config.py
+
+CLI helper: registers a new Knowledge Item in doc_config.json.
+
+Usage:
+    python add_ki_to_config.py <ki_name> <description> <covers_json> <depends_on_json>
+
+Example:
+    python add_ki_to_config.py KI_utils.md "Utility helpers" '["Utilities"]' '["src/utils/"]'
+"""
+
+import sys
+import os
+import json
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import ki_utils
+
+
+def add_ki(ki_name: str, description: str, covers: list, depends_on: list):
+    config = ki_utils.get_doc_config()
+    if not config:
+        print("[!] doc_config.json not found or empty")
+        return
+
+    if "knowledge_items" not in config:
+        config["knowledge_items"] = {}
+
+    config["knowledge_items"][ki_name] = {
+        "description": description,
+        "covers": covers,
+        "depends_on": depends_on,
+    }
+
+    with open(ki_utils.get_doc_config_path(), "w", encoding="utf-8") as f:
+        json.dump(config, f, indent=4, ensure_ascii=False)
+
+    print(f"[+] KI registered in doc_config.json: {ki_name}")
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 5:
+        print("Usage: python add_ki_to_config.py <ki_name> <description> "
+              "<covers_list_json> <depends_on_list_json>")
+        sys.exit(1)
+
+    ki_name = sys.argv[1]
+    description = sys.argv[2]
+    try:
+        covers = json.loads(sys.argv[3])
+        depends_on = json.loads(sys.argv[4])
+    except json.JSONDecodeError:
+        print("[!] Error: covers and depends_on must be valid JSON arrays")
+        sys.exit(1)
+
+    add_ki(ki_name, description, covers, depends_on)

ki_manager-2.0.0/src/ki_manager/scripts/analyze_module.py

@@ -0,0 +1,103 @@
+import os
+import sys
+import argparse
+import io
+from typing import Dict, List, Optional
+
+# Добавляем путь к скриптам, чтобы импортировать ki_utils
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import ki_utils
+
+def format_size(size_bytes: int) -> str:
+    if size_bytes < 1024:
+        return f"{size_bytes} B"
+    elif size_bytes < 1024 * 1024:
+        return f"{size_bytes / 1024:.2f} KB"
+    else:
+        return f"{size_bytes / (1024 * 1024):.2f} MB"
+
+def get_tracked_files(config: Dict) -> Dict[str, str]:
+    """Возвращает мапу {путь_к_файлу: имя_KI}"""
+    tracked = {}
+    ki_items = config.get("knowledge_items", {})
+    for ki_name, ki_data in ki_items.items():
+        for file_path in ki_data.get("depends_on", []):
+            tracked[os.path.normpath(file_path)] = ki_name
+    return tracked
+
+def analyze_path(target_path: str, recursive: bool = False):
+    project_root = ki_utils.get_project_root()
+    config = ki_utils.get_doc_config()
+    tracked_map = get_tracked_files(config)
+    
+    # Резолвим абсолютный путь
+    abs_target = os.path.normpath(os.path.join(project_root, target_path))
+
+    if not os.path.exists(abs_target):
+        print(f"Error: Path {target_path} not found.")
+        return
+
+    print(f"### Analysis for: `{target_path}`")
+    print("| Status | File / Directory | Size | KI Link | Density |")
+    print("|:---:|:---|:---|:---|:---|")
+
+    items = []
+    if os.path.isfile(abs_target):
+        items = [abs_target]
+    elif os.path.isdir(abs_target):
+        if recursive:
+            for root, dirs, files in os.walk(abs_target):
+                if any(part in root.split(os.sep) for part in ["__pycache__", ".git", "node_modules", "venv", ".venv"]):
+                    continue
+                for name in files:
+                    items.append(os.path.join(root, name))
+        else:
+            for name in os.listdir(abs_target):
+                items.append(os.path.join(abs_target, name))
+
+    for item_path in sorted(items):
+        try:
+            rel_path = os.path.relpath(item_path, project_root)
+            is_dir = os.path.isdir(item_path)
+            size = 0
+            if is_dir:
+                for root, _, files in os.walk(item_path):
+                    for f in files:
+                        fp = os.path.join(root, f)
+                        if os.path.exists(fp):
+                            size += os.path.getsize(fp)
+            else:
+                size = os.path.getsize(item_path)
+
+            ki_name = tracked_map.get(os.path.normpath(rel_path), "")
+            status = "✅" if ki_name else "❌"
+            
+            density = "-"
+            if ki_name:
+                ki_path = os.path.join(ki_utils.get_knowledge_root(), "knowledge", ki_name)
+                if os.path.exists(ki_path):
+                    ki_size = os.path.getsize(ki_path)
+                    if ki_size > 0:
+                        density_val = size / ki_size
+                        density = f"{density_val:.1f} B_code/B_doc"
+            
+            name_display = f"`{os.path.basename(item_path)}`" + ("/" if is_dir else "")
+            print(f"| {status} | {name_display} | {format_size(size)} | {ki_name} | {density} |")
+        except:
+            continue
+
+def main():
+    # Исправление кодировки для Windows при прямом запуске
+    if sys.platform == "win32":
+        import io
+        sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8", errors="replace")
+
+    parser = argparse.ArgumentParser(description="Analyze module statistics with knowledge context.")
+    parser.add_argument("path", help="Path relative to project root")
+    parser.add_argument("--recursive", action="store_true", help="Recursive analysis")
+    
+    args = parser.parse_args()
+    analyze_path(args.path, args.recursive)
+
+if __name__ == "__main__":
+    main()