Clarifyprompt Mcp

ClarifyPrompt MCP

ワークスペースのシグナル（CLAUDE.md、AGENTS.md、.cursorrules、package.json）、解決された意図、対象モデルの機能を踏まえ、曖昧なプロンプトを7カテゴリにわたる60以上のAIプラットフォーム向けに最適化する、コンテキスト対応のMCPプロンプトコンパイラーです。

生のプロンプトを送るだけで、ClarifyPromptが適切なコンテキストを収集し、実際に何をしようとしているのかを判断して、Midjourney、GPT Image 2、Veo、Runway、Kling、Seedance、Higgsfield、ElevenLabs、Suno、Claude、ChatGPT、Cursor、または対応する61のプラットフォームのいずれかに特化したバージョンを返します。適切な構文、パラメーター、構成、根拠が備わっています。

1.16.0 の新機能： プラットフォーム情報を最新化したリリースです。 すべての組み込みパックについて、最新のベンダー公式ドキュメント（2026-10-05）と照合して事実確認を行いました。Midjourney V8.x、Runway Gen-4.5、Veo 3.1、Kling 3.0/Omni、Pika 2.2、Suno v6、ElevenLabs v3、gpt-4o-mini-tts、GPT Image 2 の各項目に、verifiedAt の日付が記載されるようになりました。Sora はすべての箇所で廃止（OpenAI が Videos API を 2026-09-24 に終了し、代替はありません）。新しいプラットフォームとして、Seedance、ElevenLabs Music v2.5、Lyria 3.5 が加わりました。さらに、プラットフォーム情報の最新度を測るベンチマークも追加しました。最新の Ollama Cloud モデル 12 種に、プラットフォーム向けプロンプトを何も指示せずに作成させたところ、12/13 が古い Midjourney フラグを出力し、12/12 がすでに終了した Sora 向けの流暢なプロンプトを作成し、疑問を示したモデルはゼロでした。Grounded モードでは、同じ依頼をパックの事実情報を与えて再実行し、スコアが逆転します。ベンチマークとCHANGELOG.mdをご覧ください。

1.15.0 の新機能： Nano Banana（Google Gemini 2.5 Flash Image）が組み込みの画像プラットフォームになりました。optimize_prompt(platform: "nano-banana") は、ネイティブのスタイル（自然言語によるシーン指示、写真用語、アイデンティティを維持する編集表現、画像内テキスト）で画像プロンプトを整えます。さらに、すべてのプロバイダーで最新モデルとの互換性を確保しました。claude-sonnet-5、gpt-5/o-series、Gemini は temperature や max_tokens を拒否します。クライアントは、既知の推論モデル ID には事前に適切なパラメーターを送信し、それ以外のモデルについては 400 から学習して、正しいパラメーターを送るようになりました。Anthropic、OpenAI、Gemini、Ollama Cloud に対してライブ検証済みです。CHANGELOG.mdをご覧ください。

1.14.1 の新機能： デフォルトで移植性の高いテキスト出力を実現しました。明示的なプラットフォーム指定がない chat/document/code プロンプトは、Claude 独自の表現（XML タグ）を暗黙に使用せず、プラットフォームに依存しない状態を保ちます。ベンダー固有の調整を適用するには、プラットフォームを指定してください。さらに、MCP Apps の作成パネルに for <platform> バッジが表示され、常時表示の差分ではなく、見やすい Your prompt → Optimized の変更前後表示（show changes の切り替え付き）になりました。CHANGELOG.mdをご覧ください。

1.14.0 の新機能： MCP Apps によるインタラクティブな作成パネル。 io.modelcontextprotocol/ui 拡張に対応したホスト（Claude Desktop、ChatGPT、Cursor、VS Code など）では、compose_prompt がライブパネルを表示します。元のプロンプトと最適化後のプロンプトの表示、6 つすべての批評スコア、パイプラインのステージ、Accept / Revise アクションを利用できます。Accept は結果を ClarifyPrompt のメモリループに記録し、Revise はフィードバックをチャットに送り返します。自己完結型の ui:// リソースを 1 つ使用します。この拡張に対応していないホストでは、変更はありません。CHANGELOG.mdをご覧ください。

1.13.0 の新機能： 平易な言葉への書き換え。 最適化されたプロンプトでは、形式ばった語彙（「utilize」ではなく「use」）に流れず、よく使われる日常的な言葉を使うようになりました。具体性は、より凝った類義語ではなく、具体的な詳細によって高めます。critique_prompt にデフォルトで有効な第 6 の評価軸 plain_language が加わり、auto_revise の反復で文体のずれが自動的に修正されます。また、コンパクトなシステムプロンプトの構成時に、小規模なローカルモデルで明示的な mode（例：simple）が暗黙に削除される問題も修正しました。CHANGELOG.mdをご覧ください。

これが重要である証拠 — 主張ではなく、測定結果

このプロジェクトが存在する理由は何でしょうか？**「モデルに聞けばいい」という方法がいつの間にか通用しなくなったことを、実際に測定したからです。**モデルは学習時点で固定されますが、プラットフォームは毎月新バージョンをリリースし（古いバージョンは廃止します）。その結果、最新のモデルにプラットフォーム向けのプロンプトを尋ねるのは、2024年の百科事典に2026年の価格を尋ねるようなものです。

2026-10-05、公開ベンチマークを実施しました。最新の Ollama Cloud モデル12個に、実際に現行のプラットフォーム向けプロンプトを、同じ質問、同じモデルで2つの条件のもと作成するよう依頼しました。

• RAW — モデル単独で、手助けなし。通常のチャットでユーザーが得る結果です。
• GROUNDED — 同じ質問に対し、まず検証済みのプラットフォーム情報を追加します。これは ClarifyPrompt が optimize_prompt を呼び出すたびに追加するものと同じパックデータです。（これが「グラウンディング」の意味です。モデルは固定された記憶を信頼するのではなく、参照カードを読みます。）

各条件で132件の回答を評価し、同日にベンダーのドキュメントと照合して検証しました。RAW の全回答に対する完全な監査結果はこちらです：evals/dialect-benchmark/out/final.json。

結果を一行で示すと：

	RAW（モデル単独）	GROUNDED（パック情報を追加）
現行の方言	36	117
古い情報	35	0
混在／汎用	7 / 54	1 / 14

同じモデル。同じ質問。古い回答が35件から0件に。

実際には、次のような結果です。

• Sora 2、12件中12件。 OpenAI は 2026-09-24 に Videos API を終了しました（コンシューマー向けアプリは April 26）。その11日後、あらゆるモデルが — OpenAI 自身のオープンウェイトである GPT-OSS も含め — 存在しない製品向けの、流暢で自信に満ちたプロンプトを作成しました。誰も終了したことを指摘しませんでした。断りを含む回答も、知識のカットオフに関する注意書きも、ひとつもありませんでした。
• Midjourney、13件中12件。 全員が --v 6.1 を使いました。現行のデフォルトは6月以来、V8.2 です。一様に、メジャーバージョン2つ分も古い情報でした。
• パック情報を追加すると、すべてのモデルが結果を覆しました。 同じモデルで、Sora が終了したと答えたのは12個すべて、--v 8.2 を指定したのも12個すべてでした。RAW で最も成績が悪かったモデルも、現行3件／古い情報5件から、8件／0件になりました。

両条件の合計コストは $0.71 でした。 ハーネス、情報ファイル、評価スクリプトはこちらです：evals/dialect-benchmark/ — node evals/dialect-benchmark/run.mjs で再現できます。

率直に言えば、モデルは現行の方言を把握していません — しかし、維持管理された知識レイヤーがあれば、完璧に実行できます。**不足しているのは知識であり、製品となるのはパックレイヤーです。**そして、これこそが optimize_prompt の役割です。ライブドキュメントに照らして更新し、verifiedAt で日付を記録したパックを使って、呼び出しのたびにグラウンディングします。

仕組み

ClarifyPromptには、単純なプロンプトテンプレートにはできないことが2つあります。以下の出力はすべて、このリポジトリでoptimize_promptを実行した際の実際の未編集のキャプチャです（このセクションの最後にある出典を参照してください）。

**1 — 各プラットフォームを把握しています。**同じ生のプロンプトでも、対象が異なれば出力はまったく異なります。

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には--ar/--v/--s/--qフラグを、DALL-EとNano Bananaにはフラグを使わない自然言語を使用します。さらにNano Bananaは、写真表現を指示する内容（レンズ、F値、カメラアングル）や、ドキュメントに記載されたスタイルである明示的なムードを加えます。同じアイデアでも、各プラットフォーム固有の表現になります。

上のMidjourneyのキャプチャにある--v 6.1に注目してください。このキャプチャは実際のもので（2026-06-22）、モデルはすでにメジャーバージョンが2つも古いバージョンフラグを出力しました。Midjourneyの現在のデフォルトはV8.2です。モデルの重みは学習時点で固定されますが、プラットフォーム固有の表現は毎月変化します。このギャップを埋めるためにあるのが、ClarifyPromptの検証済みプラットフォームパック（verifiedAtで日付が記録され、最新のドキュメントに照らして更新されます）です。古くなる問題についてを参照してください。

2 — 作業中の内容を把握しています。ここはテンプレートでは真似できない部分です。このリポジトリでsrc/transport.tsを編集中に曖昧な一文を入力すると、エンジンは実際のワークスペース（package.json、gitの状態、アクティブなファイル）を根拠として、出力を整える前に意図を明確にします。

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)

この一文のプロンプトには、CLARIFYPROMPT_HTTP_*という命名規則も、startTransport()というエントリーポイントも、維持する必要があるstdio/a2aトランスポートも含まれていません。エンジンはアクティブなファイルとpackage.jsonからそれらを読み取り、出力に反映しました。これが、プロンプトを言い換えることと、コンテキストに照らしてコンパイルすることの違いです。

3 — パイプライン全体を実行できます。clarify → ground/optimize → critique → reviseの各処理を、1回のcompose_prompt呼び出しで実行できます。以下の1.4.0で追加 — 組み合わせ可能なパイプラインを参照してください。

**出典。**画像出力はglm-5.2:cloud、コンテキストに基づくコード出力はqwen3-coder:480b-cloudを使用してキャプチャしました。どちらもOllamaのクラウドモデルで、OllamaのOpenAI互換エンドポイント（LLM_API_URL=http://localhost:11434/v1）を通じて提供されています。2026-06-22に、このリポジトリでoptimize_promptを実行して取得しました（Nano Bananaのキャプチャは同じglm-5.2:cloudモデルを使用し、2026-07-03に追加しました）。ClarifyPromptはモデルに依存せず、ローカルまたはホスト型のOpenAI互換APIならどれでも利用できます。出力はモデルによって異なり、表現は変わりますが、構造は変わりません。

1.16.0 の新機能

プラットフォームの最新化リリースです。 パックの内容が古くなっていました。Midjourney は現在のデフォルトが V8.2 であるにもかかわらず、--v 6.1 のままで、動画パックには「Runway Gen-3」と「Google Veo 2」の記述が残っており、Higgsfield の項目はすでに使えないモデルに誘導していました。組み込みパックはすべて、2026-10-05 時点の各ベンダーの最新ドキュメントに照らして事実確認を行いました。検証済みの各項目には verifiedAt の日付が付与され、古さを確認、追跡し、CI で検出できるようになりました。

Sora を全面的に廃止しました。 OpenAI は 2026-04-26 に Sora アプリの提供を終了し、2026-09-24 には Videos API とすべての sora-2 モデル ID を終了しました。後継製品の発表はありません。パック、戦略ガイダンス、A2A カード、ツールドキュメント、README、npm のキーワードから削除しました。新たに第一級プラットフォームとして追加したのは、seedance、eleven-music（ElevenLabs Music v2.5）、lyria（Google 3.5）です。

方言の最新性を測るベンチマーク（evals/dialect-benchmark/） — このプロジェクトの存在意義を示すものです。最新の Ollama Cloud モデル 12 種に、プラットフォーム向けのプロンプトを何も指示せずに書かせ、同じ検証済みの事実に基づいて回答を採点しました。

• 回答した 13 モデルのうち 12 モデルが、古い Midjourney の --v 6.x を出力しました（V8.2 は 6 月からデフォルトです）
• 回答した 12 モデルすべてが、Sora 2 向けの流暢なプロンプトを書きました。実行の 11 日前に OpenAI が終了した製品です。OpenAI 自身のオープンウェイトである GPT-OSS も含まれます。知識の期限について言及したり、回答を控えたりしたモデルは 0 でした。
• グラウンデッドモード（BENCH_GROUNDED=1）では、同じ依頼をシステムプロンプトにパックの事実を含めて再実行します。同じモデル構成での実行前後の差は、このプロジェクトの価値を測定可能な形で示しています。モデルは最新の方言を 把握していません が、更新される知識レイヤーがあれば、それを活用できます。
• 追加の発見：ベンチマークの対照モデル 2 つが、実行中に HTTP 410 retired を返しました（qwen3.5:397b、2026-09-25）。方言だけでなく、モデルも入れ替わります。

1.15.0 の新機能

Nano Banana を標準搭載しました。 Google の Gemini 2.5 Flash Image（「Nano Banana」）が、第一級の画像プラットフォームとして利用可能になりました。optimize_prompt(category: "image", platform: "nano-banana") を使うと、アイデアをネイティブなプロンプト形式に変換します。キーワードの羅列ではなく、文によるシーン描写、カメラ・レンズ・被写界深度に関する写真用語、明示的な照明指定、被写体の同一性を保つ編集指示、複数の参照画像を用いたキャラクターの一貫性、画像内テキストの安定した生成に対応します。他のすべての画像プラットフォームと同様に、ClarifyPrompt がプロンプトを組み立て、モデルへの送信はユーザーが行います。

すべてのプロバイダーで最新モデルに対応しました。 思考機能を有効にしたモデルでは、ClarifyPrompt が常に送信していたパラメーターが拒否されていました。claude-sonnet-5 と OpenAI の推論モデルは temperature を拒否し、gpt-5 と o シリーズも max_tokens を拒否します（max_completion_tokens が必要です）。そのため、従来は呼び出しのたびに失敗し、元のプロンプトにフォールバックしていました。現在は適切なリクエスト本文を送信します。既知の推論モデル ID には 事前に対応 するため、無駄な往復はありません。ヒントで識別できないモデル（今後登場するモデルも含む）については、400 エラーから学習して再試行します。標準パラメーターを受け付けるモデルでは、送信内容に一切変更はありません。Anthropic（claude-sonnet-5）、OpenAI（gpt-5）、Gemini（gemini-flash-latest）、Ollama Cloud（glm-5.2:cloud）で実環境の検証を行いました。推論モデルは多くの時間を思考に費やすため、LLM_TIMEOUT_MS を延長してください（デフォルトの 30 秒では短すぎることがよくあります）。

1.14.1 の新機能

デフォルトでポータブルに。 プラットフォームを指定せずにテキストプロンプト（chat、document、code）を最適化すると、ClarifyPrompt は Claude 固有の表現（<task>／<context> の XML タグ）を暗黙的にデフォルトとして使うのではなく、どのアシスタントでも使える、すっきりとしたポータブルな構造のプラットフォーム非依存の出力を返すようになりました。特定のプラットフォーム向けに最適化するには、プラットフォーム（platform: "claude"、"chatgpt"、… 60 種類のいずれか）を指定します。クリエイティブなカテゴリ（画像／動画／音声／音楽）は変更されていません。出力には具体的なプラットフォーム形式が必要なため、これまでどおり代表的なプラットフォーム（Midjourney、Runway、…）がデフォルトで適用されます。

