src/MCP_README.md

# AI Prompt Optimizer MCP Server

This MCP (Model Context Protocol) server provides AI-powered prompt optimization tools to reduce token usage while preserving meaning.

## Features

- **3 Optimization Methods**:
  - `simple`: LLM-based optimization using personas
  - `agent`: Advanced optimization with web search integration
  - `spacy`: Local NLP-based optimization (no API required)

- **8 Specialized Personas**: Default, UI/UX Designer, Software Engineer, Marketing Copywriter, Creative Writer, Technical Writer, Legal Advisor, Medical Professional, Financial Analyst

- **Token Counting**: Accurate token counting for various models

## Tools Available

1. **optimize_prompt**: Optimize prompts using different methods
2. **get_available_personas**: List all available optimization personas
3. **count_tokens**: Count tokens in text for specific models

## Installation & Setup

### Prerequisites
- Python 3.8+
- UV package manager
- API keys for AIMLAPI and Tavily (for LLM-based optimization)

### 1. Clone and Install Dependencies
```bash
git clone <your-repo>
cd AI-Prompt-Optimizer
pip install -r requirements.txt
```

### 2. Set Up Environment Variables
Create a `.env` file in the `mcp/` directory:
```bash
AIMLAPI_API_KEY=your_aimlapi_key_here
TAVILY_API_KEY=your_tavily_key_here
```

## Configuration

### Option 1: STDIO Transport (Recommended)

#### For Claude Desktop/Cursor
Add to your MCP configuration file (`~/.cursor/mcp.json` or Claude Desktop config):

```json
{
  "mcpServers": {
    "promptcraft": {
      "command": "uv",
      "args": ["run", "--python", "/path/to/your/project/.venv/bin/python3", "mcp_server_stdio.py"],
      "cwd": "/path/to/your/project/mcp",
      "env": {
        "AIMLAPI_API_KEY": "your_aimlapi_key_here",
        "TAVILY_API_KEY": "your_tavily_key_here"
      }
    }
  }
}
```

#### For Claude CLI
```bash
# Add STDIO transport
claude mcp add --transport stdio promptcraft uv run mcp_server_stdio.py --cwd /path/to/your/project/mcp --env AIMLAPI_API_KEY=your_key --env TAVILY_API_KEY=your_key
```

### Option 2: HTTP Transport

#### Start the HTTP Server
```bash
cd mcp
python mcp_server_fastmcp.py
```

#### For Claude Desktop/Cursor
```json
{
  "mcpServers": {
    "promptcraft-http": {
      "name": "promptcraft",
      "url": "http://127.0.0.1:8003/mcp/"
    }
  }
}
```

#### For Claude CLI
```bash
# Add HTTP transport
claude mcp add --transport http promptcraft http://127.0.0.1:8003/mcp/
```

## Usage Examples

### Basic Prompt Optimization
```
Use the optimize_prompt tool with:
- prompt: "Can you please help me write a very detailed explanation about machine learning?"
- method: "spacy"
- aggressiveness: 0.8
```

### Persona-based Optimization
```
Use the optimize_prompt tool with:
- prompt: "We need to create a comprehensive user interface design document"
- method: "simple" 
- persona: "UI/UX Designer"
```

### Advanced Agent Optimization
```
Use the optimize_prompt tool with:
- prompt: "I want you to research and provide information about the latest trends in AI"
- method: "agent"
- persona: "Technical Writer"
```

## Available Methods

1. **spacy**: Local optimization using NLP techniques
   - Removes filler words
   - Simplifies complex phrases
   - Applies lemmatization
   - No API keys required

2. **simple**: LLM-based optimization with persona guidance
   - Requires AIMLAPI_API_KEY
   - Uses specialized personas for domain-specific optimization

3. **agent**: Advanced optimization with web search
   - Requires both AIMLAPI_API_KEY and TAVILY_API_KEY
   - Enhances prompts with real-time web information

## Troubleshooting

### Common Issues

1. **"No tools found"**: Ensure the server is starting correctly and environment variables are set
2. **Import errors**: Make sure all dependencies are installed in the correct virtual environment
3. **API key errors**: Verify your AIMLAPI and TAVILY API keys are valid and properly set

### Testing the Server

#### Test with MCP Inspector
```bash
# Install MCP Inspector
npm install -g @modelcontextprotocol/inspector

# Test the server
mcp-inspector

# Use these settings:
# Command: uv
# Arguments: run mcp_server_stdio.py
# Working Directory: /path/to/your/project/mcp
# Environment Variables: AIMLAPI_API_KEY=your_key, TAVILY_API_KEY=your_key
```

#### Direct Testing
```bash
cd mcp
uv run mcp_server_stdio.py
```

## Architecture

- `mcp_server_stdio.py`: STDIO transport server (recommended)
- `mcp_server_fastmcp.py`: HTTP transport server with Bearer token auth
- `engine.py`: Core spaCy-based optimization logic
- `llm_optimizer.py`: LLM-based optimization with personas and agents

## API Keys

- **AIMLAPI**: Get your key from [AIMLAPI](https://aimlapi.com)
- **Tavily**: Get your key from [Tavily](https://tavily.com)

Both keys are required for full functionality, but spaCy-based optimization works without any API keys.