LumabyteCo/clarifyprompt-mcp

Highlights

Four new MCP tools turn ClarifyPrompt's core operations into a composable pipeline. A single compose_prompt call runs the canonical happy path: clarify → ground OR optimize → critique → optional auto-revise — with a per-stage audit log so you can see exactly what ran.

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

New MCP tools (5)

• clarify_with_user — 1–3 targeted clarifying questions for ambiguous prompts, each with a suggested_answer you can accept verbatim, optional 2–4 quick-pick options, and a dimension tag. Short-circuits with clarificationNeeded: false on confident, well-formed prompts so it pipelines cleanly in front of optimize_prompt.
• ground_prompt — Strict, retrieval-augmented variant of optimize_prompt. Caller-provided sources 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.
• 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), returns an improvedPrompt you can drop in.
• compose_prompt — One MCP call runs the canonical pipeline. Auto-decides ground vs. optimize 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.
• UserProvidedSource injection point on optimize_prompt — A new top-priority slot in the curator. Both ground_prompt and compose_prompt use it under the hood.

Tool count: 16 → 20.

Eval harness + CI gate

• 20 deterministic YAML fixtures under evals/. Tool-aware: any fixture can target optimize_prompt (default) / clarify_with_user / ground_prompt / critique_prompt / compose_prompt via input.tool. npm run eval produces a console summary + self-contained dark-themed HTML report.
• CI-gated evals (opt-in). When OPENAI_API_KEY is set as a repo secret, GitHub Actions runs npm run eval against gpt-4o-mini as a release gate. Off by default; nothing leaves your machine without the secret.
• Eval baseline (qwen2.5-coder:7b-instruct-q4_K_M, single-model run): 16 passed / 1 failed / 3 skipped / 96% avg score across 20 fixtures. The lone failure (analyzer-creative-media) is a deliberately retained signal — 7B coder-tuned models can't reliably classify creative-media prompts. Multi-model matrix per evals/README.md.

Compatibility

• Same env-var surface as 1.3.x.
• Same publish surface (dist/ + packs/ + README.md + LICENSE + CHANGELOG.md + .env.example).
• All pre-1.4 tools and result shapes are unchanged. optimize_prompt's response shape is fully back-compat; userProvidedSources is a new optional field.

See CHANGELOG.md for the full list.

Install

npx clarifyprompt-mcp

Or as an MCP server:

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