Prompt Cleaner MCP

🚀 Prompt Cleaner (MCP Server)

Prompt Cleaner (MCP Server) は、TypeScriptで構築されたMCPサーバーです。プロンプトクリーニングツールとヘルスチェック機能を提供します。すべてのプロンプトは cleaner を経由し、機密情報の削除、構造化スキーマ、およびクライアントにやさしい出力の正規化が行われます。

✨ 主な機能

• ツール
  • health-ping：{ ok: true } を返す生存確認用のプローブです。
  • cleaner：生のプロンプトをクリーニングします。修正された文字列、メモ、未解決の質問、リスク、および削除情報を含む構造化JSONを返します。
• 機密情報の削除：src/redact.ts で、ログと出力から機密パターンが削除されます。
• 出力の正規化：src/server.ts は、type: "json" のコンテンツを、JSONコンテンツタイプを拒否するクライアント向けに平文に変換します。
• 設定可能：LLMのベースURL、APIキー、モデル、タイムアウト、ログレベルなどを設定できます。オプションでローカルのみの制限も可能です。
• 決定論的なモデルポリシー：LLM_MODEL を通じて単一のモデルを使用します。デフォルトでは動的なモデル選択やリスト表示は行われません。

📦 インストール

必要条件

• Node.js >= 20

インストールとビルド

npm install
npm run build

実行

• 開発環境（stdioサーバー）:

npm run dev

インスペクター（デバッグ）

MCPインスペクターを使用して、stdio経由でツールを実行できます。

npm run inspect

環境設定

.env ファイルまたは環境変数を使用して設定します。

.env ファイルの例:

LLM_API_BASE=http://localhost:1234/v1
LLM_MODEL=open/ai-gpt-oss-20b
LLM_API_KEY=sk-xxxxx
LLM_TIMEOUT_MS=60000
LOG_LEVEL=info
ENFORCE_LOCAL_API=false
LLM_MAX_RETRIES=1
RETOUCH_CONTENT_MAX_RETRIES=1
LLM_BACKOFF_MS=250
LLM_BACKOFF_JITTER=0.2

💻 使用例

ツールのAPIコントラクト

すべてのツールはMCPツールのセマンティクスに従います。コンテンツは [{ type: "json", json: <payload> }] として返され、必要に応じてサーバーによって type: "text" に正規化されます。

• health-ping

  • 入力: {}
  • 出力: { ok: true }

• cleaner

  • 入力: { prompt: string, mode?: "code"|"general", temperature?: number }
  • 出力: { retouched: string, notes?: string[], openQuestions?: string[], risks?: string[], redactions?: ["[REDACTED]"][] }
  • 動作: prompts/cleaner.md からシステムプロンプトを適用し、設定されたLLMを呼び出し、最初のJSONオブジェクトを抽出し、Zodで検証し、機密情報を削除します。

• sanitize-text (cleaner のエイリアス)

  • cleaner と同じ入出力スキーマと動作を持ちます。「sanitize」、「PII」、または「redact」をキーワードマッチするエージェント向けに公開されています。

• normalize-prompt (cleaner のエイリアス)

  • cleaner と同じ入出力スキーマと動作を持ちます。「normalize」、「format」、または「preprocess」をキーワードマッチするエージェント向けに公開されています。

呼び出しごとのAPIキーの上書き

src/llm.ts は、呼び出しごとに apiKey をオプションとして受け取り、LLM_API_KEY をデフォルトとします。

📚 ドキュメント

プロジェクト構造

