scope-mcp 0.1.0__py3-none-any.whl

scope/__main__.py

@@ -0,0 +1,17 @@
+import asyncio
+import sys
+
+
+def main_cli():
+    from .server import run
+    project_path = "."
+    args = sys.argv[1:]
+    if "--project" in args:
+        i = args.index("--project")
+        if i + 1 < len(args):
+            project_path = args[i + 1]
+    asyncio.run(run(project_path))
+
+
+if __name__ == "__main__":
+    main_cli()

scope/lsp_client.py

@@ -0,0 +1,168 @@
+import asyncio
+import json
+import pathlib
+import shutil
+from typing import Any
+
+
+class LSPError(Exception):
+    pass
+
+
+class LSPClient:
+    def __init__(self, binary: str, args: list[str], root_path: str):
+        self._binary = binary
+        self._args = args
+        self._root = pathlib.Path(root_path)
+        self._proc: asyncio.subprocess.Process | None = None
+        self._pending: dict[int, asyncio.Future] = {}
+        self._seq = 0
+        self.capabilities: dict = {}
+        # path -> content hash; tracks what the LSP has open
+        self._open_files: dict[str, str] = {}
+        self._diagnostics: dict[str, list] = {}
+        self._diag_events: dict[str, asyncio.Event] = {}
+
+    @staticmethod
+    def available(binary: str) -> bool:
+        return shutil.which(binary) is not None
+
+    async def start(self) -> None:
+        self._proc = await asyncio.create_subprocess_exec(
+            self._binary, *self._args,
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.DEVNULL,
+        )
+        asyncio.create_task(self._read_loop())
+
+        root_uri = self._root.as_uri()
+        result = await self.request("initialize", {
+            "processId": None,
+            "rootUri": root_uri,
+            "workspaceFolders": [{"uri": root_uri, "name": self._root.name}],
+            "capabilities": {
+                "textDocument": {
+                    "hover": {"contentFormat": ["plaintext", "markdown"]},
+                    "references": {},
+                    "documentSymbol": {"hierarchicalDocumentSymbolSupport": True},
+                    "callHierarchy": {},
+                    "typeHierarchy": {},
+                    "implementation": {},
+                },
+                "workspace": {"symbol": {}},
+            },
+        })
+        self.capabilities = result.get("capabilities", {}) if result else {}
+        await self.notify("initialized", {})
+
+    async def request(self, method: str, params: Any, timeout: float = 30.0) -> Any:
+        self._seq += 1
+        msg_id = self._seq
+        loop = asyncio.get_event_loop()
+        fut: asyncio.Future = loop.create_future()
+        self._pending[msg_id] = fut
+        await self._send({"jsonrpc": "2.0", "id": msg_id, "method": method, "params": params})
+        try:
+            return await asyncio.wait_for(fut, timeout=timeout)
+        except TimeoutError:
+            self._pending.pop(msg_id, None)
+            raise LSPError(f"LSP timeout: {method}")
+
+    async def notify(self, method: str, params: Any) -> None:
+        await self._send({"jsonrpc": "2.0", "method": method, "params": params})
+
+    async def ensure_open(self, file_path: str, language_id: str) -> None:
+        """Open or refresh a file in the LSP, sending didChange only if content changed."""
+        path = pathlib.Path(file_path)
+        if not path.exists():
+            return
+        text = path.read_text(encoding="utf-8", errors="replace")
+        content_hash = str(hash(text))
+        uri = path.as_uri()
+
+        if file_path in self._open_files:
+            if self._open_files[file_path] == content_hash:
+                return
+            await self.notify("textDocument/didChange", {
+                "textDocument": {"uri": uri, "version": 2},
+                "contentChanges": [{"text": text}],
+            })
+        else:
+            await self.notify("textDocument/didOpen", {
+                "textDocument": {"uri": uri, "languageId": language_id, "version": 1, "text": text},
+            })
+        self._open_files[file_path] = content_hash
+
+    async def get_diagnostics(self, file_path: str, timeout: float = 5.0) -> list:
+        uri = pathlib.Path(file_path).as_uri()
+        if uri not in self._diag_events:
+            self._diag_events[uri] = asyncio.Event()
+        ev = self._diag_events[uri]
+        if not ev.is_set():
+            try:
+                await asyncio.wait_for(ev.wait(), timeout=timeout)
+            except asyncio.TimeoutError:
+                pass
+        return self._diagnostics.get(uri, [])
+
+    async def shutdown(self) -> None:
+        try:
+            await self.request("shutdown", None, timeout=5)
+            await self.notify("exit", None)
+        except Exception:
+            pass
+        if self._proc:
+            self._proc.terminate()
+            try:
+                await asyncio.wait_for(self._proc.wait(), timeout=3)
+            except Exception:
+                self._proc.kill()
+
+    async def _send(self, msg: dict) -> None:
+        if not self._proc or self._proc.stdin.is_closing():
+            raise LSPError("LSP process not running")
+        data = json.dumps(msg).encode()
+        header = f"Content-Length: {len(data)}\r\n\r\n".encode()
+        self._proc.stdin.write(header + data)
+        await self._proc.stdin.drain()
+
+    async def _read_loop(self) -> None:
+        while self._proc and not self._proc.stdout.at_eof():
+            try:
+                content_length = None
+                while True:
+                    line = await self._proc.stdout.readline()
+                    if not line or line == b"\r\n":
+                        break
+                    if line.lower().startswith(b"content-length:"):
+                        content_length = int(line.split(b":")[1].strip())
+
+                if content_length is None:
+                    continue
+
+                body = await self._proc.stdout.readexactly(content_length)
+                msg = json.loads(body)
+
+                msg_id = msg.get("id")
+                if msg_id is not None and msg_id in self._pending:
+                    fut = self._pending.pop(msg_id)
+                    if not fut.done():
+                        if "error" in msg:
+                            fut.set_exception(LSPError(msg["error"].get("message", "LSP error")))
+                        else:
+                            fut.set_result(msg.get("result"))
+                elif msg.get("method") == "textDocument/publishDiagnostics":
+                    params = msg.get("params", {})
+                    uri = params.get("uri", "")
+                    self._diagnostics[uri] = params.get("diagnostics", [])
+                    ev = self._diag_events.get(uri)
+                    if ev:
+                        ev.set()
+            except Exception:
+                break
+
+        for fut in self._pending.values():
+            if not fut.done():
+                fut.set_exception(LSPError("LSP process disconnected"))
+        self._pending.clear()

