Prompt Cleaner

You can run the Prompt Cleaner MCP Server locally to clean raw prompts, redact secrets, and return structured results that are easy to audit and reason about. This server exposes a health check and a core cleaner tool that processes prompts through a deterministic model, with output normalization and secret redaction built in. You’ll learn how to install, run, and use it with an MCP client from start to finish.

How to use

Start the MCP server locally and connect your MCP client to it. Use the health-ping tool to verify the server is responsive, which returns { ok: true }. Then invoke the cleaner tool with your raw prompt to obtain a structured response containing the retouched prompt, notes, open questions, risks, and redactions. The server normalizes outputs so clients receive usable text when JSON is not accepted.

Typical workflow in an MCP client:

1) Verify health:
   - Call health-ping to ensure the MCP server is reachable.

2) Clean a prompt:
   - Call cleaner with { prompt: "<your raw prompt>", mode: "general", temperature: 0.5 }
   - Read the response fields: retouched, notes, openQuestions, risks, redactions.

How to install

Prerequisites you need before installing:
- Node.js >= 20
- npm (comes with Node.js)

Install and build the MCP server locally with these commands in sequence:

npm install
npm run build

Run the server in development mode (stdio server):

npm run dev

Configuration and usage notes

Key environment variables control how the MCP server talks to the LLM and how it behaves. You can provide these via a .env file or your environment. The primary options include the base URL for the LLM API, the model to use, timeout, and retry/backoff settings. You can optionally enforce localhost-only API usage for development.

Examples of common environment variables you may configure:

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

Security and reliability

All sensitive patterns are scrubbed from logs and outputs by the redaction utilities. If you ever notice leaked tokens, update the redaction patterns and retry.

The server includes liveness checks and deterministic model usage to keep behavior predictable. If you enable LOCAL API enforcement, only localhost endpoints are allowed for LLM calls.

Troubleshooting

If the LLM times out, increase LLM_TIMEOUT_MS or verify network reachability to the LLM API base URL.

If cleaner returns non-JSON content, retry up to RETOUCH_CONTENT_MAX_RETRIES. If persistent, adjust temperature or the model configuration to align with the output contract.

HTTP 5xx errors from the LLM trigger automatic retries up to LL M_MAX_RETRIES with backoff settings LLM_BACKOFF_MS and LLM_BACKOFF_JITTER.

Windsurf (example) and runtime configuration

To run the local MCP server from Windsurf or a similar MCP client, use the following stdio configuration. This starts the built server as a local process and passes the necessary environment variables.

{
  "mcpServers": {
    "prompt-cleaner": {
      "type": "stdio",
      "name": "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"
      }
    }
  }
}

Available tools

health-ping

Liveness probe tool that returns { ok: true } to confirm the MCP server is responsive.

cleaner

Core prompt-cleaning tool. Accepts { prompt, mode, temperature } and returns a structured JSON with retouched text, notes, openQuestions, risks, and redactions.

sanitize-text

Alias of cleaner for agents that search on sanitize or redaction behavior.

normalize-prompt

Alias of cleaner for agents that search on normalize or preprocess behavior.