Prompt Cleaner MCP

🚀 Prompt Cleaner (MCP Server)

A TypeScript MCP server that provides a prompt cleaning tool and health checks. All prompts are processed through the cleaner, which includes secret redaction, structured schemas, and client-friendly output normalization.

🚀 Quick Start

This is a TypeScript MCP server that offers a prompt cleaning tool and health checks. All prompts are routed through the cleaner, with features like secret redaction, structured schemas, and client-friendly output normalization.

✨ Features

• Tools:
  • health-ping: A liveness probe that returns { ok: true }.
  • cleaner: Cleans a raw prompt and returns structured JSON with a retouched string, notes, open questions, risks, and redactions.
• Secret redaction: Sensitive patterns are removed from logs and outputs in src/redact.ts.
• Output normalization: src/server.ts converts content with type: "json" to plain text for clients that don't accept JSON content types.
• Configurable: You can configure the LLM base URL, API key, model, timeout, log level, and optionally enforce local-only access.
• Deterministic model policy: It uses a single model via LLM_MODEL; there is no dynamic model selection or listing by default.

📦 Installation

Requirements

• Node.js >= 20

Install & Build

npm install
npm run build

💻 Usage Examples

Run

• Dev (stdio server):

npm run dev

Inspector (Debugging)

Use the MCP Inspector to test tools via stdio:

npm run inspect

Environment

You can configure the server via .env or environment variables:

Example .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

Tools (API Contracts)

All tools follow MCP Tool semantics. Content is returned as [{ type: "json", json: <payload> }] and normalized to type: "text" by the server for clients that require it.

• health-ping
  • Input: {}
  • Output: { ok: true }
• cleaner
  • Input: { prompt: string, mode?: "code"|"general", temperature?: number }
  • Output: { retouched: string, notes?: string[], openQuestions?: string[], risks?: string[], redactions?: ["[REDACTED]"][] }
  • Behavior: Applies a system prompt from prompts/cleaner.md, calls the configured LLM, extracts the first JSON object, validates it with Zod, and redacts secrets.
• sanitize-text (alias of cleaner)
  • Same input/output schema and behavior as cleaner. Exposed for agents that keyword-match on “sanitize”, “PII”, or “redact”.
• normalize-prompt (alias of cleaner)
  • Same input/output schema and behavior as cleaner. Exposed for agents that keyword-match on “normalize”, “format”, or “preprocess”.

Per-call API key override

src/llm.ts accepts apiKey in options for per-call overrides; it falls back to LLM_API_KEY.

📚 Documentation

Project Structure

• src/server.ts: Handles MCP server wiring, tool listing/calls, output normalization, and logging.
• src/tools.ts: Manages the tool registry and dispatch.
• src/cleaner.ts: Implements the cleaner pipeline and JSON extraction/validation.
• src/llm.ts: Provides an LLM client with timeout, retry, and error normalization.
• src/redact.ts: Contains secret redaction utilities.
• src/config.ts: Deals with environment configuration and validation.
• test/*.test.ts: A Vitest suite that covers tools, shapes, cleaner, and health.

Testing

npm test

Design decisions

• Single-model policy: It uses the LLM_MODEL from the environment; there is no model listing/selection tool to keep the behavior deterministic and reduce the attack surface.
• Output normalization: src/server.ts converts json content to text for clients that reject JSON.
• Secret redaction: src/redact.ts removes sensitive tokens from logs and outputs.

Troubleshooting

• LLM timeout: Increase LLM_TIMEOUT_MS and check network reachability to LLM_API_BASE.
• Non-JSON from cleaner: Retry up to RETOUCH_CONTENT_MAX_RETRIES times. If the issue persists, reduce temperature or ensure the configured model adheres to the output contract.
• HTTP 5xx from LLM: Automatic retries up to LLM_MAX_RETRIES times with exponential backoff (LLM_BACKOFF_MS, LLM_BACKOFF_JITTER).
• Local API enforcement error: If ENFORCE_LOCAL_API=true, LLM_API_BASE must point to localhost.
• Secrets in logs/outputs: Redaction runs automatically; if you see leaked tokens, update the patterns in src/redact.ts.

Windsurf (example)

Add an MCP server in Windsurf settings, pointing to the built stdio server:

{
  "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"
      }
    }
  }
}

Usage:

• In a chat, ask the agent to use cleaner with your raw prompt.
• Or invoke tools from the agent UI if your setup exposes them.

LLM API compatibility

• It works with OpenAI-compatible Chat Completions APIs (e.g., LM Studio local server) that expose /v1/chat/completions.
• Configure it via LLM_API_BASE and optionally LLM_API_KEY. Use ENFORCE_LOCAL_API=true to restrict to localhost for development.
• Set LLM_MODEL to the provider-specific model identifier. This server follows a single-model policy for determinism and reproducibility.
• Providers must return valid JSON; the cleaner includes limited retries when the content is not strictly JSON.

Links

• Model Context Protocol (spec): https://modelcontextprotocol.io
• Cleaner system prompt: prompts/cleaner.md

Notes

• Logs are emitted to stderr as JSON lines to avoid interfering with MCP stdio.
• Some clients reject json content types; this server normalizes them to text automatically.

Security

• Secrets are removed by src/redact.ts from logs and cleaner outputs.
• ENFORCE_LOCAL_API=true restricts usage to local API endpoints.