scope/lsp_registry.py

@@ -0,0 +1,58 @@
+LSP_REGISTRY = {
+    "typescript": {
+        "binary": "typescript-language-server",
+        "args": ["--stdio"],
+        "install": "npm install -g typescript-language-server typescript",
+        "root_markers": ["tsconfig.json", "package.json"],
+        "extensions": {".ts", ".tsx", ".js", ".jsx"},
+        "language_ids": {".ts": "typescript", ".tsx": "typescriptreact", ".js": "javascript", ".jsx": "javascriptreact"},
+    },
+    "python": {
+        "binary": "pyright-langserver",
+        "args": ["--stdio"],
+        "install": "pip install pyright",
+        "root_markers": ["pyproject.toml", "setup.py", "requirements.txt"],
+        "extensions": {".py", ".pyi"},
+        "language_ids": {".py": "python", ".pyi": "python"},
+    },
+    "rust": {
+        "binary": "rust-analyzer",
+        "args": [],
+        "install": "rustup component add rust-analyzer",
+        "root_markers": ["Cargo.toml"],
+        "extensions": {".rs"},
+        "language_ids": {".rs": "rust"},
+    },
+    "go": {
+        "binary": "gopls",
+        "args": [],
+        "install": "go install golang.org/x/tools/gopls@latest",
+        "root_markers": ["go.mod"],
+        "extensions": {".go"},
+        "language_ids": {".go": "go"},
+    },
+    "c_cpp": {
+        "binary": "clangd",
+        "args": [],
+        "install": "apt install clangd  # or: brew install llvm",
+        "root_markers": ["CMakeLists.txt", "compile_commands.json"],
+        "extensions": {".c", ".cpp", ".h", ".hpp", ".cc", ".cxx"},
+        "language_ids": {".c": "c", ".cpp": "cpp", ".h": "c", ".hpp": "cpp", ".cc": "cpp", ".cxx": "cpp"},
+    },
+}
+
+SYMBOL_KINDS = {
+    1: "file", 2: "module", 3: "namespace", 4: "package", 5: "class",
+    6: "method", 7: "property", 8: "field", 9: "constructor", 10: "enum",
+    11: "interface", 12: "function", 13: "variable", 14: "constant",
+    15: "string", 16: "number", 17: "boolean", 18: "array", 19: "object",
+    20: "key", 21: "null", 22: "enum_member", 23: "struct", 24: "event",
+    25: "operator", 26: "type_parameter",
+}
+
+KIND_TO_LSP = {
+    "file": 1, "module": 2, "namespace": 3, "package": 4, "class": 5,
+    "method": 6, "property": 7, "field": 8, "constructor": 9, "enum": 10,
+    "interface": 11, "function": 12, "variable": 13, "constant": 14,
+    "struct": 23, "type": 26,
+}

scope/project.py

