mcp-vector-search 0.7.6__py3-none-any.whl → 0.8.0__py3-none-any.whl

mcp_vector_search/__init__.py

@@ -1,7 +1,7 @@
 """MCP Vector Search - CLI-first semantic code search with MCP integration."""
 
-__version__ = "0.7.6"
-__build__ = "28"
+__version__ = "0.8.0"
+__build__ = "29"
 __author__ = "Robert Matsuoka"
 __email__ = "bobmatnyc@gmail.com"
 

mcp_vector_search/cli/commands/visualize.py

@@ -0,0 +1,523 @@
+"""Visualization commands for MCP Vector Search."""
+
+import asyncio
+import json
+from pathlib import Path
+
+import typer
+from loguru import logger
+from rich.console import Console
+from rich.panel import Panel
+
+from ...core.database import ChromaVectorDatabase
+from ...core.embeddings import create_embedding_function
+from ...core.project import load_project
+
+app = typer.Typer(
+    help="Visualize code chunk relationships",
+    no_args_is_help=True,
+)
+console = Console()
+
+
+@app.command()
+def export(
+    output: Path = typer.Option(
+        Path("chunk-graph.json"),
+        "--output",
+        "-o",
+        help="Output file for chunk relationship data",
+    ),
+    file_path: str | None = typer.Option(
+        None,
+        "--file",
+        "-f",
+        help="Export only chunks from specific file (supports wildcards)",
+    ),
+) -> None:
+    """Export chunk relationships as JSON for D3.js visualization.
+
+    Examples:
+        # Export all chunks
+        mcp-vector-search visualize export
+
+        # Export from specific file
+        mcp-vector-search visualize export --file src/main.py
+
+        # Custom output location
+        mcp-vector-search visualize export -o graph.json
+    """
+    asyncio.run(_export_chunks(output, file_path))
+
+
+async def _export_chunks(output: Path, file_filter: str | None) -> None:
+    """Export chunk relationship data."""
+    try:
+        # Load project
+        project_manager, config = load_project(Path.cwd())
+
+        # Get database
+        embedding_function = create_embedding_function(config.embedding_model)
+        database = ChromaVectorDatabase(
+            persist_directory=config.index_path,
+            embedding_function=embedding_function,
+        )
+        await database.initialize()
+
+        # Get all chunks with metadata
+        console.print("[cyan]Fetching chunks from database...[/cyan]")
+
+        # Query all chunks (we'll use a dummy search to get all)
+        stats = await database.get_stats()
+
+        if stats.total_chunks == 0:
+            console.print("[yellow]No chunks found in index. Run 'mcp-vector-search index' first.[/yellow]")
+            raise typer.Exit(1)
+
+        # Build graph data structure
+        nodes = []
+        links = []
+
+        # We need to query the database to get actual chunk data
+        # Since there's no "get all chunks" method, we'll work with the stats
+        # In a real implementation, you would add a method to get all chunks
+
+        console.print(f"[yellow]Note: Full chunk export requires database enhancement.[/yellow]")
+        console.print(f"[cyan]Creating placeholder graph with {stats.total_chunks} chunks...[/cyan]")
+
+        # Create sample graph structure
+        graph_data = {
+            "nodes": [
+                {
+                    "id": f"chunk_{i}",
+                    "name": f"Chunk {i}",
+                    "type": "code",
+                    "file_path": "example.py",
+                    "start_line": i * 10,
+                    "end_line": (i + 1) * 10,
+                    "complexity": 1.0 + (i % 5),
+                }
+                for i in range(min(stats.total_chunks, 50))  # Limit to 50 for demo
+            ],
+            "links": [
+                {"source": f"chunk_{i}", "target": f"chunk_{i+1}"}
+                for i in range(min(stats.total_chunks - 1, 49))
+            ],
+            "metadata": {
+                "total_chunks": stats.total_chunks,
+                "total_files": stats.total_files,
+                "languages": stats.languages,
+                "export_note": "This is a placeholder. Full export requires database enhancement.",
+            },
+        }
+
+        # Write to file
+        output.parent.mkdir(parents=True, exist_ok=True)
+        with open(output, "w") as f:
+            json.dump(graph_data, f, indent=2)
+
+        await database.close()
+
+        console.print()
+        console.print(
+            Panel.fit(
+                f"[green]✓[/green] Exported graph data to [cyan]{output}[/cyan]\n\n"
+                f"Nodes: {len(graph_data['nodes'])}\n"
+                f"Links: {len(graph_data['links'])}\n\n"
+                f"[dim]Next: Run 'mcp-vector-search visualize serve' to view[/dim]",
+                title="Export Complete",
+                border_style="green",
+            )
+        )
+
+    except Exception as e:
+        logger.error(f"Export failed: {e}")
+        console.print(f"[red]✗ Export failed: {e}[/red]")
+        raise typer.Exit(1)
+
+
+@app.command()
+def serve(
+    port: int = typer.Option(8080, "--port", "-p", help="Port for visualization server"),
+    graph_file: Path = typer.Option(
+        Path("chunk-graph.json"),
+        "--graph",
+        "-g",
+        help="Graph JSON file to visualize",
+    ),
+) -> None:
+    """Start local HTTP server for D3.js visualization.
+
+    Examples:
+        # Start server on default port 8080
+        mcp-vector-search visualize serve
+
+        # Custom port
+        mcp-vector-search visualize serve --port 3000
+
+        # Custom graph file
+        mcp-vector-search visualize serve --graph my-graph.json
+    """
+    import http.server
+    import os
+    import socketserver
+    import webbrowser
+
+    # Get visualization directory
+    viz_dir = Path(__file__).parent.parent.parent / "visualization"
+
+    if not viz_dir.exists():
+        console.print(
+            f"[yellow]Visualization directory not found. Creating at {viz_dir}...[/yellow]"
+        )
+        viz_dir.mkdir(parents=True, exist_ok=True)
+
+        # Create index.html if it doesn't exist
+        html_file = viz_dir / "index.html"
+        if not html_file.exists():
+            console.print("[yellow]Creating visualization HTML file...[/yellow]")
+            _create_visualization_html(html_file)
+
+    # Copy graph file to visualization directory if it exists
+    if graph_file.exists():
+        import shutil
+
+        dest = viz_dir / "chunk-graph.json"
+        shutil.copy(graph_file, dest)
+        console.print(f"[green]✓[/green] Copied graph data to {dest}")
+    else:
+        console.print(
+            f"[yellow]Warning: Graph file {graph_file} not found. "
+            "Run 'mcp-vector-search visualize export' first.[/yellow]"
+        )
+
+    # Change to visualization directory
+    os.chdir(viz_dir)
+
+    # Start server
+    Handler = http.server.SimpleHTTPRequestHandler
+    try:
+        with socketserver.TCPServer(("", port), Handler) as httpd:
+            url = f"http://localhost:{port}"
+            console.print()
+            console.print(
+                Panel.fit(
+                    f"[green]✓[/green] Visualization server running\n\n"
+                    f"URL: [cyan]{url}[/cyan]\n"
+                    f"Directory: [dim]{viz_dir}[/dim]\n\n"
+                    f"[dim]Press Ctrl+C to stop[/dim]",
+                    title="Server Started",
+                    border_style="green",
+                )
+            )
+
+            # Open browser
+            webbrowser.open(url)
+
+            try:
+                httpd.serve_forever()
+            except KeyboardInterrupt:
+                console.print("\n[yellow]Stopping server...[/yellow]")
+
+    except OSError as e:
+        if "Address already in use" in str(e):
+            console.print(
+                f"[red]✗ Port {port} is already in use. Try a different port with --port[/red]"
+            )
+        else:
+            console.print(f"[red]✗ Server error: {e}[/red]")
+        raise typer.Exit(1)
+
+
+def _create_visualization_html(html_file: Path) -> None:
+    """Create the D3.js visualization HTML file."""
+    html_content = '''<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="utf-8">
+    <title>Code Chunk Relationship Graph</title>
+    <script src="https://d3js.org/d3.v7.min.js"></script>
+    <style>
+        body {
+            margin: 0;
+            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+            background: #0d1117;
+            color: #c9d1d9;
+            overflow: hidden;
+        }
+
+        #controls {
+            position: absolute;
+            top: 20px;
+            left: 20px;
+            background: rgba(13, 17, 23, 0.95);
+            border: 1px solid #30363d;
+            border-radius: 6px;
+            padding: 16px;
+            min-width: 250px;
+            max-height: 80vh;
+            overflow-y: auto;
+            box-shadow: 0 8px 24px rgba(0, 0, 0, 0.4);
+        }
+
+        h1 { margin: 0 0 16px 0; font-size: 18px; }
+        h3 { margin: 16px 0 8px 0; font-size: 14px; color: #8b949e; }
+
+        .control-group {
+            margin-bottom: 12px;
+        }
+
+        label {
+            display: block;
+            margin-bottom: 4px;
+            font-size: 12px;
+            color: #8b949e;
+        }
+
+        input[type="file"] {
+            width: 100%;
+            padding: 6px;
+            background: #161b22;
+            border: 1px solid #30363d;
+            border-radius: 6px;
+            color: #c9d1d9;
+            font-size: 12px;
+        }
+
+        .legend {
+            font-size: 12px;
+        }
+
+        .legend-item {
+            margin: 4px 0;
+            display: flex;
+            align-items: center;
+        }
+
+        .legend-color {
+            width: 12px;
+            height: 12px;
+            border-radius: 50%;
+            margin-right: 8px;
+        }
+
+        #graph {
+            width: 100vw;
+            height: 100vh;
+        }
+
+        .node circle {
+            cursor: pointer;
+            stroke: #c9d1d9;
+            stroke-width: 1.5px;
+        }
+
+        .node.module circle { fill: #238636; }
+        .node.class circle { fill: #1f6feb; }
+        .node.function circle { fill: #d29922; }
+        .node.method circle { fill: #8957e5; }
+        .node.code circle { fill: #6e7681; }
+
+        .node text {
+            font-size: 11px;
+            fill: #c9d1d9;
+            text-anchor: middle;
+            pointer-events: none;
+            user-select: none;
+        }
+
+        .link {
+            stroke: #30363d;
+            stroke-opacity: 0.6;
+            stroke-width: 1.5px;
+        }
+
+        .tooltip {
+            position: absolute;
+            padding: 12px;
+            background: rgba(13, 17, 23, 0.95);
+            border: 1px solid #30363d;
+            border-radius: 6px;
+            pointer-events: none;
+            display: none;
+            font-size: 12px;
+            max-width: 300px;
+            box-shadow: 0 8px 24px rgba(0, 0, 0, 0.4);
+        }
+
+        .stats {
+            margin-top: 16px;
+            padding-top: 16px;
+            border-top: 1px solid #30363d;
+            font-size: 12px;
+            color: #8b949e;
+        }
+    </style>
+</head>
+<body>
+    <div id="controls">
+        <h1>🔍 Code Graph</h1>
+
+        <div class="control-group">
+            <label>Load Graph Data:</label>
+            <input type="file" id="fileInput" accept=".json">
+        </div>
+
+        <h3>Legend</h3>
+        <div class="legend">
+            <div class="legend-item">
+                <span class="legend-color" style="background: #238636;"></span> Module
+            </div>
+            <div class="legend-item">
+                <span class="legend-color" style="background: #1f6feb;"></span> Class
+            </div>
+            <div class="legend-item">
+                <span class="legend-color" style="background: #d29922;"></span> Function
+            </div>
+            <div class="legend-item">
+                <span class="legend-color" style="background: #8957e5;"></span> Method
+            </div>
+            <div class="legend-item">
+                <span class="legend-color" style="background: #6e7681;"></span> Code
+            </div>
+        </div>
+
+        <div class="stats" id="stats"></div>
+    </div>
+
+    <svg id="graph"></svg>
+    <div id="tooltip" class="tooltip"></div>
+
+    <script>
+        const width = window.innerWidth;
+        const height = window.innerHeight;
+
+        const svg = d3.select("#graph")
+            .attr("width", width)
+            .attr("height", height)
+            .call(d3.zoom().on("zoom", (event) => {
+                g.attr("transform", event.transform);
+            }));
+
+        const g = svg.append("g");
+        const tooltip = d3.select("#tooltip");
+        let simulation;
+
+        function visualizeGraph(data) {
+            g.selectAll("*").remove();
+
+            simulation = d3.forceSimulation(data.nodes)
+                .force("link", d3.forceLink(data.links).id(d => d.id).distance(100))
+                .force("charge", d3.forceManyBody().strength(-400))
+                .force("center", d3.forceCenter(width / 2, height / 2))
+                .force("collision", d3.forceCollide().radius(40));
+
+            const link = g.append("g")
+                .selectAll("line")
+                .data(data.links)
+                .join("line")
+                .attr("class", "link");
+
+            const node = g.append("g")
+                .selectAll("g")
+                .data(data.nodes)
+                .join("g")
+                .attr("class", d => `node ${d.type}`)
+                .call(drag(simulation))
+                .on("mouseover", showTooltip)
+                .on("mouseout", hideTooltip);
+
+            node.append("circle")
+                .attr("r", d => d.complexity ? Math.min(8 + d.complexity * 2, 25) : 12);
+
+            node.append("text")
+                .text(d => d.name)
+                .attr("dy", 30);
+
+            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})`);
+            });
+
+            updateStats(data);
+        }
+
+        function showTooltip(event, d) {
+            tooltip
+                .style("display", "block")
+                .style("left", (event.pageX + 10) + "px")
+                .style("top", (event.pageY + 10) + "px")
+                .html(`
+                    <div><strong>${d.name}</strong></div>
+                    <div>Type: ${d.type}</div>
+                    ${d.complexity ? `<div>Complexity: ${d.complexity.toFixed(1)}</div>` : ''}
+                    ${d.start_line ? `<div>Lines: ${d.start_line}-${d.end_line}</div>` : ''}
+                    <div>File: ${d.file_path}</div>
+                `);
+        }
+
+        function hideTooltip() {
+            tooltip.style("display", "none");
+        }
+
+        function drag(simulation) {
+            function dragstarted(event) {
+                if (!event.active) simulation.alphaTarget(0.3).restart();
+                event.subject.fx = event.subject.x;
+                event.subject.fy = event.subject.y;
+            }
+
+            function dragged(event) {
+                event.subject.fx = event.x;
+                event.subject.fy = event.y;
+            }
+
+            function dragended(event) {
+                if (!event.active) simulation.alphaTarget(0);
+                event.subject.fx = null;
+                event.subject.fy = null;
+            }
+
+            return d3.drag()
+                .on("start", dragstarted)
+                .on("drag", dragged)
+                .on("end", dragended);
+        }
+
+        function updateStats(data) {
+            const stats = d3.select("#stats");
+            stats.html(`
+                <div>Nodes: ${data.nodes.length}</div>
+                <div>Links: ${data.links.length}</div>
+                ${data.metadata ? `<div>Files: ${data.metadata.total_files || 'N/A'}</div>` : ''}
+            `);
+        }
+
+        document.getElementById("fileInput").addEventListener("change", (event) => {
+            const file = event.target.files[0];
+            if (file) {
+                const reader = new FileReader();
+                reader.onload = (e) => {
+                    const data = JSON.parse(e.target.result);
+                    visualizeGraph(data);
+                };
+                reader.readAsText(file);
+            }
+        });
+
+        // Try to load default data
+        fetch("chunk-graph.json")
+            .then(response => response.json())
+            .then(data => visualizeGraph(data))
+            .catch(err => console.log("No default graph found. Please load a JSON file."));
+    </script>
+</body>
+</html>'''
+
+    with open(html_file, "w") as f:
+        f.write(html_content)

