Prompt Cleaner MCP

🚀 Prompt Cleaner (MCP Server)

Prompt Cleaner (MCP Server) 是一個用 TypeScript 編寫的 MCP 服務器，它提供了一個提示清理工具和健康檢查功能。所有提示都會通過 cleaner 進行處理，具備敏感信息屏蔽、結構化模式處理以及對客戶端友好的輸出規範化功能。

🚀 快速開始

要使用 Prompt Cleaner (MCP Server)，請按照以下步驟操作：

1. 確保滿足項目的要求。
2. 完成安裝和構建。
3. 運行項目。

✨ 主要特性

• 工具功能
  • health-ping：存活探針，返回 { ok: true }。
  • cleaner：清理原始提示；返回結構化的 JSON，包含潤色後的字符串、註釋、待解決問題、風險和屏蔽信息。
• 敏感信息屏蔽：在 src/redact.ts 中，敏感模式會從日誌和輸出中被清除。
• 輸出規範化：src/server.ts 會將 type: "json" 的內容轉換為純文本，以適應拒絕 JSON 內容類型的客戶端。
• 可配置性：可以配置大語言模型的基礎 URL、API 密鑰、模型、超時時間、日誌級別；還可以選擇僅在本地使用。
• 確定性模型策略：通過 LLM_MODEL 指定單一模型；默認情況下不支持動態模型選擇或列出模型。

📦 安裝指南

要求

• Node.js >= 20

安裝與構建

npm install
npm run build

運行項目

• 開發模式（標準輸入輸出服務器）：

npm run dev

💻 使用示例

基礎用法

使用 MCP Inspector 通過標準輸入輸出來測試工具：

npm run inspect

高級用法

在 Windsurf 設置中添加 MCP 服務器，指向已構建的標準輸入輸出服務器：

{
  "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 調用工具。

📚 詳細文檔

環境配置

可以通過 .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> }] 的形式返回，並由服務器將其轉換為 text 類型，以適應拒絕 JSON 內容類型的客戶端。

• 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 中的系統提示，調用配置好的大語言模型，提取第一個 JSON 對象，使用 Zod 進行驗證，並屏蔽敏感信息。
• sanitize-text（cleaner 的別名）
  • 輸入輸出模式和行為與 cleaner 相同。此別名用於匹配包含 “sanitize”、“PII” 或 “redact” 關鍵字的代理。
• normalize-prompt（cleaner 的別名）
  • 輸入輸出模式和行為與 cleaner 相同。此別名用於匹配包含 “normalize”、“format” 或 “preprocess” 關鍵字的代理。

每次調用的 API 密鑰覆蓋

src/llm.ts 允許在選項中傳入 apiKey 以覆蓋每次調用的 API 密鑰；如果未提供，則使用 LLM_API_KEY。

項目結構

• src/server.ts：MCP 服務器的連接、工具列表/調用、輸出規範化和日誌記錄。
• src/tools.ts：工具註冊表和調度。
• src/cleaner.ts：清理器管道和 JSON 提取/驗證。
• src/llm.ts：具有超時、重試和錯誤規範化功能的大語言模型客戶端。
• src/redact.ts：敏感信息屏蔽工具。
• src/config.ts：環境配置和驗證。
• test/*.test.ts：Vitest 測試套件，涵蓋工具、數據結構、清理器和健康檢查。

測試

npm test

設計決策

• 單一模型策略：使用環境變量中的 LLM_MODEL；不提供模型列表/選擇工具，以確保行為的確定性並減少風險。
• 輸出規範化：src/server.ts 會將 json 內容轉換為 text，以適應拒絕 JSON 的客戶端。
• 敏感信息屏蔽：src/redact.ts 會從日誌和輸出中清除敏感令牌。

故障排除

• 大語言模型超時：增加 LLM_TIMEOUT_MS；檢查到 LLM_API_BASE 的網絡可達性。
• 清理器返回非 JSON 內容：最多重試 RETOUCH_CONTENT_MAX_RETRIES 次。如果問題仍然存在，降低 temperature 或確保配置的模型符合輸出契約。
• 大語言模型返回 HTTP 5xx 錯誤：自動重試最多 LLM_MAX_RETRIES 次，採用指數退避策略（LLM_BACKOFF_MS，LLM_BACKOFF_JITTER）。
• 本地 API 強制使用錯誤：如果 ENFORCE_LOCAL_API=true，LLM_API_BASE 必須指向本地主機。
• 日誌/輸出中出現敏感信息：src/redact.ts 會自動進行屏蔽；如果發現有令牌洩露，請更新 src/redact.ts 中的模式。

大語言模型 API 兼容性

• 可與兼容 OpenAI 的聊天完成 API（例如 LM Studio 本地服務器）配合使用，這些 API 需暴露 /v1/chat/completions。
• 通過 LLM_API_BASE 和可選的 LLM_API_KEY 進行配置。可以將 ENFORCE_LOCAL_API 設置為 true，以在開發時限制僅使用本地主機。
• 將 LLM_MODEL 設置為特定提供商的模型標識符。此服務器遵循單一模型策略，以確保確定性和可重複性。
• 提供商必須返回有效的 JSON；當內容不是嚴格的 JSON 時，清理器會進行有限次數的重試。

鏈接

• 模型上下文協議（規範）：https://modelcontextprotocol.io
• 清理器系統提示：prompts/cleaner.md

注意事項

• 日誌以 JSON 行的形式輸出到標準錯誤輸出，以避免干擾 MCP 的標準輸入輸出。
• 一些客戶端拒絕 json 內容類型；此服務器會自動將其規範化為 text 類型。

安全

• src/redact.ts 會從日誌和清理器輸出中清除敏感信息。
• ENFORCE_LOCAL_API=true 會將使用範圍限制在本地 API 端點。