Prompt Enhancer MCP

Local MCP server that uses a local Ollama model as a "Prompt Engineer" to rewrite rough prompt drafts into structured, optimized prompts before you send them to a paid API (Claude, GPT-4o, etc.) — saving tokens and improving output quality on the paid model.

Every request runs a self-critique pipeline (generate a first draft, then have the local model critique and refine it) unless the draft is trivial enough to skip the critique pass. Optional features layer on top: multi-persona brainstorming, a 1-line summary of what the critic changed, an in-memory response cache, and per-project default presets.

Model Agnostic: The server supports both local execution via Ollama (Llama 3, Mistral, Qwen, Phi, etc.) and cloud execution via the Anthropic API (Claude 3.5 Haiku, Sonnet, etc.). You can configure the engine and model per project or per request!

Prerequisites

• Node.js 20+

• Option A (Local Ollama): Ollama running locally with a model pulled, e.g.:

  ollama pull qcwind/qwen2.5-7B-instruct-Q4_K_M

• Option B (Remote Ollama): Ollama running on a machine you control (e.g. a home server exposed through a tunnel), with OLLAMA_BASE_URL (and optionally OLLAMA_EXTRA_HEADERS for an authenticating proxy) pointed at it. See Remote Ollama endpoint below. Useful when local model execution isn't available on your machine (e.g. a locked-down company laptop).

• Option C (Cloud): An Anthropic API Key (ANTHROPIC_API_KEY environment variable). Useful when neither local nor remote Ollama is an option.

Related MCP server: mcp-ollama-code-analyzer

Local Development

If you want to clone and modify the server locally:

npm install
npm run build
npm test

npm run build compiles src/ to dist/index.js. You can then run it via node dist/index.js.

CLI Usage

The package ships a global mcp command that you can use from the terminal. See the full reference in docs/cli.md.

Register with an MCP client

You do not need to clone the repository to use this MCP server. You can run it directly via npx.

All MCP clients register a server the same way. Below are the exact config file and key for each client this server has been used with.

Claude Desktop

Edit claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "prompt-enhancer": {
      "command": "npx",
      "args": [
        "-y",
        "--package=@nuno-morais/prompt-enhancer-mcp@latest",
        "prompt-enhancer-mcp"
      ]
    }
  }
}

Restart Claude Desktop for the change to take effect.

Claude Code

Add the same block to Claude Code's MCP settings (.claude/settings.json or via claude mcp add, depending on your Claude Code version):

{
  "mcpServers": {
    "prompt-enhancer": {
      "command": "npx",
      "args": [
        "-y",
        "--package=@nuno-morais/prompt-enhancer-mcp@latest",
        "prompt-enhancer-mcp"
      ]
    }
  }
}

Antigravity CLI / Gemini CLI

Both use the same config file and key: ~/.gemini/settings.json.

{
  "mcpServers": {
    "prompt-enhancer": {
      "command": "npx",
      "args": [
        "-y",
        "--package=@nuno-morais/prompt-enhancer-mcp@latest",
        "prompt-enhancer-mcp"
      ]
    }
  }
}

If the file already has an "mcpServers" object with other servers in it, add "prompt-enhancer" as a new key inside it rather than replacing the file.

Restart the CLI session after editing.

Cursor

Navigate to Cursor Settings -> Features -> MCP -> Add new MCP server.

• Name: prompt-enhancer

• Type: command

• Command: npx -y --package=@nuno-morais/prompt-enhancer-mcp@latest prompt-enhancer-mcp

Click "Add" and ensure the green light indicates a successful connection.

PI.dev, Zed, or Any Other MCP Client

Since this tool uses the standard Model Context Protocol, it can be connected to any IDE or agent that acts as an MCP client. If your client requires a JSON configuration (like Zed or PI.dev configurations), the pattern is typically the same:

{
  "mcpServers": {
    "prompt-enhancer": {
      "command": "npx",
      "args": [
        "-y",
        "--package=@nuno-morais/prompt-enhancer-mcp@latest",
        "prompt-enhancer-mcp"
      ]
    }
  }
}

If your client provides a UI to add tools instead of a configuration file, use the equivalent shell command: npx -y --package=@nuno-morais/prompt-enhancer-mcp@latest prompt-enhancer-mcp.

Calling the tool

The server exposes one tool, optimize_prompt:

{
  "draft": "quero um resumo do texto mas curto",
  "context": "MCP in this project means Model Context Protocol server",
  "target_model": "claude",
  "brainstorm": false,
  "explain": false,
  "session_id": "my-iteration-1",
  "auto_cot": true,
  "auto_guardrails": true,
  "show_stats": true,
  "engine": "ollama",
  "model": "llama3.1:8b"
}

Only draft is required — every other field has a default.

HTTP API

The optimizer can be accessed over HTTP, which is handy for scripts, editors, or any tool that can issue a simple curl request.

