[![PyPI](https://img.shields.io/pypi/v/scope-mcp)](https://pypi.org/project/scope-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/scope-mcp)](https://pypi.org/project/scope-mcp/)

# 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.

[→ See the benchmarks](BENCHMARKS.md) — up to 25x fewer tokens, 0% false positives.

## 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

Choose the path that fits your workflow:

### 🚀 Auto-install (recommended)

If you have [`uv`](https://docs.astral.sh/uv/) installed, `uvx` will auto-install scope on first run — no `pip install` needed.

**Claude Desktop**

**File:** `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows)

```json
{
  "mcpServers": {
    "scope": {
      "command": "uvx",
      "args": ["scope-mcp", "--project", "."]
    }
  }
}
```

**Cursor**

**Settings → Cursor Settings → MCP → Add new MCP server**

```
Name:     scope
Type:     command
Command:  uvx scope-mcp --project .
```

**Windsurf**

**File:** `~/.codeium/windsurf/mcp_config.json`

```json
{
  "mcpServers": {
    "scope": {
      "command": "uvx",
      "args": ["scope-mcp", "--project", "."]
    }
  }
}
```

**VS Code (GitHub Copilot)**

**File:** `.vscode/mcp.json` (project-level) or `~/AppData/Roaming/Code/User/globalStorage/github.copilot-chat/mcp.json`

```json
{
  "servers": {
    "scope": {
      "command": "uvx",
      "args": ["scope-mcp", "--project", "."]
    }
  }
}
```

---

### 📦 Manual install

```bash
pip install scope-mcp
```

Then use `scope` instead of `uvx scope-mcp` in your config:

```
command:  scope
args:     ["--project", "."]
```

### 🔧 From source

```bash
git clone https://github.com/deviprasadshetty-dev/scope.git
cd scope
pip install -e .
```

Optional extras: `rg` (ripgrep) for text searches, `git` for change tracking.

---

### 🤖 One-click agent setup

Copy-paste this to your AI coding agent and it will set up scope for you automatically:

> Install and configure **scope-mcp** for this project.
>
> 1. **Check if `uv` is installed** — if yes, use `uvx scope-mcp --project .` in the MCP config (it auto-installs on first run). If not, `pip install scope-mcp` first and use `scope --project .`.
> 2. **Find my editor's MCP config** and add the scope server entry:
>    - **Claude Desktop**: `claude_desktop_config.json`
>    - **Cursor**: Cursor Settings → MCP
>    - **Windsurf**: `mcp_config.json`
>    - **VS Code Copilot**: `.vscode/mcp.json`
> 3. **Verify** — use the `scope_status` tool to confirm it's running.
>
> Actually do it — don't just show me the config, edit the file.

## 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