Promptlint MCP

promptlint-mcp

AI プロンプトをコードのように lint します。トークンを節約し、矛盾を検出します。

AI プロンプト（システムプロンプト、エージェントへの指示、ツールの説明など）を対象とする静的アナライザーです。CLI と MCP サーバーとして動作し、Claude Code （または MCP 対応の任意のエージェント）がプロンプトを送信する前に lint できます。

---

クイックデモ

よくある（気づかないうちに問題のある）システムプロンプトで promptlint を実行します：

$ node src/cli.mjs examples/bad-prompt.md

promptlint examples/bad-prompt.md
  score  14/100
  tokens 367 → 307 (-60, 16% saved)
  issues 14

  info   [ambiguous-pronoun] Pronoun "that" has no clear referent (line 1)
         → Replace with a concrete noun, e.g. "this" → "the config file".
  ...
  error  [contradiction] Contradicting directives (length): "concise" vs "detailed"
         → Pick one, or scope each with a clear condition (e.g. by task type).
  error  [contradiction] Contradicting directives (commenting): "do not add comments" vs "explain each step"
         → Pick one, or scope each with a clear condition (e.g. by task type).
  info   [trailing-fluff] "please" fluff (match 1 of 1)
         → Delete. AIs do not need politeness tokens.
         · Please
  ...

error レベルの矛盾を 2 件検出し、スコアを 14/100 に制限しました。--trim を使うと 60 トークン（16%）を削減できます。

こちらは、小さな入力に対する --trim の動作例です：

$ echo "You are a helpful assistant. Please always be concise. Thank you for your help! When the user asks a question, handle it carefully." | node src/cli.mjs - --trim

You are a helpful assistant. Always be concise. When the user asks a question, handle it carefully.

投稿用の下書きと（TODO の）asciinema キャストについては、docs/promo/ をご覧ください。

---

その理由

• 矛盾："be concise" と "be thorough" を併記しても、気づかれないまま使われ、リクエストのたびにトークンを無駄にします。promptlint は、対になる反対の指示（長さ／トーン／頻度／コメント／質問）に error のフラグを付けます。
• 冗長性：よく似た文（Jaccard > 0.6）には、それぞれ warn が 1 件付きます。一方を削除してください。
• 曖昧な代名詞："use it" や "handle that" のように、文の途中に指示対象がない表現には、行番号付きでフラグが付きます。文頭の大文字は指示対象として数えないため、通常の英語で誤検出は発生しません。
• 長いコード例：約 1200 文字または 30 行を超えるフェンス付きコードブロックには warn が付きます。コード例は、形だけを残してほとんどの場合短縮できます。
• 過剰な丁寧表現：Please／Thanks／I hope this helps／Let me know if…／Feel free to… を検出・カウントします。また、--trim を使うと、実際の命令形を保ったまま削除します。

対象範囲：英語のプロンプトや文章であり、ソースコードではありません。 日本語のプロンプトや JavaScript ファイルは、実際には問題があっても問題なしと判定されます。

---

インストール

CLI と MCP サーバーを一度にインストールします：

npm install -g promptlint-mcp

2 つの実行ファイルが $PATH に配置されます：

実行ファイル	説明
promptlint	CLI（ファイルまたは stdin を lint）
promptlint-mcp	MCP サーバー（stdio トランスポート）

インストールせずに実行

# CLI: lint a file
npx -p promptlint-mcp promptlint <file>

# CLI: lint stdin
echo "be concise and thorough" | npx -p promptlint-mcp promptlint -

# MCP server (auto-launched by Claude Code via mcp config; see below)
npx -y promptlint-mcp

ソースから（開発する場合）

git clone https://github.com/sean-sunagaku/promptlint-mcp.git
cd promptlint-mcp
npm install
node src/cli.mjs examples/bad-prompt.md

Node >= 18 が必要です。MCP SDK 以外に、実行時の依存関係はありません。

---

CLI の使い方

デフォルトの人間向けレポート

node src/cli.mjs examples/bad-prompt.md

promptlint examples/bad-prompt.md
  score  14/100
  tokens 367 → 307 (-60, 16% saved)
  issues 14

  info   [ambiguous-pronoun] Pronoun "that" has no clear referent (line 1)
         → Replace with a concrete noun, e.g. "this" → "the config file".
  ...
  error  [contradiction] Contradicting directives (length): "concise" vs "detailed"
         → Pick one, or scope each with a clear condition (e.g. by task type).
  error  [contradiction] Contradicting directives (commenting): "do not add comments" vs "explain each step"
         → Pick one, or scope each with a clear condition (e.g. by task type).
  info   [trailing-fluff] "thanks" fluff (match 1 of 2)
         → Delete. AIs do not need politeness tokens.
         · Thank you
  info   [trailing-fluff] "please" fluff (match 1 of 1)
         → Delete. AIs do not need politeness tokens.
         · Please
  info   [trailing-fluff] "hope-helps" fluff (match 1 of 1)
         → Delete. AIs do not need politeness tokens.
         · I hope this helps
  ...

