contextl-mcp 0.1.2__tar.gz

contextl_mcp-0.1.2/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,125 @@
+# 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/prune_mcp/__init__.py

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

contextl_mcp-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()

contextl_mcp-0.1.2/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "contextl-mcp"
+version = "0.1.2"
+description = "Repository Intelligence Engine — MCP server for AI coding agents"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "dev7shah" }]
+keywords = [
+  "mcp",
+  "model-context-protocol",
+  "ai",
+  "code-search",
+  "context",
+  "cursor",
+  "windsurf",
+  "claude",
+  "vscode",
+  "typescript",
+  "nextjs",
+  "repository",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries",
+  "Topic :: Utilities",
+]
+requires-python = ">=3.9"
+dependencies = ["networkx", "mcp"]
+
+[project.urls]
+Homepage = "https://github.com/dev7shah/prune"
+Issues = "https://github.com/dev7shah/prune/issues"
+
+[project.scripts]
+contextl = "prune_mcp.__main__:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["prune_mcp", "python"]

contextl_mcp-0.1.2/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()