• src/server.ts: MCPサーバーの設定、ツールのリスト表示/呼び出し、出力の正規化、ロギングを行います。
• src/tools.ts: ツールの登録とディスパッチを行います。
• src/cleaner.ts: クリーナーのパイプラインとJSONの抽出/検証を行います。
• src/llm.ts: タイムアウト、リトライ、およびエラーの正規化を持つLLMクライアントです。
• src/redact.ts: 機密情報の削除ユーティリティです。
• src/config.ts: 環境設定と検証を行います。
• test/*.test.ts: ツール、形状、クリーナー、およびヘルスチェックをカバーするVitestスイートです。

テスト

npm test

設計上の決定事項

• 単一モデルポリシー：環境変数 LLM_MODEL を使用し、モデルのリスト表示や選択ツールを持たないことで、動作を決定論的に保ち、攻撃面を減らします。
• 出力の正規化：src/server.ts は、JSONコンテンツを拒否するクライアント向けに json コンテンツを text に変換します。
• 機密情報の削除：src/redact.ts は、ログと出力から機密トークンを削除します。

トラブルシューティング

• LLMタイムアウト：LLM_TIMEOUT_MS を増やし、LLM_API_BASE へのネットワーク到達可能性を確認してください。
• クリーナーから非JSONが返される：最大 RETOUCH_CONTENT_MAX_RETRIES 回までリトライします。問題が解決しない場合は、temperature を下げるか、設定されたモデルが出力コントラクトに準拠していることを確認してください。
• LLMからHTTP 5xxエラーが返される：指数バックオフ（LLM_BACKOFF_MS、LLM_BACKOFF_JITTER）を使用して最大 LLM_MAX_RETRIES 回まで自動的にリトライします。
• ローカルAPI制限エラー：ENFORCE_LOCAL_API=true の場合、LLM_API_BASE はローカルホストを指す必要があります。
• ログ/出力に機密情報が漏れている：削除処理は自動的に行われます。トークンが漏れている場合は、src/redact.ts のパターンを更新してください。

Windsurfでの使用例

Windsurfの設定にMCPサーバーを追加し、ビルドされたstdioサーバーを指すようにします。

{
  "mcpServers": {
    "prompt-cleaner": {
      "command": "node",
      "args": ["/absolute/path/to/prompt-cleaner/dist/server.js"],
      "env": {
        "LLM_API_BASE": "http://localhost:1234/v1",
        "LLM_API_KEY": "sk-xxxxx",
        "LLM_MODEL": "open/ai-gpt-oss-20b",
        "LLM_TIMEOUT_MS": "60000",
        "LOG_LEVEL": "info",
        "ENFORCE_LOCAL_API": "false",
        "LLM_MAX_RETRIES": "1",
        "RETOUCH_CONTENT_MAX_RETRIES": "1",
        "LLM_BACKOFF_MS": "250",
        "LLM_BACKOFF_JITTER": "0.2"
      }
    }
  }
}

使用方法:

• チャットで、エージェントに生のプロンプトを使用して cleaner を使用するように依頼します。
• または、設定によって公開されている場合は、エージェントUIからツールを呼び出すことができます。

LLM API互換性

• /v1/chat/completions を公開するOpenAI互換のチャット補完API（例: LM Studioローカルサーバー）と互換性があります。
• LLM_API_BASE とオプションの LLM_API_KEY を使用して設定します。開発時には ENFORCE_LOCAL_API=true を使用してローカルホストに制限できます。
• LLM_MODEL をプロバイダー固有のモデル識別子に設定します。このサーバーは、決定論的な動作と再現性のために単一モデルポリシーを採用しています。
• プロバイダーは有効なJSONを返す必要があります。クリーナーは、コンテンツが厳密なJSONでない場合に限定的なリトライを行います。

リンク

• モデルコンテキストプロトコル（仕様）: https://modelcontextprotocol.io
• クリーナーのシステムプロンプト: prompts/cleaner.md

注意事項

• ログはJSON行としてstderrに出力され、MCPのstdioと干渉しないようになっています。
• 一部のクライアントは json コンテンツタイプを拒否するため、このサーバーは自動的に text に正規化します。

セキュリティ

• src/redact.ts によって、ログとクリーナーの出力から機密情報が削除されます。
• ENFORCE_LOCAL_API=true を設定すると、ローカルAPIエンドポイントのみを使用できるように制限されます。