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