MCP Py Prompt Cleaner

🚀 MCP提示清理器

本項目是對用TypeScript編寫的 Prompt Cleaner 的增強版本。同時，這也是我的 “羅塞塔石碑” 項目，通過它我能更深入地理解Python。顯然，這個項目是在Cursor的幫助下完成編碼的。

這是一個模型上下文協議（MCP）服務器，它利用人工智能來增強和清理原始提示，使其更加清晰、可操作且有效。

✨ 主要特性

• 人工智能驅動的增強：使用大語言模型提高提示的清晰度和特異性。
• 簡潔的系統提示：採用結構化、高效的提示格式，以獲得一致的結果。
• 上下文感知處理：接受額外的上下文信息，以指導增強過程。
• 特定模式優化：支持 “通用” 和 “代碼” 兩種模式，適用於不同的使用場景。
• 質量評估：為增強後的提示提供質量分數和詳細反饋。
• 兩級重試策略：針對網絡問題進行HTTP級重試，針對人工智能輸出質量進行內容級重試。
• 指數退避：具備強大的錯誤處理能力，帶有抖動機制，防止驚群效應。
• MCP集成：完全符合MCP協議，使用標準輸入輸出傳輸。
• 生產就緒：擁有全面的測試覆蓋、簡潔的代碼和強大的錯誤處理能力。

📦 安裝指南

使用uv（推薦）

uv sync

使用pip

pip install -e .

注意：本項目使用 pyproject.toml 進行依賴管理。

📚 詳細文檔

配置

本地大語言模型（LMStudio） - 默認設置

服務器默認配置為與LMStudio等本地大語言模型配合使用，無需API密鑰：

# 默認配置（無需.env文件）
# LLM_API_ENDPOINT=http://localhost:1234/v1/chat/completions
# LLM_API_KEY=None（本地大語言模型不需要）
# LLM_MODEL=local-model

雲大語言模型（OpenAI、Anthropic等）

對於基於雲的大語言模型，在項目根目錄下創建一個 .env 文件：

# 大語言模型API配置
LLM_API_ENDPOINT=https://api.openai.com/v1/chat/completions
LLM_API_KEY=your-api-key-here
LLM_MODEL=gpt-4
LLM_TIMEOUT=60
LLM_MAX_TOKENS=600

# 重試配置
CONTENT_MAX_RETRIES=2

注意：.env 文件支持由 pydantic-settings 提供，無需額外的依賴項。

LMStudio設置

1. 下載並安裝 LMStudio。
2. 啟動LMStudio並加載模型。
3. 啟動本地服務器（通常在 http://localhost:1234）。
4. MCP服務器將自動連接到您的本地大語言模型。

運行服務器

要運行MCP服務器，請執行以下命令：

python main.py

工具使用

服務器提供了一個 clean_prompt 工具，該工具接受以下參數：

• raw_prompt（必需）：用戶的原始、未加工的提示。
• context（可選）：關於任務的額外上下文信息。
• mode（可選）：處理模式 - “通用” 或 “代碼”（默認：“通用”）。
• temperature（可選）：人工智能採樣溫度，範圍為0.0 - 1.0（默認：0.2）。

工具調用示例

可以直接使用參數調用該工具：

# 直接函數調用
result = await clean_prompt_tool(
    raw_prompt="help me write code",
    context="web development with Python",
    mode="code",
    temperature=0.1
)

或者通過MCP協議調用：

{
  "method": "tools/call",
  "params": {
    "name": "clean_prompt",
    "arguments": {
      "raw_prompt": "help me write code",
      "context": "web development with Python",
      "mode": "code",
      "temperature": 0.1
    }
  }
}

響應示例

{
  "cleaned": "Help me write Python code for web development. I need assistance with [specific task] using [framework/library]. The code should [requirements] and handle [error cases].",
  "notes": [
    "Added placeholders for specific task and framework",
    "Specified requirements and error handling"
  ],
  "open_questions": [
    "What specific web development task?",
    "Which Python framework?",
    "What are the exact requirements?"
  ],
  "risks": ["Without specific details, the code may not meet requirements"],
  "unchanged": false,
  "quality": {
    "score": 4,
    "reasons": ["Clear structure", "Identifies missing information", "Actionable guidance"]
  }
}

MCP客戶端配置

Claude桌面版

本地大語言模型（LMStudio） - 無需API密鑰

{
  "mcpServers": {
    "mcp-prompt-cleaner": {
      "command": "python",
      "args": ["main.py"]
    }
  }
}

雲大語言模型（OpenAI等） - 需要API密鑰

{
  "mcpServers": {
    "mcp-prompt-cleaner": {
      "command": "python",
      "args": ["main.py"],
      "env": {
        "LLM_API_KEY": "your-api-key-here",
        "LLM_API_ENDPOINT": "https://api.openai.com/v1/chat/completions",
        "LLM_MODEL": "gpt-4"
      }
    }
  }
}

其他MCP客戶端

服務器使用標準輸入輸出傳輸，可以通過指向 main.py 文件與任何兼容MCP的客戶端進行配置。

開發

運行測試

uv run pytest

測試覆蓋

項目包含了針對以下方面的全面測試：

• 從混合內容中提取JSON。
• 帶有重試邏輯的大語言模型客戶端。
• 提示清理功能。
• MCP協議集成。

項目結構

├── main.py                 # 帶有工具註冊的MCP服務器
├── config.py              # 配置管理
├── schemas.py             # 用於驗證的Pydantic模型
├── tools/
│   └── cleaner.py         # 主要的clean_prompt實現
├── llm/
│   └── client.py          # 帶有重試邏輯的人工智能API客戶端
├── utils/
│   └── json_extractor.py  # JSON提取實用工具
├── prompts/
│   └── cleaner.md         # 人工智能系統提示
└── tests/                 # 全面的測試套件

要求

• Python 3.11+
• MCP Python SDK
• 用於HTTP客戶端的httpx
• 用於數據驗證的pydantic
• 用於測試的pytest

📄 許可證

MIT