より分かりやすい作成パネル。 MCP Apps パネルに for <platform>（または general purpose）バッジが表示されるようになりました。また、最適化後の出力の上に、元のプロンプトを あなたのプロンプト というラベル付きのブロックで表示し、最適化後のプロンプトをそのまま表示します。常時表示の差分表示に代わり、単語単位の差分を確認できる 変更を表示 トグルも追加されました。

1.14.0 の新機能

compose_prompt に画面が追加されました。 ClarifyPrompt に MCP Apps パネル（拡張機能 io.modelcontextprotocol/ui）が追加されました。対応ホストでは、ツールの結果の横にインラインで表示されます。

• 元のプロンプトと最適化後のプロンプトを単語単位の差分で表示 — コンパイラーによって変更された箇所を正確に確認できます。
• 視覚化された批評 — 6 つの評価軸（clarity、specificity、intent_alignment、format_fitness、length_appropriateness、plain_language）をスコアバーで表示し、判定結果と呼び出しごとの stages 監査証跡をバッジで表示します。
• 承認 — パネルからワンクリックで save_outcome(accepted) を記録して少数例メモリループに反映し、プロンプトが承認されたことをモデルに通知します。
• 修正… — 変更内容を入力すると、パネルからチャットに送り返し、モデルに再構成させることができます。
• 明確化への対応 — 事前明確化ステージが質問を出して処理チェーンを停止した場合、パネルには差分ではなく、質問（推奨回答付き）が表示されます。

リスクのない段階的な導入です。このパネルは、単独で動作する 1 つの HTML リソース（ui://clarifyprompt/compose-panel.html、インライン CSS／JS — 拡張機能のサンドボックスが外部リクエストをブロックします）で、compose_prompt の _meta.ui からリンクされています。拡張機能に対応していないホストでは完全に無視されます。テキストと structuredContent の出力はバイト単位で同一です。既存の SDK ^1.29 の要件を維持しています。新たに追加された決定論的な npm run test:apps テストスイートが、配線を固定します。

そのほかの新機能として、評価ハーネスに max_reading_grade チェックが追加されました。決定論的な Flesch–Kincaid の上限値により、1.13.0 の平易な言葉遣いを測定可能なゲートとして固定します（形式的な文体の冗長な文は約 20 以上、平易な書き換えは約 3～6 になります）。

1.13.0 の新機能

最初から最後まで、平易な表現に書き換えます。 LLM は、同じ意味を持つ形式的な同義語よりも、一般的で日常的な表現を安定して扱えます。ClarifyPrompt がデフォルトで対象とする小型のローカルモデルには、特に大きな効果があります。このリリースでは、出力の表現に影響するすべての段階に、この考え方を取り入れました。

• オプティマイザーが一般的な語を優先します。 共有システムプロンプトに新たな基本原則（「USE COMMON WORDS」）を追加し、7 つのカテゴリー戦略と optimize_prompt、ground_prompt の両方に適用します。同じ意味を表せる一般的な語がある場合、より珍しい語に置き換えてはいけません。詳細とは、より多くの情報を含めることであり、凝った語を使うことではありません。具体性、構成、制約はそのまま維持されます。
• critique_prompt に 6 つ目のデフォルト評価軸 plain_language が加わりました。 より簡単な語で十分な場合に、不要に形式的な語彙や珍しい語彙を使うと減点します。スコアが 7 未満の評価軸からの提案はすべて書き換えパスで適用されるため、auto_revise のループで、文体のずれも追加コストなしで修正されるようになりました。カスタムの criteria による上書きには影響しません。
• 修正：小型のローカルモデルで明示的に指定した mode が、暗黙のうちに削除されなくなりました。 これまでは、システムプロンプトをコンパクトに整形する際にモードの指示が完全に削られることがあり、3B クラスのモデルでは mode: "simple" が効果を発揮しませんでした。現在は、どのモードもコンパクト整形後に 1 行のルールとして残ります。
• 動作を保証する新しい評価用フィクスチャを 2 つ追加しました。 31-plain-language-vocabulary（最適化後の出力に形式的な文体の語が含まれないこと）と 32-shape-compact-keeps-mode（モードの行が小型モデルに届くこと）です。

1.12.1 の新機能

Issue #3 に対する真の修正です。思考チャネルを使うモデルが、最適化されたプロンプトを安定して生成するようになりました。 断続的に空のコンテンツを返すことがなくなります。gpt-oss:20b-cloud と glm-5.2:cloud のどちらも、実行の約 40% で空だった状態から 0% になりました。

根本原因を改めて調査した結果、文書に記載されていた原因は誤りだと判明しました。原因は決して「Ollama の /v1 shim が harmony の final チャネルを破棄する」ことではありません。これらのモデルは max_tokens の予算を最初に思考チャネルで使い切り、final チャネルに到達しません。そのため content は "" になります（推論の強度が高いほど、この問題は悪化します）。モデルファミリーによって有効なレバーが異なるため、次の 2 つを組み合わせて適用します。

• 推論モデルとして検出されたモデルに対する max_tokens の下限（8192） — 汎用的なレバーです。根本原因に直接対処するため、各モデルファミリーがどの思考設定を尊重するかに関係なく機能します。これは上限であり、目標値ではありません。短い回答はすぐに完了するため、遅延は増えません。
• reasoning_effort: "low" — これを尊重するモデルファミリー（gpt-oss）では、遅延とコストも削減します。LLM_REASONING_EFFORT（low | medium | high）で調整できます。

それぞれのレバーが有効なモデルファミリーは、実際に異なります。gpt-oss は reasoning_effort を尊重しますが、Ollama の think は無視します。glm はその正反対で、reasoning_effort を無視するため、予算の下限設定だけが有効です。

検出は堅牢で、新しいモデルの登場とともに古くなるハードコードされたモデル一覧には依存しません。「これは思考モデルか？」という判定結果はモデルごとにキャッシュされ、次の方法で取得されます。（1）ランタイム自体 — Ollama の /api/show が thinking 機能を報告します（minimax-m3:cloud は名前の照合なしでこの方法により検出されます）。（2）レスポンスからの学習 — 推論のトレース、またはトークンがあるのにコンテンツが空の場合、そのモデルを以降、思考モデルとして扱います（どのプロバイダーでも機能します）。（3）最後の手段としての、簡易的な名前ヒント。推論を行わないモデルの動作はバイト単位で変わらず、名前に依存しない空コンテンツの再試行が最後の安全策となります。gpt-oss:20b-cloud、glm-5.2:cloud、minimax-m3:cloud で検証済みです（いずれも初回呼び出し時の空コンテンツは 0%）。

以前提案された「Ollama のネイティブ /api/chat に切り替える」案は、行き止まりでした。think:false を指定した /api/chat でも gpt-oss は空のコンテンツを返します（gpt-oss がこの設定を無視するため）。また、壊れやすい 2 つ目のコードパスを追加することにもなります。

1.12.0 の新機能

MCP モダナイゼーションロードマップのステップ #7 — 最終ステップです。ClarifyPrompt が A2A（Agent-to-Agent） に対応し、ほかのエージェントから呼び出してプロンプトを作成できるようになりました。デフォルトは引き続き stdio です。既存のセットアップに変更はありません。

CLARIFYPROMPT_TRANSPORT=a2a を設定すると、ClarifyPrompt は Node 組み込みの http 上で検出可能な A2A ピアとして起動します（追加される依存関係は公式の @a2a-js/sdk のみで、これ自体が取り込むのは uuid だけです）。

エンドポイント	用途
GET /.well-known/agent-card.json	エージェントカード — 検出用情報：ID、機能、compile-prompt-for-platform スキル
POST /a2a	A2A JSON-RPC 2.0：message/send、message/stream（SSE）、tasks/get、tasks/cancel、…
GET /health	稼働状態の確認

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)

ロードマップ全体の成果がここに結実します。受信した A2A メッセージは同じ作成パイプラインを通り、これまでのステップで構築した基本機能が A2A のセマンティクスにそのまま対応します。

• 作成 — 生のプロンプト（プレーンテキスト、または JSON { prompt, platform?, category?, … }）を指定した message/send は、最適化されたプロンプト（テキスト）と完全な構造化作成結果（データ）を含む アーティファクト を持つタスクを返します。
• ストリーミング（1.10.0 の進捗 → A2A） — message/stream は、各パイプラインステージの実行中に status-update イベントを発行し、その後アーティファクトを SSE で送信します。
• キャンセル（1.10.0 の AbortSignal → A2A） — tasks/cancel は実行中の作成を数ミリ秒以内に中止し、最終状態として canceled を報告します。
• 確認（1.9.0 の elicitation → A2A） — 1 回限りのピアでは、確認機能はデフォルトで無効です。pre_clarify: 'auto' | 'always' で有効にすると、曖昧なプロンプトによってタスクは A2A の第一級の input-required 状態になり、質問（読みやすいテキストと構造化データ）が示されます。同じタスクに回答すると、作成が行われます。

カードで公開するベース URL は CLARIFYPROMPT_A2A_BASE_URL で設定できます（プロキシの背後で使う場合に便利です）。ポートとホストは streamable-http と共用です。新しい決定論的な npm run test:a2a テスト一式では、カードの検出、実際の作成、確認の往復、SSE ストリーミングを実行します。

1.11.0 の新機能

MCP モダナイゼーションロードマップのステップ #6：プラグイン可能な トランスポートファクトリー を導入しました。ClarifyPrompt は Streamable HTTP 経由でも提供できるようになり、A2A やリモート MCP ホストに向けた準備が整いました。デフォルトは引き続き stdio です。既存のセットアップに変更はありません。

トランスポート

CLARIFYPROMPT_TRANSPORT を設定します。

値	動作
stdio（デフォルト）	stdin/stdout 経由の単一サーバー — これまでとまったく同じです
streamable-http	Node 組み込みの http を使用した MCP Streamable HTTP（新しい依存関係なし）：ステートフルセッション（mcp-session-id）、SSE ストリーミング、/health プローブ
a2a	A2A（Agent-to-Agent） ピアとして提供 — エージェントカード、JSON-RPC + SSE（上記の 1.12.0 を参照）

HTTP 設定（streamable-http / a2a モード）：CLARIFYPROMPT_HTTP_PORT（3000）、CLARIFYPROMPT_HTTP_HOST（127.0.0.1 — デフォルトでは localhost のみ）、CLARIFYPROMPT_HTTP_PATH（/mcp、streamable-http のみ）。

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

ツールとリソースの登録は、エクスポートされた createServer() ファクトリーに移されました。stdio ではサーバーを 1 つ、streamable-http ではセッションごとに 1 つ使用します（SDK が推奨する GHSA 対策済みのパターンで、HTTP クライアント間でサーバーを共有することはありません）。新しい決定論的な npm run test:http テスト一式では、HTTP セッション全体を実行します。

1.10.0 の新機能

MCP モダナイゼーションロードマップのステップ #5、安定したコア機能です。compose_prompt がキャンセル可能になり、リアルタイムの進捗を報告します。 モデル非依存で、オプトイン方式、完全な後方互換性を備えています。

キャンセル

AbortSignal は LLM の処理経路全体（simpleGenerate → chat → fetch。呼び出しごとのタイムアウトと組み合わせます）と、すべてのエンジンステージに渡されます。クライアントが compose_prompt 呼び出しに対して notifications/cancelled を送信すると、処理中のモデルリクエストは直ちに中断され、修正ループは次のステージ境界で停止します。すべての反復が完了するまで実行されることはありません。設定されているモデル／プロバイダーにかかわらず、シグナルは fetch に届きます。

進捗

compose_prompt リクエストの _meta に progressToken を含めると、サーバーは各ステージ（clarify／optimize／ground／critique）で、単調増加するカウンターと optimizing prompt [iter 2/3] のような人間向けメッセージを含む notifications/progress を送信します。ホストは、複数回の反復を伴う長時間の compose の進捗状況をリアルタイムで表示できます。トークンがなければ通知は送信されず、オーバーヘッドもゼロです。

MCP タスクをまだ採用しない理由

ロードマップの #5 では MCP tasks API が挙げられていました。これは今も SDK の experimental/ にあり（「予告なく変更される可能性があります」）、リファレンスは約 600 行に及び、現在 tasks/* プロトコルに対応しているクライアントもありません。そのため、完全な実装を行っても、現時点ではデフォルトで無効なまま使われないコードになってしまいます。実際に必要な機能（キャンセル可能で進捗を報告する compose）は、ここで 安定したプリミティブを使って提供します。実験的な非同期タスクのラッパーは #7（A2A）とともに追加する予定です。ここで整えた AbortSignal の基盤も、その実装に役立ちます。新しい決定論的な npm run test:cancel テスト一式で、この動作を固定します。

1.9.0 の新機能

MCP 近代化ロードマップのステップ #4：clarify_with_user がホスト標準のフォーム UI を通じて回答を引き出せるようになりました。オプトイン方式で、完全な後方互換性があります。

対話型の明確化

elicit: true を渡します。MCP elicitation に対応したクライアントでは、明確化の質問が実際のフォームになります。

• 各質問はフィールドになり、options は列挙型のドロップダウンに、各 suggestedAnswer はフィールドのデフォルト値（ワンクリックで承認可能）になります。
• ユーザーがフォーム内で回答すると、エンジンは elicited: true とともに answers: [{ question, dimension, answer, usedSuggested }] を返します。

elicit が指定されていない場合、クライアントが非対応の場合、またはラウンドトリップでエラーが発生した場合、ツールは従来どおり同じ生の質問 JSON を返します。既存の呼び出し元には影響しません。decline／cancel は elicitationAction を通じて通知されます。

これにより、明確化は「質問の JSON データを渡すので、表示方法はそちらで実装してください」から、Claude Desktop などのホストにおける第一級の対話型体験へと変わります。マッピングは小規模な純粋モジュール（src/engine/clarification/elicit.ts）に実装しており、後ほど compose_prompt の事前明確化ステージでも再利用できます。新しい決定論的な npm run test:elicit テスト一式（純粋ヘルパーと、モッククライアントを使った実際のラウンドトリップ）で、この動作を固定します。

1.8.0 の新機能

MCP 近代化ロードマップのステップ #3：エンジンの読み取り用インターフェイスが、引数の自動補完に対応した参照可能なリソーステンプレートになりました。ツールやエンジンの動作に変更はありません。

リソーステンプレート

既存のエンジン getter をそれぞれ使う 4 つのテンプレートが、静的な clarifyprompt://categories に加わりました。

URI テンプレート	読み取る内容
clarifyprompt://platforms/{category}/{id}	1 つのプラットフォームの完全な設定 — resources/list は、60 件以上あるすべてのプラットフォームを個別の URI として列挙します
clarifyprompt://traces/{date}	UTC 日付ごとの最適化トレースの概要インデックス
clarifyprompt://packs/{id}	読み込み済みナレッジパック 1 件のメタデータ
clarifyprompt://memory/facts/{scope}	スコープ内で現在記憶されている事実

リソースブラウザーを備えた MCP ホスト（Claude Desktop、Cursor）では、単一の静的データではなく、ナビゲーション可能なツリーが表示されます。

自動補完

completion/complete はテンプレート変数を補完します。{category} → 7 つのカテゴリ ID、{id} → 選択した {category} に対応するプラットフォーム ID、{date} → トレースがある日付、パック ID、メモリースコープ。（MCP の補完が対象とするのは、プロンプト引数とリソーステンプレート変数のみで、ツール入力は対象外です。ClarifyPrompt はプロンプトを登録しないため、補完はテンプレートに対して行われます。）

