contextl-mcp 0.1.2__py3-none-any.whl

contextl_mcp-0.1.2.dist-info/METADATA

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: contextl-mcp
+Version: 0.1.2
+Summary: Repository Intelligence Engine — MCP server for AI coding agents
+Project-URL: Homepage, https://github.com/dev7shah/prune
+Project-URL: Issues, https://github.com/dev7shah/prune/issues
+Author: dev7shah
+License: MIT
+Keywords: ai,claude,code-search,context,cursor,mcp,model-context-protocol,nextjs,repository,typescript,vscode,windsurf
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Requires-Dist: mcp
+Requires-Dist: networkx
+Description-Content-Type: text/markdown
+
+# contextl
+
+> **Context-selection engine for AI coding assistants.**  
+> Finds the most relevant files in your codebase for a natural-language change request — no LLM, no embeddings, no vector database. Pure graph + text scoring.
+
+```
+"fix the upload error" → [FileUploader.tsx, lib/upload.ts, UploadSection.tsx]
+```
+
+Instead of feeding your entire repo to an AI, `contextl` reduces 5 000 files down to the 5 most relevant ones in milliseconds.
+
+---
+
+## Installation
+
+```bash
+pip install contextl
+```
+
+Python 3.9+ required. `networkx` and `mcp` are installed automatically as dependencies.
+
+---
+
+## Quick start — connect to your IDE
+
+Paste this into your IDE's MCP config file:
+
+```json
+{
+  "mcpServers": {
+    "contextl": {
+      "command": "contextl"
+    }
+  }
+}
+```
+
+#### Config file locations
+
+| IDE | Config file |
+|-----|-------------|
+| **Antigravity** | `~/.gemini/antigravity/mcp/` (MCP server directory) |
+| **Cursor** | `~/.cursor/mcp.json` |
+| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` |
+| **Claude Code** | `~/.claude.json` (or run `claude mcp add`) |
+| **VS Code** | `.vscode/mcp.json` in your workspace root |
+
+### Use it
+
+Just talk to your IDE's AI normally:
+
+```
+You:  "fix the file upload error handler"
+IDE:  calls query_repo → gets [FileUploader.tsx, lib/upload.ts, …]
+IDE:  reads only those 5 files instead of the whole repo
+```
+
+---
+
+## Tools exposed
+
+### `query_repo(repo_path, query, top_n?)`
+
+Ranks the most relevant files for a change request.
+
+**Parameters:**
+- `repo_path` — absolute path to the repository root
+- `query` — natural-language description of the change (e.g. `"change the download button color"`)
+- `top_n` — max results to return (default `5`, max `20`)
+
+**Returns:**
+```json
+{
+  "query": "change the download button",
+  "repo": "/path/to/repo",
+  "total_files_scanned": 142,
+  "results": [
+    {
+      "rank": 1,
+      "path": "components/DownloadButton.tsx",
+      "score": 0.9800,
+      "confidence": "high",
+      "matched_terms": ["button", "download"],
+      "reasoning": "Filename strongly matches query terms; file contents heavily reference query terms."
+    }
+  ]
+}
+```
+
+### `scan_repo(repo_path)`
+
+Lists all source files the engine can see in a repository.
+
+---
+
+## How it works
+
+The engine runs **entirely locally** — no network calls, no AI APIs, no data leaves your machine.
+
+Scoring uses four signals:
+
+| Signal | Weight | Description |
+|--------|--------|-------------|
+| Keyword match | 0.5 | Query terms in the file path / name |
+| Content match | 0.5 | Query terms inside the file source |
+| Neighbor bonus | +0.15 | Files near high-scoring files in the import graph |
+| PageRank | 0.05 | Tiebreaker: more connected files rank slightly higher |
+
+Supports **Next.js / React / TypeScript** repos (`.ts`, `.tsx`, `.js`, `.jsx`). Automatically detects `@/` path aliases from `tsconfig.json`.
+
+---
+
+## Also available as an npm package
+
+```bash
+npx contextl
+```
+
+For IDE configs that prefer `npx` over a Python command.
+
+---
+
+## License
+
+MIT

contextl_mcp-0.1.2.dist-info/RECORD

@@ -0,0 +1,12 @@
+prune_mcp/__init__.py,sha256=YvuYzWnKtqBb-IqG8HAu-nhIYAsgj9Vmc_b9o7vO-js,22
+prune_mcp/__main__.py,sha256=H0u5ZJVpl1c9Mq914yWTBEl_TJfcBqwlChT6Ne70fhw,1463
+python/graph_builder.py,sha256=NRpBQxDmCXmlBOpxHmiHv2LZKI8ece-Pngv8pQKEk7c,5536
+python/import_parser.py,sha256=acvH6iy9S_aMa_DqV-jZuTZANHv6hMOT998pTQt-0Kk,9252
+python/main.py,sha256=KdD_RZW8xZ126zKwFXMyOlm4V3U5n-8qY7N0xuRJ9N0,7616
+python/mcp_server.py,sha256=tyzuI2dwIN_ISinX95WuKQZ2cHoUvHh4uZYOHiKbggw,6946
+python/query_engine.py,sha256=gfwte3o2Wyl95vxA0lUdDYrrxuqxwyJYgcKEF7CUA0c,8212
+python/scanner.py,sha256=Vz38YhQf6iDfx6of0lhIT6LQFbzGN8L6uD7BLQLvZlg,3251
+contextl_mcp-0.1.2.dist-info/METADATA,sha256=41xSu1UUWZSYyVWJmeSFj5VHGJYq2w1vr7B4ACr1flM,4060
+contextl_mcp-0.1.2.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+contextl_mcp-0.1.2.dist-info/entry_points.txt,sha256=iPuOmo8ThSrk9UQojtAvo_oGcizUOPjTZn4Ca1A6wUU,53
+contextl_mcp-0.1.2.dist-info/RECORD,,

contextl_mcp-0.1.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

contextl_mcp-0.1.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+contextl = prune_mcp.__main__:main

prune_mcp/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.2"

prune_mcp/__main__.py

@@ -0,0 +1,46 @@
+"""
+prune-mcp — entry point
+
+Called when a user runs:
+    prune-mcp                  (console_scripts shim installed by pip)
+    python -m prune_mcp        (module execution)
+
+Resolves the bundled mcp_server.py, sets up the environment, then uses
+os.execve to *replace* the current process with Python running mcp_server.py.
+This means no subprocess wrapper, no extra PID, and clean signal forwarding —
+the IDE talks directly to mcp_server.py over stdio.
+"""
+
+import os
+import sys
+from pathlib import Path
+
+
+def main() -> None:
+    # The bundled engine files live in python/ next to this package.
+    # Installed layout (wheel):
+    #   site-packages/
+    #     prune_mcp/          ← this file lives here
+    #     python/             ← engine files live here
+    python_dir = Path(__file__).parent.parent / "python"
+    mcp_server = python_dir / "mcp_server.py"
+
+    if not mcp_server.exists():
+        print(
+            f"Error: cannot find mcp_server.py at {mcp_server}\n"
+            "The package may be corrupted — try reinstalling:\n"
+            "    pip install --force-reinstall prune-mcp",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    env = os.environ.copy()
+    env["PYTHONPATH"] = str(python_dir)
+    env["PYTHONUNBUFFERED"] = "1"
+
+    # Replace this process entirely — clean stdio passthrough, no extra PID.
+    os.execve(sys.executable, [sys.executable, str(mcp_server)], env)
+
+
+if __name__ == "__main__":
+    main()

python/graph_builder.py

@@ -0,0 +1,171 @@
+"""
+Repository Intelligence Engine
+Step 3: Graph Builder
+
+Takes the import relationships from the parser and builds a directed graph
+where nodes are files and edges are import dependencies.
+
+Adds useful metadata to each node:
+  - in_degree:  how many files import this file (how "shared" it is)
+  - out_degree: how many files this file imports (how many deps it has)
+  - centrality: PageRank score (overall importance in the graph)
+
+Also computes connected clusters so we can understand which files
+belong to the same logical feature.
+"""
+
+import networkx as nx
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from scanner import scan_repo
+from import_parser import parse_imports, ParseResult
+
+
+@dataclass
+class FileNode:
+    """A file in the repository graph with computed metrics."""
+    path: str
+    extension: str
+    size_bytes: int
+
+    # Graph metrics (computed after graph is built)
+    in_degree: int = 0        # files that import this
+    out_degree: int = 0       # files this imports
+    centrality: float = 0.0   # PageRank score
+
+
+@dataclass
+class RepoGraph:
+    """
+    The complete dependency graph of the repository.
+    Wraps a NetworkX DiGraph with helper methods.
+    """
+    graph: nx.DiGraph
+    nodes: dict[str, FileNode]   # path → FileNode
+    root: str
+
+    def get_dependents(self, file_path: str) -> list[str]:
+        """Files that directly import this file (who uses me?)."""
+        return list(self.graph.predecessors(file_path))
+
+    def get_dependencies(self, file_path: str) -> list[str]:
+        """Files this file directly imports (what do I use?)."""
+        return list(self.graph.successors(file_path))
+
+    def get_neighbors(self, file_path: str, depth: int = 1) -> set[str]:
+        """
+        All files within `depth` hops of file_path (both directions).
+        depth=1 → direct imports + direct importers
+        depth=2 → their imports/importers too
+        """
+        neighbors = set()
+        frontier = {file_path}
+
+        for _ in range(depth):
+            next_frontier = set()
+            for node in frontier:
+                next_frontier.update(self.graph.predecessors(node))
+                next_frontier.update(self.graph.successors(node))
+            new_nodes = next_frontier - neighbors - {file_path}
+            neighbors.update(new_nodes)
+            frontier = new_nodes
+
+        return neighbors
+
+    def most_central_files(self, top_n: int = 5) -> list[FileNode]:
+        """Return the top N files by PageRank centrality."""
+        sorted_nodes = sorted(
+            self.nodes.values(),
+            key=lambda n: n.centrality,
+            reverse=True,
+        )
+        return sorted_nodes[:top_n]
+
+    def summary(self) -> str:
+        lines = [
+            f"Repository: {self.root}",
+            f"Nodes (files):        {self.graph.number_of_nodes()}",
+            f"Edges (imports):      {self.graph.number_of_edges()}",
+            f"Connected components: {nx.number_weakly_connected_components(self.graph)}",
+            "",
+            "Most central files (PageRank):",
+        ]
+        for node in self.most_central_files():
+            lines.append(
+                f"  {node.centrality:.4f}  {node.path}"
+                f"  (imported by {node.in_degree}, imports {node.out_degree})"
+            )
+        return "\n".join(lines)
+
+    def print_adjacency(self) -> None:
+        """Print a human-readable view of the full graph."""
+        print("Full dependency graph:")
+        for node_path in sorted(self.graph.nodes):
+            deps = self.get_dependencies(node_path)
+            used_by = self.get_dependents(node_path)
+            print(f"\n  {node_path}")
+            if deps:
+                for d in deps:
+                    print(f"    imports  → {d}")
+            if used_by:
+                for u in used_by:
+                    print(f"    used by  ← {u}")
+
+
+def build_graph(scan_result, parse_result: ParseResult) -> RepoGraph:
+    """
+    Build a directed dependency graph from scan + parse results.
+
+    Args:
+        scan_result:  Output from scan_repo()
+        parse_result: Output from parse_imports()
+
+    Returns:
+        RepoGraph with computed metrics on every node.
+    """
+    G = nx.DiGraph()
+
+    # Add all scanned files as nodes
+    file_nodes: dict[str, FileNode] = {}
+    for f in scan_result.files:
+        node = FileNode(
+            path=f.path,
+            extension=f.extension,
+            size_bytes=f.size_bytes,
+        )
+        file_nodes[f.path] = node
+        G.add_node(f.path, **vars(node))
+
+    # Add edges from import relationships
+    for rel in parse_result.relationships:
+        if rel.source in G and rel.target in G:
+            G.add_edge(rel.source, rel.target, raw_import=rel.raw_import)
+
+    # Compute PageRank (importance score)
+    try:
+        pagerank = nx.pagerank(G, alpha=0.85)
+    except nx.PowerIterationFailedConvergence:
+        pagerank = {n: 1.0 / len(G.nodes) for n in G.nodes}
+
+    # Attach metrics to each node
+    for path, node in file_nodes.items():
+        node.in_degree = G.in_degree(path)
+        node.out_degree = G.out_degree(path)
+        node.centrality = pagerank.get(path, 0.0)
+
+    return RepoGraph(graph=G, nodes=file_nodes, root=scan_result.root)
+
+
+if __name__ == "__main__":
+    import sys
+
+    target = sys.argv[1] if len(sys.argv) > 1 else "."
+
+    scan = scan_repo(target)
+    parse = parse_imports(scan)
+    repo_graph = build_graph(scan, parse)
+
+    print(repo_graph.summary())
+    print()
+    repo_graph.print_adjacency()

python/import_parser.py

@@ -0,0 +1,271 @@
+"""
+Repository Intelligence Engine
+Step 2: Import Parser
+
+Reads each scanned file and extracts import relationships.
+Handles:
+  - Relative imports:  import X from "./foo"  or  "../../lib/bar"
+  - Alias imports:     import X from "@/components/Button"
+  - Type imports:      import type { X } from "@/types"
+  - Named imports:     import { X, Y } from "./utils"
+
+Returns only imports that resolve to other files in the repository.
+External packages (react, next, etc.) are ignored.
+"""
+
+import re
+from pathlib import Path
+from dataclasses import dataclass, field
+
+from scanner import ScannedFile, ScanResult
+
+
+# Matches any ES6 import statement and captures the module path
+IMPORT_PATTERN = re.compile(
+    r"""import\s+(?:type\s+)?          # import or import type
+        (?:
+            \{[^}]*\}                  # named imports: { Foo, Bar }
+            |[\w*]+                    # default or namespace: Foo or *
+            |[\w*]+\s*,\s*\{[^}]*\}   # mixed: Foo, { Bar }
+        )?
+        \s*(?:from\s+)?                # optional "from"
+        ['"](.*?)['"]                  # the module path in quotes
+    """,
+    re.VERBOSE,
+)
+
+# Also catch: import("./foo")  — dynamic imports
+DYNAMIC_IMPORT_PATTERN = re.compile(r"""import\s*\(\s*['"](.*?)['"]\s*\)""")
+
+
+@dataclass
+class ImportRelationship:
+    """A resolved import from one file to another."""
+    source: str       # Relative path of the file doing the importing
+    target: str       # Relative path of the file being imported
+    raw_import: str   # The original import string (e.g. "@/components/Button")
+
+
+@dataclass
+class ParseResult:
+    """All import relationships discovered across the repository."""
+    relationships: list[ImportRelationship] = field(default_factory=list)
+    unresolved: list[tuple[str, str]] = field(default_factory=list)
+    # unresolved = [(source_file, raw_import), ...] — external packages or not found
+
+    def summary(self) -> str:
+        lines = [
+            f"Import relationships found: {len(self.relationships)}",
+            f"Unresolved (external/missing): {len(self.unresolved)}",
+            "",
+            "Resolved imports:",
+        ]
+        for rel in self.relationships:
+            lines.append(f"  {rel.source}")
+            lines.append(f"    → {rel.target}  (from '{rel.raw_import}')")
+        return "\n".join(lines)
+
+
+def _extract_raw_imports(source_code: str) -> list[str]:
+    """Pull all import paths out of a TypeScript/JSX file."""
+    paths = []
+    for match in IMPORT_PATTERN.finditer(source_code):
+        paths.append(match.group(1))
+    for match in DYNAMIC_IMPORT_PATTERN.finditer(source_code):
+        paths.append(match.group(1))
+    return paths
+
+
+def _is_external(import_path: str) -> bool:
+    """Return True if this is an npm package rather than a local file."""
+    # Local files start with . (relative) or @ followed by / (alias like @/)
+    # but NOT @scope/package style from npm — those don't contain our alias prefix
+    if import_path.startswith("./") or import_path.startswith("../"):
+        return False
+    if import_path.startswith("@/"):
+        return False
+    return True  # Everything else is an external package
+
+
+def _resolve_alias(import_path: str, alias_map: dict[str, str]) -> str | None:
+    """
+    Convert an aliased import path to a repo-relative path.
+    Example: "@/components/Button" → "frontend/components/Button"
+    """
+    for alias, real_prefix in alias_map.items():
+        if import_path.startswith(alias):
+            suffix = import_path[len(alias):].lstrip("/")
+            prefix = real_prefix.rstrip("/")
+            if prefix:
+                return prefix + "/" + suffix
+            else:
+                # alias maps directly to the repo root — no leading slash
+                return suffix
+    return None
+
+
+def _resolve_relative(import_path: str, source_file: str) -> str:
+    """
+    Resolve a relative import path against the source file's directory.
+    Example: source="frontend/app/page.tsx", import="../lib/api" → "frontend/lib/api"
+    """
+    source_dir = Path(source_file).parent
+    resolved = (source_dir / import_path).resolve()
+    # Make it relative again (we'll strip the absolute prefix below)
+    return str(resolved)
+
+
+def _find_file_in_repo(
+    candidate: str,
+    file_index: dict[str, str],
+    root: str,
+) -> str | None:
+    """
+    Given a candidate path (without extension), find the matching file
+    in the repository. Tries adding common extensions if missing.
+    
+    file_index maps absolute_path → relative_path.
+    """
+    root_path = Path(root)
+    candidate_path = Path(candidate)
+
+    # If candidate is absolute, make it relative to root
+    if candidate_path.is_absolute():
+        try:
+            candidate_path = candidate_path.relative_to(root_path)
+        except ValueError:
+            return None
+
+    candidate_str = str(candidate_path)
+
+    # Try exact match first (already has extension)
+    if candidate_str in file_index:
+        return candidate_str
+
+    # Try adding each supported extension
+    for ext in [".tsx", ".ts", ".jsx", ".js"]:
+        with_ext = candidate_str + ext
+        if with_ext in file_index:
+            return with_ext
+
+    # Try as a directory index file (e.g. components/Button/index.tsx)
+    for ext in [".tsx", ".ts", ".jsx", ".js"]:
+        index_path = candidate_str + "/index" + ext
+        if index_path in file_index:
+            return index_path
+
+    return None
+
+
+def _detect_alias_map(scan_result: ScanResult) -> dict[str, str]:
+    """
+    Auto-detect the @/ alias by finding tsconfig.json or next.config files
+    and inferring the project root. Falls back to a heuristic.
+    
+    Returns a map like {"@/": "frontend/"} or {"@/": ""}
+    """
+    root = Path(scan_result.root)
+
+    # Look for tsconfig.json to find paths config
+    for tsconfig in root.rglob("tsconfig.json"):
+        try:
+            import json
+            data = json.loads(tsconfig.read_text())
+            paths = data.get("compilerOptions", {}).get("paths", {})
+            base_url = data.get("compilerOptions", {}).get("baseUrl", ".")
+
+            alias_map = {}
+            for alias, targets in paths.items():
+                if not targets:
+                    continue
+                # "@/*": ["./src/*"] → strip trailing /* from both
+                clean_alias = alias.rstrip("/*").rstrip("*")
+                clean_target = targets[0].rstrip("/*").rstrip("*").lstrip("./")
+
+                tsconfig_dir = tsconfig.parent.relative_to(root)
+                prefix = str(tsconfig_dir / clean_target).lstrip("./")
+                alias_map[clean_alias + "/"] = prefix + "/" if prefix else ""
+
+            if alias_map:
+                return alias_map
+        except Exception:
+            continue
+
+    # Heuristic fallback: if all files share a common top-level dir, use that
+    top_dirs = {Path(f.path).parts[0] for f in scan_result.files if Path(f.path).parts}
+    if len(top_dirs) == 1:
+        top = list(top_dirs)[0]
+        return {"@/": top + "/"}
+
+    return {"@/": ""}
+
+
+def parse_imports(scan_result: ScanResult) -> ParseResult:
+    """
+    Parse all import statements from scanned files and resolve them
+    to concrete file paths within the repository.
+
+    Args:
+        scan_result: Output from scan_repo().
+
+    Returns:
+        ParseResult containing all resolved ImportRelationships.
+    """
+    result = ParseResult()
+
+    # Build lookup: relative_path → ScannedFile
+    file_index: dict[str, ScannedFile] = {f.path: f for f in scan_result.files}
+
+    # Auto-detect alias map (e.g. @/ → frontend/)
+    alias_map = _detect_alias_map(scan_result)
+
+    for scanned_file in scan_result.files:
+        try:
+            source_code = Path(scanned_file.absolute_path).read_text(encoding="utf-8")
+        except Exception:
+            continue
+
+        raw_imports = _extract_raw_imports(source_code)
+
+        for raw in raw_imports:
+            if _is_external(raw):
+                result.unresolved.append((scanned_file.path, raw))
+                continue
+
+            # Resolve to a candidate path string
+            if raw.startswith("@/"):
+                resolved_alias = _resolve_alias(raw, alias_map)
+                if resolved_alias is None:
+                    result.unresolved.append((scanned_file.path, raw))
+                    continue
+                candidate = resolved_alias
+            else:
+                # Relative import
+                candidate = _resolve_relative(raw, scanned_file.path)
+
+            # Find the actual file in the repo
+            matched = _find_file_in_repo(candidate, file_index, scan_result.root)
+
+            if matched:
+                result.relationships.append(
+                    ImportRelationship(
+                        source=scanned_file.path,
+                        target=matched,
+                        raw_import=raw,
+                    )
+                )
+            else:
+                result.unresolved.append((scanned_file.path, raw))
+
+    return result
+
+
+if __name__ == "__main__":
+    import sys
+    from scanner import scan_repo
+
+    target = sys.argv[1] if len(sys.argv) > 1 else "."
+    scan = scan_repo(target)
+    parse = parse_imports(scan)
+
+    print(parse.summary())