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 端点。