問題のないプロンプト（examples/good-prompt.md を参照）は、問題が 0 件で score 100/100 を返します。何も表示されないのは仕様です。

機械処理向けの --json

node src/cli.mjs examples/bad-prompt.md --json

{
  "score": 14,
  "issues": [
    {
      "rule": "ambiguous-pronoun",
      "severity": "info",
      "message": "Pronoun \"that\" has no clear referent (line 1)",
      "line": 1,
      "suggestion": "Replace with a concrete noun, e.g. \"this\" → \"the config file\"."
    },
    {
      "rule": "contradiction",
      "severity": "error",
      "message": "Contradicting directives (length): \"concise\" vs \"detailed\"",
      "suggestion": "Pick one, or scope each with a clear condition (e.g. by task type)."
    }
  ],
  "trimmed": "…",
  "tokensBefore": 367,
  "tokensAfter": 307,
  "saved": 60,
  "savedPercent": 16
}

入力が空の場合は "note": "empty input" が追加されます。余分な表現だけの入力（例："Thanks!"）は、削除すると空になるため、代わりに元の内容と "trimmerFallback": true を返します。安全なドロップイン実装が、LLM に空のプロンプトを渡すことはありません。

削除後の出力を表示する --trim（パイプ用）

echo "You are a helpful coding assistant. Please always be concise. Thank you for your help! When the user asks a question, handle it carefully. If they provide code, review it. Let me know if anything is unclear. I hope this helps!" \
  | node src/cli.mjs - --trim

You are a helpful coding assistant. Always be concise. When the user asks a question, handle it carefully. If they provide code, review it.

フェンス付きコードブロックはそのまま保持されます。クォート文字列（"…"）とインラインのバッククォート（`…`）は、余分な表現を削除する前にマスクされるため、例のテキストは変更されません。

標準入力

cat prompt.md | node src/cli.mjs -

レポートのヘッダーには promptlint <stdin> と表示されます。

その他のフラグ

node src/cli.mjs --rules      # list the 5 rule IDs, one per line
node src/cli.mjs --help       # usage

終了コード

コード	意味
0	エラーなし（warn／info は問題ありません）
1	error 重要度の問題が 1 件以上
2	不正な使い方（ファイルの指定漏れ、読み込み失敗など）

---

MCP サーバーの使用方法

Claude Code に 1 つのコマンドで登録します（クローンやグローバルインストールは不要です）。

claude mcp add promptlint -- npx -y promptlint-mcp

または、~/.claude.json（ユーザースコープ）もしくはプロジェクトの .mcp.json （プロジェクトスコープ）に以下を追加します。

{
  "mcpServers": {
    "promptlint": {
      "command": "npx",
      "args": ["-y", "promptlint-mcp"]
    }
  }
}

パッケージをグローバルインストールしている場合は、絶対パス形式も使用でき、 npx の初回ダウンロードを省略できます。

{
  "mcpServers": {
    "promptlint": {
      "command": "promptlint-mcp"
    }
  }
}

公開されるツール

ツール	入力	返される値
lint_prompt	{ text: string }	2 つの text コンテンツ項目：[0] 人間向けの 1 行の概要（"score: X/100 · issues: N · tokens: A → B …"）、[1] lint() の結果全体を含む JSON（JSON.parse(result.content[1].text) で解析します）。
trim_prompt	{ text: string }	2 つの text コンテンツ項目：[0] トリミングされたプロンプト、[1] 削減量のフッター（"Saved N tokens (P%). Original: A, trimmed: B."）。矛盾、冗長性、曖昧さは解決しません。これらについては lint_prompt を実行してください。

両方のツールは純粋で、冪等です。ネットワーク、ファイルシステム、状態は使用しません。

---

ルール