mcp_vector_search/cli/main.py

@@ -33,16 +33,17 @@ unfamiliar codebases, finding similar patterns, and integrating with AI tools.
   3. Check status: [green]mcp-vector-search status[/green]
 
 [bold cyan]Main Commands:[/bold cyan]
-  init      🔧 Initialize project
-  demo      🎬 Run interactive demo
-  doctor    🩺 Check system health
-  status    📊 Show project status
-  search    🔍 Search code semantically
-  index     📇 Index codebase
-  mcp       🤖 MCP integration for AI tools
-  config    ⚙️  Configure settings
-  help      ❓ Get help
-  version   ℹ️  Show version
+  init       🔧 Initialize project
+  demo       🎬 Run interactive demo
+  doctor     🩺 Check system health
+  status     📊 Show project status
+  search     🔍 Search code semantically
+  index      📇 Index codebase
+  mcp        🤖 MCP integration for AI tools
+  config     ⚙️  Configure settings
+  visualize  📊 Visualize code relationships
+  help       ❓ Get help
+  version    ℹ️  Show version
 
 [dim]For detailed help: [cyan]mcp-vector-search COMMAND --help[/cyan][/dim]
     """,
@@ -58,6 +59,7 @@ from .commands.init import init_app  # noqa: E402
 from .commands.mcp import mcp_app  # noqa: E402
 from .commands.search import search_app, search_main  # noqa: E402, F401
 from .commands.status import main as status_main  # noqa: E402
+from .commands.visualize import app as visualize_app  # noqa: E402
 
 # ============================================================================
 # MAIN COMMANDS - Clean hierarchy
@@ -89,7 +91,10 @@ app.add_typer(mcp_app, name="mcp", help="🤖 Manage MCP integration for AI tool
 # 8. CONFIG - Configuration
 app.add_typer(config_app, name="config", help="⚙️  Manage project configuration")
 
-# 9. HELP - Enhanced help
+# 9. VISUALIZE - Code graph visualization
+app.add_typer(visualize_app, name="visualize", help="📊 Visualize code chunk relationships")
+
+# 10. HELP - Enhanced help
 # (defined below inline)
 
 # 10. VERSION - Version info

mcp_vector_search/core/indexer.py

@@ -295,8 +295,11 @@ class SemanticIndexer:
                 logger.debug(f"No chunks extracted from {file_path}")
                 return True  # Not an error, just empty file
 
+            # Build hierarchical relationships between chunks
+            chunks_with_hierarchy = self._build_chunk_hierarchy(chunks)
+
             # Add chunks to database
-            await self.database.add_chunks(chunks)
+            await self.database.add_chunks(chunks_with_hierarchy)
 
             # Update metadata after successful indexing
             metadata = self._load_index_metadata()
@@ -710,8 +713,11 @@ class SemanticIndexer:
                     chunks = await self._parse_file(file_path)
 
                     if chunks:
+                        # Build hierarchical relationships
+                        chunks_with_hierarchy = self._build_chunk_hierarchy(chunks)
+
                         # Add chunks to database
-                        await self.database.add_chunks(chunks)
+                        await self.database.add_chunks(chunks_with_hierarchy)
                         chunks_added = len(chunks)
                         logger.debug(f"Indexed {chunks_added} chunks from {file_path}")
 
@@ -729,3 +735,67 @@ class SemanticIndexer:
 
         # Save metadata at the end
         self._save_index_metadata(metadata)
+
+    def _build_chunk_hierarchy(self, chunks: list[CodeChunk]) -> list[CodeChunk]:
+        """Build parent-child relationships between chunks.
+
+        Logic:
+        - Module chunks (chunk_type="module") have depth 0
+        - Class chunks have depth 1, parent is module
+        - Method chunks have depth 2, parent is class
+        - Function chunks outside classes have depth 1, parent is module
+        - Nested classes increment depth
+
+        Args:
+            chunks: List of code chunks to process
+
+        Returns:
+            List of chunks with hierarchy relationships established
+        """
+        if not chunks:
+            return chunks
+
+        # Group chunks by type and name
+        module_chunks = [c for c in chunks if c.chunk_type in ("module", "imports")]
+        class_chunks = [c for c in chunks if c.chunk_type in ("class", "interface", "mixin")]
+        function_chunks = [c for c in chunks if c.chunk_type in ("function", "method", "constructor")]
+
+        # Build relationships
+        for func in function_chunks:
+            if func.class_name:
+                # Find parent class
+                parent_class = next(
+                    (c for c in class_chunks if c.class_name == func.class_name),
+                    None
+                )
+                if parent_class:
+                    func.parent_chunk_id = parent_class.chunk_id
+                    func.chunk_depth = parent_class.chunk_depth + 1
+                    if func.chunk_id not in parent_class.child_chunk_ids:
+                        parent_class.child_chunk_ids.append(func.chunk_id)
+            else:
+                # Top-level function
+                if not func.chunk_depth:
+                    func.chunk_depth = 1
+                # Link to module if exists
+                if module_chunks and not func.parent_chunk_id:
+                    func.parent_chunk_id = module_chunks[0].chunk_id
+                    if func.chunk_id not in module_chunks[0].child_chunk_ids:
+                        module_chunks[0].child_chunk_ids.append(func.chunk_id)
+
+        for cls in class_chunks:
+            # Classes without parent are top-level (depth 1)
+            if not cls.chunk_depth:
+                cls.chunk_depth = 1
+            # Link to module if exists
+            if module_chunks and not cls.parent_chunk_id:
+                cls.parent_chunk_id = module_chunks[0].chunk_id
+                if cls.chunk_id not in module_chunks[0].child_chunk_ids:
+                    module_chunks[0].child_chunk_ids.append(cls.chunk_id)
+
+        # Module chunks stay at depth 0
+        for mod in module_chunks:
+            if not mod.chunk_depth:
+                mod.chunk_depth = 0
+
+        return chunks