# ast-grep-mcp

MCP server that exposes [ast-grep](https://ast-grep.github.io/) (`sg`) as two tools for structural code search.

## Prerequisites

Install `sg` (ast-grep CLI):

```bash
# via npm
npm i -g @ast-grep/cli

# via cargo
cargo install ast-grep
```

Verify: `sg --version`

## Install & run

```bash
# from this directory
npm install
node src/index.js        # starts MCP server on stdio
# or via npx after publish:
# npx ast-grep-mcp
```

## Tools

### `ast_search`

Structural code search using an ast-grep pattern.

| param | type | required | description |
|-------|------|----------|-------------|
| `lang` | string | yes | Language: `js`, `ts`, `py`, `go`, `rust`, `java`, … |
| `pattern` | string | yes | ast-grep pattern (e.g. `console.log($MSG)`) |
| `dir` | string | no | Directory to search (default: `.`) |

**Returns:** JSON array of `{ file, line, match, snippet }`

**Example prompt:**
> Use ast_search with lang=ts, pattern=`console.log($MSG)`, dir=./src

### `ast_search_preset`

Run a named code-smell preset.

| param | type | required | description |
|-------|------|----------|-------------|
| `name` | enum | yes | One of the 5 presets below |
| `dir` | string | no | Directory to search (default: `.`) |

**Available presets:**

| name | what it finds |
|------|--------------|
| `async-no-catch` | `await` expressions — check for missing try/catch |
| `hooks-missing-deps` | `useEffect(..., [])` — empty deps may hide missing dependencies |
| `route-no-auth` | Express `app.METHOD(path, handler)` — routes that may lack auth middleware |
| `sql-no-param` | Template-literal SQL strings — potential injection risk |
| `promise-no-return` | `new Promise(...)` bodies — check all paths resolve/reject |

## Claude Desktop config

`~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "ast-grep": {
      "command": "node",
      "args": ["/absolute/path/to/ast-grep-mcp/src/index.js"]
    }
  }
}
```

## Cursor `mcp.json`

`.cursor/mcp.json` in your project root:

```json
{
  "mcpServers": {
    "ast-grep": {
      "command": "node",
      "args": ["/absolute/path/to/ast-grep-mcp/src/index.js"]
    }
  }
}
```

Or if you publish to npm:

```json
{
  "mcpServers": {
    "ast-grep": {
      "command": "npx",
      "args": ["ast-grep-mcp"]
    }
  }
}
```

## Pattern quick-reference

```
$VAR          – single node (any)
$$$NODES      – multiple nodes (spread)
`template $X` – template literal containing X
foo($A, $B)   – function call with two args
```

See [ast-grep pattern syntax](https://ast-grep.github.io/guide/pattern-syntax.html) for full docs.