codegraphy-lite 1.0.0__py3-none-any.whl

codegraphy_lite/__init__.py

@@ -0,0 +1,7 @@
+"""CodeGraphy Lite — Standalone Open-Source Visual Architecture Graph & MCP Server.
+
+Lightweight, local-first interactive architecture visualization and Model Context Protocol (MCP) server.
+"""
+
+__version__ = "1.0.0"
+__all__ = ["__version__"]

codegraphy_lite/cli.py

@@ -0,0 +1,113 @@
+"""CLI entrypoint for CodeGraphy Lite.
+
+Usage:
+    codegraphy-lite [path] [--port 8000] [--host 127.0.0.1] [--no-browser] [--scan]
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import threading
+import time
+import webbrowser
+from pathlib import Path
+
+import uvicorn
+
+from codegraphy_lite import __version__
+from codegraphy_lite.scanner import build_graph_and_workspace, scan_project
+from codegraphy_lite.server import app
+from codegraphy_lite.storage import get_storage_dir, load_graph, save_graph, save_workspace, set_active_root
+
+
+def open_browser_later(url: str, delay_sec: float = 1.0):
+    def _open():
+        time.sleep(delay_sec)
+        try:
+            webbrowser.open(url)
+        except Exception:
+            pass
+
+    t = threading.Thread(target=_open, daemon=True)
+    t.start()
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="codegraphy-lite",
+        description="CodeGraphy Lite — Standalone Open-Source Visual Architecture Graph & MCP Server",
+    )
+    parser.add_argument(
+        "path",
+        nargs="?",
+        default=".",
+        help="Target project directory to visualize (default: current directory)",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=8000,
+        help="HTTP server port (default: 8000)",
+    )
+    parser.add_argument(
+        "--host",
+        default="127.0.0.1",
+        help="HTTP server bind host (default: 127.0.0.1)",
+    )
+    parser.add_argument(
+        "--no-browser",
+        action="store_true",
+        help="Do not automatically launch the browser",
+    )
+    parser.add_argument(
+        "--scan",
+        action="store_true",
+        help="Force automatic project directory scan on startup (up to 35 files)",
+    )
+    parser.add_argument(
+        "-v", "--version",
+        action="version",
+        version=f"codegraphy-lite {__version__}",
+    )
+
+    args = parser.parse_args()
+
+    project_root = Path(args.path).resolve()
+    if not project_root.exists() or not project_root.is_dir():
+        print(f"Error: Directory '{project_root}' does not exist.", file=sys.stderr)
+        sys.exit(1)
+
+    set_active_root(project_root)
+
+    # Check if graph exists; if not or if --scan requested, run Lite scanner
+    storage_dir = get_storage_dir(project_root)
+    existing_graph = load_graph(project_root)
+
+    if args.scan or not existing_graph.nodes:
+        print(f"[*] Scanning project architecture in '{project_root}' (Lite limit: max 35 files)...")
+        try:
+            preview = scan_project(project_root)
+            graph, ws = build_graph_and_workspace(preview)
+            save_graph(graph, project_root)
+            save_workspace(ws, project_root)
+            print(f"[+] Discovered {preview.total_files} files, {len(graph.nodes)} topics, {len(graph.edges)} dependency edges.")
+        except Exception as e:
+            print(f"[!] Warning: Initial project scan skipped ({e})", file=sys.stderr)
+
+    url = f"http://{args.host}:{args.port}"
+    print(f"\n=======================================================")
+    print(f"  CodeGraphy Lite v{__version__} (Open Source Edition)")
+    print(f"  Visual Architecture Canvas & MCP Server")
+    print(f"  Project Root: {project_root}")
+    print(f"  Web UI:       {url}")
+    print(f"=======================================================\n")
+
+    if not args.no_browser:
+        open_browser_later(url, delay_sec=0.8)
+
+    uvicorn.run(app, host=args.host, port=args.port, log_level="info")
+
+
+if __name__ == "__main__":
+    main()

codegraphy_lite/mcp.py

@@ -0,0 +1,338 @@
+"""Model Context Protocol (MCP) STDIO Server for CodeGraphy Lite.
+
+Exposes 3 basic workspace/graph architectural tools to Claude Code, Cursor, Windsurf,
+and agentic coding assistants via standard JSON-RPC 2.0 over STDIO.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from codegraphy_lite import __version__
+from codegraphy_lite.models import GraphState, WorkspaceModel
+from codegraphy_lite.scanner import extract_ast_signatures
+from codegraphy_lite.storage import get_active_root, load_graph, load_workspace, set_active_root
+
+PROTOCOL_VERSION = "2024-11-05"
+SERVER_NAME = "codegraphy-lite-mcp"
+MAX_PAYLOAD_CHARS = 32000
+
+SECRET_PATTERNS = [
+    re.compile(r"\b(?:sk|whsec)_[a-zA-Z0-9_\-]{16,}\b"),
+    re.compile(r"\bsk-(?:live|test|ant|proj)?[a-zA-Z0-9_\-]{16,}\b"),
+    re.compile(r"\bAIza[0-9A-Za-z\-_]{35}\b"),
+    re.compile(r"\bghp_[0-9a-zA-Z]{36}\b"),
+    re.compile(r"\bAKIA[0-9A-Z]{16}\b"),
+]
+
+
+def scrub_secrets(val: Any) -> Any:
+    """Redacts potential API tokens and keys."""
+    if isinstance(val, str):
+        text = val
+        for pat in SECRET_PATTERNS:
+            text = pat.sub("[REDACTED_SECRET]", text)
+        return text
+    if isinstance(val, dict):
+        return {k: scrub_secrets(v) for k, v in val.items()}
+    if isinstance(val, list):
+        return [scrub_secrets(item) for item in val]
+    return val
+
+
+TOOLS_MANIFEST = [
+    {
+        "name": "list_workspace_topics",
+        "description": "Lists all architectural topics/nodes in the workspace with their status, lanes, attached files, and descriptions.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "status": {
+                    "type": "string",
+                    "enum": ["all", "todo", "in_progress", "done"],
+                    "description": "Filter topics by status (default: all)",
+                }
+            },
+        },
+    },
+    {
+        "name": "get_topic_context",
+        "description": "Retrieves comprehensive architectural context for a topic, including 1-hop connected dependencies and AST-extracted signatures from attached files.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "topic": {
+                    "type": "string",
+                    "description": "Topic ID or label to inspect",
+                },
+                "include_ast": {
+                    "type": "boolean",
+                    "description": "Whether to include AST-extracted class/function signatures (default: true)",
+                    "default": True,
+                },
+            },
+            "required": ["topic"],
+        },
+    },
+    {
+        "name": "get_architecture_summary",
+        "description": "Returns a high-level architectural overview: total topics, dependency edges, lanes, status distribution, and key architectural modules.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {},
+        },
+    },
+]
+
+
+class CodeGraphyLiteMCP:
+    def __init__(self, root_dir: Optional[str | Path] = None) -> None:
+        if root_dir:
+            set_active_root(root_dir)
+        elif "CODEGRAPHY_ROOT" in os.environ:
+            set_active_root(os.environ["CODEGRAPHY_ROOT"])
+
+    @property
+    def root(self) -> Path:
+        return get_active_root()
+
+    def handle_list_workspace_topics(self, args: Dict[str, Any]) -> Dict[str, Any]:
+        graph = load_graph(self.root)
+        status_filter = args.get("status", "all")
+
+        topics = []
+        for n in graph.nodes:
+            d = n.data
+            if status_filter != "all" and d.status != status_filter:
+                continue
+
+            incoming = sum(1 for e in graph.edges if e.target == n.id)
+            outgoing = sum(1 for e in graph.edges if e.source == n.id)
+            files = [f.filepath for f in d.attached_files]
+
+            topics.append({
+                "id": n.id,
+                "label": d.label,
+                "status": d.status,
+                "lane_id": d.lane_id,
+                "description": d.description,
+                "files_count": len(files),
+                "files": files,
+                "incoming_dependencies": incoming,
+                "outgoing_dependencies": outgoing,
+            })
+
+        return {
+            "root_path": str(self.root),
+            "total_topics": len(topics),
+            "topics": topics,
+        }
+
+    def handle_get_topic_context(self, args: Dict[str, Any]) -> Dict[str, Any]:
+        query = args.get("topic", "").strip().lower()
+        if not query:
+            raise ValueError("Parameter 'topic' is required.")
+        include_ast = args.get("include_ast", True)
+
+        graph = load_graph(self.root)
+        target = None
+        for n in graph.nodes:
+            if n.id.lower() == query or n.data.label.lower() == query:
+                target = n
+                break
+
+        if not target:
+            raise ValueError(f"Topic '{query}' not found in workspace.")
+
+        # Dependencies
+        incoming_ids = [e.source for e in graph.edges if e.target == target.id]
+        outgoing_ids = [e.target for e in graph.edges if e.source == target.id]
+
+        def resolve_label(nid: str) -> str:
+            m = next((x.data.label for x in graph.nodes if x.id == nid), nid)
+            return m
+
+        # Files & AST signatures
+        files_data = []
+        for f in target.data.attached_files:
+            file_info: Dict[str, Any] = {"filepath": f.filepath}
+            full_p = self.root / f.filepath
+            if full_p.exists() and full_p.is_file():
+                file_info["exists"] = True
+                if include_ast:
+                    try:
+                        content = full_p.read_text(encoding="utf-8", errors="ignore")
+                        file_info["signatures"] = extract_ast_signatures(content)
+                    except Exception as e:
+                        file_info["signatures"] = f"# Error extracting AST: {e}"
+            else:
+                file_info["exists"] = False
+                file_info["signatures"] = "# File not found on disk"
+            files_data.append(file_info)
+
+        return {
+            "topic_id": target.id,
+            "label": target.data.label,
+            "status": target.data.status,
+            "description": target.data.description,
+            "connected_dependencies": {
+                "incoming": [resolve_label(x) for x in incoming_ids],
+                "outgoing": [resolve_label(x) for x in outgoing_ids],
+            },
+            "attached_files": files_data,
+        }
+
+    def handle_get_architecture_summary(self, args: Dict[str, Any]) -> Dict[str, Any]:
+        graph = load_graph(self.root)
+        ws = load_workspace(self.root)
+
+        status_counts = {"todo": 0, "in_progress": 0, "done": 0}
+        for n in graph.nodes:
+            st = n.data.status
+            if st in status_counts:
+                status_counts[st] += 1
+
+        degree_map: Dict[str, int] = {}
+        for e in graph.edges:
+            degree_map[e.source] = degree_map.get(e.source, 0) + 1
+            degree_map[e.target] = degree_map.get(e.target, 0) + 1
+
+        top_components = sorted(
+            [{"topic_id": k, "degree": v} for k, v in degree_map.items()],
+            key=lambda x: x["degree"],
+            reverse=True,
+        )[:6]
+
+        return {
+            "project_name": ws.name or self.root.name,
+            "root_path": str(self.root),
+            "edition": "CodeGraphy Lite (Open Source)",
+            "total_topics": len(graph.nodes),
+            "total_dependencies": len(graph.edges),
+            "status_distribution": status_counts,
+            "lanes": [l.title for l in ws.lanes],
+            "top_connected_topics": top_components,
+            "pro_features_available": [
+                "AST Smart Context (-85% tokens)",
+                "Blast Radius (Reverse Impact)",
+                "Test Impact Static Analysis",
+                "Git Architecture Diff Overlay",
+                "Full 11 MCP Tools Suite",
+            ],
+        }
+
+    def call_tool(self, name: str, args: Dict[str, Any]) -> Dict[str, Any]:
+        if name == "list_workspace_topics":
+            return self.handle_list_workspace_topics(args)
+        elif name == "get_topic_context":
+            return self.handle_get_topic_context(args)
+        elif name == "get_architecture_summary":
+            return self.handle_get_architecture_summary(args)
+        else:
+            raise ValueError(
+                f"Unknown or proprietary tool '{name}'. "
+                "CodeGraphy Lite includes 3 core workspace tools. "
+                "Upgrade to CodeGraphy Pro for the full 11-tool suite."
+            )
+
+    def dispatch(self, request: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+        req_id = request.get("id")
+        method = request.get("method")
+        params = request.get("params", {})
+
+        if method == "initialize":
+            return {
+                "jsonrpc": "2.0",
+                "id": req_id,
+                "result": {
+                    "protocolVersion": PROTOCOL_VERSION,
+                    "serverInfo": {
+                        "name": SERVER_NAME,
+                        "version": __version__,
+                    },
+                    "capabilities": {
+                        "tools": {"listChanged": False},
+                    },
+                },
+            }
+        elif method == "tools/list":
+            return {
+                "jsonrpc": "2.0",
+                "id": req_id,
+                "result": {"tools": TOOLS_MANIFEST},
+            }
+        elif method == "tools/call":
+            tool_name = params.get("name")
+            args = params.get("arguments", {})
+            try:
+                raw_res = self.call_tool(tool_name, args)
+                scrubbed = scrub_secrets(raw_res)
+                text_out = json.dumps(scrubbed, indent=2, ensure_ascii=False)
+                if len(text_out) > MAX_PAYLOAD_CHARS:
+                    text_out = text_out[:MAX_PAYLOAD_CHARS] + "\n... [Payload truncated for Lite MCP]"
+                return {
+                    "jsonrpc": "2.0",
+                    "id": req_id,
+                    "result": {
+                        "content": [{"type": "text", "text": text_out}],
+                        "isError": False,
+                    },
+                }
+            except Exception as e:
+                return {
+                    "jsonrpc": "2.0",
+                    "id": req_id,
+                    "result": {
+                        "content": [{"type": "text", "text": f"Error: {str(e)}"}],
+                        "isError": True,
+                    },
+                }
+        elif method == "ping":
+            return {"jsonrpc": "2.0", "id": req_id, "result": {}}
+        elif method in ("notifications/initialized", "$/cancelRequest"):
+            return None
+        return {
+            "jsonrpc": "2.0",
+            "id": req_id,
+            "error": {"code": -32601, "message": f"Method not found: {method}"},
+        }
+
+
+def run_stdio_server():
+    server = CodeGraphyLiteMCP()
+    while True:
+        try:
+            line = sys.stdin.readline()
+            if not line:
+                break
+            line = line.strip()
+            if not line:
+                continue
+            req = json.loads(line)
+            res = server.dispatch(req)
+            if res is not None:
+                sys.stdout.write(json.dumps(res, ensure_ascii=False) + "\n")
+                sys.stdout.flush()
+        except (KeyboardInterrupt, SystemExit):
+            break
+        except Exception as e:
+            err_res = {
+                "jsonrpc": "2.0",
+                "id": None,
+                "error": {"code": -32603, "message": f"MCP STDIO Server Error: {str(e)}"},
+            }
+            sys.stdout.write(json.dumps(err_res) + "\n")
+            sys.stdout.flush()
+
+
+def main():
+    run_stdio_server()
+
+
+if __name__ == "__main__":
+    main()

codegraphy_lite/models.py

@@ -0,0 +1,204 @@
+"""Data models for CodeGraphy Lite.
+
+Clean, standalone Pydantic models for React Flow graph, workspace domain,
+topics, lanes, tasks, and preview scanner payloads.
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Literal, Optional, Tuple
+from pydantic import BaseModel, Field, model_validator
+
+
+def utc_now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def new_id(prefix: str = "") -> str:
+    uid = str(uuid.uuid4())
+    return f"{prefix}_{uid[:8]}" if prefix else uid
+
+
+NodeStatus = Literal["todo", "in_progress", "done"]
+
+
+class FileReference(BaseModel):
+    filepath: str
+
+
+class NodeData(BaseModel):
+    id: str
+    label: str
+    description: str = ""
+    status: NodeStatus = "todo"
+    lane_id: Optional[str] = None
+    task_id: Optional[str] = None
+    parent_topic_id: Optional[str] = None
+    subtopic_count: int = 0
+    done_subtopic_count: int = 0
+    progress_percent: int = 0
+    attached_files: List[FileReference] = Field(default_factory=list)
+
+
+class Position(BaseModel):
+    x: float = 0.0
+    y: float = 0.0
+
+
+class ReactFlowNode(BaseModel):
+    id: str
+    type: str = "contextNode"
+    position: Position = Field(default_factory=Position)
+    data: NodeData
+
+
+class EdgeData(BaseModel):
+    id: str
+    source: str
+    target: str
+    sourceHandle: Optional[str] = None
+    targetHandle: Optional[str] = None
+
+
+class GraphState(BaseModel):
+    nodes: List[ReactFlowNode] = Field(default_factory=list)
+    edges: List[EdgeData] = Field(default_factory=list)
+
+
+class FileSource(BaseModel):
+    id: str = Field(default_factory=lambda: new_id("src"))
+    path: str
+    type: Literal["file", "directory"] = "file"
+    recursive: bool = True
+    include: List[str] = Field(default_factory=lambda: [".py", ".ts", ".tsx", ".js", ".md", ".json"])
+    exclude: List[str] = Field(
+        default_factory=lambda: [
+            ".git", "node_modules", "dist", "build", ".venv", "venv",
+            "__pycache__", "release", ".codegraphy", ".archflow"
+        ]
+    )
+
+
+class TopicLane(BaseModel):
+    id: str = Field(default_factory=lambda: new_id("lane"))
+    title: str = ""
+    name: Optional[str] = None
+    order: int = 0
+    collapsed: bool = False
+    color: str = "#38bdf8"
+
+    @model_validator(mode="before")
+    @classmethod
+    def sync_name_and_title(cls, data: Any) -> Any:
+        if isinstance(data, dict):
+            t = data.get("title") or data.get("name") or "Lane"
+            data["title"] = t
+            data["name"] = t
+        return data
+
+    def model_dump(self, *args, **kwargs) -> Dict[str, Any]:
+        d = super().model_dump(*args, **kwargs)
+        val = d.get("name") or d.get("title") or ""
+        d["name"] = val
+        d["title"] = val
+        return d
+
+
+class TaskItem(BaseModel):
+    id: str = Field(default_factory=lambda: new_id("task"))
+    title: str
+    description: str = ""
+    status: NodeStatus = "todo"
+    lane_id: Optional[str] = None
+    assigned_user_id: Optional[str] = None
+    progress: int = 0
+    topic_ids: List[str] = Field(default_factory=list)
+    updated_at: str = Field(default_factory=utc_now_iso)
+
+
+class Topic(BaseModel):
+    id: str
+    label: str
+    description: str = ""
+    status: NodeStatus = "todo"
+    lane_id: Optional[str] = None
+    task_id: Optional[str] = None
+    parent_topic_id: Optional[str] = None
+    position: Position = Field(default_factory=Position)
+    attached_files: List[FileReference] = Field(default_factory=list)
+    sources: List[FileSource] = Field(default_factory=list)
+    ai_context_settings: Dict[str, Any] = Field(
+        default_factory=lambda: {"include_neighbors": True, "strip_bodies": True}
+    )
+    updated_at: str = Field(default_factory=utc_now_iso)
+
+
+class WorkspaceModel(BaseModel):
+    version: str = "2.0"
+    id: str = "default_workspace"
+    name: str = "CodeGraphy Workspace"
+    root_path: Optional[str] = None
+    lanes: List[TopicLane] = Field(
+        default_factory=lambda: [
+            TopicLane(id="lane_plan", title="Planning", order=0, color="#a855f7"),
+            TopicLane(id="lane_dev", title="Development", order=1, color="#38bdf8"),
+            TopicLane(id="lane_test", title="Testing", order=2, color="#eab308"),
+            TopicLane(id="lane_done", title="Done", order=3, color="#22c55e"),
+        ]
+    )
+    topics: List[Topic] = Field(default_factory=list)
+    edges: List[EdgeData] = Field(default_factory=list)
+    tasks: List[TaskItem] = Field(default_factory=list)
+    file_sources: List[FileSource] = Field(default_factory=list)
+    updated_at: str = Field(default_factory=utc_now_iso)
+
+    def get_topic_progress(self, topic_id: str) -> Tuple[int, int, int]:
+        children = [t for t in self.topics if t.parent_topic_id == topic_id]
+        if not children:
+            t = next((x for x in self.topics if x.id == topic_id), None)
+            pct = 100 if t and t.status == "done" else (50 if t and t.status == "in_progress" else 0)
+            return 0, (1 if pct == 100 else 0), pct
+        total = len(children)
+        done = sum(1 for c in children if c.status == "done")
+        pct = int((done / total) * 100) if total else 0
+        return total, done, pct
+
+
+class ScannedEdgePreview(BaseModel):
+    source_topic_id: str
+    target_topic_id: str
+    source_file: str
+    target_module: str
+    line_number: int = 1
+
+
+class ScannedTopicPreview(BaseModel):
+    id: str
+    label: str
+    category: str = "module"
+    files: List[str] = Field(default_factory=list)
+    incoming_count: int = 0
+    outgoing_count: int = 0
+
+
+class ScanPreviewRequest(BaseModel):
+    root_path: str
+    ignore_dirs: List[str] = Field(
+        default_factory=lambda: [
+            ".git", ".venv", "venv", "node_modules", "__pycache__",
+            "dist", "build", "release", ".codegraphy", ".archflow",
+            ".idea", ".vscode", "coverage"
+        ]
+    )
+
+
+class ScanPreviewResponse(BaseModel):
+    root_path: str
+    project_name: str
+    total_files: int
+    topics: List[ScannedTopicPreview] = Field(default_factory=list)
+    edges: List[ScannedEdgePreview] = Field(default_factory=list)
+    unresolved_imports: List[str] = Field(default_factory=list)
+    ignored_dirs_triggered: List[str] = Field(default_factory=list)