ClarifyPrompt MCP

A context-aware MCP prompt compiler that transforms vague prompts into platform-optimized prompts for 60+ AI platforms across 7 categories — grounded in your workspace signals (CLAUDE.md, AGENTS.md, .cursorrules, package.json), resolved intent, and the capabilities of the target model.

Send a raw prompt. ClarifyPrompt gathers the right context, resolves what you're actually trying to do, and returns a version specifically optimized for Midjourney, DALL-E, Sora, Runway, Higgsfield, ElevenLabs, Claude, ChatGPT, Cursor, or any of the 60+ supported platforms — with the right syntax, parameters, structure, and grounding.

New in 1.15.0: Nano Banana (Google Gemini 2.5 Flash Image) is now a built-in image platform — optimize_prompt(platform: "nano-banana") compiles image prompts in its native style (natural-language scene direction, photographic terms, edit-preserving-identity phrasing, in-image text). Plus latest-model compatibility across every provider: claude-sonnet-5, gpt-5/o-series, and Gemini reject temperature and/or max_tokens; the client now sends the right parameters (proactively for known reasoning ids, and learns the rest from a 400). Verified live against Anthropic, OpenAI, Gemini, and Ollama Cloud. See CHANGELOG.md.

New in 1.14.1: Portable-by-default text output — a chat/document/code prompt with no explicit platform now stays platform-neutral instead of quietly defaulting to Claude's idioms (XML tags); name a platform to opt into vendor-specific tuning. Plus the MCP Apps compose panel now shows a for <platform> badge and a clean Your prompt → Optimized before/after (with a show changes toggle) instead of an always-on diff. See CHANGELOG.md.

New in 1.14.0: An interactive compose panel via MCP Apps. In hosts that speak the io.modelcontextprotocol/ui extension (Claude Desktop, ChatGPT, Cursor, VS Code, …), compose_prompt renders a live panel: original-vs-optimized view, all six critique scores, the pipeline stages, and Accept / Revise actions — Accept records the outcome into ClarifyPrompt's memory loop, Revise sends your feedback back into the chat. One self-contained ui:// resource; hosts without the extension see zero change. See CHANGELOG.md.

New in 1.13.0: Plain-language rewrites. Optimized prompts now stick to common, everyday words instead of drifting into formal vocabulary ("use", never "utilize") — specificity comes from concrete details, not fancier synonyms. critique_prompt gained a 6th default dimension, plain_language, so auto_revise loops correct register drift automatically. Also fixed: an explicit mode (e.g. simple) is no longer silently dropped for small local models under compact system-prompt shaping. See CHANGELOG.md.

How It Works

ClarifyPrompt does two things a plain prompt template can't. Every output below is a real, unedited capture from optimize_prompt run against this repo (see Provenance at the end of this section).

1 — It knows each platform. Same raw prompt, different target, completely different output:

You write:    "a dragon flying over a castle at sunset"

→ Midjourney  A colossal, majestic dragon with shimmering scales soaring over a towering
              medieval stone castle, dramatic sunset sky with vibrant orange and deep purple
              hues, cinematic fantasy concept art, volumetric lighting, highly detailed
              --ar 16:9 --v 6.1 --s 250 --q 2

→ DALL-E      A majestic dragon with glowing crimson scales soars over a towering medieval
              stone castle, silhouetted against a vibrant orange and purple sunset sky.
              Rendered in a high-fantasy digital art style with dramatic, warm lighting and
              highly detailed textures, wide aspect ratio.

→ Nano Banana A majestic dragon with deep crimson scales and a leathery, bat-like wingspan
              glides through the warm, golden-hour sky just above a towering medieval castle
              made of weathered grey stone. ... Frame this as a wide cinematic landscape shot
              using a 24mm lens at f/8 for deep depth of field, camera positioned at a
              slightly elevated three-quarter angle... Aspect ratio 16:9.

Midjourney gets --ar/--v/--s/--q flags; DALL-E and Nano Banana get flag-free natural language — and Nano Banana layers in photographic direction (lens, f-stop, camera angle) and explicit mood, its documented style. Same idea, each platform's native dialect.

