# tsx-query

Semantic React/TSX analysis MCP server for AI coding assistants.

**Save 70-90% tokens** compared to grep + file reads.

[![npm version](https://img.shields.io/npm/v/%40paramhq%2Ftsx-query.svg)](https://www.npmjs.com/package/@paramhq/tsx-query)
[![npm downloads](https://img.shields.io/npm/dm/%40paramhq%2Ftsx-query.svg)](https://www.npmjs.com/package/@paramhq/tsx-query)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Why tsx-query?

LLMs waste tokens on grep + file reads. tsx-query uses semantic AST analysis to return precisely what you need.

| Query | grep + read | tsx-query | Savings |
|-------|-------------|-----------|---------|
| Find Button usages | ~15,000 tokens | ~800 tokens | **95%** |
| Trace prop flow (5 levels) | ~75,000 tokens | ~3,000 tokens | **96%** |
| Find all setState calls | ~30,000 tokens | ~1,500 tokens | **95%** |
| Analyze re-render triggers | ~40,000 tokens | ~2,000 tokens | **95%** |

## Installation

```bash
npm install -g @paramhq/tsx-query
```

## Quick Start

### For Claude Code

```bash
claude mcp add tsx-query -- npx -y @paramhq/tsx-query
```

Or manually add to your MCP config (`~/.claude/mcp.json` or project `.mcp.json`):

```json
{
  "mcpServers": {
    "tsx-query": {
      "command": "npx",
      "args": ["-y", "@paramhq/tsx-query"]
    }
  }
}
```

### For Other MCP Clients

```json
{
  "command": "npx",
  "args": ["-y", "@paramhq/tsx-query"]
}
```

### From Source

```bash
git clone https://github.com/paramhq/tsx-query.git
cd tsx-query
npm install
npm run build
npm run mcp
```

## High-Value Tools

### 1. find_component_usages

Find all JSX usages of a component with powerful filtering.

```json
{
  "projectPath": "/path/to/project",
  "componentName": "Button",
  "withProp": "onClick",
  "hasInlineHandler": true
}
```

**Filters:**
- `withProp` / `withoutProp` - Filter by prop existence
- `withPropValue` - Filter by prop value (exact or regex)
- `hasInlineHandler` - Find inline arrow handlers
- `hasSpreadProps` - Find spread props usage
- `onlyConditional` - Only conditional renders

**Returns:** File locations, props with values, parent component, code snippets.

### 2. trace_prop_flow

Trace a prop through the component hierarchy. **Replaces reading 5-10 files manually.**

```json
{
  "projectPath": "/path/to/project",
  "propName": "userId",
  "startFile": "src/components/UserDetails.tsx",
  "direction": "up"
}
```

**Returns:** Complete prop path through components with transformations (renamed, destructured, spread).

### 3. trace_state_updates

Find all locations that update a state variable. **Understand state flow without reading handlers.**

```json
{
  "projectPath": "/path/to/project",
  "filePath": "src/components/UserForm.tsx",
  "stateName": "formData"
}
```

**Returns:** All setState calls with context (handler, useEffect, inline), trigger events, async/conditional flags.

### 4. find_render_triggers

Analyze what causes a component to re-render with optimization suggestions.

```json
{
  "projectPath": "/path/to/project",
  "filePath": "src/components/UserProfile.tsx",
  "componentName": "UserProfile"
}
```

**Returns:** Props, state, context, hooks that trigger renders + memoization status + suggestions.

### 5. analyze_imports

Analyze import/export relationships with cached import graph.

```json
{
  "projectPath": "/path/to/project",
  "filePath": "src/components/Button/index.ts",
  "direction": "importedBy"
}
```

**Returns:** What imports this file, unused exports, circular dependencies.

## Additional Tools

| Tool | Purpose |
|------|---------|
| `find_hook_usages` | Find all usages of a hook across codebase |
| `analyze_hook_deps` | Find missing/unnecessary hook dependencies |
| `analyze_file` | Analyze single file structure |
| `list_components` | List all JSX in a file |
| `clear_cache` | Clear project cache after external changes |

## Roadmap

- [ ] `trace_event_handler` - Trace callback chains from event to side effects
- [ ] `trace_context_usage` - Map Context providers to consumers

## Why Use Over Grep?

| Grep Limitation | tsx-query Solution |
|-----------------|-------------------|
| Finds "Button" in comments/strings | Only finds JSX `<Button>` usages |
| Can't filter by prop values | `withPropValue: { prop: "variant", value: "danger" }` |
| Can't detect aliased imports | Handles `import { Button as Btn }` |
| Can't trace prop flow | Full cross-file prop tracing |
| Reads entire files | Returns only relevant data |

## Built With

- [ts-morph](https://github.com/dsherret/ts-morph) - TypeScript AST manipulation
- [Model Context Protocol SDK](https://modelcontextprotocol.io) - MCP server implementation
- [Zod](https://github.com/colinhacks/zod) - Schema validation

## Author

**Sukhdev** - [@paramhq](https://github.com/paramhq)

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## License

MIT - see [LICENSE](LICENSE)