# code-intel-mcp

MCP server for efficient codebase exploration by coding agents. List exports, get file outlines, read targeted regions, and find references — without loading whole files into context.

## Tools

| Tool | Input | Output | When to use |
|---|---|---|---|
| `list_exports` | path (file/folder), filter?, depth? | Name + signature + line + totalLines | Discover what a file/folder contains |
| `file_outline` | path (file), exportedOnly? | All symbols with line ranges | Understand structure before reading |
| `read_region` | path, start, end (max 200 lines) | Numbered source lines | Read only the code you need |
| `find_references` | symbol, path (dir), filePattern?, maxResults? | File:line + context | Trace call chains and usage |

## Recommended agent workflow

```
1. list_exports(path, filter) → discover what exists and where
2. file_outline(file) → understand structure and line ranges
3. read_region(file, start, end) → read only the relevant ±30 lines
4. find_references(symbol, dir) → trace who calls it before modifying
```

## Setup

### Any MCP-compatible client (via npx)

No local install needed. Point your MCP client at:

```
command: npx
args: ["-y", "@dothinh/code-intel-mcp"]
```

### Codex (desktop app / CLI)

Add to `~/.codex/config.toml`:

```toml
[mcp_servers.code-intel]
command = "npx"
args = ["-y", "@dothinh/code-intel-mcp"]
```

### Cursor

Add to `.cursor/mcp.json` (project-level) or global MCP settings:

```json
{
  "mcpServers": {
    "code-intel": {
      "command": "npx",
      "args": ["-y", "@dothinh/code-intel-mcp"]
    }
  }
}
```

### Claude Code

```bash
claude mcp add code-intel -- npx -y @dothinh/code-intel-mcp
```

### Windsurf / Cline / Continue / other MCP clients

Use the same `npx` command and args in your client's MCP server configuration. The server communicates over stdio using newline-delimited JSON-RPC.

## Requirements

- Node.js >= 20
- `rg` (ripgrep) on PATH — used by `find_references`

## Supported languages

TypeScript, JavaScript, Vue SFC, and Svelte for export detection and file outlines. `find_references` works with any text file that ripgrep can read (Python, Go, Rust, etc.).

## Local development

```bash
git clone git@github.com:dothinh115/code-intel-mcp.git
cd code-intel-mcp
yarn install
yarn build
node dist/index.js   # starts MCP server on stdio
```

## License

MIT