tsx-query

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

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

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

npm install -g @paramhq/tsx-query

Quick Start

For Claude Code

Add to your MCP config (~/.claude/mcp.json or project .mcp.json):

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

For Other MCP Clients

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

From Source

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.

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

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

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

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

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

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT - see LICENSE