PromptTuner MCP

PromptTuner MCP is an MCP server that refines, analyzes, optimizes, and validates prompts using OpenAI, Anthropic, or Google Gemini.

What it does

1. Validates and trims input prompts (enforces MAX_PROMPT_LENGTH).
2. Resolves the target format (auto uses heuristics; falls back to gpt if no format is detected).
3. Calls the selected provider with retry and timeout controls.
4. Validates and normalizes LLM output, falling back to stricter prompts or the basic technique when needed.
5. Returns human-readable text plus machine-friendly structuredContent (and resource blocks for refined/optimized outputs).

Features

• Refine prompts with single techniques or full multi-technique optimization.
• Analyze quality with scores, characteristics, and actionable suggestions.
• Validate prompts for issues, token limits, and injection risks.
• Auto-detect target format (Claude XML, GPT Markdown, or JSON).
• Structured outputs with provider/model metadata, fallback indicators, and score normalization.
• Retry logic with exponential backoff for transient provider failures.
• Emits MCP progress notifications for analyze_prompt when a progress token is provided.

Quick Start

PromptTuner runs over stdio only. The dev:http and start:http scripts are compatibility aliases (no HTTP transport yet).

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "prompttuner": {
      "command": "npx",
      "args": ["-y", "@j0hanz/prompt-tuner-mcp-server@latest"],
      "env": {
        "LLM_PROVIDER": "openai",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Replace the API key and provider with your preferred LLM. Only configure the key for the active provider.

Configuration (Essentials)

PromptTuner reads configuration from environment variables. CLI flags can override them (run prompt-tuner-mcp-server --help). Full reference in CONFIGURATION.md.

CLI Options

CLI flags override environment variables (run prompt-tuner-mcp-server --help).

| Flag | Env var | Description | | ------------------------------ | ----------------------- | ------------------------------------------- | --------------------------------------- | | --log-format <text | json> | LOG_FORMAT | Override log format (currently unused). | | --debug / --no-debug | DEBUG | Enable/disable debug logging. | | --include-error-context | INCLUDE_ERROR_CONTEXT | Include sanitized prompt snippet in errors. | | --llm-provider <provider> | LLM_PROVIDER | openai, anthropic, or google. | | --llm-model <name> | LLM_MODEL | Override the default model. | | --llm-timeout-ms <number> | LLM_TIMEOUT_MS | Override request timeout (ms). | | --llm-max-tokens <number> | LLM_MAX_TOKENS | Override output token cap. | | --max-prompt-length <number> | MAX_PROMPT_LENGTH | Override max prompt length (chars). |

Tools

All tools accept plain text, Markdown, or XML prompts. Responses include content (human-readable) and structuredContent (machine-readable).

refine_prompt

Fix grammar, improve clarity, and apply a single technique.

Returns (structuredContent): ok, original, refined, corrections, technique, targetFormat, usedFallback, provider, model.

analyze_prompt

Score prompt quality (0-100) and provide suggestions.

Returns: ok, hasTypos, isVague, missingContext, suggestions, score, characteristics, usedFallback, scoreAdjusted, overallSource, provider, model.

optimize_prompt

Apply multiple techniques sequentially and return before/after scores.

Returns: ok, original, optimized, techniquesApplied, targetFormat, beforeScore, afterScore, scoreDelta, improvements, usedFallback, scoreAdjusted, overallSource, provider, model.

validate_prompt

Pre-flight validation: issues, token estimate, and injection risks.

Returns: ok, isValid, issues, tokenEstimate, tokenLimit, tokenUtilization, overLimit, targetModel, securityFlags, provider, model.

Token limits used for validate_prompt: claude 200000, gpt 128000, gemini 1000000, generic 8000.

Response Format

• content: array of content blocks (human-readable Markdown text plus optional resources).
• structuredContent: machine-parseable results.
• Errors return structuredContent.ok=false and an error object with code, message, optional context (sanitized, up to 200 chars), details, and recoveryHint.
• Error responses also include isError: true.
• refine_prompt and optimize_prompt include a resource content block with a file:/// URI and the prompt text in resource.text (Markdown).

Prompts

All prompts accept a single argument: { "prompt": "..." }.

Prompt Optimization Workflow

Technique selection guide

Recommended prompt architecture

1. Role or identity
2. Context or background
3. Task or objective
4. Steps or instructions
5. Requirements or constraints (ALWAYS or NEVER)
6. Output format
7. Examples (if helpful)
8. Final reminder

Development

Prerequisites

• Node.js >= 22.0.0
• npm

Scripts

Project Structure

src/
  index.ts        Entry point
  server.ts       MCP server setup (stdio transport)
  config/         Configuration and constants
  lib/            Shared utilities (LLM, retry, validation)
  tools/          Tool implementations
  prompts/        MCP prompt templates
  schemas/        Zod input/output schemas

tests/            node:test suites

dist/             Compiled output (generated)

docs/             Static assets

Security

• API keys are supplied only via environment variables.
• Inputs are validated with Zod and additional length checks.
• Error context is sanitized and truncated when INCLUDE_ERROR_CONTEXT=true.
• Google safety filters can be disabled only via GOOGLE_SAFETY_DISABLED=true.

Contributing

Pull requests are welcome. Please include a short summary, tests run, and note any configuration changes.

License

MIT License. See LICENSE for details.