# mcp-component-finder

[![npm version](https://badge.fury.io/js/mcp-component-finder.svg)](https://badge.fury.io/js/mcp-component-finder)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

MCP (Model Context Protocol) server for finding component, function, and type usage in React/TypeScript projects. Perfect for use with Claude Code!

## 🚀 Quick Start

### Install in your project

```bash
npm install --save-dev mcp-component-finder
```

### Auto-setup for Claude Code

```bash
npx mcp-component-finder setup
```

This will give you two options:
1. **Local setup** (recommended) - Creates `.claude_config.json` in your project
2. **Global setup** - Configures Claude Desktop globally

Local setup is recommended as it keeps the MCP server configuration project-specific.

## 📋 Manual Setup

### Option 1: Local Project Configuration (Recommended)

Create `.claude_config.json` in your project root:

```json
{
  "mcpServers": {
    "component-finder": {
      "command": "npx",
      "args": ["mcp-component-finder"],
      "env": {
        "PROJECT_ROOT": "."
      }
    }
  }
}
```

This approach:
- ✅ Works only for the specific project
- ✅ No global Claude Desktop configuration needed
- ✅ Claude Code automatically detects the config
- ✅ Easy to share with team (if not in .gitignore)

### Option 2: Claude Desktop Configuration

Add to your Claude Desktop config file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "component-finder": {
      "command": "npx",
      "args": ["mcp-component-finder"],
      "env": {
        "PROJECT_ROOT": "/path/to/your/project"
      }
    }
  }
}
```

## 💡 Usage Examples

Once configured, you can ask Claude Code:

```
Find all usage of SearchIcon component
```

```
Show me where Button from @mui/material is used
```

```
Find useState imports from react in .tsx files only
```

```
List files that use the UserProfile component
```

## 🔧 Features

- **Find React Components**: JSX usage, imports, exports
- **Find Functions**: Function calls, imports from any package
- **Find TypeScript Types**: Interface usage, type annotations
- **NPM Package Support**: Search components from any installed package
- **Smart Filtering**: Excludes comments, includes only relevant files
- **Fast Search**: Optimized for large codebases

## 📊 Search Capabilities

### Import Detection
- `import { Component } from './path'`
- `import Component from './Component'`
- `import * as Components from 'package'`
- `import 'package'` (side-effect imports)

### Usage Detection
- JSX: `<Component />`, `<Component prop="value">`
- Function calls: `Component()`, `Component.method()`
- TypeScript types: `: Component`, `Component<T>`
- Destructuring: `{ Component } = obj`

## 🎯 Tool Parameters

- `targetName` (required): Name of component/function/type to find
- `packageName` (optional): NPM package name for external dependencies  
- `projectRoot` (optional): Project root path (defaults to current directory)
- `extensions` (optional): File extensions to search (default: .ts, .tsx, .js, .jsx)
- `excludeDirs` (optional): Directories to exclude (default: node_modules, .git, dist, build)
- `format` (optional): Output format - 'detailed' or 'files-only'

## 📁 Project Structure

Works with any React/TypeScript project structure:
- Create React App
- Next.js
- Vite
- Custom webpack setups
- Monorepos

## 🤝 Contributing

Contributions welcome! Please read our [Contributing Guide](CONTRIBUTING.md) first.

## 📄 License

MIT © [Deonis Peretyagin](https://github.com/karudo)

## 🐛 Issues

Found a bug? Please [open an issue](https://github.com/karudo/mcp-component-finder/issues).

## 🏷️ Changelog

See [CHANGELOG.md](CHANGELOG.md) for version history.