source-kb 0.2.2__py3-none-any.whl

mcp_server/tools/generation.py

@@ -0,0 +1,184 @@
+"""Generation fallback tool — direct LLM API call for agents without sub-agent support."""
+
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+
+
+def register(mcp: FastMCP) -> None:
+    """Register generation tools on the MCP server."""
+
+    @mcp.tool()
+    def generate_doc(
+        kb_name: str,
+        module_name: str,
+        doc_type: str,
+        shard: int = 0,
+    ) -> str:
+        """Directly call the LLM API to generate a single document (fallback when sub-agent capability is unavailable).
+
+        Requires environment variables:
+        - LLM_BASE_URL: API endpoint (e.g., https://api.anthropic.com)
+        - LLM_API_KEY: API key
+        - LLM_MODEL: Model name (e.g., claude-sonnet-4-6)
+
+        Internal flow: render_prompt -> call LLM -> write output file
+
+        Args:
+            kb_name: Knowledge base name
+            module_name: Module name
+            doc_type: Document type
+            shard: Shard index (0 = no sharding)
+        """
+        import os
+
+        # Check LLM config
+        base_url = os.environ.get("LLM_BASE_URL", "")
+        api_key = os.environ.get("LLM_API_KEY", "")
+        model = os.environ.get("LLM_MODEL", "")
+
+        if not all([base_url, api_key, model]):
+            missing = []
+            if not base_url:
+                missing.append("LLM_BASE_URL")
+            if not api_key:
+                missing.append("LLM_API_KEY")
+            if not model:
+                missing.append("LLM_MODEL")
+            return json.dumps({
+                "status": "error",
+                "message": f"Missing environment variables: {', '.join(missing)}. generate_doc requires direct LLM API access.",
+                "hint": "If your agent supports sub-agents, use get_subagent_prompt to get the prompt and dispatch a sub-agent instead.",
+            }, ensure_ascii=False, indent=2)
+
+        from mcp_server import find_config
+        from core.config import load_config
+        from core.preset import load_preset, get_template_path
+        from core.prompt.renderer import render_prompt
+        from core.prompt.variables import ReferencePromptAssembler
+
+        config_path = find_config()
+        if not config_path:
+            return json.dumps({"status": "error", "message": "kb-project.yaml not found"})
+
+        config = load_config(config_path)
+        kb_cfg = config.get_kb(kb_name)
+        preset_name = kb_cfg.get("preset", "generic")
+        preset = load_preset(preset_name)
+
+        # Resolve template
+        template_name = get_template_path(preset, doc_type, preset_name)
+        if not template_name:
+            template_name = f"subagent-{doc_type}.md"
+
+        from core.preset import find_preset_template
+        from mcp_server import PROJECT_ROOT
+        template_path = find_preset_template(preset_name, template_name)
+        if not template_path:
+            candidate = PROJECT_ROOT / "skills" / "kb-init" / "templates" / template_name
+            if candidate.exists():
+                template_path = candidate
+
+        if not template_path:
+            return json.dumps({
+                "status": "error",
+                "message": f"Template not found: {template_name}",
+            }, ensure_ascii=False, indent=2)
+
+        # Render prompt
+        extra_vars: dict[str, str] = {}
+        if shard > 0:
+            base_dir = config.config_path.parent
+            kb_dir = Path(kb_cfg["knowledge_dir"])
+            if not kb_dir.is_absolute():
+                kb_dir = (base_dir / kb_dir).resolve()
+            module_dir = kb_dir / module_name
+            shard_file = module_dir / ".meta" / "shards" / f"{doc_type}-shard-{shard}.txt"
+            if shard_file.exists():
+                extra_vars["file_list_override"] = str(shard_file)
+
+        assembler = ReferencePromptAssembler(
+            project_root=config.config_path.parent,
+            preset=preset,
+        )
+
+        rendered_prompt = render_prompt(
+            template_path=template_path,
+            config=config.raw,
+            kb_name=kb_name,
+            module_name=module_name,
+            doc_type=doc_type,
+            assembler=assembler,
+            extras=extra_vars,
+            preset=preset,
+        )
+
+        # Determine output path
+        base_dir = config.config_path.parent
+        kb_dir = Path(kb_cfg["knowledge_dir"])
+        if not kb_dir.is_absolute():
+            kb_dir = (base_dir / kb_dir).resolve()
+        module_dir = kb_dir / module_name
+        module_dir.mkdir(parents=True, exist_ok=True)
+
+        doc_types_cfg = preset.get("doc_types", {})
+        dt_cfg = doc_types_cfg.get(doc_type, {})
+        filename = dt_cfg.get("filename", f"{doc_type}.md") if isinstance(dt_cfg, dict) else f"{doc_type}.md"
+        output_path = module_dir / filename
+
+        # Call LLM API
+        start_time = time.time()
+        try:
+            from engine.llm_client import call_llm
+            response = call_llm(
+                prompt=rendered_prompt,
+                model=model,
+                base_url=base_url,
+                api_key=api_key,
+            )
+        except ImportError:
+            # Fallback: use requests directly for OpenAI-compatible API
+            import requests
+            headers = {
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+            }
+            payload = {
+                "model": model,
+                "messages": [{"role": "user", "content": rendered_prompt}],
+                "max_tokens": 8192,
+            }
+            try:
+                resp = requests.post(
+                    f"{base_url.rstrip('/')}/chat/completions",
+                    headers=headers,
+                    json=payload,
+                    timeout=600,
+                )
+                resp.raise_for_status()
+                data = resp.json()
+                response = data["choices"][0]["message"]["content"]
+            except Exception as e:
+                elapsed = time.time() - start_time
+                return json.dumps({
+                    "status": "failed",
+                    "error": str(e),
+                    "elapsed_seconds": round(elapsed, 1),
+                }, ensure_ascii=False, indent=2)
+
+        elapsed = time.time() - start_time
+
+        # Write output
+        output_path.write_text(response, encoding="utf-8")
+
+        return json.dumps({
+            "status": "done",
+            "output_path": str(output_path),
+            "file_size_kb": round(output_path.stat().st_size / 1024, 1),
+            "elapsed_seconds": round(elapsed, 1),
+        }, ensure_ascii=False, indent=2)

