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.8.0: Roadmap step #3 — the engine's read surfaces are now browseable MCP resource templates with autocomplete: clarifyprompt://platforms/{category}/{id}, traces/{date}, packs/{id}, memory/facts/{scope}. resources/list enumerates all 60+ platforms as individual URIs; completion/complete autocompletes the template variables ("im"→image, "mid"(category=image)→midjourney). The server now advertises resources + completions capabilities. Read-only and additive — no tool or engine changes. See CHANGELOG.md.

How It Works

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

ClarifyPrompt returns (for Midjourney):
  "a majestic dragon flying over a medieval castle at sunset
   --ar 16:9 --v 6.1 --style raw --q 2 --chaos 30 --s 700"

ClarifyPrompt returns (for DALL-E):
  "A majestic dragon flying over a castle at sunset. Size: 1024x1024"

Same prompt, different platform, completely different output. ClarifyPrompt knows what each platform expects — and in 1.2.0, it also knows what you're working on.

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) is a tracked follow-up — out of scope for a patch. The silent-failure harm is resolved now.
• 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 llama3.2:3b,qwen2.5-coder:7b-instruct-q4_K_M,qwen2.5:14b-instruct-q4_K_M

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:

• Image: Soul 2.0, Soul Cinema, Soul Cast (character-consistent), Flux 2, Seedream 5, Nano Banana Pro, GPT Image 2
• Video: Cinema Studio, Sora 2, Veo 3.1, Kling 3.0, WAN 2.6, Seedance 2.0
• Workflows: Soul ID character training, Lipsync Studio, UGC Factory, Marketing Studio, virality_predictor

The 1.6.1 ClarifyPrompt platform entries surface Higgsfield's model identifiers and prompt-style conventions (long-form natural-language prose; composition + lighting + textures + mood; up to 4K images / 15 s video / Soul ID for character consistency) as syntax hints to the curator.

Recommended pattern: install both clarifyprompt-mcp AND Higgsfield's MCP in your client (Claude Desktop / Cursor / AI Butler / Claude Code). Use optimize_prompt(platform: 'higgsfield', ...) or compose_prompt(platform: 'higgsfield', ...) to compile, then pass the compiled prompt to Higgsfield's generate_image / generate_video tool. MCPs compose at the client; ClarifyPrompt stays at the "compile" layer.

29 → 30 eval fixtures. Same MCP tool surface as 1.6.0 (23 tools, 1 resource). No env-var changes.

What's new in 1.6.0

Four targeted additions across the engine's four pillars (memory / agentic / models / context), each shipped behind real eval fixtures. 3 new MCP tools (23 total). Fully back-compat with 1.5.x — no removed tools, no removed fields, no required env-var changes.

Memory — explicit fact CRUD (memory_remember, memory_forget, memory_list_facts)

Before 1.6, facts only entered persistent memory via reflection on save_outcome — implicit, LLM-extracted, after-the-fact. 1.6 adds the explicit path:

• memory_remember — directly insert a (subject, predicate, object) triple with explicit confidence. Source tagged user:explicit. Auto-embedded for future semantic retrieval.
• memory_forget — soft-delete (bi-temporal invalidated_at) a fact by id. Idempotent: re-forgetting an already-invalidated fact is a no-op and returns success: false cleanly.
• memory_list_facts — list live facts in a scope (default user), optionally filtered by predicate. Sorted by most-recently-observed.

This closes the obvious UX gap where the engine could only learn from outcomes — now users can say "remember I prefer X" directly.

Agentic — compose_prompt's new max_iterations revise loop

compose_prompt used to revise once (the critique's improvedPrompt replaced the optimization, if the verdict wasn't accept). 1.6 adds a loop:

{ "prompt": "...", "post_critique": true, "auto_revise": true, "max_iterations": 3 }

Each iteration after the first re-runs optimize + critique on the previous iteration's improved prompt. Stops at verdict=accept, no improvedPrompt to feed back, or the cap. pre_clarify only runs once (no point re-asking on a rewrite). The response includes a new iterations field showing how many fired. Hard cap of 5 to prevent cost runaways.

Models — per-stage model routing

Each compose stage can now target a different model:

{
  "prompt": "...",
  "clarify_model": "qwen2.5-coder:7b-instruct-q4_K_M",
  "optimize_model": "claude-sonnet-4-20250514",
  "critique_model": "gpt-4o-mini"
}

Run clarify on a cheap local model, optimize on the big-budget frontier model, critique on the cheap judge. The override flows through every layer — optimization.metadata.model and critique.judgeModel in the response reflect the actual model that ran each stage.

Context — git-state + environment signals

Two new signal collectors feed the Context Curator:

