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

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:

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):

{
  "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

# 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

cd mcp
python mcp_server_fastmcp.py

For Claude Desktop/Cursor

{
  "mcpServers": {
    "promptcraft-http": {
      "name": "promptcraft",
      "url": "http://127.0.0.1:8003/mcp/"
    }
  }
}

For Claude CLI

# 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

# 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

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
• Tavily: Get your key from Tavily

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