# MCP Configuration Wizard

Universal MCP configuration tool for Claude Code - works on any system, any user.

## 🎯 Features

- **Auto-Detection**: Automatically detects your system, existing configs, and environment
- **Interactive Wizard**: Step-by-step guided setup
- **Cross-Platform**: Works on Windows, macOS, and Linux
- **Safe Installation**: Backup existing configs before changes
- **Export/Import**: Share configurations between machines
- **19 MCP Services**: Pre-configured popular services

## 📦 Quick Start

### 1. Install Dependencies

```bash
npm install
```

### 2. Detect Your System

```bash
npm run detect
```

This will scan your system and detect:
- Claude Code installation
- Existing MCP configurations
- Environment variables
- Installed npm packages

### 3. Run Configuration Wizard

```bash
npm start
```

Choose from 4 modes:
1. **Quick Setup** - Install recommended services (no API keys needed)
2. **Custom Setup** - Choose specific services
3. **Import** - Load configuration from file
4. **Export** - Save current config for another machine

### 4. Apply Configuration

```bash
npm run apply
```

This will:
- Install MCP configuration to `~/.claude.json`
- Generate environment variable scripts
- Create installation guide

### 5. Restart Claude Code

Close and reopen Claude Code to load the new MCP services.

## 🔧 Configuration Modes

### Quick Setup (Recommended for beginners)

Installs 6 essential services that work without API keys:
- playwright - Browser automation
- chrome-devtools - Chrome DevTools integration
- context7 - Programming documentation
- deep-research - Research assistant
- sequential-thinking - Reasoning engine
- scrapling - Web scraping

### Custom Setup (For advanced users)

Choose from 19 services across categories:
- **Automation**: playwright, chrome-devtools, browserbase
- **Development**: github, vercel, firebase
- **Communication**: slack
- **Productivity**: linear, notion
- **Documentation**: context7
- **Research**: deep-research
- **Web**: scrapling, firecrawl
- **Database**: supabase
- **Monitoring**: sentry
- **Infrastructure**: cloudflare

### Import/Export

**Export** your configuration to share with another machine:
```bash
npm start
# Select option 4
```

**Import** a configuration file:
```bash
npm start
# Select option 3
# Enter path to config file
```

## 📋 Available Services

### No API Key Required (9 services)

| Service | Description | Category |
|---------|-------------|----------|
| playwright | Browser automation testing | Automation |
| chrome-devtools | Chrome DevTools integration | Automation |
| context7 | Programming documentation | Documentation |
| deep-research | Deep research assistant | Research |
| sequential-thinking | Sequential reasoning | Reasoning |
| scrapling | Web scraping tool | Web |
| figma | Figma design integration | Design |

### API Key Required (10 services)

| Service | Description | Setup Link |
|---------|-------------|------------|
| github | GitHub repository integration | [Get Token](https://github.com/settings/tokens) |
| slack | Slack team collaboration | [Create App](https://api.slack.com/apps) |
| linear | Linear project management | [API Settings](https://linear.app/settings/api) |
| browserbase | Cloud browser service | [Dashboard](https://browserbase.com) |
| cloudflare | Cloudflare CDN management | [API Tokens](https://dash.cloudflare.com/profile/api-tokens) |
| firecrawl | Intelligent web crawler | [Sign Up](https://firecrawl.dev) |
| supabase | Supabase database | [API Settings](https://supabase.com/dashboard) |
| sentry | Error monitoring | [Auth Tokens](https://sentry.io/settings/account/api/auth-tokens/) |
| notion | Notion knowledge base | [Integrations](https://www.notion.so/my-integrations) |
| vercel | Vercel deployment | [Tokens](https://vercel.com/account/tokens) |
| firebase | Firebase backend | [Service Accounts](https://console.firebase.google.com) |

## 🔐 Environment Variables

The wizard generates scripts to set environment variables:

**Windows (PowerShell):**
```powershell
.\apply-env.ps1
```

**Unix/Mac (Bash/Zsh):**
```bash
source ./apply-env.sh
```

Or set them manually from `generated-env.json`.

## 📁 Generated Files

After running the wizard, you'll get:

- `detection-result.json` - System detection results
- `generated-claude.json` - MCP configuration for Claude Code
- `generated-env.json` - Environment variables (JSON format)
- `apply-env.ps1` - PowerShell script (Windows)
- `apply-env.sh` - Shell script (Unix/Mac)
- `INSTALL.md` - Installation guide

## 🚀 Usage Examples

### Example 1: First-time setup on new machine

```bash
npm install
npm run detect
npm start
# Choose option 1 (Quick Setup)
npm run apply
# Restart Claude Code
```

### Example 2: Add GitHub integration

```bash
npm start
# Choose option 2 (Custom Setup)
# Enter: github
# Enter your GitHub token
npm run apply
# Restart Claude Code
```

### Example 3: Export config for another machine

```bash
npm start
# Choose option 4 (Export)
# Copy mcp-config-export.json to other machine
```

On the other machine:
```bash
npm install
npm start
# Choose option 3 (Import)
# Enter path to mcp-config-export.json
npm run apply
```

## 🛠️ Manual Installation

If automatic installation fails:

1. Copy content from `generated-claude.json`
2. Paste into `~/.claude.json` (create if doesn't exist)
3. Set environment variables from `generated-env.json`
4. Restart Claude Code

## ⚠️ Troubleshooting

### "Cannot find module 'inquirer'"

```bash
npm install
```

### "Permission denied" on Unix/Mac

```bash
chmod +x apply-env.sh
```

### PowerShell execution policy error

```powershell
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
```

### MCP services not loading

1. Check `~/.claude.json` exists and has `mcpServers` section
2. Verify environment variables are set: `echo $GITHUB_PERSONAL_ACCESS_TOKEN`
3. Restart Claude Code completely
4. Check Claude Code logs for errors

## 📖 Documentation

- [MCP Protocol](https://modelcontextprotocol.io/)
- [Claude Code](https://claude.ai/code)
- [Service Documentation](./docs/services.md)

## 🤝 Contributing

Contributions welcome! To add a new MCP service:

1. Add service definition to `MCP_SERVICES` in `wizard.js`
2. Include package name, description, category, and required env vars
3. Test with `npm start`
4. Submit PR

## 📄 License

MIT

## 🔗 Links

- [MCP Official Site](https://modelcontextprotocol.io/)
- [Claude Code](https://claude.ai/code)
- [GitHub Repository](https://github.com/your-repo/mcp-config-wizard)

---

**Version**: 1.0.0  
**Last Updated**: 2026-04-04  
**Maintained by**: Bookworm Team