mcp_server/tools/planning.py

@@ -0,0 +1,144 @@
+"""Planning tools — dispatch plan computation."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+
+
+def register(mcp: FastMCP) -> None:
+    """Register planning tools on the MCP server."""
+
+    @mcp.tool()
+    def dispatch_plan(kb_name: str, module_name: str) -> str:
+        """Compute a document generation dispatch plan. The agent should present this to the user for confirmation before execution.
+
+        Based on the skeleton and file lists, determines the generation strategy for each doc_type:
+        - Whether sharding is needed (based on file count and line count)
+        - Batch order (based on depends_on dependencies)
+        - Estimated time
+
+        Args:
+            kb_name: Knowledge base name
+            module_name: Module name
+        """
+        from mcp_server import find_config
+        from core.config import load_config
+        from core.preset import load_preset, get_batch_plan
+
+        config_path = find_config()
+        if not config_path:
+            return json.dumps({"status": "error", "message": "kb-project.yaml not found"})
+
+        config = load_config(config_path)
+        kb_cfg = config.get_kb(kb_name)
+        preset_name = kb_cfg.get("preset", "generic")
+        preset = load_preset(preset_name)
+
+        # Resolve module dir
+        base_dir = config.config_path.parent
+        kb_dir = Path(kb_cfg["knowledge_dir"])
+        if not kb_dir.is_absolute():
+            kb_dir = (base_dir / kb_dir).resolve()
+        module_dir = kb_dir / module_name
+
+        # Load skeleton stats
+        skeleton_path = module_dir / ".meta" / "skeleton" / "skeleton.json"
+        if not skeleton_path.exists():
+            return json.dumps({
+                "status": "error",
+                "message": f"Skeleton does not exist: {skeleton_path}. Please call skeleton_extract first.",
+            }, ensure_ascii=False, indent=2)
+
+        from core.skeleton.query import load_skeleton, stats
+        entries = load_skeleton(skeleton_path)
+        skel_stats = stats(entries)
+
+        # Read file lists to determine which doc types have files
+        file_list_dir = module_dir / ".meta" / "file-lists"
+        doc_types = preset.get("doc_types", {})
+
+        plan_entries: list[dict[str, Any]] = []
+        total_subagents = 0
+
+        for dt_key, dt_cfg in doc_types.items():
+            if not isinstance(dt_cfg, dict):
+                continue
+
+            filename = dt_cfg.get("filename", f"{dt_key}.md")
+            batch = dt_cfg.get("batch", 99)
+            conditional = dt_cfg.get("conditional", False)
+
+            # Check file list
+            fl_path = file_list_dir / f"{dt_key}.txt"
+            file_count = 0
+            total_lines = 0
+            if fl_path.exists():
+                content = fl_path.read_text(encoding="utf-8").strip()
+                files = [f for f in content.splitlines() if f.strip() and not f.startswith("#")]
+                file_count = len(files)
+                # Estimate lines from skeleton
+                for e in entries:
+                    if e["file"] in files:
+                        total_lines += e.get("total_lines", 0)
+
+            # Skip conditional doc types with no files
+            if conditional and file_count == 0:
+                continue
+
+            # Global view docs don't need file lists
+            if dt_cfg.get("global_view", False):
+                file_count = skel_stats.get("files", 0)
+                total_lines = skel_stats.get("total_lines", 0)
+
+            # Determine split strategy
+            split_count = 1
+            if total_lines > 12000:
+                split_count = min(4, (total_lines + 5999) // 6000)
+            elif total_lines > 6000:
+                split_count = 2
+
+            total_subagents += split_count
+
+            plan_entries.append({
+                "doc_type": dt_key,
+                "filename": filename,
+                "batch": batch,
+                "file_count": file_count,
+                "total_lines": total_lines,
+                "split_count": split_count,
+                "conditional": conditional,
+                "global_view": dt_cfg.get("global_view", False),
+            })
+
+        # Sort by batch
+        plan_entries.sort(key=lambda x: x["batch"])
+
+        # Group by batch
+        batches: dict[int, list[str]] = {}
+        for entry in plan_entries:
+            b = entry["batch"]
+            if b not in batches:
+                batches[b] = []
+            batches[b].append(entry["doc_type"])
+
+        # Estimate time (rough: 2 min per subagent)
+        estimated_minutes = total_subagents * 2
+
+        return json.dumps({
+            "status": "ok",
+            "module_stats": {
+                "source_files": skel_stats.get("files", 0),
+                "total_lines": skel_stats.get("total_lines", 0),
+                "methods": skel_stats.get("methods", 0),
+                "skeleton_size_kb": round(skeleton_path.stat().st_size / 1024, 1),
+            },
+            "entries": plan_entries,
+            "batch_order": [{"batch": k, "doc_types": v} for k, v in sorted(batches.items())],
+            "total_subagents": total_subagents,
+            "total_doc_types": len(plan_entries),
+            "estimated_minutes": estimated_minutes,
+        }, ensure_ascii=False, indent=2)

mcp_server/tools/source.py

@@ -0,0 +1,175 @@
+"""Source management tools — skeleton extraction and file classification."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+
+
+def register(mcp: FastMCP) -> None:
+    """Register source tools on the MCP server."""
+
+    @mcp.tool()
+    def skeleton_extract(
+        repo_path: str,
+        preset: str = "generic",
+        output: str = "",
+        summary: bool = True,
+        subpath: str = "",
+    ) -> str:
+        """Extract code skeleton (classes, methods, field signatures) from a source repository.
+
+        The skeleton is a structured summary of the source code containing class names, method signatures,
+        field lists, and complexity assessments for each file. Used for subsequent document generation
+        and coverage validation.
+
+        Args:
+            repo_path: Local repository path (e.g., .source-cache/backend)
+            preset: Language preset (generic | java-spring)
+            output: Output directory (module knowledge base directory; skeleton is written to .meta/skeleton/)
+            summary: Whether to also generate a summary file (recommended true)
+            subpath: Monorepo module subdirectory path (e.g., services/user-service)
+        """
+        from core.skeleton.extract import extract_skeleton
+        from core.preset import load_preset
+
+        preset_cfg = load_preset(preset)
+        repo = Path(repo_path)
+        output_dir = Path(output) if output else None
+
+        if not repo.exists():
+            return json.dumps({
+                "status": "error",
+                "message": f"Repository path does not exist: {repo_path}",
+            }, ensure_ascii=False, indent=2)
+
+        entries = extract_skeleton(
+            repo, preset_cfg,
+            ref="HEAD",
+            subpath=subpath or None,
+            output_dir=output_dir,
+            compact=True,
+        )
+
+        result: dict[str, Any] = {
+            "status": "ok",
+            "files_parsed": len(entries),
+            "methods": sum(len(e.get("methods", [])) for e in entries),
+            "classes": sum(len(e.get("classes", [])) for e in entries),
+        }
+
+        if output_dir:
+            skeleton_path = output_dir / ".meta" / "skeleton" / "skeleton.json"
+            summary_path = output_dir / ".meta" / "skeleton" / "skeleton-summary.json"
+            result["skeleton_path"] = str(skeleton_path)
+            if skeleton_path.exists():
+                result["skeleton_size_kb"] = round(skeleton_path.stat().st_size / 1024, 1)
+            if summary and summary_path.exists():
+                result["summary_path"] = str(summary_path)
+        else:
+            result["note"] = f"Total {len(entries)} entries. Specify the output parameter to save to disk."
+
+        return json.dumps(result, ensure_ascii=False, indent=2)
+
+    @mcp.tool()
+    def classify_files(kb_name: str, module_name: str) -> str:
+        """Extract file lists for all doc_types in a module and check coverage.
+
+        Performs in one pass: load skeleton -> match against preset classification rules ->
+        write to .meta/file-lists/ -> compute coverage statistics.
+
+        Args:
+            kb_name: Knowledge base name (key in kb-project.yaml)
+            module_name: Module name
+        """
+        from mcp_server import find_config
+        from core.config import load_config
+        from core.preset import load_preset
+        from core.skeleton.file_list import load_skeleton, extract_file_list
+
+        config_path = find_config()
+        if not config_path:
+            return json.dumps({"status": "error", "message": "kb-project.yaml not found"})
+
+        config = load_config(config_path)
+        kb_cfg = config.get_kb(kb_name)
+        preset_name = kb_cfg.get("preset", "generic")
+        preset = load_preset(preset_name)
+
+        # Resolve paths
+        base_dir = config.config_path.parent
+        kb_dir = Path(kb_cfg["knowledge_dir"])
+        if not kb_dir.is_absolute():
+            kb_dir = (base_dir / kb_dir).resolve()
+        module_dir = kb_dir / module_name
+
+        # Find skeleton
+        skeleton_path = module_dir / ".meta" / "skeleton" / "skeleton.json"
+        if not skeleton_path.exists():
+            return json.dumps({
+                "status": "error",
+                "message": f"Skeleton file does not exist: {skeleton_path}. Please call skeleton_extract first.",
+            }, ensure_ascii=False, indent=2)
+
+        entries = load_skeleton(module_dir)
+
+        # Resolve source_cache
+        source = kb_cfg.get("source", {})
+        cache_dir = Path(source.get("cache_dir", "./.source-cache"))
+        if not cache_dir.is_absolute():
+            cache_dir = (base_dir / cache_dir).resolve()
+
+        if source.get("structure") == "monorepo":
+            repo_name = source.get("repo_name", "repo")
+            # Find module path
+            module_path = module_name
+            for m in source.get("modules", []):
+                if m["name"] == module_name:
+                    module_path = m.get("path", module_name)
+                    break
+            source_cache = cache_dir / repo_name / module_path
+        else:
+            source_cache = cache_dir / module_name
+
+        # Extract file lists for all doc types
+        doc_types = preset.get("doc_types", {})
+        file_list_dir = module_dir / ".meta" / "file-lists"
+        file_list_dir.mkdir(parents=True, exist_ok=True)
+
+        per_doc_type: dict[str, int] = {}
+        all_classified_files: set[str] = set()
+
+        for dt_key, dt_cfg in doc_types.items():
+            if not isinstance(dt_cfg, dict):
+                continue
+            if dt_cfg.get("global_view", False):
+                continue
+
+            files = extract_file_list(entries, preset, dt_key, source_cache)
+            per_doc_type[dt_key] = len(files)
+            all_classified_files.update(files)
+
+            # Write file list
+            output_file = file_list_dir / f"{dt_key}.txt"
+            output_file.write_text("\n".join(files) + "\n" if files else "", encoding="utf-8")
+
+        # Compute coverage
+        all_source_files = {e["file"] for e in entries}
+        uncovered = sorted(all_source_files - all_classified_files)
+        coverage_pct = round(
+            (len(all_source_files) - len(uncovered)) / max(len(all_source_files), 1) * 100, 1
+        )
+
+        return json.dumps({
+            "status": "ok",
+            "per_doc_type": per_doc_type,
+            "total_source_files": len(all_source_files),
+            "classified_files": len(all_classified_files),
+            "uncovered_files": uncovered[:20],
+            "uncovered_count": len(uncovered),
+            "coverage_pct": coverage_pct,
+            "file_list_dir": str(file_list_dir),
+        }, ensure_ascii=False, indent=2)