ID	重大度	検出対象	発動例
contradiction	error	長さ／語調／頻度／禁止／コメント／質問に関する、対になった相反する指示	"be concise" + "be thorough"
redundancy	warn	Jaccard 単語集合類似度が 0.6 を超える 2 つの文	言い回しを変えて、どちらも「英語で回答する」と述べる 2 つの段落
long-example	warn	1200 文字または 30 行を超えるフェンス付きコードブロック	40 行のヘルパー関数をそのまま貼り付ける
ambiguous-pronoun	info	文の途中に具体的な指示対象がない it / this / that / these / those	"Use it to figure out what to do."
trailing-fluff	info	丁寧表現／埋め草：please、thanks、I hope this helps、let me know if…、feel free to…、sorry、certainly/absolutely/of course	"Please refactor the code. Thanks!"

スコアの計算式：100 - (errors*25 + warns*10 + infos*3)。その後、エラーがある場合は <=59、 警告が 2 件以上ある場合は <=79 に制限されます。重大度の上限は 信号機のように機能します。エラーが 1 件でもあれば、件数にかかわらず危険域です。

---

料金とロードマップ

無料（OSS、MIT）

• CLI（node src/cli.mjs）— 3 つすべてのモード（レポート／JSON／トリミング）と 5 つすべてのルール。
• MCP サーバー（node src/mcp.mjs）— 両方のツールを無制限に使用できます。
• アカウント不要、テレメトリーなし、ネットワーク接続なし。

Pro（提供予定、月額 $9）

• チームで共有できるカスタムルール辞書（プロジェクトで禁止する語句、必須ヘッダー、禁止する矛盾）。
• 差分表示付きのプロジェクトごとの lint 履歴。
• プロジェクト横断のトークン節約ダッシュボード（「今月、チームで 120 万トークンを節約しました」）。

Pro はまだ提供されていません。現在、登録フォームはありません。 関心がある場合は👍 先行アクセスの Issue（#1） で登録してください。招待は 👍 の順に DM でお送りします。

---

開発

スモークテスト

npm run lint:self         # lints examples/bad-prompt.md

期待される結果：終了コード 1（矛盾による error が 2 件）、スコアは 10 点台前半、すべてのルールが発動します。これが変わった場合、ルールが後退しています。

ベースライン

examples/good-prompt.md は常に 100/100、問題 0 件でなければなりません。変更によってこの条件が崩れるなら、その変更は誤りです。

ルールの追加

ルールは src/linter.mjs にあります。各ルールは単純な関数です。

function ruleFooBar(text) {
  // return an array of { rule, severity, message, samples?, suggestion, line? }
  return [];
}

lint() 内の issues 配列に追加し、RULES エクスポートに ID を追加してください。コードではなく文章を対象にする場合は、フェンス付きの例で発動しないよう、maskCodeBlocks() のコピーに対して実行してください。文の分割が必要な場合は、splitSentences（引用符を考慮）または splitSentencesPreservingDelims（引用符を考慮し、トリマー用に区切り文字を保持）を再利用してください。

矛盾

src/linter.mjs の先頭にある CONTRADICTION_PAIRS を拡張してください。各項目は次のとおりです。

{ a: ["keyword-a", ...], b: ["keyword-b", ...], label: "short-label" }

既存のラベル：length、tone、frequency、prohibition、commenting、 asking。

---

コミュニティ

• 💬 ディスカッション — 質問、アイデア、プロンプトにまつわる体験談
• 🐛 Issue — バグ、機能リクエスト
  • #1 Pro の早期アクセス（ピン留め）
  • #2 ロードマップ
  • #3 既知の問題 / 2日目以降のバックログ
• ⭐ トークンの節約に役立ったら、リポジトリにスターを付けてください — 見つけてもらいやすくなり、ほかの AI ユーザーにも役立ちます。

開発方法

このパッケージは、2つの AI エージェントチームによって最初から最後まで開発されました。

• ai-auto-improve-app — 製品の構築と改善を担当しました。顧客 AI がツールを使ってフィードバックを作成 → 開発者 AI がコードを修正 → これを繰り返します。各ラウンドのコミット（round-001 … round-003）は、そのラウンドの顧客 AI のフィードバックに対する開発者 AI の対応です。
• ai-launch-team — 公開と配布を担当しました。5つのサブエージェントが、npm への公開、GitHub Release、awesome-mcp への PR、Discussions のスレッド、SNS 投稿文の草案、SVG/PNG アセットの生成を担当しました。

これらを合わせて、製品は「空のリポジトリ」から「npm 上の v0.1.2 + awesome-mcp への PR 2件 + Discussions のシードスレッド 2件 + Issue 4件 + SNS 投稿文の草案一式」へと成長しました。手作業で行ったのは、プラットフォームで義務付けられている SMS / OTP 認証（X アカウントの作成、npm の 2FA 設定）だけで、あとはすべて AI が担当しました。

ライセンス

MIT — LICENSE を参照してください。