2 — It knows what you're working on. This is the part a template can't fake. Drop a vague one-liner while editing src/transport.ts in this very repo, and the engine grounds it in your real workspace — package.json, git state, the active file — and resolves intent before it shapes the output:

You write:    "add a configurable request timeout to the http transport"
              · active file: src/transport.ts   · resolved intent: production-code
              · grounded in: active-file · workspace-meta · git-state · environment ·
                target-model · platform-hints

→ Cursor      Implement a configurable request timeout for the HTTP transport in
              `src/transport.ts`.
              Requirements:
              1. Add a new environment variable `CLARIFYPROMPT_HTTP_TIMEOUT` … (default 30000 ms)
              2. Apply this timeout to all incoming requests in the streamable-http transport
              …
              5. Preserve existing behavior for stdio and a2a transports
              …
              The implementation should be added to the streamable-http section of
              `startTransport()`.
              (excerpted — the full rewrite has 7 numbered requirement groups)

Nothing in that one-line prompt mentioned the CLARIFYPROMPT_HTTP_* naming convention, the startTransport() entry point, or the stdio/a2a transports it must preserve — the engine read those from the active file and package.json and folded them in. That's the difference between rephrasing a prompt and compiling it against context.

3 — It can run the whole pipeline. clarify → ground/optimize → critique → revise, in one compose_prompt call — see Previously in 1.4.0 — the composable pipeline below.

Provenance. Image outputs captured via glm-5.2:cloud, the grounded code output via qwen3-coder:480b-cloud — both Ollama cloud models served over Ollama's OpenAI-compatible endpoint (LLM_API_URL=http://localhost:11434/v1), run through optimize_prompt against this repo on 2026-06-22 (the Nano Banana capture added 2026-07-03, same glm-5.2:cloud model). ClarifyPrompt is model-agnostic (any OpenAI-compatible API, local or hosted); outputs are model-dependent — yours will differ in wording, not in structure.

What's new in 1.15.0

Nano Banana, built in. Google's Gemini 2.5 Flash Image ("Nano Banana") is now a first-class image platform — optimize_prompt(category: "image", platform: "nano-banana") compiles your idea into its native prompting style: full-sentence scene direction (not keyword piles), photographic terminology for camera/lens/depth, explicit lighting, edit-phrasing that preserves subject identity, multi-reference character consistency, and reliable in-image text. Like every image platform, ClarifyPrompt compiles the prompt; you send it to the model.

Latest-model compatibility, every provider. Thinking-enabled models reject parameters clarifyprompt always sent: claude-sonnet-5 and OpenAI reasoning models reject temperature; gpt-5 / o-series also reject max_tokens (they require max_completion_tokens). Every call to them used to fail and degrade to the original prompt. Now the client sends the right body — proactively for well-known reasoning ids (no wasted round-trip) and, for anything the hints don't recognize (including future models), it learns from the 400 and retries. Models that accept the standard parameters are byte-identical. Verified live against Anthropic (claude-sonnet-5), OpenAI (gpt-5), Gemini (gemini-flash-latest), and Ollama Cloud (glm-5.2:cloud). Reasoning models think a lot — bump LLM_TIMEOUT_MS (the 30s default is often too short).

What's new in 1.14.1

Portable by default. When you optimize a text prompt (chat, document, code) without naming a platform, ClarifyPrompt now returns platform-neutral output — clean, portable structure that works in any assistant — instead of quietly defaulting to Claude's idioms (its <task>/<context> XML tags). Name a platform (platform: "claude", "chatgpt", … any of the 60) to opt into that platform's specific tuning. Creative categories (image/video/voice/music) are unchanged: their output needs a concrete platform format, so the flagship default (Midjourney, Runway, …) still applies.

Clearer compose panel. The MCP Apps panel now shows a for <platform> (or general purpose) badge, renders your original prompt as a labeled Your prompt block above the optimized output, and shows the optimized prompt plainly — with a show changes toggle for the word-level diff — instead of an always-on diff.

