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 — 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 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)

{
  "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

{
  "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

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

---

📦 Manual install

pip install scope-mcp

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

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

🔧 From source

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