• bundle.git — current branch, short SHA, dirty flag, last 5 commit titles. Lets the engine ground prompts in "what you're iterating on" without you spelling it out. Detected via git rev-parse / git status / git log; fails soft when cwd isn't a repo.
• bundle.environment — nowIso / weekday / timezone (IANA from Intl.DateTimeFormat). Helps with time-sensitive prompts ("send this email tomorrow"). Pure JS, never fails.

Both are low-utility candidates in the curator (won't dominate budget) but surface as grounding sources when relevant.

Eval coverage

23 → 29 fixtures (6 new):

• 24 memory-remember-persists / 25 memory-forget-invalidates — Me1 CRUD round-trip
• 26 compose-loop-iterates — A1 loop infrastructure (new iterations_min / iterations_max checks)
• 27 compose-per-stage-models-honored — M1 per-stage routing (new optimization_model_eq / critique_model_eq checks)
• 28 context-includes-git-state / 29 context-includes-environment-time — C1 + C4 signals (new bundle_has_git / bundle_has_environment / git_branch_present checks)

Local baseline on qwen2.5-coder:7b: 25 passed / 1 failed / 3 skipped / 97% avg. The lone failure remains the persistent analyzer-creative-media model-class signal (untouched).

What's new in 1.5.2

The first release where CI's eval gate (against gpt-4o-mini) drove the diff. Three real fixes that the gate caught the moment we wired in the OPENAI_API_KEY secret:

• Memory store now supports any embedding dimension (#2). The persistent vec table was hardcoded to 768 dims (the nomic-embed-text default), so anyone configuring EMBED_MODEL=text-embedding-3-small (1536), voyage-3 (1024), embed-english-v3.0 (1024), or any non-768 model would hit Dimension mismatch: expected 768, got N on the first memory_search call. The store now derives the table name from the embedder's actual dimension and creates the dim-specific table at boot. Existing 768-dim installs are unaffected.
• LLM_TIMEOUT_MS env-var override on the LLM client. Default stays at 30s; users on slow hosted models can bump it. The eval workflow uses 120s for gpt-4o-mini.
• Eval harness hardened — no longer crashes when a tool throws an exception (the SDK returns plain-text error responses; the harness used to JSON.parse them and die). One bad fixture no longer tanks the whole run.
• Live evals badge. The evals.yml workflow runs on every push to main. The [![evals]](...) badge at the top of this README is its real-time status. Currently green at 20/0/3 · 100% on gpt-4o-mini.

No new MCP tools. No env-var surface changes (only an added optional LLM_TIMEOUT_MS). Fully back-compat with 1.5.x.

What's new in 1.5.1

A patch release on top of 1.5.0. Pure docs + ship-process improvements; runtime behavior is identical to 1.5.0.

• README marketing surfaces refreshed — the 1.5.0 release shipped with the README still on 1.4.0 in three places (headline blockquote, "What's new in X" heading, "cumulative through X" annotation). Every other version surface (package.json, package-lock.json, server.json, src/index.ts, CHANGELOG) was correct, but the prose drifted because nothing automated touched it. 1.5.1 fixes that.
• Two new ship-check audits — CP-11 (README marketing-surface coherence) hard-fails if any of the three above don't reference the current package.json#version. CP-12 (Platform-pack format validity) parses every packs/platforms/*.yaml and asserts schema validity. CP-11 was promoted to the user-scoped (cross-project) ship-check skill the same day, so future projects benefit too.
• No code changes. No new MCP tools. No new env vars. Same tarball anatomy as 1.5.0 plus a few hundred bytes of CHANGELOG.

What's new in 1.5.0

Built-in platforms become declarative. The 58+ hardcoded TypeScript platform arrays move to packs/platforms/*.yaml — adding a built-in platform is now a YAML edit, not a TS edit. The TypeScript layer becomes a runtime loader with a hardcoded fallback table. Malformed YAML can never soft-brick the server.

packs/platforms/
  chat.yaml       9 platforms
  code.yaml       9
  document.yaml   8
  image.yaml     10
  music.yaml      4
  video.yaml     11
  voice.yaml      7
  README.md      contributor docs

To add a new built-in platform: append an entry to the relevant category file, run npm run build, open a PR. No TS edit required. Custom-platform-via-runtime (register_platform) still works identically for user-installed platforms.

• Memory-layer eval coverage. The eval harness now supports setup: [{tool, args}, ...] — a list of MCP tool calls executed BEFORE the main input. Two new fixtures use it: one loads a knowledge pack inline and verifies the chunk surfaces in grounding.sources after the embed → store → retrieve → curate → ground pipeline; the other proves vector-search ranking quality. 23 fixtures total (was 20 in 1.4.0).
• Test infrastructure modernization. The integration + Day-2 test batteries used to assert literal version strings (1.3.0, 16 tools) and broke on every bump. Now they read EXPECTED_VERSION from package.json and assert presence of a tool set rather than a tool count. Future bumps don't break the tests.
• Adoption materials. docs/adoption/ ships with copy/paste-ready Show HN body, Reddit posts, Twitter thread, awesome-mcp-servers PR template, and catalog submission specs (mcp.so, Smithery, mcp-get, PulseMCP, modelcontextprotocol/servers).
• One new runtime dep: js-yaml promoted from devDependency for the platform loader (~200 KB).
• Same MCP tool surface as 1.4. 20 tools, 1 resource. No new tools; no removed tools; result shapes unchanged.

Previously in 1.4.0 — the composable pipeline

Four core operations as first-class MCP tools that compose. Use any tool standalone, or run the whole chain in one call:

  ┌─────────────┐     ┌─────────────────────┐     ┌──────────────┐
  │  clarify    │ →   │  ground OR optimize │ →   │   critique   │
  │  (optional) │     │       (core)        │     │  (optional)  │
  └─────────────┘     └─────────────────────┘     └──────────────┘

  one call = compose_prompt(prompt, [sources], post_critique, auto_revise, ...)

• clarify_with_user — Given an ambiguous draft, returns 1–3 targeted clarifying questions, each with a suggested_answer you can accept verbatim, optional 2–4 quick-pick options, and a dimension tag (audience/scope/format/length/tone/constraints/goal/platform). Short-circuits with clarificationNeeded: false on confident, well-formed prompts so it pipelines cleanly in front of optimize_prompt without a per-call latency tax.
• ground_prompt — The strict, retrieval-augmented variant of optimize_prompt. Caller-provided sources are pinned at the highest priority — above project rules, above pinned instructions — and tracked individually in the trace as user-source:N. Strict mode: zero non-empty sources → error, no silent fall-through. Per-source body cap (4000 chars) so a single huge paste can't dominate the budget.
• critique_prompt — LLM-as-judge. Scores a candidate prompt 0–10 across 5 default dimensions (clarity, specificity, intent_alignment, format_fitness, length_appropriateness) — or your own criteria — with per-dimension rationale + concrete suggestions, an overall score, and a verdict (accept / revise / reject). Below revise_threshold (default 7.0) it also returns an improvedPrompt you can drop in. Use it pre-flight ("is this prompt good enough for the expensive model?"), postmortem ("was the prompt the cause?"), or to A/B-pick the best of N optimization variants.
• compose_prompt — One MCP call runs the canonical pipeline. Auto-decides the ground vs. optimize branch from whether you passed sources. pre_clarify: 'auto' | 'always' | 'never'. post_critique: true adds a judge pass. auto_revise: true replaces final_prompt with the rewrite when the verdict isn't accept. Returns a per-stage stages audit array so the caller sees exactly what ran.
• Eval harness v0 — Deterministic regression tests under evals/. 20 YAML fixtures cover analyzer, shape, intent-overlay, grounding, clarify, critique, ground, and compose surfaces. npm run eval produces a console summary + self-contained dark-themed HTML report. Multi-model matrix is just bash: run LLM_MODEL=... npm run eval -- --report-path evals/report-X.html per model.
• CI-gated evals (opt-in) — When OPENAI_API_KEY is set as a repo secret, the eval harness runs in CI against gpt-4o-mini as a release gate. Off by default; nothing leaves your machine without the secret.
• 5 new MCP tools (20 total). optimize_prompt also gains a userProvidedSources injection point — both ground_prompt and compose_prompt use it under the hood, but it's available directly if you want explicit control without the strict-mode validation.

Carried over from 1.3: persistent memory + knowledge packs + reflective learning. The curator continues to score and fit grounding sources into the target model's remaining window. explain_last_curation still gives you a per-call breakdown of selected vs. rejected candidates with reasons.

What's in the box (cumulative through 1.8.0)

• Context Engine — auto-gathers workspace rules (CLAUDE.md, AGENTS.md, .cursorrules, .clinerules, clarify.md), detects frameworks and languages from package.json and sibling manifests, tracks an active file excerpt, and maintains a per-session ring buffer of recent optimizations and their outcomes.
• Unified PromptAnalyzer — one LLM call produces { category, intent, recommendedMode, confidence } together. 10 intents: production-code, brand-voice, stakeholder-comm, data-extract, creative-media, technical-spec, analysis, quick-draft, exploration, unknown. Intent beats surface keywords on ambiguity.
• Target-model-aware prompt shaping — system prompt, maxTokens, and temperature adapt to the downstream LLM's context window and the resolved intent. Small local models get a compact prompt; Claude/GPT-4/Gemini get the full richness.
• Grounding Context (single, priority-ordered) — user pinned instructions → project rules → active file → prior accepted examples → web search → workspace metadata → target-model hints → custom platform instructions → built-in syntax hints. No more parallel context silos.
• Session retrieval (save_outcome) — the caller reports accepted | edited | rejected per optimization; similar accepted outputs in the same session get injected as few-shot examples into future similar prompts. Persistent memory lands in 1.3.
• Local JSONL tracing — every optimization writes a structured trace line (now with shape, groundingSources, error fields) to $CLARIFYPROMPT_HOME/traces/YYYY-MM-DD.jsonl. Nothing is uploaded. Toggle via CLARIFYPROMPT_TRACE=off.
• Unified $CLARIFYPROMPT_HOME — one env var for everything ClarifyPrompt writes. Legacy CLARIFYPROMPT_CONFIG_DIR / CLARIFYPROMPT_DATA_DIR still work (deprecation hint, silenceable).
• 60+ platforms, 7 categories, custom platforms — the original core is unchanged and fully backward-compatible.
• Any LLM, any provider. One code path works with any OpenAI-compatible API — Ollama (local + cloud), LM Studio, vLLM, OpenAI, Google Gemini, xAI Grok, Groq, Mistral, DeepSeek, Cohere, Perplexity, Together, Fireworks, OpenRouter — plus Anthropic Claude directly. Reasoning models (o1/o3/o4, deepseek-reasoner, gpt-oss, *-thinking) are auto-detected and given a larger token budget so they actually produce content. See 15+ pre-configured provider examples below.
• Apache-2.0, forever. Open-source core, no relicensing.

Quick Start

With Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "clarifyprompt": {
      "command": "npx",
      "args": ["-y", "clarifyprompt-mcp"],
      "env": {
        "LLM_API_URL": "http://localhost:11434/v1",
        "LLM_MODEL": "qwen2.5:7b"
      }
    }
  }
}

With Claude Code

claude mcp add clarifyprompt -- npx -y clarifyprompt-mcp

Set the environment variables in your shell before launching:

export LLM_API_URL=http://localhost:11434/v1
export LLM_MODEL=qwen2.5:7b

With Cursor

Add to your .cursor/mcp.json:

{
  "mcpServers": {
    "clarifyprompt": {
      "command": "npx",
      "args": ["-y", "clarifyprompt-mcp"],
      "env": {
        "LLM_API_URL": "http://localhost:11434/v1",
        "LLM_MODEL": "qwen2.5:7b"
      }
    }
  }
}

With AI Butler

AI Butler is a self-hosted personal AI agent runtime — single Go binary, multi-channel chat, MCP ecosystem hub. Drop ClarifyPrompt into its mcp.servers config and the agent picks up all 23 tools as native capabilities, callable from any channel (web chat, terminal, Telegram, Slack, etc.). AI Butler discovers tools dynamically via MCP's tools/list, so adding / removing tools in ClarifyPrompt updates the agent's surface automatically — no config edits needed on the butler side.

Edit ~/.aibutler/config.yaml:

configurations:
  mcp:
    servers:
      - name: clarifyprompt
        command: clarifyprompt-mcp
        env:
          LLM_API_URL: "http://localhost:11434/v1"
          LLM_MODEL: "qwen3-vl:8b"

Restart AI Butler. The boot log confirms the tools are wired in:

The agent enumerates the full surface on request — every tool prefixed with clarifyprompt.:

📸 Screenshots above are from a 1.2-era integration (11 tools). Current 1.6.x exposes 23 tools — optimize_prompt, clarify_with_user, ground_prompt, critique_prompt, compose_prompt, plus the management / inspection / memory tools (memory_search, memory_remember, memory_forget, memory_list_facts, knowledge-pack tools, traces, custom platforms, etc.). AI Butler picks them up automatically via the MCP tools/list discovery; no config changes needed.

Drive the Context Engine end-to-end

You can preview what the engine would gather (without running the optimization) using inspect_context:

Then run the actual optimizer for any of the 60+ supported platforms:

Every optimization gets a single JSONL line in ~/.clarifyprompt/traces/YYYY-MM-DD.jsonl — strictly local, never uploaded. The list_traces tool turns that into a queryable summary with replay support via get_trace:

The full integration walkthrough — including all 11 tools driven from chat, configuration options, and natural-language usage examples — is in the AI Butler docs: Integrate an MCP Server.

Supported Platforms (58+ built-in, unlimited custom)

Documentation truncated — see the full README on GitHub.