What's new in 1.14.0

compose_prompt now has a face. ClarifyPrompt ships an MCP Apps panel (extension io.modelcontextprotocol/ui) that supporting hosts render inline next to the tool result:

• Original vs optimized, as a word-level diff — see exactly what the compiler changed.
• Critique, visualized — all six dimensions (clarity, specificity, intent_alignment, format_fitness, length_appropriateness, plain_language) as score bars, with the verdict and the per-call stages audit trail as badges.
• Accept — one click records save_outcome(accepted) from the panel, feeding the few-shot memory loop, and quietly tells the model the prompt was accepted.
• Revise… — type what should change; the panel sends it back into the chat so the model re-composes.
• Clarification-aware — when the pre-clarify stage stops the chain with questions, the panel renders them (with suggested answers) instead of a diff.

Zero-risk rollout: the panel is one self-contained HTML resource (ui://clarifyprompt/compose-panel.html, inline CSS/JS — the extension sandbox blocks external requests) linked from compose_prompt's _meta.ui. Hosts without the extension ignore it entirely; the text + structuredContent output is byte-identical. Runs on the existing SDK ^1.29 floor. New deterministic npm run test:apps battery locks the wiring.

Also new: the eval harness gained a max_reading_grade check — a deterministic Flesch–Kincaid ceiling that locks 1.13.0's plain-language behavior as a measurable gate (formal-register slop scores ~20+; plain rewrites ~3–6).

What's new in 1.13.0

Plain-language rewrites, end to end. LLMs handle common, everyday wording more reliably than formal synonyms of the same meaning — and small local models, ClarifyPrompt's default targets, benefit the most. This release bakes that into every stage that shapes output wording:

• The optimizer prefers common words. A new core principle in the shared system prompt ("USE COMMON WORDS") applies to all 7 category strategies and both optimize_prompt and ground_prompt: never swap in a rarer word where a common one carries the same meaning. Detail means more information, not fancier words — specificity, structure, and constraints are untouched.
• critique_prompt gained a 6th default dimension: plain_language. It penalizes needlessly formal or rare vocabulary where a simpler word would do. Because the rewrite pass applies every suggestion from dimensions scoring below 7, auto_revise loops now correct register drift for free. Custom criteria overrides are unaffected.
• Fixed: explicit mode no longer silently dropped for small local models. Compact system-prompt shaping used to trim the mode instructions entirely — so mode: "simple" had no effect on 3B-class models. Every mode now survives compact shaping as a one-line rule.
• Two new eval fixtures guard the behavior: 31-plain-language-vocabulary (optimized output must not contain formal-register words) and 32-shape-compact-keeps-mode (the mode line reaches small models).

What's new in 1.12.1

The real fix for issue #3: thinking-channel models now reliably produce optimized prompts instead of intermittently returning empty content. Both gpt-oss:20b-cloud and glm-5.2:cloud went from empty ~40% of runs to 0%.

Re-investigating from scratch overturned the documented root cause. It was never "Ollama's /v1 shim drops the harmony final channel." These models spend their max_tokens budget on the thinking channel first and never reach the final channel — so content comes back "" (worse at higher reasoning effort). Two levers, applied together because different families honor different ones:

• A max_tokens floor (8192) for detected reasoning models — the universal lever. It attacks the root cause directly, so it works regardless of which thinking knob a family respects. It's a ceiling, not a target: short answers finish early, so no added latency.
• reasoning_effort: "low" — for families that respect it (gpt-oss), also trimming latency/cost. Tune with LLM_REASONING_EFFORT (low | medium | high).

The levers are genuinely family-specific: gpt-oss honors reasoning_effort but ignores Ollama's think; glm is the exact opposite — it ignores reasoning_effort, so only the budget floor saves it.

Detection is robust, not a hardcoded model list (which would rot as new models ship). "Is this a thinking model?" is answered, cached per model, by: (1) the runtime itself — Ollama's /api/show reports a thinking capability (this is how minimax-m3:cloud is detected, with no name match); (2) response-learning — any reasoning trace, or empty-content-with-tokens, marks that model thereafter (works for any provider); (3) a small name hint as last resort. Non-reasoning models stay byte-identical, and the name-agnostic empty-content retry is the final backstop. Validated on gpt-oss:20b-cloud, glm-5.2:cloud, and minimax-m3:cloud (all 0% empty on the first call).

The previously-proposed "switch to Ollama's native /api/chat" was a dead end — /api/chat with think:false still returns empty content for gpt-oss (it ignores it), and it would have added a fragile second code path.

What's new in 1.12.0

Step #7 — the final step — of the MCP modernization roadmap: ClarifyPrompt now speaks A2A (Agent-to-Agent), so other agents can call it to compile prompts. stdio stays the default; nothing about existing setups changes.

Set CLARIFYPROMPT_TRANSPORT=a2a and ClarifyPrompt comes up as a discoverable A2A peer on Node's built-in http (the only new dependency is the official @a2a-js/sdk, which itself pulls just uuid):

Endpoint	Purpose
GET /.well-known/agent-card.json	Agent card — discovery: identity, capabilities, the compile-prompt-for-platform skill
POST /a2a	A2A JSON-RPC 2.0: message/send, message/stream (SSE), tasks/get, tasks/cancel, …
GET /health	Liveness probe

CLARIFYPROMPT_TRANSPORT=a2a CLARIFYPROMPT_HTTP_PORT=3000 npx clarifyprompt-mcp
# → card:  http://127.0.0.1:3000/.well-known/agent-card.json
# → a2a:   POST http://127.0.0.1:3000/a2a   (message/send · message/stream)

The whole roadmap pays off here — one incoming A2A message flows through the same compose pipeline, and the primitives built in earlier steps map straight onto A2A semantics:

• Compile — a message/send with the raw prompt (plain text, or JSON { prompt, platform?, category?, … }) returns a task whose artifact carries the optimized prompt (text) plus the full structured compose result (data).
• Streaming (1.10.0 progress → A2A) — message/stream emits status-update events as each pipeline stage runs, then the artifact, over SSE.
• Cancellation (1.10.0 AbortSignal → A2A) — tasks/cancel aborts the in-flight compose within milliseconds and reports a terminal canceled state.
• Clarification (1.9.0 elicitation → A2A) — clarify is off by default for one-shot peers; opt in with pre_clarify: 'auto' | 'always' and an ambiguous prompt pauses the task in A2A's first-class input-required state with the questions (readable text + structured data). Answer on the same task and it compiles.

Configure the public base URL advertised in the card with CLARIFYPROMPT_A2A_BASE_URL (handy behind a proxy); port/host are shared with streamable-http. New deterministic npm run test:a2a battery drives card discovery, a live compile, the clarify round-trip, and SSE streaming.

What's new in 1.11.0

Step #6 of the MCP modernization roadmap: a pluggable transport factory — ClarifyPrompt can now serve over Streamable HTTP, the runway toward A2A and remote MCP hosts. stdio stays the default; nothing about existing setups changes.

Transports

Set CLARIFYPROMPT_TRANSPORT:

Value	Behaviour
stdio (default)	One server over stdin/stdout — exactly as before
streamable-http	MCP Streamable HTTP over Node's built-in http (no new deps): stateful sessions (mcp-session-id), SSE streaming, a /health probe
a2a	Serve as an A2A (Agent-to-Agent) peer — agent card, JSON-RPC + SSE (see 1.12.0 above)

HTTP knobs (in streamable-http / a2a mode): CLARIFYPROMPT_HTTP_PORT (3000), CLARIFYPROMPT_HTTP_HOST (127.0.0.1 — localhost-only by default), CLARIFYPROMPT_HTTP_PATH (/mcp, streamable-http only).

CLARIFYPROMPT_TRANSPORT=streamable-http CLARIFYPROMPT_HTTP_PORT=3000 npx clarifyprompt-mcp
# → POST http://127.0.0.1:3000/mcp  ·  GET http://127.0.0.1:3000/health

Tool/resource registration moved into an exported createServer() factory: stdio gets one server, streamable-http gets one per session (the SDK-recommended, GHSA-safe pattern — never shares a server across HTTP clients). New deterministic npm run test:http battery drives a full HTTP session.

What's new in 1.10.0

Step #5 of the MCP modernization roadmap, stable core: compose_prompt is cancellable and reports live progress. Model-agnostic, opt-in, fully back-compat.

Cancellation

An AbortSignal is plumbed through the entire LLM path (simpleGenerate → chat → fetch, combined with the per-call timeout) and every engine stage. When a client sends notifications/cancelled for a compose_prompt call, the in-flight model request aborts immediately and the revise loop stops at the next stage boundary — instead of running every iteration to completion. The signal reaches fetch regardless of which model/provider is configured.

Progress

Include a progressToken in the compose_prompt request _meta and the server emits notifications/progress at each stage (clarify / optimize / ground / critique) with a monotonic counter and a human message like optimizing prompt [iter 2/3]. Hosts can show a live status on a long multi-iteration compose. No token → no notifications, zero overhead.

Why not MCP tasks (yet)

Roadmap #5 named the MCP tasks API. It's still experimental/ in the SDK ("may change without notice"), its reference is ~600 lines, and no current client speaks the tasks/* protocol — so a full implementation would be unusable off-by-default code today. The real value (cancellable + progress-reporting compose) is delivered here on stable primitives; the experimental async-task wrapper is deferred to land with #7 (A2A), which the AbortSignal groundwork here already sets up. New deterministic npm run test:cancel battery locks the behavior.

What's new in 1.9.0

Step #4 of the MCP modernization roadmap: clarify_with_user can elicit answers through the host's native form UI. Opt-in, fully back-compat.

Interactive clarification

Pass elicit: true. On a client that supports MCP elicitation, the clarifying questions become a real form:

• each question is a field, options become enum dropdowns, and each suggestedAnswer is the field default (one-click accept);
• the user answers inline; the engine returns answers: [{ question, dimension, answer, usedSuggested }] with elicited: true.

Without elicit, on a non-capable client, or if the round-trip errors, the tool returns the same raw-questions JSON it always has — every existing caller is unaffected. decline / cancel are surfaced via elicitationAction.

This turns clarification from "here's a JSON blob of questions, you render it" into a first-class interactive moment in hosts like Claude Desktop. The mapping lives in a small pure module (src/engine/clarification/elicit.ts), reusable by compose_prompt's pre-clarify stage later. New deterministic npm run test:elicit battery (pure helpers + a live mock-client round-trip) locks it.

What's new in 1.8.0

Step #3 of the MCP modernization roadmap: the engine's read surfaces become browseable resource templates with argument autocompletion. No tool or engine behavior changes.

Resource templates

Four templates join the static clarifyprompt://categories, each backed by an existing engine getter:

URI template	What it reads
clarifyprompt://platforms/{category}/{id}	One platform's full config — resources/list enumerates all 60+ as individual URIs
clarifyprompt://traces/{date}	Optimization-trace summary index for a UTC day
clarifyprompt://packs/{id}	One loaded knowledge pack's metadata
clarifyprompt://memory/facts/{scope}	Live remembered facts under a scope

MCP hosts with a resource browser (Claude Desktop, Cursor) now get a navigable tree instead of a single static blob.

Autocomplete

completion/complete resolves the template variables: {category} → the 7 category ids, {id} → platform ids scoped by the chosen {category}, {date} → days with traces, pack ids, memory scopes. (MCP completion applies to prompt args + resource-template variables only — not tool inputs; ClarifyPrompt registers no prompts, so it lives on the templates.)

Capabilities

The server now advertises resources (with templates) and completions at initialize. New deterministic npm run test:resources battery locks the surface.

What's new in 1.7.1

Patch fixing #3: a silent empty optimized prompt from models whose answer didn't land in content.