ctxgraph 0.1.0__py3-none-any.whl

ctxgraph/mcp/server.py

@@ -0,0 +1,216 @@
+"""
+Phase 2: MCP (Model Context Protocol) Server
+
+This server implements the MCP protocol to allow Claude Desktop
+and other MCP-compatible clients to query the knowledge graph
+directly through tools instead of static context capsules.
+
+Protocol: https://modelcontextprotocol.io
+
+Usage:
+    ctx serve                  # Start MCP server (stdio mode)
+    ctx serve --port 8080      # Start MCP server (SSE mode)
+
+Claude Desktop config:
+{
+    "mcpServers": {
+        "ctxgraph": {
+            "command": "ctx",
+            "args": ["serve"]
+        }
+    }
+}
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Any, Optional
+
+try:
+    import mcp.types as types
+    from mcp.server import NotificationOptions, Server
+    from mcp.server.models import InitializationOptions
+
+    HAS_MCP = True
+except ImportError:
+    HAS_MCP = False
+
+from ctxgraph.capsule.renderer import render_capsule, render_project_overview
+from ctxgraph.clients.models import ModelMode, get_mode_config
+from ctxgraph.graph.builder import get_storage
+from ctxgraph.graph.query import search_relevant_nodes
+
+
+def create_server(repo_path: Optional[str] = None) -> Optional[Any]:
+    if not HAS_MCP:
+        return None
+
+    path = Path(repo_path).resolve() if repo_path else Path.cwd()
+    storage = get_storage(path)
+
+    server = Server("ctxgraph")
+
+    @server.list_tools()
+    async def list_tools() -> list[types.Tool]:
+        return [
+            types.Tool(
+                name="search_graph",
+                description="Search the codebase knowledge graph for relevant files, classes, and functions",
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "query": {
+                            "type": "string",
+                            "description": "Search query describing what you're looking for",
+                        },
+                        "max_results": {
+                            "type": "integer",
+                            "description": "Maximum number of results",
+                            "default": 15,
+                        },
+                    },
+                    "required": ["query"],
+                },
+            ),
+            types.Tool(
+                name="get_context_capsule",
+                description="Generate a token-efficient context capsule for a specific task",
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "query": {
+                            "type": "string",
+                            "description": "The task description for context generation",
+                        },
+                        "mode": {
+                            "type": "string",
+                            "enum": ["fast", "balanced", "deep"],
+                            "description": "Detail level: fast (minimal), balanced, deep (comprehensive)",
+                            "default": "balanced",
+                        },
+                    },
+                    "required": ["query"],
+                },
+            ),
+            types.Tool(
+                name="get_file_dependencies",
+                description="Get the dependency graph for a specific file",
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "file_path": {
+                            "type": "string",
+                            "description": "Path to the file (relative to repo root)",
+                        },
+                    },
+                    "required": ["file_path"],
+                },
+            ),
+            types.Tool(
+                name="get_project_overview",
+                description="Get a high-level overview of the entire codebase structure",
+                inputSchema={
+                    "type": "object",
+                    "properties": {},
+                },
+            ),
+        ]
+
+    @server.call_tool()
+    async def call_tool(
+        name: str, arguments: dict
+    ) -> list[types.TextContent]:
+        nonlocal storage
+        if storage is None:
+            storage = get_storage(path)
+
+        if storage is None:
+            return [types.TextContent(
+                type="text",
+                text="No graph found. Run `ctx build` first.",
+            )]
+
+        if name == "search_graph":
+            query = arguments.get("query", "")
+            max_results = arguments.get("max_results", 15)
+            results = search_relevant_nodes(storage, query, max_nodes=max_results)
+            lines = [f"Search results for: {query}", ""]
+            for node, score in results:
+                lines.append(f"  [{node.type}] {node.name} ({node.path}) - score: {score}")
+                if node.summary:
+                    lines.append(f"    {node.summary}")
+            return [types.TextContent(type="text", text="\n".join(lines))]
+
+        elif name == "get_context_capsule":
+            query = arguments.get("query", "")
+            mode_str = arguments.get("mode", "balanced")
+            mode = ModelMode.from_str(mode_str)
+            cfg = get_mode_config(mode)
+            capsule = render_capsule(storage, query, max_nodes=cfg["max_nodes"])
+            return [types.TextContent(type="text", text=capsule)]
+
+        elif name == "get_file_dependencies":
+            file_path = arguments.get("file_path", "")
+            node_id = f"file:{file_path}"
+            node = storage.get_node(node_id)
+            if not node:
+                return [types.TextContent(
+                    type="text",
+                    text=f"File not found in graph: {file_path}",
+                )]
+            edges = storage.get_edges_for_nodes({node_id})
+            lines = [f"Dependencies for: {file_path}", ""]
+            for e in edges:
+                target = storage.get_node(e.target_id)
+                source = storage.get_node(e.source_id)
+                if target and source:
+                    lines.append(f"  {source.name} --{e.relation}--> {target.name}")
+            return [types.TextContent(type="text", text="\n".join(lines))]
+
+        elif name == "get_project_overview":
+            overview = render_project_overview(storage)
+            return [types.TextContent(type="text", text=overview)]
+
+        else:
+            return [types.TextContent(type="text", text=f"Unknown tool: {name}")]
+
+    return server
+
+
+def run_server(repo_path: Optional[str] = None, port: Optional[int] = None):
+    if not HAS_MCP:
+        print(
+            "MCP support requires additional dependencies.\n"
+            "Install with: pip install ctxgraph[mcp]",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    server = create_server(repo_path)
+    if server is None:
+        print("Failed to create MCP server", file=sys.stderr)
+        sys.exit(1)
+
+    from mcp.server.stdio import stdio_server
+
+    import anyio
+
+    async def _run():
+        async with stdio_server() as (read_stream, write_stream):
+            await server.run(
+                read_stream,
+                write_stream,
+                InitializationOptions(
+                    server_name="ctxgraph",
+                    server_version="0.1.0",
+                    capabilities=server.get_capabilities(
+                        notification_options=NotificationOptions(),
+                        experimental_capabilities={},
+                    ),
+                ),
+            )
+
+    anyio.run(_run)

ctxgraph/view/visualizer.py

@@ -0,0 +1,282 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from ctxgraph.graph.storage import Storage
+
+
+def render_view(storage: Storage) -> str:
+    nodes = storage.get_all_nodes()
+    edges = storage.get_all_edges()
+
+    file_nodes = [n for n in nodes if n.type == "file"]
+    symbol_nodes = [n for n in nodes if n.type != "file"]
+
+    graph_data = {
+        "nodes": [],
+        "links": [],
+    }
+
+    file_node_ids = {n.id for n in file_nodes}
+
+    for node in file_nodes:
+        graph_data["nodes"].append(
+            {
+                "id": node.id,
+                "label": _short_path(node.path or node.name),
+                "type": "file",
+                "summary": (node.summary or "")[:100],
+                "importance": node.importance,
+            }
+        )
+
+    for node in symbol_nodes:
+        graph_data["nodes"].append(
+            {
+                "id": node.id,
+                "label": node.name,
+                "type": node.type,
+                "summary": (node.summary or "")[:100],
+                "importance": node.importance,
+            }
+        )
+
+    seen_links = set()
+    for edge in edges:
+        if edge.source_id in file_node_ids or edge.target_id in file_node_ids:
+            key = (edge.source_id, edge.target_id)
+            if key not in seen_links:
+                seen_links.add(key)
+                graph_data["links"].append(
+                    {
+                        "source": edge.source_id,
+                        "target": edge.target_id,
+                        "relation": edge.relation,
+                    }
+                )
+
+    json_data = json.dumps(graph_data, indent=2)
+
+    template = _get_html_template()
+    return template.replace("/* GRAPH_DATA */", json_data)
+
+
+def _short_path(path: str) -> str:
+    parts = path.split("/")
+    if len(parts) > 3:
+        return "/".join(parts[:2] + ["..."] + parts[-1:])
+    return path
+
+
+def _get_html_template() -> str:
+    return """<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>ctxgraph - Knowledge Graph</title>
+<script src="https://d3js.org/d3.v7.min.js"></script>
+<style>
+* { margin: 0; padding: 0; box-sizing: border-box; }
+body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: #0d1117; color: #c9d1d9; overflow: hidden; }
+#container { width: 100vw; height: 100vh; position: relative; }
+svg { width: 100%; height: 100%; }
+#toolbar { position: absolute; top: 16px; left: 16px; z-index: 10; display: flex; gap: 8px; align-items: center; background: #161b22; padding: 12px 16px; border-radius: 8px; border: 1px solid #30363d; }
+#toolbar input { background: #0d1117; border: 1px solid #30363d; color: #c9d1d9; padding: 6px 12px; border-radius: 4px; width: 220px; font-size: 13px; }
+#toolbar select { background: #0d1117; border: 1px solid #30363d; color: #c9d1d9; padding: 6px 8px; border-radius: 4px; font-size: 13px; }
+#toolbar label { font-size: 13px; color: #8b949e; }
+#legend { position: absolute; bottom: 16px; left: 16px; z-index: 10; background: #161b22; padding: 12px; border-radius: 8px; border: 1px solid #30363d; font-size: 12px; display: flex; gap: 16px; }
+.legend-item { display: flex; align-items: center; gap: 6px; }
+.legend-dot { width: 10px; height: 10px; border-radius: 50%; }
+#tooltip { position: absolute; z-index: 20; background: #161b22; border: 1px solid #30363d; border-radius: 8px; padding: 12px; font-size: 13px; max-width: 400px; pointer-events: none; display: none; box-shadow: 0 4px 12px rgba(0,0,0,0.4); }
+#tooltip .tt-name { font-weight: 600; color: #58a6ff; margin-bottom: 4px; }
+#tooltip .tt-type { color: #8b949e; font-size: 11px; margin-bottom: 4px; }
+#tooltip .tt-summary { color: #c9d1d9; font-size: 12px; }
+#stats { position: absolute; bottom: 16px; right: 16px; z-index: 10; background: #161b22; padding: 8px 12px; border-radius: 8px; border: 1px solid #30363d; font-size: 11px; color: #8b949e; }
+.link { stroke-opacity: 0.4; }
+.link.imports { stroke: #58a6ff; }
+.link.calls { stroke: #3fb950; }
+.link.defines { stroke: #d29922; }
+.link.extends { stroke: #bc8cff; }
+.node { cursor: pointer; transition: opacity 0.2s; }
+.node:hover { opacity: 0.8; }
+.node-label { font-size: 11px; fill: #8b949e; pointer-events: none; text-shadow: 0 1px 2px #0d1117, 0 -1px 2px #0d1117, 1px 0 2px #0d1117, -1px 0 2px #0d1117; }
+.node.highlighted .node-label { fill: #c9d1d9; font-weight: 600; }
+.link.highlighted { stroke-opacity: 0.8; }
+</style>
+</head>
+<body>
+<div id="container">
+  <div id="toolbar">
+    <label>Search:</label>
+    <input type="text" id="search" placeholder="Search nodes..." oninput="filterGraph(this.value)">
+    <label>Filter:</label>
+    <select id="filterType" onchange="filterByType(this.value)">
+      <option value="all">All</option>
+      <option value="file">Files</option>
+      <option value="class">Classes</option>
+      <option value="function">Functions</option>
+    </select>
+  </div>
+  <div id="legend">
+    <div class="legend-item"><div class="legend-dot" style="background:#58a6ff"></div> File</div>
+    <div class="legend-item"><div class="legend-dot" style="background:#d29922"></div> Class</div>
+    <div class="legend-item"><div class="legend-dot" style="background:#3fb950"></div> Function</div>
+    <div class="legend-item"><svg width="20" height="2"><line x1="0" y1="1" x2="20" y2="1" stroke="#58a6ff" stroke-width="1.5" stroke-dasharray="4,2"/></svg> Import</div>
+    <div class="legend-item"><svg width="20" height="2"><line x1="0" y1="1" x2="20" y2="1" stroke="#3fb950" stroke-width="1.5" stroke-dasharray="2,2"/></svg> Call</div>
+  </div>
+  <div id="stats"></div>
+  <div id="tooltip">
+    <div class="tt-name"></div>
+    <div class="tt-type"></div>
+    <div class="tt-summary"></div>
+  </div>
+  <svg></svg>
+</div>
+<script>
+const graphData = /* GRAPH_DATA */;
+const width = window.innerWidth;
+const height = window.innerHeight;
+
+const svg = d3.select("svg");
+const g = svg.append("g");
+
+const zoom = d3.zoom()
+  .scaleExtent([0.1, 4])
+  .on("zoom", (event) => g.attr("transform", event.transform));
+
+svg.call(zoom);
+
+const colorMap = { file: "#58a6ff", class: "#d29922", function: "#3fb950", module: "#bc8cff" };
+
+const simulation = d3.forceSimulation(graphData.nodes)
+  .force("link", d3.forceLink(graphData.links).id(d => d.id).distance(d => {
+    return d.relation === "imports" ? 100 : 80;
+  }))
+  .force("charge", d3.forceManyBody().strength(-200))
+  .force("center", d3.forceCenter(width / 2, height / 2))
+  .force("collision", d3.forceCollide(20));
+
+const link = g.append("g")
+  .selectAll("line")
+  .data(graphData.links)
+  .join("line")
+  .attr("class", d => `link ${d.relation}`)
+  .attr("stroke-width", 1.5);
+
+const node = g.append("g")
+  .selectAll("g")
+  .data(graphData.nodes)
+  .join("g")
+  .attr("class", "node")
+  .call(d3.drag()
+    .on("start", (event, d) => {
+      if (!event.active) simulation.alphaTarget(0.3).restart();
+      d.fx = d.x;
+      d.fy = d.y;
+    })
+    .on("drag", (event, d) => {
+      d.fx = event.x;
+      d.fy = event.y;
+    })
+    .on("end", (event, d) => {
+      if (!event.active) simulation.alphaTarget(0);
+      d.fx = null;
+      d.fy = null;
+    })
+  );
+
+node.append("circle")
+  .attr("r", d => 5 + (d.importance || 0.5) * 8)
+  .attr("fill", d => colorMap[d.type] || "#8b949e")
+  .attr("stroke", "#161b22")
+  .attr("stroke-width", 1.5);
+
+node.append("text")
+  .attr("class", "node-label")
+  .text(d => d.label)
+  .attr("dx", d => 10 + (d.importance || 0.5) * 5)
+  .attr("dy", 4);
+
+node.on("mouseover", function(event, d) {
+  const tt = d3.select("#tooltip");
+  tt.style("display", "block");
+  tt.select(".tt-name").text(d.label);
+  tt.select(".tt-type").text(`Type: ${d.type}`);
+  tt.select(".tt-summary").text(d.summary || "");
+
+  const connected = new Set();
+  graphData.links.forEach(l => {
+    const sid = typeof l.source === 'object' ? l.source.id : l.source;
+    const tid = typeof l.target === 'object' ? l.target.id : l.target;
+    if (sid === d.id) connected.add(tid);
+    if (tid === d.id) connected.add(sid);
+  });
+
+  d3.selectAll(".node").each(function(n) {
+    if (n.id === d.id || connected.has(n.id)) {
+      d3.select(this).classed("highlighted", true);
+      d3.select(this).select("circle").attr("opacity", 1);
+      d3.select(this).select("text").attr("opacity", 1);
+    } else {
+      d3.select(this).select("circle").attr("opacity", 0.15);
+      d3.select(this).select("text").attr("opacity", 0.15);
+    }
+  });
+
+  d3.selectAll(".link").each(function(l) {
+    const sid = typeof l.source === 'object' ? l.source.id : l.source;
+    const tid = typeof l.target === 'object' ? l.target.id : l.target;
+    if (sid === d.id || tid === d.id) {
+      d3.select(this).classed("highlighted", true);
+    }
+  });
+})
+.on("mousemove", function(event) {
+  d3.select("#tooltip")
+    .style("left", (event.pageX + 12) + "px")
+    .style("top", (event.pageY - 10) + "px");
+})
+.on("mouseout", function() {
+  d3.select("#tooltip").style("display", "none");
+  d3.selectAll(".node").each(function(n) {
+    d3.select(this).classed("highlighted", false);
+    d3.select(this).select("circle").attr("opacity", 1);
+    d3.select(this).select("text").attr("opacity", 1);
+  });
+  d3.selectAll(".link").classed("highlighted", false);
+});
+
+simulation.on("tick", () => {
+  link
+    .attr("x1", d => d.source.x)
+    .attr("y1", d => d.source.y)
+    .attr("x2", d => d.target.x)
+    .attr("y2", d => d.target.y);
+  node.attr("transform", d => `translate(${d.x},${d.y})`);
+});
+
+d3.select("#stats").text(`Nodes: ${graphData.nodes.length} | Edges: ${graphData.links.length}`);
+
+window.filterGraph = function(query) {
+  const q = query.toLowerCase();
+  d3.selectAll(".node").each(function(d) {
+    const match = !q || d.label.toLowerCase().includes(q) || (d.summary && d.summary.toLowerCase().includes(q));
+    d3.select(this).style("display", match ? null : "none");
+  });
+};
+
+window.filterByType = function(type) {
+  d3.selectAll(".node").each(function(d) {
+    const match = type === "all" || d.type === type;
+    d3.select(this).style("display", match ? null : "none");
+  });
+};
+
+window.addEventListener("resize", () => {
+  svg.attr("width", window.innerWidth).attr("height", window.innerHeight);
+});
+</script>
+</body>
+</html>"""

ctxgraph/wrapper/claude.py

@@ -0,0 +1,139 @@
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+from ctxgraph.clients.models import ModelMode, get_mode_config
+from ctxgraph.graph.builder import get_storage
+
+try:
+    from ctxgraph.capsule.renderer import render_capsule, render_project_overview
+
+    HAS_CAPSULE = True
+except ImportError:
+    HAS_CAPSULE = False
+
+
+def main():
+    args = sys.argv[1:]
+
+    if not args:
+        print("Usage: ccg [--mode fast|balanced|deep] <query>")
+        print("       ccg --overview")
+        print("       ccg --chat <query>")
+        sys.exit(1)
+
+    mode = ModelMode.BALANCED
+    is_overview = False
+    is_chat = False
+    query_parts = []
+
+    for arg in args:
+        if arg == "--overview" or arg == "-o":
+            is_overview = True
+        elif arg == "--chat" or arg == "-c":
+            is_chat = True
+        elif arg.startswith("--mode="):
+            mode = ModelMode.from_str(arg.split("=", 1)[1])
+        elif arg == "--mode" or arg == "-m":
+            continue
+        else:
+            query_parts.append(arg)
+
+    if not is_overview and not query_parts:
+        print("No query provided.")
+        sys.exit(1)
+
+    query = " ".join(query_parts)
+    mode_cfg = get_mode_config(mode)
+
+    repo_path = Path.cwd()
+    capsule_text = ""
+    storage = None
+
+    try:
+        storage = get_storage(repo_path)
+    except Exception:
+        storage = None
+
+    if storage:
+        if is_overview:
+            capsule_text = render_project_overview(storage)
+        else:
+            capsule_text = render_capsule(
+                storage,
+                query,
+                max_nodes=mode_cfg["max_nodes"],
+            )
+    else:
+        capsule_text = (
+            "[INFO]No ctxgraph data found. "
+            "Run `ctx build` for enriched context."
+        )
+
+    mode_hint = {
+        ModelMode.FAST: "Use fast, concise reasoning. Prioritize direct answers.",
+        ModelMode.BALANCED: "",
+        ModelMode.DEEP: "Take your time. Analyze deeply before responding.",
+    }.get(mode, "")
+
+    augmented_prompt = (
+        f"[CONTEXT]\n{capsule_text}\n[/CONTEXT]\n\n"
+        f"TASK: {query}\n\n"
+        f"{mode_hint}\n" if mode_hint else ""
+    )
+
+    claude_cmd = _find_claude()
+    if not claude_cmd:
+        print(
+            "[red]Claude CLI not found. Install it or ensure it's in PATH.[/red]",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    if is_chat:
+        context_file = repo_path / ".ctxgraph" / "context.md"
+        context_file.parent.mkdir(parents=True, exist_ok=True)
+        context_file.write_text(capsule_text, encoding="utf-8")
+
+        system_msg = (
+            f"Project context is loaded from {context_file}.\n"
+            f"Read it first, then help the user.\n"
+            f"{mode_hint}"
+        )
+
+        proc = subprocess.Popen(
+            [claude_cmd, "-p", system_msg],
+            stdin=sys.stdin,
+            stdout=sys.stdout,
+            stderr=sys.stderr,
+        )
+        proc.wait()
+    else:
+        proc = subprocess.run(
+            [claude_cmd, "-p", augmented_prompt],
+            capture_output=False,
+        )
+        sys.exit(proc.returncode)
+
+
+def _find_claude() -> str | None:
+    claude_names = ["claude", "claude.exe"]
+    for name in claude_names:
+        try:
+            result = subprocess.run(
+                ["where", name] if sys.platform == "win32" else ["which", name],
+                capture_output=True,
+                text=True,
+                timeout=5,
+            )
+            if result.returncode == 0:
+                return name
+        except (subprocess.TimeoutExpired, FileNotFoundError):
+            pass
+    return None
+
+
+if __name__ == "__main__":
+    main()