PromptTuner MCP

PromptTuner MCP is an MCP server that fixes and boosts prompts using OpenAI, Anthropic, or Google Gemini.

What it does

1. Validates and trims input prompts (enforces MAX_PROMPT_LENGTH).
2. Wraps the prompt as JSON inside sentinel markers (sanitizing markers, bidi control chars, and null bytes).
3. Calls the selected provider.
4. Normalizes LLM output (strips code fences / labels if present).
5. Returns human-readable text plus machine-friendly structuredContent.

Features

• Polish and refine a prompt for clarity and flow (fix_prompt).
• Boost and enhance a prompt for clarity and effectiveness (boost_prompt).
• Craft a reusable workflow prompt for complex tasks (crafting_prompt).
• Simple structured outputs.
• Retry logic with exponential backoff for transient provider failures.

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

PromptTuner uses minimal configuration. Set the provider and API key, and you're ready to go.

| Variable | Default | Description | | ------------------- | -------- | ----------------------------------------------------- | | LLM_PROVIDER | openai | openai, anthropic, or google. | | OPENAI_API_KEY | - | Required for all tools when LLM_PROVIDER=openai. | | ANTHROPIC_API_KEY | - | Required for all tools when LLM_PROVIDER=anthropic. | | GOOGLE_API_KEY | - | Required for all tools when LLM_PROVIDER=google. | | LLM_MODEL | - | Override the default model. | | DEBUG | false | Enable debug logging. |

All tools are LLM-backed and require an API key for the selected provider.

Default Models

| Provider | Default Model | | ----------- | ---------------------------- | | openai | gpt-4o | | anthropic | claude-3-5-sonnet-20241022 | | google | gemini-2.0-flash-exp |

CLI Options

| Flag | Description | | --------------------------- | ----------------------------------- | | -h, --help | Show help text. | | -v, --version | Print version. | | --debug / --no-debug | Enable/disable debug logging. | | --llm-provider <provider> | openai, anthropic, or google. | | --llm-model <name> | Override the default model. |

Tools

All tools accept plain text, Markdown, or XML prompts. Responses include content (human-readable) and structuredContent (machine-readable). Inputs are strict: extra fields are rejected. For fix_prompt/boost_prompt, only the prompt field is accepted.

fix_prompt

Polish and refine a prompt for clarity and flow while preserving intent and structure.

| Parameter | Type | Required | Notes | | --------- | ------ | -------- | ----------------------------------------------- | | prompt | string | Yes | Trimmed, length-checked; extra fields rejected. |

Returns: ok, fixed.

boost_prompt

Refine and enhance a prompt for clarity and effectiveness.

| Parameter | Type | Required | Notes | | --------- | ------ | -------- | ----------------------------------------------- | | prompt | string | Yes | Trimmed, length-checked; extra fields rejected. |

Returns: ok, boosted.

crafting_prompt

Generate a structured, reusable workflow prompt for complex tasks based on a raw request and a few settings.

| Parameter | Type | Required | Notes | | ------------- | ------ | -------- | ------------------------------------------------------- | | request | string | Yes | Trimmed, length-checked; strict input. | | constraints | string | No | Hard requirements to enforce (bullet list recommended). | | mode | string | No | general, plan, review, troubleshoot. | | approach | string | No | conservative, balanced, creative. | | tone | string | No | direct, neutral, friendly. | | verbosity | string | No | brief, normal, detailed. |

Returns: ok, prompt, settings.

Response Format

• content: array of content blocks. First block is JSON for structuredContent, second is a short human message (or Error: ...).
• 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.

Development

Prerequisites

• Node.js >= 22.0.0
• npm

Scripts

| Command | Description | | ------------------------ | ----------------------------------------------------- | | npm run build | Compile TypeScript and set permissions. | | npm run prepare | Build on install (publishing helper). | | npm run dev | Run from source in watch mode. | | npm run dev:http | Alias of npm run dev (no HTTP transport yet). | | npm run watch | TypeScript compiler in watch mode. | | npm run start | Run the compiled server from dist/. | | npm run start:http | Alias of npm run start (no HTTP transport yet). | | npm run test | Run node:test once. | | npm run test:coverage | Run node:test with experimental coverage. | | npm run test:watch | Run node:test in watch mode. | | npm run lint | Run ESLint. | | npm run format | Run Prettier. | | npm run type-check | TypeScript type checking. | | npm run inspector | Run MCP Inspector against dist/index.js. | | npm run inspector:http | Alias of npm run inspector (no HTTP transport yet). | | npm run duplication | Run jscpd duplication report. | | npm run prepublishOnly | Lint, type-check, and build before publish. |

Project Structure

  src/
    index.ts        Entry point
    cli.ts          CLI parsing, logging bootstrap, shutdown handling
    server.ts       MCP server setup (stdio transport)
    tools.ts        Tool implementations
    schemas.ts      Zod input/output schemas
    config.ts       Configuration and constants
    types.ts        Shared types and error codes
    lib/            Shared utilities (LLM, retry, telemetry, prompt utils)

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 included in debug mode (sanitized and truncated to 200 chars).
• Google safety filters are always enabled.

Contributing

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

License

MIT License. See LICENSE for details.