curl -X POST http://localhost:3000/optimize \
  -H "Content-Type: application/json" \
  -d '{
    "draft": "quero um resumo do texto mas curto",
    "target_model": "claude",
    "brainstorm": false,
    "explain": false
  }'

The response is a JSON object with a content array, exactly like the MCP tool returns. Example response:

{
  "content": [
    { "type": "text", "value": "<optimized‑prompt>" },
    { "type": "text", "value": "<optional‑explanation>" }
  ]
}

Set the port with the MCP_HTTP_PORT environment variable (default 3000). The endpoint is POST /optimize. No authentication or rate‑limit is applied – it is intended for local development use only.

The response is an MCP content array: one text block with the optimized prompt, plus a second text block when explain: true.

Configuration

Remote Ollama endpoint

By default, the server talks to Ollama at http://localhost:11434. To point it at a remote Ollama instance instead — for example, one exposed through a Cloudflare Tunnel or reverse proxy from a machine you control — set:

• OLLAMA_BASE_URL — the base URL of the remote Ollama instance, e.g. https://your-ollama-host.example.com. Defaults to http://localhost:11434.

• OLLAMA_EXTRA_HEADERS — a JSON object of extra HTTP headers to send with every Ollama request, e.g. {"CF-Access-Client-Id":"...","CF-Access-Client-Secret":"..."} if the endpoint sits behind an authenticating proxy such as Cloudflare Access. Defaults to no extra headers.

For the MCP server itself, set these in the env block of your MCP host's server configuration (e.g. .mcp.json):

{
  "mcpServers": {
    "prompt-enhancer": {
      "command": "prompt-enhancer-mcp",
      "env": {
        "OLLAMA_BASE_URL": "https://your-ollama-host.example.com",
        "OLLAMA_EXTRA_HEADERS": "{\"CF-Access-Client-Id\":\"...\",\"CF-Access-Client-Secret\":\"...\"}"
      }
    }
  }
}

For the standalone mcp CLI tool, use flags instead (these take precedence over the env vars above):

mcp --draft "quick note" --ollama-url https://your-ollama-host.example.com \
  --ollama-header "CF-Access-Client-Id=..." \
  --ollama-header "CF-Access-Client-Secret=..."

Behavior you should know about

• Self-critique pipeline: every non-trivial request makes 2 Ollama calls (draft, then critique/refine); explain: true adds a 3rd. A trivial draft (target_model: "generic", brainstorm: false, ≤15 words) skips the critique call entirely — 1 call instead of 2.

• Output lint: every response is checked (no extra LLM calls) for unresolved {{placeholders}}, acronym expansions not supported by your draft/context, and leaked meta-commentary. Problems are appended as a ⚠️ Prompt lint warnings block instead of silently shipping a broken prompt.

• Response cache: identical requests (same draft + target_model + brainstorm + explain + model) are cached in memory for 1 hour (100-entry LRU). A cache hit returns instantly with zero Ollama calls.

• Project presets: drop a .prompt-enhancer.json file anywhere in your project (the server searches upward from its working directory to find it, like .eslintrc) to set project-wide defaults.

  For Ollama:

  { "target_model": "claude", "explain": true, "show_stats": true, "model": "mistral" }

  For Anthropic (e.g. upgrading from Haiku to Sonnet):

  { "engine": "anthropic", "model": "claude-3-5-sonnet-latest", "target_model": "claude", "explain": true, "show_stats": true }

  Any parameter can be set this way. An explicit argument in a tool call always overrides the preset.

• Background Processes (Zero-Cost Latency): auto_cot and auto_guardrails are executed asynchronously in parallel with the first draft generation, causing zero extra wait time.

• Progress notifications: if your MCP client attaches a progressToken to its tools/call request, the server sends notifications/progress updates as the pipeline advances through its stages. Clients that don't ask for this see no behavior change.

• Domain context: pass context with a sentence or two of background (glossary, project description) whenever the draft contains ambiguous or domain-specific terms. The local model uses it only to interpret the draft — it is never rewritten into the output. Without it, small local models will guess what acronyms mean.

• Iterating on a prompt: pass a session_id on the first call, then call again with the same session_id and your feedback as the new draft ("make it shorter", "the MCP here is Model Context Protocol"). The server keeps the conversation and refines the previous prompt instead of starting over. Session requests always bypass the response cache.

Manual testing

test-manual.sh drives the server over raw JSON-RPC on stdio (MCP doesn't speak HTTP, so curl won't work here):

./test-manual.sh "<draft>" [target_model] [brainstorm] [explain]

Examples:

# Defaults (generic, no brainstorm, no explain)
./test-manual.sh "quero um resumo curto do texto"

# Claude-formatted, with the change-summary block
./test-manual.sh "I want a detailed and comprehensive summary of this long article covering many different topics in depth" claude false true

# Brainstorm mode
./test-manual.sh "preciso de ideias para o nome de uma nova cafetaria" generic true