# PromptTuner MCP
<img src="docs/logo.png" alt="PromptTuner MCP Logo" width="200">
[](https://www.npmjs.com/package/@j0hanz/prompt-tuner-mcp-server)
[](LICENSE)
[](https://nodejs.org/)
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`:
```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
```text
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.