@@ -0,0 +1,134 @@
+import asyncio
+import pathlib
+import sys
+from typing import Optional
+
+from .lsp_client import LSPClient
+from .lsp_registry import LSP_REGISTRY
+
+# Package managers we'll auto-install for; others need manual setup (e.g. apt)
+_AUTO_INSTALL_PREFIXES = ("pip ", "npm ", "rustup ", "go ")
+
+
+def detect_root(start: str) -> pathlib.Path:
+    path = pathlib.Path(start).resolve()
+    all_markers = {m for cfg in LSP_REGISTRY.values() for m in cfg["root_markers"]}
+    all_markers.add(".git")
+    for candidate in [path, *path.parents]:
+        if any((candidate / m).exists() for m in all_markers):
+            return candidate
+    return path
+
+
+def detect_languages(root: pathlib.Path) -> list[str]:
+    langs = [
+        lang for lang, cfg in LSP_REGISTRY.items()
+        if any((root / m).exists() for m in cfg["root_markers"])
+    ]
+    return langs or ["python"]
+
+
+class ProjectManager:
+    def __init__(self, project_path: str):
+        self.root = detect_root(project_path)
+        self.languages = detect_languages(self.root)
+        self._lsps: dict[str, LSPClient] = {}
+        self._install_locks: dict[str, asyncio.Lock] = {}
+
+    async def _try_install(self, lang: str, install_cmd: str) -> bool:
+        """Run the install command for a language server. Returns True if binary is now available."""
+        if not any(install_cmd.startswith(p) for p in _AUTO_INSTALL_PREFIXES):
+            print(f"[scope] Cannot auto-install {lang}. Run manually: {install_cmd}", file=sys.stderr)
+            return False
+
+        parts = install_cmd.split()
+        # Use current Python for pip installs so the binary lands in the right place
+        if parts[0] == "pip":
+            parts = [sys.executable, "-m", "pip"] + parts[1:]
+
+        print(f"[scope] Auto-installing {lang} LSP: {' '.join(parts)}", file=sys.stderr, flush=True)
+        try:
+            proc = await asyncio.create_subprocess_exec(
+                *parts,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+            _, stderr = await asyncio.wait_for(proc.communicate(), timeout=120)
+            if proc.returncode != 0:
+                print(f"[scope] Install failed: {stderr.decode(errors='replace').strip()}", file=sys.stderr)
+                return False
+        except asyncio.TimeoutError:
+            print(f"[scope] Install timed out for {lang}", file=sys.stderr)
+            return False
+        except FileNotFoundError:
+            print(f"[scope] Install command not found: {parts[0]}", file=sys.stderr)
+            return False
+
+        cfg = LSP_REGISTRY[lang]
+        ok = LSPClient.available(cfg["binary"])
+        if ok:
+            print(f"[scope] {lang} LSP installed successfully", file=sys.stderr, flush=True)
+        else:
+            print(f"[scope] Install ran but binary '{cfg['binary']}' still not found (PATH issue?)", file=sys.stderr)
+        return ok
+
+    async def get_lsp(self, lang: str) -> Optional[LSPClient]:
+        if lang not in self.languages:
+            return None
+        cfg = LSP_REGISTRY.get(lang)
+        if not cfg:
+            return None
+        if not LSPClient.available(cfg["binary"]):
+            # Serialize installs per language to avoid double-installing
+            if lang not in self._install_locks:
+                self._install_locks[lang] = asyncio.Lock()
+            async with self._install_locks[lang]:
+                if not LSPClient.available(cfg["binary"]):
+                    if not await self._try_install(lang, cfg["install"]):
+                        return None
+        if lang not in self._lsps:
+            client = LSPClient(cfg["binary"], cfg["args"], str(self.root))
+            await client.start()
+            self._lsps[lang] = client
+        return self._lsps[lang]
+
+    def lang_for_file(self, file_path: str) -> Optional[str]:
+        ext = pathlib.Path(file_path).suffix.lower()
+        for lang, cfg in LSP_REGISTRY.items():
+            if ext in cfg["extensions"]:
+                return lang
+        return None
+
+    def lang_id_for_file(self, file_path: str) -> str:
+        ext = pathlib.Path(file_path).suffix.lower()
+        lang = self.lang_for_file(file_path)
+        if lang:
+            return LSP_REGISTRY[lang]["language_ids"].get(ext, lang)
+        return "plaintext"
+
+    async def get_lsp_for_file(self, file_path: str) -> tuple[Optional[LSPClient], Optional[str]]:
+        lang = self.lang_for_file(file_path)
+        if not lang:
+            return None, None
+        return await self.get_lsp(lang), lang
+
+    async def get_all_lsps(self) -> dict[str, LSPClient]:
+        result = {}
+        for lang in self.languages:
+            lsp = await self.get_lsp(lang)
+            if lsp:
+                result[lang] = lsp
+        return result
+
+    def missing_lsps(self) -> list[str]:
+        missing = []
+        for lang in self.languages:
+            cfg = LSP_REGISTRY.get(lang, {})
+            if not LSPClient.available(cfg.get("binary", "")):
+                missing.append(f"{lang}: install with `{cfg.get('install', '?')}`")
+        return missing
+
+    async def shutdown(self) -> None:
+        for lsp in self._lsps.values():
+            await lsp.shutdown()
+        self._lsps.clear()

scope/server.py

@@ -0,0 +1,683 @@
+import asyncio
+import json
+import pathlib
+import urllib.parse
+from typing import Optional
+
+from mcp.server.fastmcp import FastMCP
+
+from .lsp_client import LSPClient, LSPError
+from .lsp_registry import LSP_REGISTRY, SYMBOL_KINDS, KIND_TO_LSP
+from .project import ProjectManager
+
+_mcp = FastMCP("scope")
+_project: Optional[ProjectManager] = None
+
+
+def _proj() -> ProjectManager:
+    assert _project is not None, "Project not initialized"
+    return _project
+
+
+def _uri_to_path(uri: str) -> str:
+    path = urllib.parse.unquote(urllib.parse.urlparse(uri).path)
+    # Windows: /D:/path -> D:/path
+    if len(path) > 2 and path[0] == "/" and path[2] == ":":
+        path = path[1:]
+    return path
+
+
+def _extract_hover_text(contents) -> str:
+    if isinstance(contents, str):
+        return contents
+    if isinstance(contents, dict):
+        return contents.get("value", "")
+    if isinstance(contents, list):
+        parts = []
+        for c in contents:
+            parts.append(c.get("value", c) if isinstance(c, dict) else str(c))
+        return "\n".join(parts)
+    return str(contents)
+
+
+def _flatten_doc_symbols(symbols: list, depth: int = 0) -> list[dict]:
+    """Recursively flatten hierarchical DocumentSymbol results."""
+    result = []
+    for sym in symbols:
+        if not isinstance(sym, dict):
+            continue
+        entry = {
+            "name": sym.get("name"),
+            "kind": SYMBOL_KINDS.get(sym.get("kind", 0), "unknown"),
+            "line": sym.get("selectionRange", sym.get("range", {})).get("start", {}).get("line", 0) + 1,
+        }
+        if depth > 0:
+            entry["depth"] = depth
+        result.append(entry)
+        children = sym.get("children", [])
+        if children:
+            result.extend(_flatten_doc_symbols(children, depth + 1))
+    return result
+
+
+async def _locate_symbol(
+    project: ProjectManager,
+    name: str,
+    file_hint: str = "",
+    line_hint: int = 0,
+    kinds: set | None = None,
+) -> Optional[tuple[LSPClient, str, str, int, int]]:
+    """Find a symbol by name. Returns (lsp, uri, file_path, line_0indexed, col) or None."""
+    lsps = await project.get_all_lsps()
+    candidates = []
+
+    for lang, lsp in lsps.items():
+        try:
+            symbols = await lsp.request("workspace/symbol", {"query": name}) or []
+            for sym in symbols:
+                if sym.get("name") != name:
+                    continue
+                if kinds and sym.get("kind") not in kinds:
+                    continue
+                loc = sym.get("location", {})
+                uri = loc.get("uri", "")
+                sym_file = _uri_to_path(uri)
+                sym_line = loc.get("range", {}).get("start", {}).get("line", 0)
+                sym_col = loc.get("range", {}).get("start", {}).get("character", 0)
+                candidates.append((lsp, uri, sym_file, sym_line, sym_col))
+        except LSPError:
+            pass
+
+    if not candidates:
+        return None
+    if file_hint:
+        for c in candidates:
+            if file_hint in c[2]:
+                return c
+    if line_hint:
+        for c in candidates:
+            if abs(c[3] - (line_hint - 1)) < 5:
+                return c
+    return candidates[0]
+
+
+# ── Tools ──────────────────────────────────────────────────────────────────
+
+
+@_mcp.tool()
+async def find_symbol(name: str, kind: str = "", file: str = "") -> str:
+    """Find a symbol by name across the project using the language server.
+
+    name: symbol name (partial match supported)
+    kind: filter by kind — function|class|interface|method|variable|constant|struct|enum|module
+    file: filter by file path (partial match)
+    Returns up to 50 results with file, line, kind.
+    """
+    project = _proj()
+    lsps = await project.get_all_lsps()
+
+    if not lsps:
+        missing = project.missing_lsps()
+        return json.dumps({"error": "No LSP servers running", "install": missing, "results": []})
+
+    results = []
+    seen: set[tuple] = set()
+    kind_filter = KIND_TO_LSP.get(kind, -1) if kind else -1
+
+    for lang, lsp in lsps.items():
+        try:
+            symbols = await lsp.request("workspace/symbol", {"query": name}) or []
+            for sym in symbols:
+                sym_name = sym.get("name", "")
+                if name.lower() not in sym_name.lower():
+                    continue
+                sym_kind_num = sym.get("kind", 0)
+                if kind_filter != -1 and sym_kind_num != kind_filter:
+                    continue
+                loc = sym.get("location", {})
+                uri = loc.get("uri", "")
+                if file and file not in uri:
+                    continue
+                key = (sym_name, uri, loc.get("range", {}).get("start", {}).get("line", 0))
+                if key in seen:
+                    continue
+                seen.add(key)
+                results.append({
+                    "name": sym_name,
+                    "kind": SYMBOL_KINDS.get(sym_kind_num, "unknown"),
+                    "file": _uri_to_path(uri),
+                    "line": loc.get("range", {}).get("start", {}).get("line", 0) + 1,
+                    "column": loc.get("range", {}).get("start", {}).get("character", 0),
+                    "container": sym.get("containerName") or None,
+                })
+        except LSPError:
+            pass
+
+    return json.dumps({"count": len(results), "results": results[:50]})
+
+
+@_mcp.tool()
+async def find_references(symbol_name: str, file_path: str = "", line: int = 0) -> str:
+    """Find all references to a symbol across the project.
+
+    symbol_name: exact symbol name
+    file_path: hint to disambiguate if multiple symbols share the name
+    line: line number hint (1-indexed) for further disambiguation
+    Returns file, line, column, and the source line for each reference.
+    """
+    project = _proj()
+    found = await _locate_symbol(project, symbol_name, file_hint=file_path, line_hint=line)
+
+    if not found:
+        return json.dumps({"error": f"Symbol '{symbol_name}' not found", "results": []})
+
+    lsp, uri, sym_file, sym_line, sym_col = found
+    lang_id = project.lang_id_for_file(sym_file)
+    await lsp.ensure_open(sym_file, lang_id)
+
+    try:
+        refs = await lsp.request("textDocument/references", {
+            "textDocument": {"uri": uri},
+            "position": {"line": sym_line, "character": sym_col},
+            "context": {"includeDeclaration": False},
+        }) or []
+    except LSPError as e:
+        return json.dumps({"error": str(e), "results": []})
+
+    results = []
+    for ref in refs:
+        ref_path = _uri_to_path(ref["uri"])
+        ref_line = ref["range"]["start"]["line"] + 1
+        try:
+            lines = pathlib.Path(ref_path).read_text(errors="replace").splitlines()
+            context = lines[ref_line - 1].strip() if ref_line <= len(lines) else ""
+        except Exception:
+            context = ""
+        results.append({
+            "file": ref_path,
+            "line": ref_line,
+            "column": ref["range"]["start"]["character"],
+            "context": context,
+        })
+
+    return json.dumps({"symbol": symbol_name, "count": len(results), "results": results[:100]})
+
+
+@_mcp.tool()
+async def hover(file_path: str, line: int, column: int = 0) -> str:
+    """Get type info and documentation for a symbol at a specific position.
+
+    file_path: absolute or project-relative file path
+    line: line number (1-indexed)
+    column: column number (0-indexed, default 0)
+    """
+    project = _proj()
+    if not pathlib.Path(file_path).is_absolute():
+        file_path = str(project.root / file_path)
+
+    lsp, _ = await project.get_lsp_for_file(file_path)
+    if not lsp:
+        return json.dumps({"error": f"No LSP available for: {file_path}"})
+
+    lang_id = project.lang_id_for_file(file_path)
+    await lsp.ensure_open(file_path, lang_id)
+
+    try:
+        result = await lsp.request("textDocument/hover", {
+            "textDocument": {"uri": pathlib.Path(file_path).as_uri()},
+            "position": {"line": line - 1, "character": column},
+        })
+    except LSPError as e:
+        return json.dumps({"error": str(e)})
+
+    if not result:
+        return json.dumps({"error": "No hover information at this position"})
+
+    return json.dumps({
+        "file": file_path,
+        "line": line,
+        "column": column,
+        "info": _extract_hover_text(result.get("contents", "")),
+    })
+
+
+@_mcp.tool()
+async def go_to_definition(file_path: str, line: int, column: int = 0) -> str:
+    """Find the definition of a symbol at a specific position.
+
+    file_path: absolute or project-relative file path
+    line: line number (1-indexed)
+    column: column number (0-indexed)
+    Returns definition location(s) with file and line.
+    """
+    project = _proj()
+    if not pathlib.Path(file_path).is_absolute():
+        file_path = str(project.root / file_path)
+
+    lsp, _ = await project.get_lsp_for_file(file_path)
+    if not lsp:
+        return json.dumps({"error": f"No LSP available for: {file_path}"})
+
+    lang_id = project.lang_id_for_file(file_path)
+    await lsp.ensure_open(file_path, lang_id)
+
+    try:
+        result = await lsp.request("textDocument/definition", {
+            "textDocument": {"uri": pathlib.Path(file_path).as_uri()},
+            "position": {"line": line - 1, "character": column},
+        })
+    except LSPError as e:
+        return json.dumps({"error": str(e)})
+
+    if not result:
+        return json.dumps({"error": "No definition found"})
+
+    if isinstance(result, dict):
+        result = [result]
+
+    locations = []
+    for loc in result:
+        uri = loc.get("uri") or loc.get("targetUri", "")
+        r = loc.get("range") or loc.get("targetSelectionRange") or loc.get("targetRange", {})
+        locations.append({
+            "file": _uri_to_path(uri),
+            "line": r.get("start", {}).get("line", 0) + 1,
+            "column": r.get("start", {}).get("character", 0),
+        })
+
+    return json.dumps({"count": len(locations), "results": locations})
+
+
+@_mcp.tool()
+async def explain_file(file_path: str, detail: str = "summary") -> str:
+    """Summarize a file's structure: exports, top-level symbols, language, line count.
+
+    file_path: absolute or project-relative file path
+    detail: 'summary' (top-level only) or 'full' (all nested symbols)
+    """
+    project = _proj()
+    if not pathlib.Path(file_path).is_absolute():
+        file_path = str(project.root / file_path)
+
+    path = pathlib.Path(file_path)
+    if not path.exists():
+        return json.dumps({"error": f"File not found: {file_path}"})
+
+    lang_id = project.lang_id_for_file(file_path)
+    lines = path.read_text(errors="replace").splitlines()
+    result: dict = {"file": file_path, "language": lang_id, "loc": len(lines)}
+
+    lsp, _ = await project.get_lsp_for_file(file_path)
+    if lsp:
+        await lsp.ensure_open(file_path, lang_id)
+        try:
+            symbols = await lsp.request("textDocument/documentSymbol", {
+                "textDocument": {"uri": path.as_uri()},
+            }) or []
+            flat = _flatten_doc_symbols(symbols)
+            result["symbols"] = flat if detail == "full" else [s for s in flat if s.get("depth", 0) == 0]
+        except LSPError:
+            result["symbols"] = []
+    else:
+        result["note"] = "LSP unavailable — no symbol info"
+
+    return json.dumps(result)
+
+
+@_mcp.tool()
+async def call_hierarchy(symbol_name: str, direction: str = "incoming", depth: int = 2) -> str:
+    """Show who calls (incoming) or is called by (outgoing) a function.
+
+    symbol_name: exact function/method name
+    direction: 'incoming' | 'outgoing' | 'both'
+    depth: recursion depth (max 3 recommended)
+    """
+    project = _proj()
+    # Restrict to callable kinds: method, constructor, function
+    found = await _locate_symbol(project, symbol_name, kinds={6, 9, 12})
+
+    if not found:
+        # Retry without kind filter — some LSPs categorize differently
+        found = await _locate_symbol(project, symbol_name)
+    if not found:
+        return json.dumps({"error": f"Symbol '{symbol_name}' not found"})
+
+    lsp, uri, sym_file, sym_line, sym_col = found
+    lang_id = project.lang_id_for_file(sym_file)
+    await lsp.ensure_open(sym_file, lang_id)
+
+    try:
+        items = await lsp.request("textDocument/prepareCallHierarchy", {
+            "textDocument": {"uri": uri},
+            "position": {"line": sym_line, "character": sym_col},
+        }) or []
+    except LSPError as e:
+        return json.dumps({"error": f"Call hierarchy not supported by LSP: {e}"})
+
+    if not items:
+        return json.dumps({"error": f"No call hierarchy item found for '{symbol_name}'"})
+
+    item = items[0]
+    depth = min(depth, 3)  # ponytail: cap depth to avoid runaway recursion
+
+    async def incoming(it, d):
+        if d == 0:
+            return []
+        try:
+            calls = await lsp.request("callHierarchy/incomingCalls", {"item": it}) or []
+        except LSPError:
+            return []
+        result = []
+        for call in calls:
+            caller = call["from"]
+            result.append({
+                "name": caller["name"],
+                "file": _uri_to_path(caller["uri"]),
+                "line": caller["range"]["start"]["line"] + 1,
+                "callers": await incoming(caller, d - 1),
+            })
+        return result
+
+    async def outgoing(it, d):
+        if d == 0:
+            return []
+        try:
+            calls = await lsp.request("callHierarchy/outgoingCalls", {"item": it}) or []
+        except LSPError:
+            return []
+        result = []
+        for call in calls:
+            callee = call["to"]
+            result.append({
+                "name": callee["name"],
+                "file": _uri_to_path(callee["uri"]),
+                "line": callee["range"]["start"]["line"] + 1,
+                "calls": await outgoing(callee, d - 1),
+            })
+        return result
+
+    out: dict = {"symbol": symbol_name}
+    if direction in ("incoming", "both"):
+        out["incoming"] = await incoming(item, depth)
+    if direction in ("outgoing", "both"):
+        out["outgoing"] = await outgoing(item, depth)
+    return json.dumps(out)
+
+
+@_mcp.tool()
+async def type_hierarchy(symbol_name: str, direction: str = "both") -> str:
+    """Show the type hierarchy (supertypes / subtypes) for a class or interface.
+
+    symbol_name: exact class/interface/enum name
+    direction: 'supertypes' | 'subtypes' | 'both'
+    """
+    project = _proj()
+    found = await _locate_symbol(project, symbol_name, kinds={5, 10, 11})  # class, enum, interface
+
+    if not found:
+        found = await _locate_symbol(project, symbol_name)
+    if not found:
+        return json.dumps({"error": f"Symbol '{symbol_name}' not found"})
+
+    lsp, uri, sym_file, sym_line, sym_col = found
+    lang_id = project.lang_id_for_file(sym_file)
+    await lsp.ensure_open(sym_file, lang_id)
+
+    try:
+        items = await lsp.request("textDocument/prepareTypeHierarchy", {
+            "textDocument": {"uri": uri},
+            "position": {"line": sym_line, "character": sym_col},
+        }) or []
+    except LSPError as e:
+        return json.dumps({"error": f"Type hierarchy not supported: {e}"})
+
+    if not items:
+        return json.dumps({"error": f"No type hierarchy for '{symbol_name}'"})
+
+    item = items[0]
+
+    def _fmt(types_list):
+        return [
+            {"name": t["name"], "file": _uri_to_path(t["uri"]), "line": t["range"]["start"]["line"] + 1}
+            for t in (types_list or [])
+            if isinstance(t, dict)
+        ]
+
+    out: dict = {"symbol": symbol_name}
+    if direction in ("supertypes", "both"):
+        try:
+            out["supertypes"] = _fmt(await lsp.request("typeHierarchy/supertypes", {"item": item}))
+        except LSPError:
+            out["supertypes"] = []
+    if direction in ("subtypes", "both"):
+        try:
+            out["subtypes"] = _fmt(await lsp.request("typeHierarchy/subtypes", {"item": item}))
+        except LSPError:
+            out["subtypes"] = []
+    return json.dumps(out)
+
+
+@_mcp.tool()
+async def implementations(symbol_name: str, file: str = "") -> str:
+    """Find all implementations of an interface, abstract class, or protocol.
+
+    symbol_name: exact interface/abstract class name
+    file: optional file hint for disambiguation
+    """
+    project = _proj()
+    found = await _locate_symbol(project, symbol_name, file_hint=file)
+
+    if not found:
+        return json.dumps({"error": f"Symbol '{symbol_name}' not found", "results": []})
+
+    lsp, uri, sym_file, sym_line, sym_col = found
+    lang_id = project.lang_id_for_file(sym_file)
+    await lsp.ensure_open(sym_file, lang_id)
+
+    try:
+        impls = await lsp.request("textDocument/implementation", {
+            "textDocument": {"uri": uri},
+            "position": {"line": sym_line, "character": sym_col},
+        }) or []
+    except LSPError as e:
+        return json.dumps({"error": str(e), "results": []})
+
+    if isinstance(impls, dict):
+        impls = [impls]
+
+    results = []
+    for impl in impls:
+        # Handles both Location and LocationLink shapes
+        impl_uri = impl.get("uri") or impl.get("targetUri", "")
+        impl_range = impl.get("range") or impl.get("targetRange") or impl.get("targetSelectionRange", {})
+        results.append({
+            "file": _uri_to_path(impl_uri),
+            "line": impl_range.get("start", {}).get("line", 0) + 1,
+        })
+
+    return json.dumps({"symbol": symbol_name, "count": len(results), "results": results})
+
+
+@_mcp.tool()
+async def get_diagnostics(file_path: str) -> str:
+    """Get language-server diagnostics (errors, warnings) for a file.
+
+    file_path: absolute or project-relative file path
+    Opens the file in the LSP and waits up to 5 s for diagnostics to arrive.
+    Returns a list with severity, message, and location for each diagnostic.
+    """
+    project = _proj()
+    if not pathlib.Path(file_path).is_absolute():
+        file_path = str(project.root / file_path)
+
+    if not pathlib.Path(file_path).exists():
+        return json.dumps({"error": f"File not found: {file_path}"})
+
+    lsp, _ = await project.get_lsp_for_file(file_path)
+    if not lsp:
+        return json.dumps({"error": f"No LSP available for: {file_path}"})
+
+    lang_id = project.lang_id_for_file(file_path)
+    await lsp.ensure_open(file_path, lang_id)
+    raw = await lsp.get_diagnostics(file_path)
+
+    SEVERITY = {1: "error", 2: "warning", 3: "information", 4: "hint"}
+    results = [
+        {
+            "severity": SEVERITY.get(d.get("severity", 1), "error"),
+            "message": d.get("message", ""),
+            "line": d.get("range", {}).get("start", {}).get("line", 0) + 1,
+            "column": d.get("range", {}).get("start", {}).get("character", 0),
+            "code": d.get("code"),
+            "source": d.get("source"),
+        }
+        for d in raw
+    ]
+    return json.dumps({"file": file_path, "count": len(results), "diagnostics": results})
+
+
+@_mcp.tool()
+async def search_pattern(pattern: str, scope: str = "", file_glob: str = "") -> str:
+    """Search for a regex or literal pattern in files using ripgrep.
+
+    pattern: regex or literal string to search for
+    scope: directory to search in (defaults to project root)
+    file_glob: file filter e.g. '*.py' or '**/*.ts'
+    Returns up to 200 matches with file, line, and context.
+    """
+    project = _proj()
+    search_path = scope if scope else str(project.root)
+
+    cmd = ["rg", "--json", "-e", pattern]
+    if file_glob:
+        cmd += ["-g", file_glob]
+    cmd.append(search_path)
+
+    try:
+        proc = await asyncio.create_subprocess_exec(
+            *cmd,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.DEVNULL,
+        )
+        stdout, _ = await asyncio.wait_for(proc.communicate(), timeout=15)
+    except FileNotFoundError:
+        return json.dumps({"error": "ripgrep (rg) not found — install from https://github.com/BurntSushi/ripgrep"})
+    except TimeoutError:
+        return json.dumps({"error": "Search timed out"})
+
+    results = []
+    for raw_line in stdout.decode(errors="replace").splitlines():
+        try:
+            obj = json.loads(raw_line)
+            if obj.get("type") != "match":
+                continue
+            data = obj["data"]
+            results.append({
+                "file": data["path"]["text"],
+                "line": data["line_number"],
+                "column": data["submatches"][0]["start"] if data.get("submatches") else 0,
+                "context": data["lines"]["text"].rstrip(),
+            })
+        except Exception:
+            pass
+
+    return json.dumps({"pattern": pattern, "count": len(results), "results": results[:200]})
+
+
+@_mcp.tool()
+async def changed_since(ref: str = "HEAD", include_symbols: bool = False) -> str:
+    """List files changed since a git ref, optionally with their top-level symbols.
+
+    ref: git ref to diff against (default: HEAD = staged changes).
+         Pass "" to get all dirty files (staged + unstaged).
+         Pass "HEAD~1" (or any ref) to compare against a prior commit.
+    include_symbols: if true, also return top-level symbols for each changed file
+    """
+    project = _proj()
+
+    if ref == "":
+        cmd = ["git", "-C", str(project.root), "status", "--porcelain"]
+    else:
+        cmd = ["git", "-C", str(project.root), "diff", "--name-only", ref]
+
+    try:
+        proc = await asyncio.create_subprocess_exec(
+            *cmd,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=10)
+    except FileNotFoundError:
+        return json.dumps({"error": "git not found"})
+    except TimeoutError:
+        return json.dumps({"error": "git command timed out"})
+
+    if proc.returncode != 0:
+        return json.dumps({"error": stderr.decode(errors="replace").strip()})
+
+    if ref == "":
+        files = []
+        for line in stdout.decode().splitlines():
+            if len(line) > 3:
+                fname = line[3:].strip()
+                # Renames: "old -> new" — take the new name
+                if " -> " in fname:
+                    fname = fname.split(" -> ")[-1]
+                files.append(fname)
+    else:
+        files = [f for f in stdout.decode().splitlines() if f]
+
+    result: dict = {"ref": ref or "working-tree", "files_changed": files}
+
+    if include_symbols and files:
+        affected: dict[str, list] = {}
+        for rel_path in files[:20]:  # ponytail: cap at 20 to avoid huge responses
+            full_path = str(project.root / rel_path)
+            lsp, _ = await project.get_lsp_for_file(full_path)
+            if lsp and pathlib.Path(full_path).exists():
+                try:
+                    lang_id = project.lang_id_for_file(full_path)
+                    await lsp.ensure_open(full_path, lang_id)
+                    syms = await lsp.request("textDocument/documentSymbol", {
+                        "textDocument": {"uri": pathlib.Path(full_path).as_uri()},
+                    }) or []
+                    affected[rel_path] = [s.get("name") for s in syms if isinstance(s, dict)]
+                except LSPError:
+                    pass
+        result["symbols_affected"] = affected
+
+    return json.dumps(result)
+
+
+@_mcp.tool()
+async def scope_status() -> str:
+    """Show project info: detected root, languages, LSP status, and any missing installs."""
+    project = _proj()
+    lsps = {}
+    for lang in project.languages:
+        cfg = LSP_REGISTRY.get(lang, {})
+        binary = cfg.get("binary", "")
+        running = lang in project._lsps
+        installed = LSPClient.available(binary)
+        lsps[lang] = {
+            "binary": binary,
+            "installed": installed,
+            "running": running,
+            "install_cmd": cfg.get("install") if not installed else None,
+        }
+    return json.dumps({
+        "project_root": str(project.root),
+        "languages_detected": project.languages,
+        "lsp_status": lsps,
+    })
+
+
+# ── Entry point ─────────────────────────────────────────────────────────────
+
+async def run(project_path: str = ".") -> None:
+    global _project
+    _project = ProjectManager(project_path)
+    try:
+        await _mcp.run_stdio_async()
+    finally:
+        await _project.shutdown()

scope_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: scope-mcp
+Version: 0.1.0
+Summary: Give your AI coding assistant real code understanding — powered by the same engines VS Code uses
+Author: Deviprasad Shetty
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/deviprasadshetty-dev/scope
+Project-URL: Repository, https://github.com/deviprasadshetty-dev/scope.git
+Project-URL: BugTracker, https://github.com/deviprasadshetty-dev/scope/issues
+Keywords: mcp,lsp,ai,code-navigation,claude,coding-assistant
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.0.0
+Dynamic: license-file
+
+# scope-mcp
+
+**A tool that gives your AI coding assistant superpowers.** Instead of guessing what your code does, it gets real answers straight from the same engines VS Code uses — so it actually understands functions, classes, types, and where things connect.
+
+No setup. No indexing. Just works.
+
+## What's the problem?
+
+When you ask an AI to "find where `get_lsp` is called," most tools do a text search — like Ctrl+Shift+F. That returns *everything* named `get_lsp`: the definition, comments, imports, false positives. You have to dig through the noise.
+
+```
+┌─ grep (text search) ─────────────────────┐
+│  project.py:75  def get_lsp(self, lang)   │  ← definition (not a call)
+│  project.py:110 return await get_lsp(lang)│  ← actual call
+│  project.py:117 lsp = await get_lsp(lang) │  ← actual call
+│  project.py:81  cfg = LSP_REGISTRY...     │  ← noise
+│  project.py:109 async def get_lsp_for...  │  ← noise
+│    5 results · 3 are noise                │
+└───────────────────────────────────────────┘
+
+┌─ scope (smart search) ────────────────────┐
+│  [call site] project.py:110               │
+│  [call site] project.py:117               │
+│    2 results · 0 noise                    │
+└───────────────────────────────────────────┘
+```
+
+Scope asks the compiler instead. You get only what you actually asked for.
+
+## What you can do with it
+
+| Instead of digging through files... | Just ask scope... | You get |
+|---|---|---|
+| Grepping for a function name and filtering out junk | `find_references("get_lsp")` | Only the places where it's actually called — no noise |
+| Reading a whole file to figure out what's in it | `explain_file("server.py")` | A clean summary: language, line count, every function and class |
+| Hunting through 50 files to find where an interface is used | `implementations("IEventHandler")` | One answer with all the implementations |
+| Tracing who calls what by hand | `call_hierarchy("validate_token")` | A tree of callers and callees, 3 levels deep |
+| Scanning a big diff to see what changed | `changed_since("HEAD~3")` | Just the changed files and affected symbols |
+
+## How it works
+
+1. **Scope looks at your project** — it spots what languages you're using (Python, TypeScript, Rust, Go, C++) from files like `package.json` or `Cargo.toml`.
+2. **It sets up the brain** — launches the same language engine your editor uses (pyright, tsserver, rust-analyzer, gopls). If missing, it installs one automatically.
+3. **Your AI asks, scope answers** — every question hits that engine live. No stale data, no sync jobs, no waiting.
+
+```
+AI Assistant (Claude, Codex, etc.)  ←→  scope  ←→  Language Engine
+                                              (pyright, tsserver, etc.)
+```
+
+## Setup
+
+```bash
+pip install scope-mcp
+```
+
+Then add one line to your AI client's config:
+
+### Claude Desktop / Code
+
+```json
+{
+  "mcpServers": {
+    "scope": {
+      "command": "scope",
+      "args": ["--project", "."]
+    }
+  }
+}
+```
+
+### Any AI coding tool
+
+```
+command:  scope
+args:     ["--project", "/path/to/your/project"]
+transport: stdio
+```
+
+### From source
+
+```bash
+git clone https://github.com/yourname/scope-mcp
+cd scope-mcp
+pip install -e .
+```
+
+Optional extras: `rg` (ripgrep) for text searches, `git` for change tracking.
+
+## Languages scope understands
+
+| Language | Detected when it sees... | Scope handles setup |
+|---|---|---|
+| Python | `pyproject.toml` · `setup.py` · `requirements.txt` | ✅ Installs pyright automatically |
+| TypeScript / JavaScript | `tsconfig.json` · `package.json` | ✅ Installs tsserver automatically |
+| Rust | `Cargo.toml` | ✅ Installs rust-analyzer automatically |
+| Go | `go.mod` | ✅ Installs gopls automatically |
+| C / C++ | `CMakeLists.txt` · `compile_commands.json` | ⚠️ You install clangd manually |
+
+## Project layout
+
+```
+scope/
+├── __init__.py
+├── __main__.py       # Where scope starts — just runs `scope --project .`
+├── server.py         # All the commands (tools) your AI can call
+├── project.py        # Figures out your project and starts language engines
+├── lsp_client.py     # Talks to language engines behind the scenes
+└── lsp_registry.py   # Knows which engine to use for each language
+```
+
+## Requirements
+
+- Python 3.11 or newer
+- ripgrep (optional, for text search)
+- git (optional, for change tracking)
+
+## License
+
+MIT

scope_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+scope/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+scope/__main__.py,sha256=n57cuNx4zzaLAk9SF5R_MNK4b4rstneP2bJOAsZRlpM,331
+scope/lsp_client.py,sha256=EYxkH-4Zv51R94ZkFe6j4dhb4NZWQtdHIKPr1Pv3C30,6518
+scope/lsp_registry.py,sha256=t6ukiUG0A95aCcy9rgJLnDOkOzG7O4b_QRJuYMN7Edo,2288
+scope/project.py,sha256=1GS1eeT1uyzLuFTdDvHlz-NdOdWZrCBLt5JuD10l75E,5227
+scope/server.py,sha256=f1QJ2ewZgb28gttHbn2yvZfBiayKWamsdS8m2CsU30U,24559
+scope_mcp-0.1.0.dist-info/licenses/LICENSE,sha256=4AfpvF_PqbEc3ks1x77JnpsblR-AcB6Ea7TNlzlVENY,1074
+scope_mcp-0.1.0.dist-info/METADATA,sha256=DBzdIWUMyAUwf7S-4JW-eKWdqCmySHzFXOBIf9XB5oo,5859
+scope_mcp-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+scope_mcp-0.1.0.dist-info/entry_points.txt,sha256=vWgiuSAbQg6PTrtx2x6x6nBKuDRJrMy2h-hv7Dtam-w,50
+scope_mcp-0.1.0.dist-info/top_level.txt,sha256=2CM6KU4wKPVS0iGdr72fQXzMA5Vn0U5FzuzOYCYth_8,6
+scope_mcp-0.1.0.dist-info/RECORD,,

scope_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

scope_mcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+scope = scope.__main__:main_cli

scope_mcp-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Deviprasad Shetty
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

scope_mcp-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+scope