# merlin-mcp

> MCP server that gives Claude Code instant access to your codebase context via merlin.build

## What This Does

Once installed, Claude Code automatically has deep understanding of any repository you've analyzed on [merlin.build](https://merlin.build):

- **No more re-explaining** your codebase every session
- **No more duplicating** code that already exists
- **No more guessing** at patterns and conventions
- **Instant context** for any task you're working on

## Quick Start

### 1. Analyze Your Repository

Visit [merlin.build](https://merlin.build) and analyze your repository. This takes ~10 minutes and creates comprehensive documentation.

### 2. Get Your API Key

Go to [merlin.build/settings](https://merlin.build/settings) and generate an API key.

### 3. Configure Claude Code

**Option A: Interactive Setup (Recommended)**

```bash
# Shows logo, validates key, guides you through setup
MERLIN_API_KEY=mrln_xxxxx npx merlin-mcp --setup
```

**Option B: Quick CLI Install**

```bash
# Add MCP server
claude mcp add merlin npx merlin-mcp@latest -e MERLIN_API_KEY=mrln_xxxxx --scope user

# Verify installation (shows logo, validates key)
npx merlin-mcp --test
```

**Option C: Manual Config**

Add to your Claude Code config (`~/.claude/config.json`):

```json
{
  "mcpServers": {
    "merlin": {
      "command": "npx",
      "args": ["merlin-mcp@latest"],
      "env": {
        "MERLIN_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

> **Upgrading from ccwiki/briefed?** The old MCP is automatically cleaned up when you start Merlin.

### 4. Use It

Just start working. Claude Code now automatically has context:

```
> "Add a new API endpoint for user settings"

Claude knows:
- Where your existing endpoints are
- What patterns they follow
- What middleware to use
- What utilities exist to reuse
- What conventions to follow
```

## Available Tools

Once connected, Claude Code has access to these tools:

| Tool | Description |
|------|-------------|
| `merlin_get_context` | Get relevant context for a task (patterns, files, conventions) |
| `merlin_find_files` | Find files by purpose or layer |
| `merlin_get_conventions` | Get coding conventions and anti-patterns |
| `merlin_quickstart` | Get a 60-second codebase overview |
| `merlin_search` | Search documentation for specific topics |
| `merlin_list_repos` | List your analyzed repositories |

## How It Works

1. **Auto-detection**: The MCP server detects which git repository you're in
2. **Lookup**: It finds the matching analyzed repo on merlin.build
3. **Context**: It provides relevant context to Claude Code
4. **Caching**: Responses are cached for fast repeat access

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `MERLIN_API_KEY` | Your Merlin API key | Required |
| `MERLIN_API_URL` | API base URL | `https://auth.merlin.build` |

## CLI Commands

```bash
# Interactive setup wizard (recommended for first-time setup)
MERLIN_API_KEY=xxx npx merlin-mcp --setup

# Validate setup - shows logo, checks API key, lists repos
npx merlin-mcp --test

# Show help
npx merlin-mcp --help

# Show version
npx merlin-mcp --version

# Run server directly (for testing)
MERLIN_API_KEY=xxx npx merlin-mcp
```

## Troubleshooting

### "Could not find repository"

This means either:
1. You're not in a git repository
2. The repository hasn't been analyzed on merlin.build
3. The git remote URL doesn't match what's on merlin

**Solution**: Make sure the repo is analyzed at merlin.build and you're in the repo directory.

### "API request failed: 401"

Your API key is invalid or expired.

**Solution**: Generate a new API key at merlin.build/settings.

### Server not starting

Check that Node.js 18+ is installed:

```bash
node --version  # Should be 18.x or higher
```

### Old "briefed" MCP still showing

If you still see `briefed` in `claude mcp list`:

```bash
# Remove it manually
claude mcp remove briefed --scope user

# Merlin should be the only one
claude mcp list
```

Note: Merlin automatically cleans up old `briefed` config when it starts, but the Claude CLI registry needs manual removal.

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Run in development
npm run dev

# Type check
npm run typecheck
```

## License

MIT

## Links

- [merlin.build](https://merlin.build) - Analyze your repositories
- [Documentation](https://merlin.build/docs) - Full documentation
- [GitHub](https://github.com/merlin/merlin) - Source code