Clarifyprompt MCP Server

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):

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:

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:

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.

• Reads all three thinking-channel field names (reasoning / thinking / reasoning_content) — fixes DeepSeek / qwen-thinking and similar.
• Retries once, then fails loudly when content is empty regardless of any thinking field. This covers the real issue #3 case: gpt-oss harmony output over Ollama's /v1 shim generates tokens (completion_tokens > 0) but returns content: "" with no thinking field. The engine now degrades to the original prompt + a surfaced error instead of returning blank.
• Genuinely recovering gpt-oss harmony output (via Ollama's native /api/chat) was tracked as a follow-up — resolved in 1.12.1, which proved the /api/chat path a dead end and fixed the actual root cause (a max_tokens floor + reasoning_effort for reasoning models; see the 1.12.1 notes above).
• New deterministic npm run test:thinking battery locks the regression with mocked responses (no live cloud dependency).

Verified: test:thinking, reasoning battery (gpt-oss degrades loudly; the genuine reasoner kimi-k2-thinking:cloud still returns real content), integration, day2, evals, wire.

What's new in 1.7.0

Step #2 of the MCP modernization roadmap: the entire tool surface migrated off the deprecated server.tool() shorthand (removed in SDK 2.0) onto server.registerTool(). No engine behavior changes; full back-compat.

What hosts get

• Titles — every tool has a human-readable display name ("Forget a fact", not memory_forget).
• Behavior annotations — all 23 tools declare readOnlyHint / destructiveHint / idempotentHint / openWorldHint. The three destructive tools (memory_forget, unload_pack, unregister_platform) are flagged for confirmation UIs; the seven read-only inspectors are flagged safe-to-call-freely; the seven tools that reach the network (LLM / embeddings / web search) carry openWorldHint: true.
• Structured output — every tool declares an outputSchema and returns structuredContent alongside the JSON text. Schemas are permissive by design (all-optional, passthrough) — they document the shape without ever rejecting engine output.

Back-compat

Text content is byte-identical for every tool — including the three array-returning list_* tools, whose text stays a bare array while structuredContent wraps it in an object per the MCP spec. Error returns unchanged. Verified: wire 7/7, integration 9/9, day2, 26/27 evals with zero output-validation errors.

Found during verification

#3 — cloud gpt-oss thinking-channel responses can yield an empty optimizedPrompt (remote API change exposing a pre-existing field-name gap in client.ts; fix targeted for 1.7.1).

What's new in 1.6.8

Housekeeping release closing the loops the 1.6.5→1.6.7 cascade opened. No engine code, MCP tool surface, platform, or env-var changes.

Changed

• CI matrix now tests Node 24 (current active LTS, EOL Apr 2028) alongside 18/20/22 across Ubuntu + macOS. The matrix previously tested two EOL Node versions but not the current LTS at all. Verified before merge that the native deps (better-sqlite3 + sqlite-vec) load and function on Node 24.16.0 in a toolchain-free node:24-slim container. engines stays >=18 — maximum compatibility, and we test what we claim.
• Publish runner moved Node 20 → 22, keeping an EOL runtime off the release-critical path (matches the Dockerfile base).

Process

• New ship-check CP-13 — lockfile regeneration safety encodes the lesson from the 1.6.5→1.6.6→1.6.7 cascade: a single npm install --package-lock-only silently dropped 4 of 5 sqlite-vec platform binaries (broke Linux CI) and pulled a within-caret better-sqlite3 bump that dropped Node 20 prebuilds (broke the Docker build). The check mandates full npm install on dep changes, a lockfile diff for dropped platform deps + native-dep version jumps, and a local slim-Docker load gate. Dogfooded on this release.

What's new in 1.6.7

Dockerfile patch. No engine code, MCP tool surface, platform, or env-var changes.

Fixed

• CI / docker build failed on 1.6.6 with npm error gyp ERR! find Python. Root cause: better-sqlite3@12.10.0 (released 2026-05) explicitly removed prebuilt binaries for Node.js v20 and v23 because Node 20 reached EOL in April 2026. The 1.6.6 lockfile regen pulled 12.10.0 within the ^12.9.0 caret, and node:20-slim doesn't have Python + a C++ toolchain to compile from source. Bumped the Dockerfile base to node:22-slim — current active LTS, still has working prebuilts.
• The non-Docker CI build matrix (Node 18 / 20 / 22 across macOS + Ubuntu) still passes because regular runners can compile-from-source as fallback. Only the slim Docker image stumbles.

Verified locally

docker build → green. Container can require('better-sqlite3') + require('sqlite-vec') cleanly. All 5 sqlite-vec platform binaries still in package-lock.json (1.6.6's fix held).

What's new in 1.6.6

Lockfile + harness patch following 1.6.5. No engine code, MCP tool surface, platform, or env-var changes. Ships the MCP-completeness audit doc.

Fixed

• package-lock.json lost 4 of 5 sqlite-vec platform binaries during the 1.6.5 SDK bump. My local npm install --package-lock-only retained only the maintainer's sqlite-vec-darwin-arm64 binary. npm ci on CI's Ubuntu runners failed with no such module: vec0 because sqlite-vec-linux-x64 wasn't in the lock. End-user npm install clarifyprompt-mcp@1.6.5 was never affected (the npm tarball doesn't ship a lockfile; users resolve platforms at install time). Regenerated with full npm install so all 5 platforms (darwin-arm64, darwin-x64, linux-arm64, linux-x64, windows-x64) are back.
• Eval harness HTML report writer crashed on ERRORED entries (evals/run.mjs:729). The pre-existing renderer assumed every non-skipped, non-filtered run had an evaluation.checks field, but errored runs carry an error field instead. Added an explicit errored-status branch — the harness now degrades gracefully and exits cleanly even when fixtures error.

Bundled docs

• docs/audits/mcp-completeness-2026-05.md — diagnostic audit of the engine's MCP surface against the current SDK + spec. Tool-by-tool registration table, resource gap analysis, SDK feature delta (1.12 → 1.29 → 2.0-alpha), capability declarations, transport refactor sketch, A2A feasibility note, and a sequenced 7-step modernization roadmap. The artifact behind next-session planning. No engine changes prescribed inline.

Numbers

• 5 sqlite-vec platforms in lockfile (was 1). npm audit --production: 0 vulnerabilities (unchanged). Tools: 23 (unchanged). Eval fixtures: 30 (unchanged).

What's new in 1.6.5

Security patch. No engine code changes, no MCP tool surface changes, no platform changes, no env-var changes.

Fixed

• CVE-2026-0621 — ReDoS in @modelcontextprotocol/sdk's UriTemplate regex (patched in SDK 1.25.2). The previous ^1.12.1 floor allowed vulnerable resolutions on stale npm caches; bumped to ^1.29.0 so the floor itself is patched.
• GHSA-345p-7cg4-v4c7 — Shared server/transport instances leak cross-client response data (patched in SDK 1.26.0). Not exploitable in practice for ClarifyPrompt (one host = one server instance) but the vulnerable code is now out of the dependency graph entirely.
• 7 transitive vulnerabilities (2 moderate, 5 high) in the SDK's bundled HTTP-transport substack (hono, express-rate-limit, fast-uri, ip-address, path-to-regexp, qs, @hono/node-server). Cleared via npm audit fix. Never affected runtime — ClarifyPrompt is stdio-only and doesn't load the HTTP transport — but they were noise in users' npm audit reports and made the install look unsafe.

Numbers

• npm audit --production → 0 vulnerabilities (was 2 SDK CVEs + 7 transitive).
• package-lock.json: net −336 lines (the old caret was pulling in heavy unused HTTP-transport ancillaries; the fix swapped them for slimmer alternates).
• Tools: 23 (unchanged). Platforms: 60+ (unchanged). Eval fixtures: 30 (unchanged).
• Wire test + integration battery + day2 + reasoning + 29/30 evals pass against the new floor on local Ollama. The one eval fail (analyzer-creative-media) is a pre-existing qwen-coder-7b classifier flake — verified SDK-independent by stash-reverting and re-running.

Why the floor bump matters

^1.12.1 was misleading documentation — caret resolution was actually pulling SDK 1.27.1 for any fresh npm install since early 2026. The floor bump aligns the declared baseline with what npm was already doing for most users while guaranteeing the floor for users on stale caches. It also positions us for the eventual 2.0.0-alpha migration when that line stabilizes (the modern SDK deprecates .tool() / .prompt() / .resource() shorthand registration in favor of registerTool() / registerPrompt() / registerResource() with title + outputSchema + annotations).

What's new in 1.6.4

Docs + process patch. No engine, MCP tool, or platform changes — but a meaningful cleanup of the pack-distribution model.

Pack registry consolidated back into the engine repo

LumabyteCo/clarifyprompt-packs (the separate community-pack registry created in 1.3 with the right principle but at the wrong scale) has been archived. Its three starter packs already lived in this repo's packs/ folder; the registry was meant to be the canonical home but in practice everything always shipped from here via the npm tarball. The drift caught up: higgsfield-creative-handbook shipped in 1.6.2 and never made it to the registry, even though the registry's own README told users to fetch packs from there.

Net result of 1.6.4:

• Single source of truth. packs/*.md knowledge packs + packs/platforms/*.yaml platform configs all live in clarifyprompt-mcp and ship in the npm tarball.
• New top-level Knowledge packs section in this README explains the loading model (load_knowledge_pack({source: "<url-or-path>", scope: ...})), the three starter packs + Higgsfield, the scope semantics, and how to contribute.
• New packs/README.md — pack authoring guide (frontmatter schema, chunk boundaries, quality bar). Lifted from the archived registry so the content isn't lost.
• Tombstone redirect on the archived repo. Anyone visiting clarifyprompt-packs lands on a banner pointing here.

When does the split come back?

When there's a forcing function: a community PR queue on packs alone, pack count >20, or divergent licensing/governance. Until then the maintenance cost of keeping two repos in sync wasn't paying for an audience that hadn't materialized.

Numbers

• Tools: 23 (unchanged).
• Platforms: 60+ (unchanged).
• Bundled knowledge packs: 4 (anthropic-brand-voice, higgsfield-creative-handbook, nextjs-14-best-practices, sox-compliance) — same as 1.6.2/1.6.3, just newly canonical.
• Eval fixtures: 30 (unchanged).
• Tarball size: unchanged from 1.6.3.

What's new in 1.6.3

Patch. The 1.6.2 CI tag-push run surfaced two real issues — fixed here without changing any engine code.

Fixed

• evals/fixtures/28-context-includes-git-state.yaml previously asserted git_branch_present: true, but GitHub Actions checks out in detached-HEAD mode where bundle.git.branch is correctly undefined (only the SHA + recent commits are populated). Relaxed to assert bundle_has_git: true only — that's what's actually invariant across local + CI environments.
• evals/fixtures/17-critique-strong-prompt-accepts.yaml asserted verdict: accept + overall_score_min: 7 on a strong prompt. gpt-4o-mini's judge calibrates stricter than qwen2.5-coder:7b's, and occasionally returned a malformed overall field that the parser defaulted to 0 → verdict=reject. The fixture's real intent is to verify engine wiring (5+ dimensions, the standard dimension names present, no harness error) — not to compare judge calibration across models. Dropped the verdict + tight score assertions; kept the wiring-level checks.
• README Glama badge swapped from inline <img> (sometimes broken via GitHub's camo proxy) to a shields.io text-link badge that's stable across all rendering surfaces.

Notes

• No engine code changes. No new MCP tools (still 23). No platform changes (still 60+). No env-var changes.
• Eval baselines unchanged on local Ollama. This is a CI-specific hardening — local runs against qwen-coder-7b produced the same results before and after.
• The CI publish-gate failure that appeared on the v1.6.2 tag push was downstream of the eval failure (Wait for evals workflow step blocked publish). Now that the underlying fixtures don't false-fail on gpt-4o-mini + detached-HEAD CI, the publish gate clears too.

What's new in 1.6.2

Patch. Two additive ships, both no-code-changes from the engine's perspective:

Higgsfield creative-handbook knowledge pack

packs/higgsfield-creative-handbook.md — a community-style markdown pack documenting Higgsfield's actual conventions: model-selection rules (which of the 13 models for which use case), Soul ID character-training workflow, camera-move vocabulary, prompt-structure pattern (long-form prose, not keyword tags), multi-reference editing, Marketing Studio modes, common pitfalls (don't translate Midjourney flags verbatim), output specs.

Load it explicitly:

load_knowledge_pack source="https://raw.githubusercontent.com/LumabyteCo/clarifyprompt-mcp/main/packs/higgsfield-creative-handbook.md"

…or, since it ships in the npm tarball, point at the installed copy. The Context Curator grounds Higgsfield-targeted prompts in this pack's chunks automatically via semantic retrieval. See the Knowledge packs section for the full loading + scoping model.

npm run matrix — multi-model eval matrix runner

evals/matrix.mjs runs npm run eval sequentially against N models and stitches the results into one side-by-side HTML (evals/matrix.html by default). Lights up the model-class-gated fixtures (shape-small-local-model / shape-mid-tier-model / shape-reasoning-model) that single-model runs skip, and exposes deltas like "qwen-7b fails analyzer-creative-media but gpt-4o-mini passes it" in a glance.

npm run matrix -- --models qwen2.5-coder:7b-instruct-q4_K_M,gpt-oss:20b-cloud,glm-5.2:cloud

Outputs a dark-themed table — rows = fixtures, columns = models, cells = pass / fail / skip / errored with tooltips showing which checks failed.

Companion fix: evals/run.mjs gains a --json-out <path> flag that writes structured per-model results (matrix.mjs uses it; CI agents can use it too).

Numbers

• No tool surface change. Still 23 MCP tools.
• No platform count change. 60+ platforms (packs/platforms/*.yaml unchanged).
• 30 → 30 fixtures (no new fixtures; matrix is tooling, not coverage).
• Tarball grows ~10 KB for the knowledge pack. evals/matrix.mjs is NOT in the tarball — it's a maintainer/contributor tool, not a runtime artifact.

What's new in 1.6.1

Patch release. Adds Higgsfield as a target platform in both image and video categories. No code changes — pure YAML platform-pack additions and one eval fixture.

Higgsfield is a multi-model creative platform that exposes its own MCP server at https://mcp.higgsfield.ai/mcp. Inside one connection you get:

Documentation truncated — see the full README on GitHub.