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

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

Or manually 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

Built With

• ts-morph - TypeScript AST manipulation
• Model Context Protocol SDK - MCP server implementation
• Zod - Schema validation

Author

Sukhdev - @paramhq

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT - see LICENSE