mcp_server/tools/validation.py

@@ -0,0 +1,140 @@
+"""Validation tools — coverage check and progress monitoring."""
+
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+
+
+def register(mcp: FastMCP) -> None:
+    """Register validation tools on the MCP server."""
+
+    @mcp.tool()
+    def coverage_check(module_dir: str, module_type: str = "service") -> str:
+        """Check documentation coverage.
+
+        Compares methods/classes in the skeleton against generated document content to compute coverage.
+        Target: >= 80%.
+
+        Args:
+            module_dir: Module knowledge base directory (containing .md documents and .meta/ skeleton)
+            module_type: Module type (service | library | api-contract)
+        """
+        from core.validators.coverage import CoverageValidator
+
+        mod_dir = Path(module_dir)
+        if not mod_dir.is_dir():
+            return json.dumps({"status": "error", "message": f"Directory does not exist: {module_dir}"})
+
+        validator = CoverageValidator()
+        result = validator.validate(mod_dir, module_type=module_type)
+
+        return json.dumps({
+            "status": "ok" if result.passed else "fail",
+            "passed": result.passed,
+            "errors": result.errors[:10],
+            "warnings": result.warnings[:10],
+            "error_count": len(result.errors),
+            "warning_count": len(result.warnings),
+        }, ensure_ascii=False, indent=2)
+
+    @mcp.tool()
+    def check_progress(module_dir: str) -> str:
+        """Check module document generation progress.
+
+        Scans the .meta/progress/ directory and target document files to determine the status
+        of each doc_type. Used to monitor sub-agent execution progress and detect stalled tasks.
+
+        Args:
+            module_dir: Module knowledge base directory
+        """
+        mod_dir = Path(module_dir)
+        if not mod_dir.is_dir():
+            return json.dumps({"status": "error", "message": f"Directory does not exist: {module_dir}"})
+
+        progress_dir = mod_dir / ".meta" / "progress"
+        file_list_dir = mod_dir / ".meta" / "file-lists"
+
+        per_doc: list[dict[str, Any]] = []
+        summary = {"done": 0, "in_progress": 0, "failed": 0, "pending": 0}
+
+        # Determine expected doc types from file lists
+        expected_docs: set[str] = set()
+        if file_list_dir.is_dir():
+            for fl in file_list_dir.glob("*.txt"):
+                if fl.stat().st_size > 0:
+                    expected_docs.add(fl.stem)
+
+        # Also check for existing .md files (already generated)
+        for md in mod_dir.glob("*.md"):
+            doc_name = md.stem
+            if doc_name in expected_docs or not expected_docs:
+                status = "done"
+                file_size = md.stat().st_size
+                per_doc.append({
+                    "doc_type": doc_name,
+                    "status": status,
+                    "file_size": file_size,
+                    "file_size_kb": round(file_size / 1024, 1),
+                })
+                summary["done"] += 1
+                expected_docs.discard(doc_name)
+
+        # Check progress files for in-progress/failed
+        if progress_dir.is_dir():
+            for pf in progress_dir.iterdir():
+                if not pf.is_file():
+                    continue
+                doc_type = pf.stem
+                try:
+                    content = pf.read_text(encoding="utf-8").strip()
+                    lines = content.splitlines()
+                    last_line = lines[-1] if lines else ""
+
+                    if "DONE" in last_line:
+                        status = "done"
+                    elif "ERROR" in last_line or "FAILED" in last_line:
+                        status = "failed"
+                    else:
+                        status = "in_progress"
+                        # Check for stall (last modified > 5 min ago)
+                        age = time.time() - pf.stat().st_mtime
+                        if age > 300:
+                            status = "stalled"
+
+                    # Only add if not already counted as done via .md file
+                    if not any(d["doc_type"] == doc_type for d in per_doc):
+                        per_doc.append({
+                            "doc_type": doc_type,
+                            "status": status,
+                            "last_update": last_line[:80],
+                        })
+                        summary[status if status != "stalled" else "failed"] += 1
+                        expected_docs.discard(doc_type)
+                except Exception:
+                    pass
+
+        # Remaining expected docs are pending
+        for doc_type in sorted(expected_docs):
+            per_doc.append({"doc_type": doc_type, "status": "pending"})
+            summary["pending"] += 1
+
+        # Generate recommendations
+        recommendations = []
+        if summary["failed"] > 0:
+            recommendations.append("Some documents failed. Check errors and retry with generate_doc or get_subagent_prompt")
+        if summary["pending"] > 0:
+            recommendations.append(f"{summary['pending']} documents still pending generation")
+        if summary["done"] > 0 and summary["pending"] == 0 and summary["in_progress"] == 0:
+            recommendations.append("All documents complete. Call coverage_check to validate quality")
+
+        return json.dumps({
+            "status": "ok",
+            "per_doc": sorted(per_doc, key=lambda x: x["doc_type"]),
+            "summary": summary,
+            "recommendations": recommendations,
+        }, ensure_ascii=False, indent=2)