# MCP Prompt Explorer Server 🚀

A comprehensive Model Context Protocol (MCP) server that demonstrates the **prompt feature** with 10 different development-focused prompts. This server is perfect for exploring how MCP prompts work and can be integrated into LLM applications like Claude Desktop.

## 📋 What are MCP Prompts?

MCP prompts are pre-configured, reusable templates that LLM applications can use. They:
- **Standardize common tasks**: Create consistent workflows
- **Accept arguments**: Dynamic prompts that adapt to your needs
- **Provide structure**: Well-formatted prompts for better results
- **Save time**: No need to craft prompts from scratch

## ✨ Features

This server includes 10 powerful prompts:

1. **🔍 code-review** - Comprehensive code review with focus areas
2. **📚 explain-concept** - Technical concept explanation with examples
3. **🐛 debug-assistant** - Debug code with error analysis
4. **📖 api-documentation** - Generate API documentation
5. **♻️ refactor-suggestion** - Code refactoring recommendations
6. **🧪 test-generator** - Generate unit tests
7. **🏗️ architecture-review** - System architecture analysis
8. **💬 git-commit-message** - Generate commit messages
9. **⚡ sql-optimizer** - SQL query optimization
10. **🎓 learning-path** - Personalized learning paths

## 🚀 Quick Start

### Prerequisites

- Python 3.10 or higher
- pip or uv package manager

### Installation

#### Option 1: Using UV (Recommended)

```bash
# Install UV if you haven't already
pip install uv

# Create and activate virtual environment
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
uv pip install mcp
```

#### Option 2: Using pip

```bash
# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install mcp
```

### Running the Server

```bash
uv run server.py
```

## 🔧 Integration with Claude Desktop

To use this server with Claude Desktop, add it to your configuration:

### macOS/Linux Configuration

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "prompt-explorer": {
      "command": "python",
      "args": ["/absolute/path/to/mcp_prompt_explorer_server.py"],
      "env": {}
    }
  }
}
```

### Windows Configuration

Edit `%APPDATA%\Claude\claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "prompt-explorer": {
      "command": "python",
      "args": ["C:\\absolute\\path\\to\\mcp_prompt_explorer_server.py"],
      "env": {}
    }
  }
}
```

**Important**: Replace `/absolute/path/to/` with the actual path where you saved the server file.

### Using with UV (Alternative)

If using UV, you can configure it like this:

```json
{
  "mcpServers": {
    "prompt-explorer": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp",
        "python",
        "/absolute/path/to/mcp_prompt_explorer_server.py"
      ]
    }
  }
}
```

## 📖 Usage Examples

Once integrated with Claude Desktop, you can use prompts like this:

### Example 1: Code Review

```
Use the code-review prompt with this Python code:

def calculate(a, b):
    return a + b
```

The prompt will automatically format a comprehensive code review request.

### Example 2: Explain a Concept

```
Use the explain-concept prompt to explain "async/await in Python" 
for a beginner audience with code examples
```

### Example 3: Debug Assistance

```
Use the debug-assistant prompt with this error:
"TypeError: unsupported operand type(s) for +: 'int' and 'str'"

And this code:
x = 5
y = "10"
result = x + y
```

### Example 4: Generate Tests

```
Use the test-generator prompt with comprehensive coverage 
for this function:

def factorial(n):
    if n <= 1:
        return 1
    return n * factorial(n - 1)
```

## 🎯 Understanding Prompt Arguments

Each prompt has specific arguments:

### Required Arguments
These must be provided for the prompt to work.

### Optional Arguments
These customize the prompt behavior but have defaults.

Example from the `code-review` prompt:
- `code` (required) - The code to review
- `language` (optional) - Programming language
- `focus` (optional) - Specific focus area

## 🔍 Exploring the Code

### Key Components

1. **`list_prompts()`** - Returns all available prompts
   - Called when client queries available prompts
   - Returns prompt metadata including arguments

2. **`get_prompt()`** - Returns a specific prompt with arguments filled in
   - Takes prompt name and argument values
   - Returns formatted prompt message

3. **Prompt Structure**:
   ```python
   Prompt(
       name="prompt-name",
       description="What this prompt does",
       arguments=[
           PromptArgument(
               name="arg_name",
               description="What this argument is for",
               required=True/False,
           ),
       ],
   )
   ```

## 🛠️ Customizing Prompts

Want to add your own prompts? Here's how:

1. **Add to `list_prompts()`**:
   ```python
   Prompt(
       name="my-custom-prompt",
       description="My awesome prompt",
       arguments=[
           PromptArgument(
               name="input",
               description="Input data",
               required=True,
           ),
       ],
   )
   ```

2. **Add handler in `get_prompt()`**:
   ```python
   elif name == "my-custom-prompt":
       input_data = arguments.get("input", "")
       return GetPromptResult(
           description="Custom prompt result",
           messages=[
               PromptMessage(
                   role="user",
                   content=TextContent(
                       type="text",
                       text=f"Process this: {input_data}"
                   ),
               ),
           ],
       )
   ```

## 📚 Learning Resources

- [MCP Documentation](https://modelcontextprotocol.io/)
- [MCP Specification](https://spec.modelcontextprotocol.io/)
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)

## 🎨 Prompt Best Practices

Based on this server's implementation:

1. **Clear Structure**: Use numbered lists and headers
2. **Specific Instructions**: Be explicit about what you want
3. **Examples**: Provide examples when helpful
4. **Formatting**: Use XML tags or markdown for clarity
5. **Flexibility**: Support optional arguments with sensible defaults

## 🐛 Troubleshooting

### Server Not Showing Up in Claude Desktop

1. Check configuration file syntax (valid JSON)
2. Verify absolute path to server file
3. Ensure Python/UV is in PATH
4. Restart Claude Desktop after configuration changes
5. Check Claude Desktop logs

### Import Errors

```bash
# Make sure mcp is installed
pip install mcp
# or
uv add mcp
```

### Python Version Issues

Ensure you're using Python 3.10+:
```bash
python --version
```

## 💡 Tips for Using Prompts

1. **Start Simple**: Try prompts with just required arguments
2. **Add Details**: Use optional arguments to refine results
3. **Iterate**: Adjust arguments based on results
4. **Combine**: Use multiple prompts for complex tasks

## 🔄 What's Next?

Try these exercises to learn more about MCP prompts:

1. **Modify** an existing prompt template
2. **Add** a new prompt for your specific use case
3. **Combine** prompts in workflows
4. **Create** argument validation logic
5. **Add** multi-turn conversation prompts

## 📝 License

This is a demonstration project for learning about MCP prompts. Feel free to use, modify, and extend it!

## 🤝 Contributing

This is a learning project! Feel free to:
- Add new prompts
- Improve existing templates
- Add features (resources, tools)
- Share your customizations

---

**Happy Prompting! 🎉**

Need help? The code is heavily commented to help you understand how everything works.