機能

サーバーは initialize 時に resources（テンプレートを含む）と completions をアドバタイズするようになりました。新しい決定論的な npm run test:resources テスト一式で、提供範囲を固定しています。

1.7.1 の新機能

#3 を修正するパッチです。モデルの回答が content に入らず、最適化されたプロンプトが無言で空になる問題を修正しました。

• 3 種類の思考チャネルのフィールド名すべてを読み取ります（reasoning / thinking / reasoning_content）。DeepSeek / qwen-thinking などでの問題を修正します。
• 思考フィールドの有無にかかわらず、コンテンツが空の場合は1 回再試行し、それでも空ならエラーを明示します。これは issue #3 の実際のケースを対象としています。Ollama の /v1 shim 経由の gpt-oss harmony 出力ではトークンが生成され（completion_tokens > 0）、思考フィールドがないまま content: "" が返されます。エンジンは空の結果を返すのではなく、元のプロンプトにフォールバックし、error を表面化するようになりました。
• Ollama のネイティブ /api/chat 経由で gpt-oss harmony 出力を実際に復旧させる対応は、後続課題として追跡されていました。1.12.1 で解決済みです。/api/chat 経路は行き止まりであることが判明し、実際の根本原因（max_tokens の下限と、推論モデル向けの reasoning_effort。上記の 1.12.1 の注記を参照）が修正されました。
• モックレスポンスを使う新しい決定論的な npm run test:thinking テスト一式で、回帰を防ぎます（クラウドへのライブ依存はありません）。

検証済み：test:thinking、推論テスト一式（gpt-oss はエラーを明示してフォールバックし、真の推論モデルである kimi-k2-thinking:cloud は引き続き実際のコンテンツを返します）、integration、day2、evals、wire。

1.7.0 の新機能

MCP モダナイゼーションロードマップのステップ #2 です。すべてのツールを、非推奨の server.tool() 簡略記法（SDK 2.0 で削除）から server.registerTool() に移行しました。エンジンの動作変更はなく、完全な後方互換性があります。

ホストで利用できる内容

• タイトル — すべてのツールに、人が読める表示名を設定しています（memory_forget ではなく「事実を忘れる」）。
• 動作アノテーション — 23 個すべてのツールで readOnlyHint / destructiveHint / idempotentHint / openWorldHint を宣言しています。破壊的な 3 つのツール（memory_forget、unload_pack、unregister_platform）には確認 UI 向けのフラグを設定し、読み取り専用のインスペクター 7 個には自由に呼び出しても安全であることを示すフラグを設定しています。ネットワークにアクセスする 7 個のツール（LLM / 埋め込み / ウェブ検索）には openWorldHint: true を設定しています。
• 構造化出力 — すべてのツールで outputSchema を宣言し、JSON テキストとともに structuredContent を返します。スキーマは設計上、許容範囲を広くしています（すべて任意項目で、追加プロパティを許可）。エンジンの出力を拒否することなく、その形状を記述します。

後方互換性

すべてのツールでテキストコンテンツはバイト単位で同一です。list_* の 3 つの配列を返すツールも同様で、テキストは配列のままですが、structuredContent は MCP 仕様に従ってオブジェクトでラップします。エラー時の戻り値にも変更はありません。検証済み：wire 7/7、integration 9/9、day2、出力検証エラーなしで evals 26/27。

検証中に見つかった問題

#3 — クラウドの gpt-oss の思考チャネル応答で optimizedPrompt が空になることがあります（リモート API の変更により、client.ts に以前からあったフィールド名の不一致が表面化。修正は 1.7.1 を予定）。

1.6.8 の新機能

1.6.5 から 1.6.7 の連続リリースで生じた課題を解消するメンテナンスリリースです。エンジンコード、MCP ツールの提供範囲、プラットフォーム、環境変数に変更はありません。

変更点

• CI マトリックスで Node 24 のテストを追加しました（現行のアクティブな LTS。EOL は 2028 年 4 月）。Ubuntu と macOS で Node 18/20/22 と合わせてテストします。これまでは EOL の Node バージョンを 2 つテストする一方、現行 LTS はまったくテストしていませんでした。マージ前に、ツールチェーンのない node:24-slim コンテナー上の Node 24.16.0 で、ネイティブ依存関係（better-sqlite3 + sqlite-vec）の読み込みと動作を検証しました。最大限の互換性を保つため、engines は >=18 のままです。公称の要件に合わせてテストしています。
• 公開ランナーの Node を 20 から 22 に変更し、リリースのクリティカルパスから EOL のランタイムを外しました（Dockerfile のベースと一致します）。

プロセス

• 新しい出荷チェック CP-13 — lockfile regeneration safety は、1.6.5→1.6.6→1.6.7の連鎖から得た教訓を反映しています。単一の npm install --package-lock-only により、sqlite-vec のプラットフォームバイナリ5個中4個がひそかに削除され（Linux CIが失敗）、さらにキャレット範囲内での better-sqlite3 のバージョン更新によりNode 20のプリビルドが削除されました（Dockerビルドが失敗）。このチェックでは、依存関係の変更時に完全な npm install を実行すること、プラットフォーム依存関係の削除とネイティブ依存関係のバージョンジャンプを確認するロックファイルの差分、ローカルのスリムDocker読み込みゲートを必須としています。このリリースで実際に適用しました。

1.6.7 の新機能

Dockerfileのパッチです。エンジンコード、MCP ツールのサーフェス、プラットフォーム、環境変数に変更はありません。

修正

• 1.6.6で CI / docker build が npm error gyp ERR! find Python により失敗しました。 根本原因は、[email protected]（2026年5月リリース）が、Node.js v20とv23のプリビルドバイナリを明示的に削除したことです。Node 20は2026年4月にEOLに達しました。1.6.6のロックファイル再生成で、^12.9.0 のキャレット範囲内にある12.10.0が取り込まれましたが、node:20-slim にはソースからコンパイルするためのPythonとC++ツールチェーンがありません。Dockerfileのベースを node:22-slim に更新しました。現在のアクティブなLTSで、引き続き動作するプリビルドもあります。
• Dockerを使わないCIビルドマトリックス（macOSとUbuntuでNode 18 / 20 / 22）は、引き続き合格します。通常のランナーではフォールバックとしてソースからコンパイルできるためです。問題が起きるのはスリムDockerイメージのみです。

ローカルで検証済み

docker build → 成功。コンテナーから better-sqlite3 と sqlite-vec を問題なく require できます。sqlite-vec のプラットフォームバイナリ5個すべてが、引き続き package-lock.json に含まれています（1.6.6での修正が維持されています）。

1.6.6 の新機能

1.6.5に続くロックファイルとハーネスのパッチです。エンジンコード、MCP ツールのサーフェス、プラットフォーム、環境変数に変更はありません。 MCP完全性監査ドキュメントを同梱しています。

修正

• 1.6.5のSDK更新中に、package-lock.json から sqlite-vec のプラットフォームバイナリ5個中4個が失われました。 ローカルで実行した npm install --package-lock-only では、メンテナーの sqlite-vec-darwin-arm64 バイナリだけが残りました。CIのUbuntuランナーで npm ci を実行すると、ロックファイルに sqlite-vec-linux-x64 がなかったため、no such module: vec0 で失敗しました。エンドユーザーによる npm install [email protected] には影響はありませんでした（npmのtarballにはロックファイルが含まれず、プラットフォームはインストール時に解決されます）。完全な npm install で再生成し、5つのプラットフォーム（darwin-arm64、darwin-x64、linux-arm64、linux-x64、windows-x64）すべてを復元しました。
• 評価ハーネスのHTMLレポートライターが、エラーになったエントリーでクラッシュしていました（evals/run.mjs:729）。既存のレンダラーは、スキップもフィルターもされていない実行にはすべて evaluation.checks フィールドがあると想定していましたが、エラーになった実行には代わりに error フィールドがあります。エラーステータスを明示的に処理する分岐を追加しました。これによりハーネスは、フィクスチャでエラーが発生しても適切に処理し、正常に終了します。

同梱ドキュメント

• docs/audits/mcp-completeness-2026-05.md — 現行のSDKと仕様に照らした、エンジンのMCPサーフェスの診断監査です。ツールごとの登録表、リソースのギャップ分析、SDK機能の差分（1.12 → 1.29 → 2.0-alpha）、機能宣言、トランスポートのリファクタリング案、A2Aの実現可能性に関する注記、順序付けされた7ステップの近代化ロードマップを掲載しています。次回セッションの計画の基礎となる成果物です。エンジンの変更を文中で指示するものではありません。

数値

• ロックファイル内のsqlite-vecプラットフォーム数：5（以前は1）。npm audit --production：脆弱性0件（変更なし）。ツール数：23（変更なし）。評価フィクスチャ数：30（変更なし）。

1.6.5 の新機能

セキュリティパッチです。エンジンコード、MCP ツールのサーフェス、プラットフォーム、環境変数に変更はありません。

修正

• CVE-2026-0621 — @modelcontextprotocol/sdk の UriTemplate 正規表現における ReDoS（SDK 1.25.2 で修正済み）。以前の下限バージョン ^1.12.1 では、古い npm キャッシュを使うと脆弱なバージョンが解決される可能性がありました。下限バージョン自体が修正済みとなるよう、^1.29.0 に引き上げました。
• GHSA-345p-7cg4-v4c7 — サーバー／トランスポートのインスタンスを共有すると、クライアント間でレスポンスデータが漏えいします（SDK 1.26.0 で修正済み）。ClarifyPrompt では実際に悪用できません（ホスト1台につきサーバーインスタンス1つ）が、脆弱なコードは依存関係ツリーから完全に除外されました。
• SDK に同梱される HTTP トランスポート関連の依存サブスタック（hono、express-rate-limit、fast-uri、ip-address、path-to-regexp、qs、@hono/node-server）における7件の推移的な脆弱性（中程度2件、高度5件）。npm audit fix で解消しました。ClarifyPrompt は stdio 専用で HTTP トランスポートを読み込まないため、実行時には影響しませんでしたが、ユーザーの npm audit レポートにノイズを加え、インストールが危険に見える原因になっていました。

数値

• npm audit --production → 脆弱性0件（修正前は SDK の CVE 2件＋推移的な脆弱性7件）。
• package-lock.json：合計336行減（以前のキャレット範囲は、使われていない HTTP トランスポート関連の大きな依存パッケージを取り込んでいました。修正では、それらをより軽量な代替パッケージに置き換えました）。
• ツール：23（変更なし）。プラットフォーム：60以上（変更なし）。評価用フィクスチャ：30（変更なし）。
• ローカルの Ollama で新しい下限バージョンを使い、Wire テスト＋統合テスト一式＋day2＋reasoning＋評価30件中29件が合格します。失敗した1件（analyzer-creative-media）は、以前から存在する qwen-coder-7b 分類器の不安定な結果です。変更を一時退避して再実行し、SDK に依存しないことを確認しました。

下限バージョンの引き上げが重要な理由

^1.12.1 という記述は誤解を招くものでした。実際には、2026年初頭以降、新規の npm install ではキャレット範囲の解決により SDK 1.27.1 がインストールされていました。下限バージョンを引き上げることで、ほとんどのユーザーに対して npm がすでに選択していたバージョンに宣言上の基準を合わせるとともに、古いキャッシュを使うユーザーにも下限バージョンの安全性を保証します。また、SDK のその系列が安定した際に予定される 2.0.0-alpha への移行に備えることにもなります（最新の SDK では、.tool()／.prompt()／.resource() による簡略な登録方法は非推奨となり、title、outputSchema、annotations を指定する registerTool()／registerPrompt()／registerResource() が推奨されます）。

1.6.4 の新機能

ドキュメントとプロセスの修正です。エンジン、MCP ツール、プラットフォームに変更はありませんが、パック配布モデルを大幅に整理しました。

パックレジストリをエンジンのリポジトリに統合

LumabyteCo/clarifyprompt-packs（適切な原則に基づきつつ、規模に見合わない形で 1.3 に作成されたコミュニティパック用の別レジストリ）はアーカイブされました。最初の3つのパックは、すでにこのリポジトリの packs/ フォルダーにありました。レジストリは正式な配布元となる予定でしたが、実際には常に npm tarball 経由でここから配布されていました。やがてずれが明らかになりました。higgsfield-creative-handbook は 1.6.2 で公開されましたが、レジストリには追加されませんでした。レジストリの README では、パックをそこから取得するようユーザーに案内していたにもかかわらずです。

1.6.4 の結果：

