Metadata-Version: 2.4
Name: scope-mcp
Version: 0.1.2
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

[![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.

## 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 scope to your AI coding tool:

### Claude Desktop

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

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

### Cursor

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

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

### Windsurf

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

```json
{
  "mcpServers": {
    "scope": {
      "command": "scope",
      "args": ["--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": "scope",
      "args": ["--project", "."]
    }
  }
}
```

### Any MCP-compatible tool

```
command:  scope
args:     ["--project", "/path/to/your/project"]
transport: stdio
```

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

> I want you to install and configure the **scope-mcp** tool for this project.
>
> 1. **Install it**: `pip install scope-mcp`
> 2. **Check it works**: run `scope --version`
> 3. **Set up MCP**: Find my editor's MCP config file and add the scope server entry:
>    - For **Claude Desktop**: `claude_desktop_config.json`
>    - For **Cursor**: Cursor Settings → MCP
>    - For **Windsurf**: `mcp_config.json`
>    - For **VS Code Copilot**: `.vscode/mcp.json`
> 4. **Verify**: Use the `scope_status` tool to confirm everything is running.
>
> The server should run with: `scope --project .` (so it analyzes the current project).
> Don't skip any step — actually install it and configure it.

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