# MCP Prompt Template Selector

<p align="center">
  <strong>AI-powered prompt template selection and generation for Claude Code</strong>
</p>

<p align="center">
  <a href="#installation">Installation</a> •
  <a href="#quick-start">Quick Start</a> •
  <a href="#usage">Usage</a> •
  <a href="#api">API</a> •
  <a href="#examples">Examples</a>
</p>

---

MCP server that automatically selects and generates specialized prompts from a knowledge base of 66+ Claude Code system prompts. Uses LLM-powered semantic search to find the best matching template and adapts it to your specific task.

## Features

- **Smart Template Selection** — Semantic search across 66+ prompt templates using Claude Haiku
- **Adaptive Generation** — Returns original template when it fits, customizes when adaptation is needed
- **Custom Templates** — Add your own templates with priority over built-in ones
- **Dual Transport** — Works via stdio (local) or HTTP (server deployment)
- **Zero Config** — Templates auto-sync from [claude-code-system-prompts](https://github.com/Piebald-AI/claude-code-system-prompts)

## Requirements

- [Bun](https://bun.sh/) v1.0+
- Anthropic API key

## Installation

```bash
# Clone the repository
git clone https://github.com/YOUR_USERNAME/mcp-prompt-tool.git
cd mcp-prompt-tool

# Install dependencies
bun install

# Configure API key
echo "ANTHROPIC_API_KEY=your-api-key-here" > .env
```

## Quick Start

### Connect to Claude Code (recommended)

Add MCP server to Claude Code via command line:

```bash
claude mcp add --transport stdio prompt-template-selector -- bun run /path/to/mcp-prompt-tool/src/index.ts
```

Verify connection:
```bash
claude mcp list
```

Then in Claude Code use `/mcp` to see available tools.

### Alternative: Run as HTTP server

```bash
bun run start:http
# Server runs at http://localhost:3000
```

## Usage

Once connected, you have 4 tools available in Claude Code:

### `list_templates`

Browse available templates:

```
list_templates category:agent
list_templates search:"code review"
```

### `select_template`

Find best matching template for your task:

```
select_template task_description:"I need to review GitHub PRs"
```

### `generate_prompt`

Generate a ready-to-use prompt:

```
generate_prompt task_description:"Agent for Python code refactoring" context:"Django, async migration"
```

### `sync_templates`

Update templates from GitHub:

```
sync_templates force_reindex:true
```

## Examples

### Example 1: Code Review Agent

**Request:**
```json
{
  "task_description": "Агент для code review Pull Request на GitHub",
  "prompt_type": "agent"
}
```

**Result:** Returns the original `agent-prompt-review-pr-slash-command` template as-is, since it's a perfect match.

```markdown
You are an expert code reviewer. Follow these steps:

1. If no PR number is provided in the args, use ${BASH_TOOL_OBJECT.name}("gh pr list") to show open PRs
2. If a PR number is provided, use ${BASH_TOOL_OBJECT.name}("gh pr view <number>") to get PR details
3. Use ${BASH_TOOL_OBJECT.name}("gh pr diff <number>") to get the diff
4. Analyze the changes and provide a thorough code review...
```

### Example 2: Custom Task with Adaptation

**Request:**
```json
{
  "task_description": "Agent for legacy Python code analysis and migration to Python 3.12 async/await",
  "prompt_type": "agent",
  "context": "Django project with synchronous callbacks"
}
```

**Result:** Adapts the `agent-prompt-plan-mode-enhanced` template with Django/async specifics:

```markdown
You are a Python code modernization specialist for legacy Django projects.
Your role is to analyze and plan refactoring of synchronous callback-based
code with migration to Python 3.12 and async/await patterns.

=== CRITICAL: READ-ONLY MODE ===
...

## Your Process
1. **Understand Requirements**: Focus on the legacy code patterns...
2. **Explore Thoroughly**: Find callback-based patterns and synchronous code...
3. **Design Solution**: Plan async context manager and async generator migrations...
```

### Example 3: Listing Agent Templates

**Request:**
```json
{
  "category": "agent",
  "search": "security"
}
```

**Result:**
```json
{
  "total_count": 2,
  "templates": [
    {
      "name": "agent-prompt-security-review-slash",
      "purpose": "Conduct focused security reviews of code changes",
      "complexity": "complex"
    },
    {
      "name": "agent-prompt-bash-command-prefix-detection",
      "purpose": "Detecting command injection attacks",
      "complexity": "complex"
    }
  ]
}
```

## Template Categories

| Category | Count | Examples |
|----------|-------|----------|
| `agent` | 28 | PR review, code exploration, security audit |
| `system` | 10 | Base behavior, plan mode, configuration |
| `tool` | 19 | Bash, Read, Edit, Grep tool descriptions |
| `reminder` | 3 | Plan mode reminders |
| `skill` | 5 | GitHub integration, specialized skills |

## Custom Templates

Add your own templates to `custom-templates/` directory:

```
custom-templates/
├── my-agent.md           # Your custom prompt
└── metadata.json         # Optional: category, tags, priority
```

**metadata.json:**
```json
{
  "templates": {
    "my-agent": {
      "category": "agent",
      "tags": ["custom", "specialized"],
      "priority": 10
    }
  }
}
```

Custom templates are prioritized over built-in ones during selection.

## API Reference

### Tools

| Tool | Description | Required Params |
|------|-------------|-----------------|
| `list_templates` | List/search templates | — |
| `select_template` | Find matching templates | `task_description` |
| `generate_prompt` | Generate customized prompt | `task_description` |
| `sync_templates` | Sync from GitHub | — |

### Parameters

**list_templates:**
- `category`: `agent` | `system` | `tool` | `reminder` | `skill` | `any`
- `search`: Text search query
- `include_custom`: Include custom templates (default: true)

**select_template / generate_prompt:**
- `task_description`: What you need the prompt for
- `prompt_type`: Filter by category
- `context`: Additional context for adaptation
- `target_llm`: Target model (default: Claude)
- `max_results`: Max templates to consider (default: 3)

**sync_templates:**
- `force_reindex`: Re-index all templates (default: false)

## Configuration

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `ANTHROPIC_API_KEY` | Anthropic API key | — |
| `PORT` | HTTP server port | 3000 |

### Claude Code Integration

**Global config** (`~/.claude.json`):
```json
{
  "mcpServers": {
    "prompt-template-selector": {
      "command": "bun",
      "args": ["run", "/path/to/mcp-prompt-tool/src/index.ts"]
    }
  }
}
```

**Project config** (`.mcp.json` in project root):
```json
{
  "mcpServers": {
    "prompt-template-selector": {
      "type": "stdio",
      "command": "bun",
      "args": ["run", "/path/to/mcp-prompt-tool/src/index.ts"]
    }
  }
}
```

## Development

```bash
# Run in stdio mode (default)
bun run start

# Run as HTTP server
bun run start:http

# Development with watch
bun run dev

# Run tests
bun test

# Type check
bun run typecheck
```

## Project Structure

```
mcp-prompt-tool/
├── src/
│   ├── index.ts                 # Entry point (stdio/http)
│   ├── tools/                   # MCP tool implementations
│   │   ├── list-templates.ts
│   │   ├── select-template.ts
│   │   ├── generate-prompt.ts
│   │   └── sync-templates.ts
│   ├── services/                # Business logic
│   │   ├── template-loader.ts   # GitHub repo sync
│   │   ├── template-indexer.ts  # LLM-powered indexing
│   │   ├── prompt-generator.ts  # Selection & generation
│   │   └── custom-templates.ts  # User templates
│   └── types/
│       └── index.ts
├── templates/                   # Cached template index
├── custom-templates/            # User custom templates
├── tests/
├── .env                         # API key (git-ignored)
└── package.json
```

## How It Works

1. **Sync**: Clones/pulls [claude-code-system-prompts](https://github.com/Piebald-AI/claude-code-system-prompts)
2. **Index**: Uses Claude Haiku to extract metadata from each template
3. **Select**: Semantic search finds best matching templates for your task
4. **Generate**: Returns original or adapts template based on match quality

## License

MIT

## Credits

- Templates from [Piebald-AI/claude-code-system-prompts](https://github.com/Piebald-AI/claude-code-system-prompts)
- Built with [Model Context Protocol SDK](https://github.com/modelcontextprotocol/sdk)