• 信頼できる情報源を一本化。 packs/*.md のナレッジパックと packs/platforms/*.yaml のプラットフォーム設定はすべて clarifyprompt-mcp に置かれ、npm tarball に含まれます。
• この README に新しいトップレベルのナレッジパックセクションを追加しました。読み込みモデル（load_knowledge_pack({source: "<url-or-path>", scope: ...})）、最初の3つのパックと Higgsfield、scope の意味、コントリビューション方法を説明します。
• 新しい packs/README.md — パック作成ガイド（frontmatter スキーマ、チャンクの区切り、品質基準）です。アーカイブされたレジストリから移管し、内容が失われないようにしました。
• アーカイブされたリポジトリに案内ページを設置。 clarifyprompt-packs を訪れた人には、こちらへのリンクを示すバナーが表示されます。

分割を再開するのはいつですか？

分割を必須とする要因がある場合です。パックだけを扱うコミュニティの PR キュー、パック数が20を超えること、またはライセンスやガバナンスの相違などが該当します。それまでは、2つのリポジトリの同期を維持するコストに見合うほどのユーザー層はまだ形成されていませんでした。

数字

• ツール： 23（変更なし）。
• プラットフォーム： 60+（変更なし）。
• 同梱ナレッジパック： 4（anthropic-brand-voice、higgsfield-creative-handbook、nextjs-14-best-practices、sox-compliance）— 1.6.2/1.6.3 と同じで、今回正式に追加されました。
• 評価フィクスチャ： 30（変更なし）。
• Tarball サイズ： 1.6.3 から変更なし。

1.6.3 の新機能

パッチリリースです。1.6.2 の CI タグプッシュ実行で実際の問題が 2 つ見つかり、エンジンコードを変更せずに修正しました。

修正

• evals/fixtures/28-context-includes-git-state.yaml は以前、git_branch_present: true をアサートしていましたが、GitHub Actions は detached-HEAD モードでチェックアウトするため、bundle.git.branch は正しく undefined になります（SHA と最近のコミットだけが設定されます）。ローカル環境と CI 環境の両方で実際に不変なのは bundle_has_git: true だけなので、そのアサートのみに変更しました。
• evals/fixtures/17-critique-strong-prompt-accepts.yaml は、強力なプロンプトに対して verdict: accept と overall_score_min: 7 をアサートしていました。gpt-4o-mini のジャッジは qwen2.5-coder:7b より厳しく評価するよう調整されており、ときどき不正な overall フィールドを返していました。パーサーがこれを 0 として処理した結果、verdict=reject になっていました。このフィクスチャの本来の目的は、エンジンの配線（5 つ以上の評価軸、標準の評価軸名が含まれていること、ハーネスエラーがないこと）を確認することであり、モデル間のジャッジ調整を比較することではありません。verdict と厳密なスコアのアサートを削除し、配線レベルのチェックは残しました。
• README の Glama バッジを、GitHub の camo プロキシ経由ではときどき壊れるインラインの <img> から、どのレンダリング環境でも安定する shields.io のテキストリンクバッジに変更しました。

注記

• エンジンコードの変更はありません。 新しい MCP ツールはありません（引き続き 23 個）。プラットフォームの変更もありません（引き続き 60+）。環境変数の変更もありません。
• ローカルの Ollama における評価ベースラインに変更はありません。 これは CI 固有の堅牢化です。qwen-coder-7b を使ったローカル実行では、修正前後で同じ結果が得られました。
• v1.6.2 のタグプッシュ時に発生した CI の公開ゲート失敗は、評価失敗の後続事象でした（Wait for evals workflow ステップが公開をブロックしていました）。gpt-4o-mini と detached-HEAD の CI 環境で対象フィクスチャが誤って失敗しなくなったため、公開ゲートも通過します。

1.6.2 の新機能

パッチリリースです。エンジンの観点では、どちらもコード変更を伴わない 2 つの追加リリースです。

Higgsfield クリエイティブハンドブックのナレッジパック

packs/higgsfield-creative-handbook.md — コミュニティ形式の Markdown パックで、Higgsfield の実際の規約をまとめています。モデル選択ルール（13 モデルのうち、どのユースケースでどれを使うか）、Soul ID のキャラクタートレーニングワークフロー、カメラ移動の用語、プロンプトの構成パターン（キーワードタグではなく長文の文章）、複数のリファレンスを使った編集、Marketing Studio のモード、よくある落とし穴（Midjourney のフラグをそのまま翻訳しない）、出力仕様を記載しています。

明示的に読み込みます。

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

…または npm tarball に同梱されているため、インストール済みのコピーを指定します。Context Curator はセマンティック検索によって、このパックのチャンクを使い、Higgsfield 向けプロンプトを自動的に補強します。読み込みとスコープの仕組みについて詳しくは、ナレッジパックセクションをご覧ください。

npm run matrix — マルチモデル評価マトリクスランナー

evals/matrix.mjs は、N 個のモデルに対して npm run eval を順次実行し、結果を 1 つの HTML にまとめます（デフォルトは evals/matrix.html）。単一モデルでの実行ではスキップされる、モデルクラス別のフィクスチャ（shape-small-local-model / shape-mid-tier-model / shape-reasoning-model）を実行し、「qwen-7b は analyzer-creative-media に失敗するが、gpt-4o-mini は合格する」といった差分を一目で確認できます。

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

ダークテーマの表を出力します。行はフィクスチャ、列はモデルで、セルには合格／失敗／スキップ／エラーが表示され、ツールチップには失敗したチェックが示されます。

併せて、evals/run.mjs に --json-out <path> フラグを追加しました。モデルごとの構造化された結果を書き出します（matrix.mjs が使用するほか、CI エージェントでも使用できます）。

数値

• ツールのサーフェスに変更はありません。 MCP ツールは引き続き23個です。
• プラットフォーム数に変更はありません。 60以上のプラットフォーム（packs/platforms/*.yaml に変更はありません）。
• フィクスチャは30個のままです。（新しいフィクスチャはありません。マトリックスはカバレッジではなく、ツールです。）
• ナレッジパックにより、tarball のサイズが約10 KB増加します。 evals/matrix.mjs は tarball に含まれません。これはランタイム成果物ではなく、メンテナー／コントリビューター向けのツールです。

1.6.1の新機能

パッチリリースです。image と video の両カテゴリに、対象プラットフォームとして Higgsfield を追加します。コードの変更はなく、YAML プラットフォームパックの追加と、評価用フィクスチャ1件のみです。

Higgsfield は、独自の MCP サーバー https://mcp.higgsfield.ai/mcp を公開するマルチモデルのクリエイティブプラットフォームです。1つの接続で、次の機能を利用できます。

• 画像：Soul 2.0、Soul Cinema、Soul Cast（キャラクターの一貫性を保持）、Flux 2、Seedream 5、Nano Banana Pro、GPT Image 2
• 動画：Cinema Studio、Veo 3.1、Kling 3.0、WAN 2.6、Seedance 2.0（Sora 2は2026-09-24に提供終了。OpenAIが代替なしでVideos APIを終了）
• ワークフロー：Soul IDによるキャラクタートレーニング、Lipsync Studio、UGC Factory、Marketing Studio、virality_predictor

1.6.1のClarifyPromptプラットフォームエントリーでは、Higgsfieldのモデル識別子とプロンプトのスタイル規則（長文の自然言語による文章、構図＋ライティング＋テクスチャ＋ムード、最大4K画像／15秒動画／キャラクターの一貫性を保つSoul ID）を、キュレーター向けの構文ヒントとして提示します。

推奨パターン： クライアント（Claude Desktop／Cursor／AI Butler／Claude Code）に、clarifyprompt-mcp とHiggsfieldのMCPを両方インストールします。optimize_prompt(platform: 'higgsfield', ...) または compose_prompt(platform: 'higgsfield', ...) でコンパイルしてから、コンパイル済みのプロンプトをHiggsfieldの generate_image／generate_video ツールに渡します。MCP同士を組み合わせるのはクライアント側であり、ClarifyPromptは「コンパイル」レイヤーにとどまります。

評価用フィクスチャは29個から30個になりました。1.6.0と同じMCPツールサーフェスです（23個のツール、1個のリソース）。環境変数に変更はありません。

1.6.0の新機能

エンジンの4つの柱（メモリ／エージェント型機能／モデル／コンテキスト）に、それぞれ実際の評価用フィクスチャを伴う、的を絞った機能を追加しました。新しいMCPツールは3個です（合計23個）。1.5.xとの完全な後方互換性があり、削除されたツールやフィールドはなく、必須の環境変数にも変更はありません。

メモリ — 明示的なファクトのCRUD（memory_remember、memory_forget、memory_list_facts）

1.6より前は、ファクトが永続メモリに保存されるのは save_outcome の振り返りを通じて のみでした。暗黙的にLLMが抽出し、事後に保存されていました。1.6では、明示的な方法を追加します。

• memory_remember — 信頼度を明示して、(subject, predicate, object) のトリプルを直接挿入します。ソースには user:explicit のタグが付与されます。今後のセマンティック検索に備えて、自動的に埋め込み表現が作成されます。
• memory_forget — IDを指定して、ファクトを論理削除します（双時制の invalidated_at）。冪等性があります。すでに無効化されたファクトを再度削除しても何も起こらず、success: false を正常に返します。
• memory_list_facts — スコープ（デフォルトは user）内の有効なファクトを一覧表示し、必要に応じて述語で絞り込みます。最終観測日時が新しい順に並びます。

これにより、エンジンが 結果 からしか学習できなかったという明らかなUX上の不足が解消されます。これからは、「Xが好みだと覚えておいて」とユーザーが直接伝えられます。

エージェント型機能 — compose_prompt に新しい max_iterations 修正ループを追加

以前の compose_prompt は、一度だけ修正していました（判定が accept でない場合、批評の improvedPrompt が最適化結果を置き換えていました）。1.6ではループを追加します。

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

最初の反復以降は毎回、前回の反復で改善されたプロンプトに対して optimize と critique を再実行します。verdict=accept になったとき、フィードバックに使える improvedPrompt がないとき、または上限に達したときに停止します。pre_clarify は一度だけ実行します（書き換えのたびに再質問する意味はありません）。レスポンスには、新たに iterations フィールドが追加され、実行された反復回数が示されます。コストが際限なく増加するのを防ぐため、上限は5回です。

モデル — ステージごとのモデルルーティング

各 compose ステージで、異なるモデルを指定できるようになりました。

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

安価なローカルモデルで clarify を実行し、高性能なフロンティアモデルで optimize を実行し、安価な判定モデルで critique を実行できます。このオーバーライドはすべてのレイヤーに反映されます。レスポンス内の optimization.metadata.model と critique.judgeModel には、各ステージで実際に実行されたモデルが反映されます。

コンテキスト — Git の状態と環境シグナル

2 つの新しいシグナルコレクターが Context Curator に情報を渡します。

• bundle.git — 現在のブランチ、短縮 SHA、変更の有無、直近 5 件のコミットタイトルを取得します。自分で明示しなくても、「現在取り組んでいる内容」を基にエンジンがプロンプトを作成できます。git rev-parse／git status／git log で検出し、cwd がリポジトリではない場合もエラーになりません。
• bundle.environment — nowIso／weekday／timezone（Intl.DateTimeFormat による IANA タイムゾーン）を取得します。「このメールを明日送る」といった、時間に左右されるプロンプトに役立ちます。純粋な JS で実装されており、失敗することはありません。

どちらも Curator で優先度の低い候補として扱われるため（予算を圧迫しません）、関連する場合にコンテキストを補う情報源として使われます。

Eval のカバレッジ

23 → 29 個のフィクスチャ（6 個追加）：

• 24 memory-remember-persists／25 memory-forget-invalidates — Me1 CRUD の一連の処理
• 26 compose-loop-iterates — A1 ループインフラ（新しい iterations_min／iterations_max チェック）
• 27 compose-per-stage-models-honored — M1 ステージごとのルーティング（新しい optimization_model_eq／critique_model_eq チェック）
• 28 context-includes-git-state／29 context-includes-environment-time — C1 + C4 シグナル（新しい bundle_has_git／bundle_has_environment／git_branch_present チェック）

qwen2.5-coder:7b でのローカルベースライン：25 件合格／1 件失敗／3 件スキップ／平均 97％。唯一の失敗は、引き続き analyzer-creative-media のモデルクラスシグナルです（変更なし）。

1.5.2 の新機能

CI の eval ゲート（gpt-4o-mini を使用）が差分を主導した初めてのリリースです。OPENAI_API_KEY シークレットを組み込んだ直後にゲートが検出した、実際の修正を 3 件行いました。

• メモリストアが任意の埋め込み次元数に対応 (#2)。永続 vec テーブルの次元数は 768（nomic-embed-text のデフォルト）に固定されていました。そのため、EMBED_MODEL=text-embedding-3-small（1536）、voyage-3（1024）、embed-english-v3.0（1024）、または 768 以外のモデルを設定すると、最初の memory_search 呼び出しで Dimension mismatch: expected 768, got N が発生していました。現在、ストアは埋め込みモデルの実際の次元数からテーブル名を決定し、起動時に次元数に応じたテーブルを作成します。既存の 768 次元のインストールには影響しません。
• LLM クライアントに LLM_TIMEOUT_MS 環境変数によるオーバーライドを追加しました。デフォルトは引き続き 30 秒です。応答の遅いホスト型モデルを使う場合は、値を増やせます。eval ワークフローでは gpt-4o-mini に 120 秒を設定しています。
• Eval ハーネスを強化しました。ツールが例外をスローしてもクラッシュしなくなりました（SDK はプレーンテキストのエラーレスポンスを返しますが、以前のハーネスはそれを JSON.parse して終了していました）。フィクスチャが 1 件失敗しても、実行全体が失敗することはありません。
• Eval のライブバッジ。 evals.yml ワークフローは、main へのプッシュごとに実行されます。この README の先頭にある [![evals]](...) バッジで、リアルタイムのステータスを確認できます。現在、gpt-4o-mini で 20/0/3・100％、緑のステータスです。

新しい MCP ツールはありません。環境変数の仕様に変更はありません（任意の LLM_TIMEOUT_MS を追加したのみです）。1.5.x と完全な後方互換性があります。

1.5.1 の新機能

1.5.0 をベースにしたパッチリリースです。ドキュメントとリリースプロセスの改善のみで、実行時の動作は 1.5.0 と同一です。

• README の製品紹介部分を更新 — 1.5.0 のリリース時、README の3か所（冒頭の引用ブロック、「What's new in X」見出し、「cumulative through X」の注記）が 1.4.0 のままでした。その他のバージョン表記（package.json、package-lock.json、server.json、src/index.ts、CHANGELOG）はすべて正しかったものの、自動更新の対象になっていなかったため、説明文だけが古くなっていました。1.5.1 で修正しました。
• リリースチェックの監査項目を2つ追加 — CP-11（README の製品紹介部分の整合性）は、上記3か所のいずれかが現在の package.json#version を参照していない場合に失敗します。CP-12（プラットフォームパックの形式検証）は、packs/platforms/*.yaml をすべて解析し、スキーマの妥当性を確認します。CP-11 は同日、ユーザースコープ（プロジェクト横断）のリリースチェックスキルにも昇格したため、今後のプロジェクトにも役立ちます。
• コードの変更はありません。 新しい MCP ツールはありません。新しい環境変数もありません。1.5.0 と同じ tarball の構成で、CHANGELOG が数百バイト増えただけです。

1.5.0 の新機能

組み込みプラットフォームを宣言的に管理できるようになりました。 ハードコードされていた58以上の TypeScript プラットフォーム配列を packs/platforms/*.yaml に移しました。組み込みプラットフォームの追加は、TS の編集ではなく YAML の編集でできるようになりました。TypeScript 層は、ハードコードされたフォールバックテーブルを備えた実行時ローダーになります。不正な YAML によってサーバーが使用不能になることはありません。

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

新しい組み込みプラットフォームを追加するには、該当するカテゴリファイルに項目を追加し、npm run build を実行して、PR を作成してください。TS の編集は不要です。実行時のカスタムプラットフォーム登録（register_platform）は、ユーザーがインストールしたプラットフォームでこれまでどおり動作します。

• メモリ層の評価カバレッジ。 評価ハーネスが setup: [{tool, args}, ...] に対応しました。これは、メインの input より前に実行される MCP ツール呼び出しのリストです。新しいフィクスチャを2つ追加しました。1つはナレッジパックをインラインで読み込み、埋め込み → 保存 → 取得 → キュレーション → グラウンディングのパイプライン後に、そのチャンクが grounding.sources に現れることを検証します。もう1つは、ベクトル検索のランキング品質を検証します。フィクスチャは合計23件（1.4.0 では20件）です。
• テストインフラを最新化。 統合テストと Day-2 テストでは、以前はバージョン文字列（1.3.0、16 tools）を直接アサートしていたため、バージョンを上げるたびに失敗していました。現在は package.json から EXPECTED_VERSION を読み込み、ツールの 数 ではなくツールの セット の存在をアサートします。今後のバージョン更新でテストが壊れることはありません。
• 導入支援資料。 docs/adoption/ に、コピーしてすぐ使える Show HN の本文、Reddit 投稿、Twitter スレッド、awesome-mcp-servers の PR テンプレート、およびカタログ登録仕様（mcp.so、Smithery、mcp-get、PulseMCP、modelcontextprotocol/servers）が含まれています。
• 実行時依存関係を1つ追加： プラットフォームローダー用に、js-yaml を devDependency から昇格しました（約200 KB）。
• MCP ツールの提供内容は 1.4 と同じです。 ツール20個、リソース1個です。新しいツールや削除されたツールはなく、結果の形式も変更ありません。

1.4.0 で追加 — 組み合わせ可能なパイプライン

4 つのコア操作を、組み合わせて使えるファーストクラスの MCP ツールとして提供します。各ツールを単独で使うことも、1 回の呼び出しでチェーン全体を実行することもできます。

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

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

• clarify_with_user — 曖昧な下書きを渡すと、的を絞った確認質問を 1～3 件返します。各質問には、そのまま採用できる suggested_answer、任意の 2～4 個のクイック選択肢 options、および dimension タグ（audience/scope/format/length/tone/constraints/goal/platform）が含まれます。自信を持って適切に構成されたプロンプトには clarificationNeeded: false を返して処理を短絡するため、呼び出しごとのレイテンシー負担なく optimize_prompt の前にスムーズにパイプラインできます。
• ground_prompt — optimize_prompt の、厳格な検索拡張版です。呼び出し元が提供したソースは最優先に固定されます。プロジェクトのルールや固定された指示よりも優先され、トレース内では user-source:N として個別に記録されます。厳格モードでは、空でないソースが 0 件の場合はエラーとなり、暗黙のフォールバックは行われません。1 つの巨大な貼り付けが予算を圧迫しないよう、ソースごとの本文上限は 4000 文字です。
• critique_prompt — LLM を審査役として使います。候補プロンプトを 5 つの既定の評価軸（clarity、specificity、intent_alignment、format_fitness、length_appropriateness）または独自の評価基準で 0～10 点で採点し、評価軸ごとの理由と具体的な提案、総合スコア、判定（accept／revise／reject）を返します。revise_threshold（既定値は 7.0）を下回る場合は、差し替えて使える improvedPrompt も返します。事前確認（「高コストなモデルに渡すのに十分なプロンプトか」）、事後分析（「原因はプロンプトだったか」）、または N 個の最適化案から最良のものを A/B テストで選ぶ場合に使えます。
• compose_prompt — 1 回の MCP 呼び出しで、標準パイプラインを実行します。sources を渡したかどうかに基づいて、ground と optimize のどちらの分岐を使うかを自動的に決定します。pre_clarify: 'auto' | 'always' | 'never'。post_critique: true を設定すると審査ステップを追加します。auto_revise: true を設定すると、判定が accept でない場合に final_prompt を書き換え後のプロンプトに置き換えます。呼び出し元が実行内容を正確に確認できるよう、ステージごとの監査配列 stages を返します。
• 評価ハーネス v0 — evals/ にある決定論的な回帰テストです。20 個の YAML フィクスチャで、analyzer、shape、intent-overlay、grounding、clarify、critique、ground、compose の各サーフェスをカバーします。npm run eval は、コンソールの概要と、単体で表示できるダークテーマの HTML レポートを生成します。複数モデルのマトリックスは bash だけで実行できます。モデルごとに LLM_MODEL=... npm run eval -- --report-path evals/report-X.html を実行してください。
• CI ゲート付き評価（オプトイン） — OPENAI_API_KEY をリポジトリのシークレットとして設定すると、評価ハーネスが CI で gpt-4o-mini を使ってリリースゲートとして実行されます。既定では無効で、シークレットがない限り、マシンから外部にデータが送信されることはありません。
• 新しい MCP ツール 5 個（合計 20 個）。optimize_prompt にも userProvidedSources の注入ポイントが追加されました。内部では ground_prompt と compose_prompt の両方で使用されますが、厳格モードの検証を使わず、明示的に制御したい場合は直接利用できます。

1.3 から引き継いだ機能：永続メモリ、ナレッジパック、内省的な学習。キュレーターは引き続き、グラウンディングソースを評価し、対象モデルの残りのコンテキストウィンドウに収まるよう選定します。explain_last_curation では、選択された候補と却下された候補を理由付きで、呼び出しごとに引き続き確認できます。

同梱内容（1.16.0 までの累積）

• コンテキストエンジン — ワークスペースのルール（CLAUDE.md、AGENTS.md、.cursorrules、.clinerules、clarify.md）を自動収集し、package.json と同階層のマニフェストからフレームワークと言語を検出し、アクティブなファイルの抜粋を追跡して、最近の最適化とその結果をセッションごとのリングバッファで管理します。
• 統合された PromptAnalyzer — 1 回の LLM 呼び出しで { category, intent, recommendedMode, confidence } をまとめて生成します。意図は 10 種類です：production-code、brand-voice、stakeholder-comm、data-extract、creative-media、technical-spec、analysis、quick-draft、exploration、unknown。曖昧な場合は、表面的なキーワードよりも意図を優先します。
• 対象モデルを考慮したプロンプト調整 — システムプロンプト、maxTokens、temperature は、下流の LLM のコンテキストウィンドウと解決された意図に応じて調整されます。小型のローカルモデルには簡潔なプロンプトを、Claude／GPT-4／Gemini には情報を十分に盛り込んだプロンプトを使います。
• グラウンディングコンテキスト（優先順位を一本化） — ユーザーが固定した指示 → プロジェクトルール → アクティブなファイル → 以前に採用された例 → ウェブ検索 → ワークスペースのメタデータ → 対象モデルのヒント → カスタムプラットフォーム指示 → 組み込みの構文ヒント。並列に分断されたコンテキストはもうありません。
• セッション内検索（save_outcome） — 呼び出し元は各最適化について accepted | edited | rejected を報告します。同じセッション内で類似した出力が採用されている場合、その出力が今後の類似プロンプトに少数例として挿入されます。永続メモリ（SQLite + sqlite-vec）を利用するため、採用結果は再起動後も保持されます。
• ローカル JSONL トレース — 最適化のたびに、構造化されたトレース行（新たに shape、groundingSources、error フィールドを追加）を $CLARIFYPROMPT_HOME/traces/YYYY-MM-DD.jsonl に書き込みます。アップロードは一切ありません。 CLARIFYPROMPT_TRACE=off で切り替えられます。
• 統一された $CLARIFYPROMPT_HOME — ClarifyPrompt が書き込むすべてのデータに、1 つの環境変数を使います。従来の CLARIFYPROMPT_CONFIG_DIR／CLARIFYPROMPT_DATA_DIR も引き続き動作します（非推奨のヒントが表示されますが、非表示にもできます）。
• 3 種類のトランスポート — stdio（デフォルト）、streamable-http（Node http 上の MCP。ステートフルなセッションと /health に対応）、a2a（エージェント間のピア。エージェントカード、JSON-RPC message/send + SSE message/stream、タスクのキャンセル、input-required による確認に対応）。環境変数は CLARIFYPROMPT_TRANSPORT 1 つだけです。stdio の動作は以前とバイト単位で同一です。
• 61 のプラットフォーム、7 つのカテゴリ、verifiedAt 日付付きパック、カスタムプラットフォーム — 組み込みの事実情報はすべて、2026-10-05 時点のベンダー公式ドキュメントと照合済みです。新たに Seedance、ElevenLabs Music、Lyria が加わり、Sora は廃止されました。
• あらゆる LLM、あらゆるプロバイダーに対応。 1 つのコードパスで、あらゆる OpenAI 互換 API（ローカルおよびクラウドの Ollama、LM Studio、vLLM、OpenAI、Google Gemini、xAI Grok、Groq、Mistral、DeepSeek、Cohere、Perplexity、Together、Fireworks、OpenRouter）に対応し、Anthropic Claude にも直接対応します。推論モデル（o1/o3/o4、deepseek-reasoner、gpt-oss、*-thinking）は自動検出され、コンテンツを実際に生成できるよう、より大きなトークン予算が割り当てられます。設定済みのプロバイダー例 15 件以上はこちら。
• Apache-2.0、永久に。 オープンソースのコアで、再ライセンスはありません。

クイックスタート

Docker を使う場合

GitHub Container Registry から公開イメージを取得します（マルチアーキテクチャ対応：amd64 + arm64。署名付きの来歴情報と SBOM を含みます）。

docker pull ghcr.io/lumabyteco/clarifyprompt-mcp:latest

設定はすべて実行時に渡されます。イメージには何も組み込まれないため、安全に共有でき、シークレットも含まれません。

# stdio (for MCP hosts that launch the container)
docker run --rm -i \
  -e LLM_API_URL=http://host.docker.internal:11434/v1 \
  -e LLM_MODEL=qwen2.5:7b \
  -e CLARIFYPROMPT_HOME=/data \
  -v clarifyprompt-data:/data \
  ghcr.io/lumabyteco/clarifyprompt-mcp:latest

# or serve over HTTP / A2A
docker run --rm -p 3000:3000 \
  -e CLARIFYPROMPT_TRANSPORT=a2a -e CLARIFYPROMPT_HTTP_HOST=0.0.0.0 \
  -e LLM_API_URL=http://host.docker.internal:11434/v1 -e LLM_MODEL=qwen2.5:7b \
  ghcr.io/lumabyteco/clarifyprompt-mcp:latest

実行間でメモリ、トレース、パックを保持するには、CLARIFYPROMPT_HOME にボリュームをマウントしてください。LLM_API_KEY／EMBED_API_KEY は実行時に -e 環境変数（または --env-file）で渡してください。イメージに組み込まないでください。

Claude Desktop を使う場合

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"
      }
    }
  }
}

Claude Code を使う場合

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

起動する前に、シェルで環境変数を設定します。

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

Cursor を使う場合

.cursor/mcp.json に追加します。

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

AI Butler を利用する

AI Butler は、セルフホスト可能なパーソナル AI エージェントのランタイムです。単一の Go バイナリで、マルチチャネルチャットと MCP エコシステムのハブを備えています。ClarifyPrompt を mcp.servers 設定に追加すると、エージェントは 23 個すべてのツールをネイティブ機能として取り込み、あらゆるチャネル（Web チャット、ターミナル、Telegram、Slack など）から呼び出せるようになります。AI Butler は MCP の tools/list を通じてツールを動的に検出するため、ClarifyPrompt のツールを追加／削除すると、butler 側で設定を編集しなくても、エージェントが利用できる機能が自動的に更新されます。

~/.aibutler/config.yaml を編集します。

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

AI Butler を再起動します。起動ログでツールが接続されたことを確認できます。

リクエストすると、エージェントは利用可能なすべての機能を列挙します。各ツールには clarifyprompt. が付いています。

📸 上のスクリーンショットは、1.2 時代の統合（11 個のツール）のものです。 現在の 1.6.x では 23 個のツールを利用できます。optimize_prompt、 clarify_with_user、ground_prompt、critique_prompt、 compose_prompt に加え、管理／検査／メモリー用の ツール（memory_search、memory_remember、memory_forget、 memory_list_facts、ナレッジパック用ツール、トレース、カスタム プラットフォームなど）もあります。AI Butler は MCP の tools/list による検出を通じてこれらを自動的に取り込みます。 設定を変更する必要はありません。

Context Engine を最初から最後まで使う

最適化を実行せずに、エンジンが収集する情報をプレビューするには inspect_context を使います。

次に、サポート対象の 60 以上のプラットフォームで実際に最適化を実行します。

最適化ごとに、~/.clarifyprompt/traces/YYYY-MM-DD.jsonl に JSONL が 1 行記録されます。すべてローカルに保存され、アップロードされることはありません。list_traces ツールを使うと、検索可能な概要を表示でき、get_trace による再生にも対応します。

チャットから 11 個すべてのツールを利用する方法、設定オプション、自然言語での使用例を含む統合手順の全編は、AI Butler のドキュメントにあります。 MCP サーバーを統合する。

設定と compose パネル

パイプライン全体を実行し、対応するホストではインタラクティブな結果パネルを表示するために必要な情報をすべて紹介します。

処理を行うモデル

ClarifyPrompt は、環境変数で設定された OpenAI 互換または Anthropic のエンドポイントを 1 つ呼び出します。

LLM_API_URL=http://localhost:11434/v1     # Ollama shown; any OpenAI-compatible URL works
LLM_API_KEY=                              # empty for local Ollama; a key for hosted providers
LLM_MODEL=qwen2.5:7b                      # the model that rewrites and judges

出力は モデルによって異なります。プラットフォームの構文や批評の観点といった 構造 はモデル間で一貫していますが、具体的な表現やスコアはモデルによって異なります。

パイプライン全体を1回の呼び出しで実行する

compose_prompt({
  "prompt": "write a product update email about our new dashboard",
  "platform": "claude",     // target a platform's tuning; omit for portable, neutral output
  "pre_clarify": "never",   // "auto" | "always" | "never"
  "post_critique": true     // adds the LLM-as-judge pass (verdict + the six score dimensions)
})

{ optimization: { id, sessionId, originalPrompt, platform, … }, finalPrompt, critique: { verdict, overallScore, dimensions[] }, stages[] }を返します。

プラットフォームを指定する

platform:（optimize_promptまたはcompose_promptで使用）を指定すると、プラットフォーム固有の調整が選択されます。たとえば、midjourney、dall-e、veo、suno、claude、chatgpt、cursor（組み込みは61種類で、それぞれverifiedAtの日付付き。さらに任意のプラットフォームを登録可能）です。チャットの場合、プラットフォームはモデルそのものです（claude、chatgpt、gemini、llama、deepseekなど）。テキストカテゴリ（chat／document／code）では、platformを省略すると、持ち運び可能なプラットフォーム非依存の出力になります。プラットフォーム固有の表現を使うには、プラットフォーム名を指定してください。

ステージごとのモデル（例：批評にはより高性能なモデルを使用）

compose_promptでは、各ステージに異なるモデル名を割り当てられます。

compose_prompt({
  "prompt": "…",
  "optimize_model": "qwen2.5:14b",   // rewrite on a cheaper model
  "critique_model": "gpt-4o",        // judge on a stronger one
  "clarify_model":  "qwen2.5:7b"
})

重要： ステージごとに指定するモデル名はすべて、同じLLM_API_URLに送信されます。オーバーライドで変わるのはモデル名だけで、エンドポイントは変わりません。そのため、LLM_API_URLがOllamaを指している場合、ステージごとのモデルはすべてOllamaのモデルである必要があります。OpenAIを指している場合は、すべてOpenAIのモデルである必要があります。プロバイダーを実際に混在させるには（例：最適化にはローカルモデル、批評にはgpt-4oを使用）、両方のモデル名を提供するゲートウェイ（OpenRouter、LiteLLMプロキシ、その他のOpenAI互換ルーターなど）をLLM_API_URLに指定してください。optimize_prompt単独では呼び出しごとのモデルオーバーライドに対応しておらず、LLM_MODELを使用します。

対話型の作成パネル（MCP Apps）

io.modelcontextprotocol/ui拡張機能に対応したホスト（Claude Desktop、Cursor、VS Codeなど）では、compose_promptが結果の横にライブパネルを表示します。パネルには、元のプロンプト、最適化後の出力（変更を表示する差分切り替え機能付き）、for <platform>／general purposeバッジ、6つの批評スコアバー、Accept／Reviseアクションが含まれます。Acceptを選ぶと、save_outcomeで結果が記録され（少数例メモリのループに反映されます）。Reviseを選ぶと、フィードバックがチャットに送られます。この拡張機能に対応していないホストには影響せず、同じテキストとstructuredContentの結果が返され、パネルは表示されません。

対応プラットフォーム（組み込み61種類、verifiedAtの日付付き、カスタムは無制限）

カテゴリ	プラットフォーム	デフォルト
画像（12）	Midjourney（V8.x）、OpenAI image（GPT Image 2/DALL-E 3）、Stable Diffusion、Flux（2）、Ideogram、Leonardo AI、Adobe Firefly、Grok Aurora、Google Imagen（4）、Nano Banana、Recraft、Higgsfield	Midjourney
動画（12）	Runway（Gen-4.5）、Pika（2.2）、Kling（3.0/Omni）、Luma（Ray 2）、Minimax/Hailuo（2.3）、Google Veo（3.1）、Seedance（2.0/2.5）、Wan（2.6）、HeyGen、Synthesia、CogVideoX、Higgsfield	Runway
チャット（9）	Claude、ChatGPT、Gemini、Llama、DeepSeek、Qwen、Kimi、GLM、Minimax	Claude
コード（9）	Claude、ChatGPT、Cursor、GitHub Copilot、Windsurf、DeepSeek Coder、Qwen Coder、Codestral、Gemini	Claude
ドキュメント（8）	Claude、ChatGPT、Gemini、Jasper、Copy.ai、Notion AI、Grammarly、Writesonic	Claude
音声（7）	ElevenLabs（v3）、OpenAI TTS（gpt-4o-mini-tts）、Fish Audio、Sesame、Google TTS、PlayHT、Kokoro	ElevenLabs
音楽（6）	Suno（v6）、Udio、ElevenLabs Music（v2.5）、Google Lyria（3.5）、Stable Audio、MusicGen	Suno

ツール

optimize_prompt

メインツールです。特定の AI プラットフォーム向けにプロンプトを最適化します。

{
  "prompt": "a cat sitting on a windowsill",
  "category": "image",
  "platform": "midjourney",
  "mode": "concise"
}

prompt 以外のパラメーターはすべて省略可能です。 category と platform を省略すると、ClarifyPrompt がプロンプトの内容から自動検出します。

呼び出しモードは 3 種類です。

モード	例
設定不要	{ "prompt": "sunset over mountains" }
カテゴリのみ	{ "prompt": "...", "category": "image" }
すべて明示	{ "prompt": "...", "category": "image", "platform": "dall-e" }

パラメーター：

パラメーター	必須	説明
prompt	はい	最適化するプロンプト
category	いいえ	chat、image、video、voice、music、code、document。省略時に自動検出されます。
platform	いいえ	プラットフォーム ID（例：midjourney、dall-e、veo、claude）。省略時はカテゴリのデフォルトが使用されます。
mode	いいえ	出力スタイル：concise、detailed、structured、step-by-step、bullet-points、technical、simple。デフォルト：detailed。
enrich_context	いいえ	コンテキストの補強にウェブ検索を使うには、true を設定します。デフォルト：false。
session_id	いいえ	関連する最適化を紐付け、セッションメモリーを後続の呼び出しに反映します。省略時は自動生成されます。
file_path	いいえ	アクティブなファイルのパス。言語を推測し、プラットフォームのヒントを調整します。
file_language	いいえ	アクティブなファイルの言語を明示的に指定します。
file_excerpt	いいえ	書き換えの根拠となる、アクティブなファイルの短い抜粋（≤2 KB）。
cwd	いいえ	CLAUDE.md／AGENTS.md／.cursorrules／package.json をスキャンする作業ディレクトリ。デフォルトはサーバーの cwd です。
user_locale	いいえ	トーンと言語の指定に使うロケールのヒント（例：en-US、ar-EG）。
user_pinned_instructions	いいえ	固定され、常に適用されるユーザー指示（短いコアメモリーブロック）。
include_bundle	いいえ	解決済みの ContextBundle の概要をレスポンスに含めます。デフォルト：false。
skip_intent_resolution	いいえ	意図分類器による LLM 呼び出しをスキップします（高速になりますが、意図のシグナルは失われます）。デフォルト：false。

レスポンス（1.2.0）：

{
  "id": "opt_mo9vlg9i_foohjx",
  "sessionId": "sess_mo9vlfn3_abc123",
  "originalPrompt": "a dragon flying over a castle at sunset",
  "optimizedPrompt": "a majestic dragon flying over a medieval castle at sunset --ar 16:9 --v 8.2 --style raw --q 2 --s 700",
  "category": "image",
  "platform": "midjourney",
  "mode": "concise",
  "modeSource": "analyzer",
  "analysis": {
    "category": "image",
    "intent": "creative-media",
    "recommendedMode": "detailed",
    "confidence": "high",
    "source": "llm"
  },
  "grounding": {
    "sources": ["project-rules", "workspace-meta", "target-model", "platform-hints"],
    "acceptedExamplesUsed": 0
  },
  "shape": {
    "systemPromptBudget": "standard",
    "maxTokens": 2048,
    "temperature": 0.9
  },
  "metadata": {
    "model": "qwen2.5:14b-instruct-q4_K_M",
    "processingTimeMs": 3911,
    "strategy": "ImageStrategy"
  },
  "detection": { "autoDetected": true, "detectedCategory": "image", "detectedPlatform": "midjourney", "confidence": "high" },
  "intent": { "detected": "creative-media", "confidence": "high" }
}

正規の分類フィールドは analysis です。detection フィールドと intent フィールドは、1.x との後方互換性のために残されている非推奨のエイリアスであり、2.x で削除されます。

modeSource は、最終的なモードの決定方法を示します（ユーザーが指定した場合は user、意図に基づく場合は analyzer、どちらでもない場合は default）。

grounding.sources は、Grounding Context のどのセクションが寄与したかを優先順位順に示します。grounding.acceptedExamplesUsed は、エンジンが save_outcome の履歴から取得した few-shot の例の数を示します。

shape は、対象モデルに合わせてシステムプロンプトがどのように調整されたかを示します。

clarify_with_user（1.4.0 で追加）

曖昧な下書きプロンプトを受け取ると、推測する代わりに、的を絞った確認質問を 1～3 件返します。ユーザーの依頼から適切な書き換えを生成できるか判断できない場合、optimize_prompt の前段階として使用します。

{
  "prompt": "make it better",
  "force": true
}

レスポンス：

{
  "clarificationNeeded": true,
  "reason": "Clarification recommended (analyzer confidence=low; intent=unknown; prompt is short (12 chars); caller passed force=true).",
  "questions": [
    {
      "question": "What outcome do you want from this prompt — what does success look like?",
      "reasoning": "The draft is ambiguous on the goal/audience dimension; pinning this typically resolves most downstream ambiguity.",
      "suggestedAnswer": "Make the email shorter, clearer, and more action-oriented.",
      "options": ["Make it shorter", "Make it more formal", "Make it more persuasive"],
      "dimension": "goal"
    }
  ],
  "analysis": { "category": "chat", "intent": "unknown", "confidence": "low" }
}

suggestedAnswer は常に設定されます。呼び出し元はそのまま回答として採用し、処理を続行できます。options は省略可能で、UI クライアントはクイック選択ボタンとして表示できます。dimension タグは、質問がどの軸について尋ねているかを分類します。

短絡処理： アナライザーの信頼度が high で、かつプロンプトが十分な長さの場合、このツールはアナライザー以外の LLM 呼び出しを行わず、clarificationNeeded: false を返します。そのため、呼び出しごとの遅延を増やすことなく、optimize_prompt の前にパイプラインとして組み込めます。短絡処理を無効にするには、force: true を渡します。

ground_prompt (1.4.0で新規)

optimize_prompt の厳格な検索拡張版です。呼び出し元が提供するソースは、プロジェクトルールやピン留めされた指示よりも優先度の高い位置に固定されます。そのため、書き換えはキュレーターが関連すると判断した内容ではなく、提供された資料に基づきます。

{
  "prompt": "rewrite the launch announcement to match our voice",
  "category": "document",
  "platform": "claude",
  "sources": [
    {
      "label": "Brand Voice Rules",
      "body": "Tone: warm, plain-spoken, no jargon. Always lead with the user benefit. Avoid 'leverage', 'synergy', 'robust'. Max sentence length: 18 words.",
      "kind": "rules"
    },
    {
      "label": "Launch Draft",
      "body": "Today we're launching FlowSync Pro — a tool to leverage AI synergy for robust team coordination...",
      "kind": "draft"
    }
  ]
}

optimize_prompt と同じ形式に加え、usedSources（キュレーションされたグラウンディングに実際に取り込まれたソース）と droppedSources（空または除外されたソース）を返します。ソースはトレース内に user-source:0、user-source:1 などとして表示されます。

**厳格モード：**空でないソースが0件の場合、暗黙にフォールスルーせずエラーになります。1ソースあたりの本文上限は4000文字です。これにより、非常に長い貼り付けが予算を独占することを防ぎます。

critique_prompt (1.4.0で新規)

LLM による評価です。候補プロンプトをデフォルトの6つの評価軸で0～10点で採点し、しきい値を下回った場合は改善した書き換えを返します。

{
  "prompt": "make it good",
  "revise_threshold": 7
}

レスポンス：

{
  "overallScore": 2.0,
  "verdict": "reject",
  "summary": "Reject — substantial rewrite required.",
  "dimensions": [
    { "name": "clarity", "score": 1, "rationale": "...", "suggestions": ["Specify what 'it' refers to", "..."] },
    { "name": "specificity", "score": 0, "rationale": "...", "suggestions": [...] },
    { "name": "intent_alignment", "score": 3, "rationale": "...", "suggestions": [...] },
    { "name": "format_fitness", "score": 2, "rationale": "...", "suggestions": [...] },
    { "name": "length_appropriateness", "score": 1, "rationale": "...", "suggestions": [...] },
    { "name": "plain_language", "score": 4, "rationale": "...", "suggestions": [...] }
  ],
  "improvedPrompt": "Improve the README's getting-started section: shorten...",
  "improvements": ["Specified the artifact (README's getting-started section)", "Added concrete success criteria", "..."],
  "judgeModel": "qwen2.5-coder:7b-instruct-q4_K_M"
}

パラメーター：

パラメーター	デフォルト	説明
prompt	—	採点する候補プロンプトです。
original_prompt	—	最適化されたバージョンを評価する場合に使用する、ユーザーの元の依頼です。intent_alignment 評価軸で使用されます。
criteria	デフォルトの6項目	カスタム評価軸：[{ name, description }, ...]。最大約8項目です。
revise_threshold	7.0	全体スコアがこの値を下回ると、書き換え処理が実行されます。
skip_rewrite	false	書き換え処理を完全にスキップします（高速化され、スコアのみを返します）。

**整合性チェック：**評価者が overall を評価軸ごとの平均より2.5点を超えて高くした場合、エンジンが補正します。

compose_prompt (1.4.0で新規)

標準的なパイプラインです。1回の呼び出しで、clarify → ground/optimize → critique → 任意の自動修正を実行します。

{
  "prompt": "Write a TypeScript function that takes an array of email strings and returns only those that match RFC 5322 syntax. Include unit tests using Vitest with at least 6 test cases.",
  "pre_clarify": "auto",
  "post_critique": true,
  "auto_revise": true
}

レスポンス（抜粋）：

{
  "stages": [
    { "name": "clarify",  "ranAt": "...", "durationMs":  541, "summary": "no clarification needed (short-circuit)" },
    { "name": "optimize", "ranAt": "...", "durationMs": 3128, "summary": "5 grounding source(s) selected" },
    { "name": "critique", "ranAt": "...", "durationMs": 3422, "summary": "verdict=accept, score=8.4" }
  ],
  "finalPrompt": "Write a TypeScript function `validateEmails(emails: string[]): string[]` that...",
  "clarificationRequired": false,
  "clarification": { "clarificationNeeded": false, ... },
  "optimization": { "id": "opt_...", "optimizedPrompt": "...", ... },
  "critique": { "overallScore": 8.4, "verdict": "accept", ... }
}

finalPrompt は、後続処理に渡すプロンプトです。auto_revise: true で、かつ critique の判定が accept ではなく、improvedPrompt がある場合を除き、optimization.optimizedPrompt（または grounding.optimizedPrompt）と同じ値になります。この場合、finalPrompt は書き換え後のプロンプトとなり、revised: true になります。

分岐：

入力	パス
sources なし	optimize_prompt 分岐（自動キュレーションによるグラウンディング）
空でない sources	ground_prompt 分岐（呼び出し元が提供したソースを厳格に固定）
pre_clarify: "auto"（デフォルト）	clarify を実行します。確信度の高いプロンプトでは、質問を提示せずに処理を続行します
pre_clarify: "always"	clarify を必ず実行し、質問が提示された場合はチェーンを停止します
pre_clarify: "never"	clarify を完全にスキップします
post_critique: true	optimize/ground の後に critique を実行します
auto_revise: true（post_critique: true の場合）	判定が accept ではなく、improvedPrompt がある場合、finalPrompt を置き換えます

**強制停止：**clarify で質問が提示された場合（pre_clarify: "always" の場合、または確信度の低いプロンプトで auto の場合のみ）、チェーンは停止し、clarificationRequired: true を返します。呼び出し元は質問に回答し、回答を反映するようプロンプトを編集してから再度呼び出します（通常は2回目の clarify をスキップするため、pre_clarify: "never" を指定します）。

1.6.0での追加項目

• max_iterations（1～5、デフォルトは1） — エージェント型の修正ループです。auto_revise: true かつ post_critique: true の場合、各イテレーションの improvedPrompt を optimize+critique に戻し、判定が accept になるか、improvedPrompt が得られなくなるか、上限に達するまで繰り返します。事前の clarify は1回だけ実行されます。レスポンスには、実行回数を示す iterations が含まれます。

• clarify_model / optimize_model / critique_model — ステージごとのモデルルーティングです。それぞれのステージで環境変数 LLM_MODEL を上書きします。コストや品質の異なるティアを使って compose をルーティングできます。例：低コストのローカルモデルで clarify、最先端のホスト型モデルで optimize、低コストモデルで critique を実行します。

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

  レスポンス内の optimization.metadata.model と critique.judgeModel には、各ステージで実際に実行されたモデルが反映されます。

inspect_context (1.2.0 で新登場)

指定したプロンプトに対して ClarifyPrompt が組み立てる ContextBundle（ワークスペースのルール、フレームワーク、対象モデルの機能、解決されたインテント、セッション履歴）を、最適化を完全に実行せずにプレビューします。最適化の結果がそのようになった理由のデバッグに役立ちます。

{
  "prompt": "Write an email to finance explaining the Q2 spend variance",
  "category": "document",
  "cwd": "/path/to/your/project"
}

完全な ContextBundle を JSON として返します。

list_traces (1.2.0 で新登場)

ローカルトレーサーが記録した最近の最適化トレースの概要一覧です（CLARIFYPROMPT_TRACE=local の場合。デフォルト）。

{ "day": "2026-04-22", "limit": 50 }

トレース ID、入力のプレビュー、解決されたインテント、対象ファミリー、レイテンシを返します。システムプロンプト全文は返しません（取得するには get_trace を使用してください）。データがある直近の日付を取得するには、day を省略します。

get_trace (1.2.0 で新登場)

ID を指定して、単一の最適化の完全なトレースを取得します。正確なシステムプロンプト、バンドルの概要、出力が含まれます。

{ "id": "opt_xxx", "lookback_days": 7 }

save_outcome (1.2.0 で新登場)

過去の最適化が accepted、edited、rejected のどれだったかを ClarifyPrompt に伝えます。採用された出力は、同じセッション内の類似した今後のプロンプト用の少数ショット例になります。1.3+ では、永続メモリレイヤーにも反映されます。IDE／エージェント／呼び出し元は、ユーザーが最適化の結果に基づいて操作した後にこれを呼び出すことが想定されています。

{
  "optimization_id": "opt_xxx",
  "session_id": "sess_yyy",
  "verdict": "accepted",
  "diff": "optional: the user's edited version or a patch"
}

list_categories

7 つのカテゴリーすべてについて、プラットフォーム数（組み込みとカスタム）およびデフォルトを一覧表示します。

list_platforms

指定したカテゴリーで利用可能なプラットフォームを、登録済みのカスタムプラットフォームも含めて一覧表示します。デフォルトのプラットフォームと、カスタム指示が設定されているかどうかも表示します。

list_modes

説明付きで、7 つの出力モードすべてを一覧表示します。

register_platform

プロンプト最適化用のカスタム AI プラットフォームを新規登録します。

{
  "id": "my-llm",
  "category": "chat",
  "label": "My Custom LLM",
  "description": "Internal fine-tuned model",
  "syntax_hints": ["JSON mode", "max 2000 tokens"],
  "instructions": "Always use structured output format",
  "instructions_file": "my-llm.md"
}

パラメーター	必須	説明
id	はい	一意の ID（小文字、英数字とハイフン）
category	はい	このプラットフォームが属するカテゴリー
label	はい	人が読みやすいプラットフォーム名
description	はい	短い説明
syntax_hints	いいえ	プラットフォーム固有の構文ヒント
instructions	いいえ	インラインの最適化指示
instructions_file	いいえ	詳細な指示を記載した .md ファイルのパス

update_platform

カスタムプラットフォームを更新するか、組み込みプラットフォームに指示のオーバーライドを追加します。

組み込みプラットフォーム（Midjourney、Claude など）には、元の設定を変更せずにカスタム指示と追加の構文ヒントを追加できます。

{
  "id": "midjourney",
  "category": "image",
  "instructions": "Always pin the current version (--v 8.2), prefer --style raw",
  "syntax_hints_append": ["--no plants", "--tile for patterns"]
}

カスタムプラットフォームでは、すべてのフィールドを更新できます。

unregister_platform

カスタムプラットフォームを削除するか、組み込みプラットフォームの指示のオーバーライドを解除します。

{
  "id": "my-llm",
  "category": "chat"
}

組み込みプラットフォームの場合は、remove_override_only: true を使用すると、プラットフォーム自体には影響を与えずにカスタム指示を解除できます。

カスタムプラットフォームと指示

ClarifyPrompt では、カスタムプラットフォームの登録と最適化指示の指定が可能です。これは、.cursorrules や CLAUDE.md が AI の動作を導く方法と似ています。

仕組み

1. register_platform でカスタムプラットフォームを登録します
2. インラインまたは .md ファイルで指示を指定します
3. カスタムプラットフォームを対象にプロンプトを最適化します。指示は最適化パイプラインに挿入されます

指示ファイル

指示は、~/.clarifyprompt/instructions/ に保存された Markdown ファイルで指定できます。

~/.clarifyprompt/
  config.json                    # custom platforms + overrides
  instructions/
    my-llm.md                   # instructions for custom platform
    midjourney-overrides.md     # extra instructions for built-in platform

指示ファイルの例（my-llm.md）：

# My Custom LLM Instructions

## Response Format
- Always output valid JSON
- Include a "reasoning" field before the answer

## Constraints
- Max 2000 tokens
- Temperature should be set low (0.1-0.3) for factual queries

## Style
- Be concise and technical
- Avoid filler phrases

組み込みプラットフォームのオーバーライド

update_platform を使用すると、61 種類の組み込みプラットフォームのどれに対してもカスタム指示を追加できます。これにより、デフォルト設定を変更せずに、Midjourney、Claude、Veo などのプラットフォーム向けのプロンプト最適化方法をカスタマイズできます。

設定ディレクトリ

設定ディレクトリのデフォルトは ~/.clarifyprompt/ で、CLARIFYPROMPT_CONFIG_DIR 環境変数で変更できます。カスタムプラットフォームとオーバーライドは、サーバーを再起動しても保持されます。

ナレッジパック

ナレッジパックは、ClarifyPromptに長期的に役立つ情報を教えるMarkdownドキュメントです。YAMLフロントマターは任意です。ブランドボイス、コーディング規約、コンプライアンス体制、ドメイン固有のプロンプトパターンなどを記述します。パックはH2の境界でチャンクに分割され、埋め込み表現に変換されます。その後のすべてのoptimize_prompt／compose_prompt呼び出しで、セマンティック検索に利用されます。コンテキストキュレーターは、ワークスペースのシグナル、指示ファイル、グラウンディングソースと合わせて各チャンクをスコアリングし、利用可能なトークン枠に収まる範囲で、効用の高いものを選びます。

同梱のスターターパック

4つのパックが、すべてのnpm tarballのpacks/に含まれています。

パック	内容
anthropic-brand-voice	Anthropicが対外的に使用するトーン、文体、語彙
higgsfield-creative-handbook	Higgsfieldのモデル選択、プロンプト構成、カメラワーク、Soul IDワークフロー
nextjs-14-best-practices	サーバーファーストなNext.js 14 App Routerの規約
sox-compliance	AIを活用した財務業務向けのSarbanes-Oxley 404ガードレール

パックの読み込み

load_knowledge_pack({
  source: "https://raw.githubusercontent.com/LumabyteCo/clarifyprompt-mcp/main/packs/nextjs-14-best-practices.md",
  scope: "user"
})

または、絶対パス、もしくはインストール済みパッケージからの相対パスを指定して、ローカルから読み込みます。

load_knowledge_pack({ source: "/path/to/my-team-style-guide.md", scope: "project" })
load_knowledge_pack({ source: "./node_modules/clarifyprompt-mcp/packs/sox-compliance.md", scope: "session" })

スコープ

• user — $CLARIFYPROMPT_HOMEに保存され、このマシン上のすべてのプロジェクトで利用できます。
• project — 保存されますが、現在の作業ツリーのID（cwdと、存在する場合はgitリモートから導出されるproject-id）にスコープが限定されます。
• session — 現在のMCPセッションにスコープが限定されます。サーバーの再起動後は取得されません。

取得時には3つすべてのスコープのパックがまとめてスコアリングされ、キュレーターがトークン予算内に残すチャンクを決定します。

作成とコントリビュート

パック作成のルール（フロントマタースキーマ、チャンク境界のガイダンス、PRのマージに必要な品質基準）はpacks/README.mdに記載されています。コントリビューションは、このリポジトリへのPRとして受け付けています。フロントマターでデュアルライセンスが指定されていない限り、Apache-2.0です。

パックを別のレジストリではなくエンジンのリポジトリに置く理由

簡単に言えば、以前は別のレジストリでした。1.3から1.6.3までは、LumabyteCo/clarifyprompt-packsという別レジストリがありました。1.6.4でアーカイブされ、clarifyprompt-mcp/packs/に統合されました。これは、外部コントリビューターの参加が実現しないまま、デュアルリポジトリの運用がメンテナンスコストを招いていたためです。また、higgsfield-creative-handbookパックは1.6.2でリリースされたものの、レジストリには一度も追加されませんでした。これが分離によって生じた不整合の一例です。コミュニティからのPRが継続的に寄せられる、パック数が20を超える、ライセンスやガバナンスが分岐するといった、分割を正当化する明確な要因が生まれれば、分離する意味があります。それまでは、単一リポジトリのモデルにより、信頼できる情報源を一つに保ち、曖昧さをなくせます。

LLMの設定

ClarifyPromptはLLMを使用してプロンプトを最適化します。OpenAI互換APIおよびAnthropic APIを直接利用できます。

環境変数

変数	必須	説明
LLM_API_URL	はい	API エンドポイントの URL
LLM_API_KEY	場合による	API キー（ローカルの Ollama では不要）
LLM_MODEL	はい	モデル名／ID
LLM_TIMEOUT_MS	いいえ	LLM リクエストの呼び出しごとのタイムアウト（ミリ秒）。デフォルトは 30000（30 秒）です。大規模なローカルモデルでは値を増やしてください。たとえば、50 GB の qwen3-next:80b は呼び出しごとに約 120 秒かかることがあり、デフォルト値を超えてタイムアウトが発生します。大規模なローカルモデルには LLM_TIMEOUT_MS=180000 が安全な値です。
LLM_REASONING_EFFORT	いいえ	（1.12.1 以降） 思考チャネルモデル（gpt-oss、glm、*-thinking、deepseek-r、qwq）の推論レベルです。low | medium | high を指定します。デフォルトは low です。これらのモデルでは、推論の過程が最終回答を圧迫しないよう、max_tokens にも下限が設定されます（#3）。推論を行わないモデルでは無視されます。
CLARIFYPROMPT_HOME	いいえ	正規の設定（1.2.0 以降） ClarifyPrompt が書き込むすべてのデータのルートです。カスタムプラットフォーム、instruction .md ファイル、トレース、メモリ DB、ナレッジパックが含まれます。デフォルトは $XDG_DATA_HOME/clarifyprompt または ~/.clarifyprompt です。
CLARIFYPROMPT_TRACE	いいえ	off | local | otel を指定します。デフォルトは local です。トレースは厳密にローカルの JSONL 形式で、アップロードされることはありません。
EMBED_API_URL	いいえ	（1.3.0 以降） メモリとナレッジパックの検索に使用する埋め込みエンドポイントです。OpenAI 互換の /v1/embeddings エンドポイントを指定できます。未設定の場合は LLM_API_URL がデフォルトで使用されます。Ollama ユーザーはそのまま利用できます。
EMBED_API_KEY	いいえ	（1.3.0 以降） 埋め込み API キーです。未設定の場合は LLM_API_KEY がデフォルトで使用されます。ローカルの Ollama では不要です。
EMBED_MODEL	いいえ	（1.3.0 以降） デフォルトは nomic-embed-text:v1.5（768 次元。ollama pull nomic-embed-text で取得）です。OpenAI の場合は text-embedding-3-small、Voyage の場合は voyage-3、Cohere の場合は embed-english-v3.0 に変更してください。
EMBED_DIMENSION	いいえ	（1.3.0 以降） 埋め込み出力の次元数です。デフォルトは 768 です。使用する埋め込みモデルに合わせる必要があります（OpenAI の text-embedding-3-small では 1536、Voyage では 1024 など）。
SEARCH_PROVIDER	いいえ	enrich_context: true の場合に、任意でウェブ検索の情報を補完するプロバイダーです。tavily（デフォルト） | brave | serper | serpapi | exa | searxng のいずれかを指定します。
SEARCH_API_KEY	いいえ	設定した SEARCH_PROVIDER の API キーです。セルフホストの SearXNG では不要です。
SEARCH_API_URL	いいえ	検索エンドポイントの URL です。セルフホストの SearXNG を使用する場合にのみ必要です（使用するインスタンスを指定してください）。
CLARIFYPROMPT_SUPPRESS_LEGACY_WARN	いいえ	1 に設定すると、CLARIFYPROMPT_CONFIG_DIR／CLARIFYPROMPT_DATA_DIR の使用時に表示される非推奨の案内メッセージを非表示にします。
CLARIFYPROMPT_CONFIG_DIR	いいえ	レガシー CLARIFYPROMPT_HOME の別名です。引き続き動作しますが、2.x で削除される予定です。
CLARIFYPROMPT_DATA_DIR	いいえ	レガシー CLARIFYPROMPT_HOME の別名です。引き続き動作しますが、2.x で削除される予定です。

プロバイダーの例

Ollama（ローカル、無料）：

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

Ollama — ローカル経由でクラウドモデルを利用（推奨）：

ローカルの Ollama で Ollama Cloud にサインインしている場合、:cloud モデルはすべて透過的に Ollama Cloud 経由でルーティングされます。同じ URL を使用でき、別途 API キーを用意する必要はありません。機能テーブルは 推論／思考バリアント（gpt-oss、kimi-k2-thinking、qwen3-thinking、deepseek-r1 など）を自動検出し、思考を完了して実際にコンテンツを生成できるよう maxTokens を引き上げます。

LLM_API_URL=http://localhost:11434/v1
LLM_MODEL=gpt-oss:20b-cloud        # or kimi-k2.6:cloud, qwen3-next:80b-cloud, glm-4.6:cloud, etc.

Ollama — クラウドエンドポイントに直接接続（ローカルへのインストール不要）：

LLM_API_URL=https://ollama.com/v1
LLM_API_KEY=your-ollama-cloud-key
LLM_MODEL=qwen2.5:7b

OpenAI：

LLM_API_URL=https://api.openai.com/v1
LLM_API_KEY=sk-...
LLM_MODEL=gpt-4o

推論モデル（gpt-5、o3、o4-mini）も動作します。クライアントが max_completion_tokens と temperature の要件を自動的に処理します。これらのモデルは長時間思考するため、LLM_TIMEOUT_MS を引き上げてください（例：180000）。デフォルトの 30 秒では短すぎることがよくあります。

Anthropic Claude：

LLM_API_URL=https://api.anthropic.com/v1
LLM_API_KEY=sk-ant-...
LLM_MODEL=claude-sonnet-5

Google Gemini：

LLM_API_URL=https://generativelanguage.googleapis.com/v1beta/openai
LLM_API_KEY=your-gemini-key
LLM_MODEL=gemini-flash-latest

API キーでアクセスできるモデルを使用してください。古い ID（例：gemini-2.0-flash、gemini-2.5-flash）は、新しい API キーでは 404 "no longer available to new users" を返します。gemini-flash-latest は現在の Flash モデルを参照します。（注：gemini-2.5-flash-image —「Nano Banana」— は画像モデルです。LLM_MODEL には指定できません。ここにはテキストモデルを指定する必要があります。代わりに、画像 プラットフォーム として指定してください。）

Groq：

LLM_API_URL=https://api.groq.com/openai/v1
LLM_API_KEY=gsk_...
LLM_MODEL=llama-3.3-70b-versatile

DeepSeek：

LLM_API_URL=https://api.deepseek.com/v1
LLM_API_KEY=your-deepseek-key
LLM_MODEL=deepseek-chat

OpenRouter（任意のモデル）：

LLM_API_URL=https://openrouter.ai/api/v1
LLM_API_KEY=your-openrouter-key
LLM_MODEL=anthropic/claude-sonnet-4

Together AI、Fireworks、Mistral、xAI、Cohere、Perplexity、LM Studio、vLLM、LocalAI、Jan、GPT4All など、20 以上の対応プロバイダーの全リストは .env.example をご覧ください。

ウェブ検索（任意）

optimize_prompt の呼び出しで enrich_context: true を設定すると、コンテキストを拡充できます。ClarifyPrompt は最適化の前にウェブを検索し、関連するコンテキストを取得します。

対応している検索プロバイダー：

プロバイダー	変数	URL
Tavily（デフォルト）	SEARCH_API_KEY	tavily.com
Brave Search	SEARCH_API_KEY	brave.com/search/api
Serper	SEARCH_API_KEY	serper.dev
SerpAPI	SEARCH_API_KEY	serpapi.com
Exa	SEARCH_API_KEY	exa.ai
SearXNG（セルフホスト）	—	github.com/searxng/searxng

SEARCH_PROVIDER=tavily
SEARCH_API_KEY=your-key

最適化前と最適化後

画像（Midjourney）

Before: "a cat sitting on a windowsill"

After:  "a tabby cat sitting on a sunlit windowsill, warm golden hour
         lighting, shallow depth of field, dust particles in light beams,
         cozy interior background, shot on 35mm film, warm amber color
         palette --ar 16:9 --v 8.2 --style raw --q 2"

動画（Veo 3.1）

Before: "a timelapse of a city"

After:  "Cinematic timelapse of a sprawling metropolitan skyline
         transitioning from golden hour to blue hour to full night.
         Camera slowly dollies forward from an elevated vantage point.
         Light trails from traffic appear as the city illuminates.
         Clouds move rapidly overhead. Ambient city soundscape builds
         as the lights come on (native audio). Duration: 8s, extendable.
         Style: documentary cinematography, 4K, 16:9."

コード（Claude）

Before: "write a function to validate emails"

After:  "Write a TypeScript function `validateEmail(input: string): boolean`
         that validates email addresses against RFC 5322. Handle edge cases:
         quoted local parts, IP address domains, internationalized domain
         names. Return boolean, no exceptions. Include JSDoc with examples
         of valid and invalid inputs. No external dependencies."

音楽（Suno）

Before: "compose a chill lo-fi beat for studying"

After:  "Compose an instrumental chill lo-fi beat for studying.
         [Tempo: medium] [Genre: lo-fi] [Length: 2 minutes]"

コンテキストエンジン（1.2.0）

すべての最適化は、コンテキストを 1 つのまとまりとして最初から最後まで引き継ぐ、5 つの統合パスを通じて実行されます。

1. 分析 — 1 回の analyzePrompt() LLM 呼び出しで category、intent、recommendedMode をまとめて生成するため、これらが食い違うことはありません。意図と表面的なキーワードが矛盾する場合は、意図が優先されます（例："validate emails" → document ではなく code）。
2. モードの調整 — ユーザーが明示した mode が優先されます。指定されていない場合は、分析から導かれた意図に基づく推奨モードが適用されます。レスポンスの modeSource で、どちらが適用されたかを確認できます。
3. プロンプトの調整 — 対象モデルの機能シグナルに基づき、systemPromptBudget（小型ローカルモデル向けには簡潔に、100K 以上のコンテキストモデル向けには充実した内容に）、maxTokens、temperature（意図を考慮）、および例を含めるかどうかが決まります。
4. 意図のオーバーレイ — 各意図に応じた短いオーバーレイ（production-code：エラー処理とテストを要求、data-extract：厳格なスキーマを要求、brand-voice：トーンを最初に提示、など）を、ストラテジーのシステムプロンプトに組み込みます。
5. グラウンディングコンテキスト — ユーザーが固定した指示 → プロジェクトルール → アクティブなファイル → セッション内の few-shot 例 → ウェブ検索 → ワークスペースのメタデータ → 対象モデルのヒント → カスタムプラットフォーム指示 → 組み込みの構文ヒントを、優先順位順に並べた 1 つのブロックに統合します。

収集される情報（ContextBundle）

• プロジェクト — CLAUDE.md、AGENTS.md、.cursorrules、.clinerules、clarify.md、.clarify/rules.mdのうち、最初に見つかったファイルです。package.jsonと、同じディレクトリにあるマニフェスト（pyproject.toml、Cargo.toml、go.mod、Gemfile、composer.jsonなど）をもとに、フレームワークとプログラミング言語を検出します。
• ファイル — 任意のfile_path／file_language／file_excerpt入力です。
• セッション — 最近の最適化とその結果を保持するリングバッファー（セッションあたり20件の操作）です。承認された出力は、今後の類似プロンプトで少数ショットの例として取得されます。
• ターゲットモデル — 書き換えを行うLLMです。機能テーブルと照合されます。
• ユーザー — ロケール、優先モード、固定された指示（最も優先度の高いグラウンディング）です。

エンジンが参照する情報の確認

最適化を実行せずにバンドル全体をプレビューするには、inspect_contextツールを使用します。include_bundle: trueを指定した場合にoptimize_promptが返すものと同じ形式です。

コンテキストの拡張

プロジェクトのルートにAGENTS.md／clarify.md／CLAUDE.mdを配置します。次回の最適化時に自動で読み込まれます。承認された出力を今後の書き換えに反映するには、ユーザーが結果を適用した後にsave_outcomeを呼び出します。

トレース

$CLARIFYPROMPT_HOME/traces/YYYY-MM-DD.jsonl

最適化のたびに、{id, ts, sessionId, category, platform, mode, input, bundleSummary, systemPrompt, output, model, strategy, latencyMs, shape, groundingSources, error}を記録したJSONL行が1行書き込まれます。要約にはlist_traces、完全なレコードにはget_traceを使用します。

プライバシーに関する方針：

• トレースは完全にローカルです。ClarifyPromptが所有するインフラへの外部ネットワーク呼び出しはありません。
• 外部への呼び出しは、設定したLLMエンドポイント（LLM_API_URL）と、任意の検索プロバイダー（SEARCH_API_KEY）に限られます。
• CLARIFYPROMPT_TRACE=offを指定すると、トレースを完全に無効化できます。
• このリリースにはテレメトリーはありません。テレメトリーのオプションを提供する場合は、ビルドに含める前に説明を公開し、オプトイン方式かつ匿名で提供します。

既知の制限事項とロードマップ

メモリの永続化（提供済み）

save_outcomeと少数ショット検索のループは、$CLARIFYPROMPT_HOME配下のSQLite + sqlite-vecにデータを永続化します。セッション、最適化、結果、事実、パックのチャンクはすべて再起動後も保持されます。同一セッション内での高速処理には、インメモリーのリングバッファーも引き続き使用します。セッション単位のエントリーはセッションIDにひも付けられるため、後続のセッションでは取得されません。

意図の判定精度は、分析に使用するモデルの性能に左右されます

分析器には、書き換えに使用するものと同じLLM_MODELが使われます。統合テストでは、次の結果が得られました。

• Qwen 2.5 7Bおよび14B → テストした形式の整ったプロンプトすべてで正しく判定しました。
• Llama 3.2 3B → あいまいなプロンプトを過剰に断定することがあります（例：本来はunknown/lowが適切な「make it better」をbrand-voice/highと判定）。同じプロンプトでも、より大きなモデルは正しくunknown/lowを返しました。

ガイダンス： LLM_MODELには、ローカルモデルなら7B以上（または任意の最先端のホスト型モデル）を推奨します。レイテンシを重視する場合は、skip_intent_resolution: trueを設定して分析器をスキップできます。この場合、エンジンはユーザーのヒントに基づくカテゴリとデフォルトモードにフォールバックします。意図に基づくモードとオーバーレイは使用されなくなりますが、グラウンディングと形式は維持されます。同梱の評価ハーネス（evals/、npm run eval）には公開フィクスチャセットが含まれているため、独自のフィクスチャを使って分析器のスコアを測定し、モデルや分類器の変更によるリグレッションを検出できます。

推奨モデル

同梱のマトリックスランナーでスコアを確認できます：npm run matrix -- --models <a>,<b>,…。最近の実行結果（2026-06、30 件のフィクスチャを使用、合格しきい値 0.85、スコア = フィクスチャスコアの平均）：

Model	Where	Suite score	Notes
glm-5.2:cloud	クラウド · 推論	99%	総合トップです。思考バジェットは自動的に処理されます（1.12.1）。
gpt-oss:20b-cloud	クラウド · 推論	98%	OpenAI のオープンウェイトモデルです。reasoning_effort は自動的に適用されます（1.12.1）。
qwen2.5-coder:7b	ローカル	97%	小型のローカルモデルで、スイートのほぼ全体に対応できます。検証済みのローカルファーストのデフォルトです。
gemma4:31b-cloud	クラウド	92%	バランスの取れた優れたモデルです。

各実行でしきい値に届かない少数のフィクスチャは、主観的な analyzer-* の意図／モード分類と、根拠付け表現のケース（モデル間のコンテンツのばらつき）です。パイプラインのエラーではありません。決定論的なパイプラインのフィクスチャ（clarify、ground、critique、compose、memory、packs）は、どのモデルでも合格します。デフォルトは引き続きローカルファースト（qwen2.5:7b）です。意図の精度をさらに高めたい場合は、最先端モデルまたは推論モデルを選んでください。推論モデル（gpt-oss、glm、*-thinking など）は、コンテンツが空で返されないよう自動調整されます（max_tokens の下限設定と reasoning_effort）。詳しくは LLM_REASONING_EFFORT を参照してください。

能力テーブルはすべてを網羅しているわけではありません

現在のエントリー：Claude、GPT-4/o-series、Gemini、Grok、DeepSeek（チャット＋推論）、Qwen、Llama、Mistral/Codestral、Mixtral、Gemma、Phi、Cohere Command、Aya、Kimi、GLM、Minimax、GPT-OSS、Yi、Nemotron。未登録のモデルは capabilities: {} と standard のプロンプト形式にフォールバックします。機能は引き続き利用できますが、モデルに応じたサイズ調整は行われません。エントリーの追加は、src/engine/context/targetModelSignals.ts のデータのみを変更すれば完了します。

推論／chain-of-thought モデル

第一級のケースとしてサポートされています。エンジンはファミリーレベル（o1/o3/o4、deepseek-reasoner、gpt-oss）とバリアントレベル（ID が /\b(thinking|reasoner|reasoning)\b/ または /\br[12]\b/ に一致するモデル。例：kimi-k2-thinking:cloud、qwen3-thinking:72b、qwen-r1-distill など）で推論モデルを自動検出します。これらのモデルでは、考察とコンテンツの生成に十分な余裕を持たせるため、maxTokens が自動的に 8192 以上に引き上げられます。reasoning フィールドが最適化済みプロンプトとして表示されることはありません。表示されるのは content のみです。

アーキテクチャ

clarifyprompt-mcp/
  src/
    index.ts                           MCP server entry point (23 tools, 6 resources: 1 static + 4 templates + 1 ui panel)
    apps/                              MCP Apps compose panel (panel.html template + panel.ts, bundled at build time)
    engine/
      config/
        categories.ts                  CategoryConfig type + CATEGORIES const (loaded from YAML in 1.5.0)
        platformLoader.ts              (1.5.0) YAML pack loader — reads packs/platforms/*.yaml at boot
        paths.ts                       Unified $CLARIFYPROMPT_HOME resolver (1.2.0)
        persistence.ts                 ConfigStore — JSON config + .md file loading
        registry.ts                    PlatformRegistry — merges built-in + custom
      context/                         Context Engine (1.2.0)
        types.ts                       ContextBundle + signal types + AnalysisSignal
        projectSignals.ts              CLAUDE.md / AGENTS.md / .cursorrules / manifests scan
        fileSignals.ts                 Active-file path + language + excerpt
        sessionSignals.ts              In-memory per-session ring buffer + outcome retrieval
        targetModelSignals.ts          Model → capabilities mapping
        promptAnalyzer.ts              Unified analyzer: category + intent + recommendedMode
        gitSignals.ts                  (1.6.0) branch + HEAD + dirty + recent commits
        environmentSignals.ts          (1.6.0) nowIso + weekday + timezone
        bundle.ts                      Bundle orchestrator
      trace/                           Local tracing (1.2.0)
        types.ts                       TraceEntry schema (shape, groundingSources, error)
        writer.ts                      JSONL + OTel-stub writer, reader, lookup
      memory/                          Persistent memory + knowledge packs (1.3.0)
        store.ts                       SQLite + sqlite-vec; bi-temporal facts, outcomes, packs
        packs.ts                       Knowledge-pack loader (local / URL / inline)
        reflection.ts                  LLM fact extraction on save_outcome
      llm/client.ts                    Multi-provider LLM client (OpenAI + Anthropic)
      search/client.ts                 Web search (6 providers; results merge into Grounding Context)
      optimization/
        engine.ts                      Core orchestrator — analyzer, shape, grounding, retrieval, trace
        curator.ts                     Token-budget grounding curator (1.3.0)
        groundingContext.ts            Priority-ordered context assembly + mode/shape helpers
        types.ts                       OptimizationContext + result shape (UserProvidedSource)
        strategies/
          base.ts                      Bundle-aware base strategy (intent overlay + shape-aware sizing)
          chat.ts                      9 platforms
          image.ts                     12 platforms
          video.ts                     11 platforms
          voice.ts                     7 platforms
          music.ts                     4 platforms
          code.ts                      9 platforms
          document.ts                  8 platforms
      clarification/clarify.ts         (1.4.0) clarify_with_user — targeted questions w/ defaults
      grounding/ground.ts              (1.4.0) ground_prompt — strict caller-provided grounding
      critique/critique.ts             (1.4.0) critique_prompt — LLM-as-judge + optional rewrite
      composition/compose.ts           (1.4.0) compose_prompt — canonical clarify→ground/opt→critique pipeline
  evals/                                Eval harness v0 (1.3.0; setup: multi-call in 1.5.0)
    run.mjs                            YAML fixtures → MCP server → scored HTML report
    fixtures/*.yaml                    33 deterministic fixtures
    schema.json                        Fixture schema
  scripts/build-panel.mjs               (1.14.0) bundles the MCP Apps panel into dist/apps/
  packs/                                Knowledge packs + platform packs (single source of truth, 1.6.4+)
    README.md                          Pack authoring guide (frontmatter, chunks, quality bar)
    *.md                               Knowledge packs — 4 bundled, community-contributable via PR
    platforms/*.yaml                   (1.5.0) built-in AI platform declarations — 7 files, 58 platforms
  docs/adoption/                        (1.5.0) launch-post drafts + catalog submission specs

Docker

docker build -t clarifyprompt-mcp .
docker run -e LLM_API_URL=http://host.docker.internal:11434/v1 -e LLM_MODEL=qwen2.5:7b clarifyprompt-mcp

開発

git clone https://github.com/LumabyteCo/clarifyprompt-mcp.git
cd clarifyprompt-mcp
npm install
npm run build

MCP Inspector でテストします：

npx @modelcontextprotocol/inspector node dist/index.js

接続する前に、Inspector の「Environment Variables」セクションで環境変数を設定してください。

テスト＋評価

Command	What it does
npm run test:integration	Day-1 統合テスト一式（意図＋根拠付け＋形式）
npm run test:day2	Day-2 メモリ＋キュレーター＋リフレクションのテスト一式
npm run test:reasoning	推論モデルのカバレッジ（chain-of-thought の maxTokens 引き上げ）
npm run test:wire	MCP ワイヤースモークテスト（サーバーの起動、ツール一覧、initialize の往復処理）
npm run test:all	4 つのテスト一式を順番にすべて実行
npm run eval	20 件の決定論的評価フィクスチャを実行し、evals/report.html を生成
npm run eval -- --filter <name>	<name>（またはタグ）に一致するフィクスチャのみを実行
npm run eval -- --quiet	終了コードのみを出力（CI に適しています）

評価ハーネスの詳細、フィクスチャ形式、複数モデルのマトリックス手順については、evals/README.md を参照してください。

CI／品質ゲート

このリポジトリには、5 つのジョブを含む GitHub Actions ワークフロー（.github/workflows/ci.yml）が用意されています。

ジョブ	実行タイミング	ゲートの内容
build	すべてのプッシュと PR	Linux と macOS で、Node 18/20/22 を使った型チェック、ビルド、起動スモークテスト
secrets-audit	すべてのプッシュと PR	トラッキング対象ファイル内の既知の API キープレフィックスを git grep で検査
evals	すべてのプッシュと PR（オプトイン）	gpt-4o-mini に対して npm run eval を実行します。OPENAI_API_KEY シークレットが設定されていない場合は成功としてスキップされ、設定されている場合はいずれかのフィクスチャにリグレッションがあると公開をブロックします
docker	すべてのプッシュと PR	docker build とコンテナーの起動スモークテスト
publish	タグのプッシュ時のみ	タグが package.json#version と一致する場合に npm publish --provenance を実行します。上記 4 つすべてのジョブの成功が条件です

フォークで evals をリリースゲートとして有効にするには：

1. リポジトリ → Settings → Secrets and variables → Actions → New repository secret
2. 名前：OPENAI_API_KEY · 値：gpt-4o-mini にアクセスできる OpenAI API キー
3. プッシュするか、任意のワークフローを再実行します

コスト：約 0.005 ドル／CI 実行（gpt-4o-mini の料金に基づき、有効なフィクスチャ 17 件 × 入力トークン約 1500 個 × 出力トークン約 600 個）。eval ハーネスの HTML レポートはビルドアーティファクトとしてアップロードされ（30 日間保持）、ローカルで再実行しなくても失敗を確認できます。

タグのプッシュ時に npm への公開を有効にするには： clarifyprompt-mcp をスコープとする Granular Access Token（2FA バイパスを有効化）を使って、NPM_TOKEN シークレットを追加します。手順は同じ Settings フローです。

ライセンス

Apache-2.0