scope-mcp 0.1.0__tar.gz

scope_mcp-0.1.0/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/PKG-INFO

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

@@ -0,0 +1,120 @@
+# 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/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "scope-mcp"
+version = "0.1.0"
+description = "Give your AI coding assistant real code understanding — powered by the same engines VS Code uses"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [
+  { name = "Deviprasad Shetty" },
+]
+keywords = ["mcp", "lsp", "ai", "code-navigation", "claude", "coding-assistant"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development",
+  "Topic :: Software Development :: Code Generators",
+]
+dependencies = ["mcp>=1.0.0"]
+
+[project.urls]
+Homepage = "https://github.com/deviprasadshetty-dev/scope"
+Repository = "https://github.com/deviprasadshetty-dev/scope.git"
+BugTracker = "https://github.com/deviprasadshetty-dev/scope/issues"
+
+[project.scripts]
+scope = "scope.__main__:main_cli"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["scope*"]

scope_mcp-0.1.0/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_mcp-0.1.0/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_mcp-0.1.0/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,
+}