dumbdown

Less jargon. More understanding.

dumbdown turns code and technical documentation into plain-language explanations: the big idea, an analogy, a step-by-step walkthrough, jargon definitions, an example, and caveats about missing context.

Open the web app · Contribute · Security and privacy · Verification

Use it

1. Paste code or technical documentation. Remove secrets and private information first.

2. Choose New to this, Know the basics, or Go deeper.

3. Select Dumb it down. Copy the explanation or download it as Markdown.

The opening debounce explanation is explicitly labeled Hand-written example and works without an API key. New explanations use the OpenAI Responses API. The public site requires your own API key and uses your API credits. The key is held in the tab's memory, sent to the site's server only to call OpenAI, and is not persisted by dumbdown. Refresh or Disconnect clears it from the app. This is separate from a ChatGPT subscription.

Code is never executed. Links inside pasted documentation are not fetched. AI explanations can be wrong: verify claims against the source and official documentation.

Related MCP server: mini-mcp-demo

One explainer, several ways to use it

A separate Discord or Telegram bot is not included; MCP provides the assistant interface without another account or bot service.

Run locally

Requires Node.js 22.13 or newer and npm.

git clone https://github.com/agammann/dumbdown.git
cd dumbdown
npm ci
npm run dev

Open the local URL printed by the server (normally http://localhost:5173). In local development only, a configured OPENAI_API_KEY in the ignored .env.local file powers the app automatically. Otherwise, use Connect in the app. The production build never falls back to an operator key. The key used for development is not shipped in the repository or client bundle.

For your own setup, use a secure API-key setup flow and store credentials outside source control. Do not paste keys into issues, commits, or chat. The MCP server and CLI read OPENAI_API_KEY from their environment or the repository's ignored .env.local. Their optional OPENAI_MODEL override defaults to gpt-5-mini.

Use with an MCP assistant

Install dependencies, configure your local key securely, and add a stdio server using your client's MCP configuration:

{
  "mcpServers": {
    "dumbdown": {
      "command": "node",
      "args": ["/absolute/path/to/dumbdown/scripts/mcp.mjs"]
    }
  }
}

Replace the example path with the actual absolute path. On Windows use forward slashes or escaped backslashes. Configure credentials in the local environment or ignored .env.local, not in a committed client configuration.

The tool accepts:

{
  "source": "const double = n => n * 2;",
  "kind": "code",
  "level": "beginner"
}

kind is code or documentation. level is beginner, intermediate, or advanced. Maximum source length: 12,000 characters. The result includes Markdown and structured content. Failures return isError: true with a sanitized message. The server never executes submitted code.

Run npm run mcp only when testing manually; MCP clients should invoke node scripts/mcp.mjs directly so npm's lifecycle output cannot interfere with stdio.

WebMCP

Open the web app in a browser with the experimental WebMCP API enabled, connect your API key, then let a browser assistant discover and invoke dumbdown_explain. Connect reports whether registration is available. Browsers without WebMCP still support the full normal UI. There is no polyfill pretending native browser support exists.

Tool calls use the same validation and visible state as clicking the button. They send the supplied text to OpenAI and use API credits. Local development can use the configured local key. Browser/client support varies; see the WebMCP draft.

CLI

npm run explain -- ./example.js code beginner
npm run explain -- ./notes.txt documentation intermediate

Files are read only when explicitly named. The CLI does not scan repositories or follow URLs.

Development and deployment

npm test
npm run typecheck
npm run lint
npm run build

The web app uses React, TypeScript, Vinext/Vite, and a Cloudflare Worker-compatible server. The shared explanation module also runs in Node for MCP and CLI. Tests cover validation, bounded inputs, prompt separation, sanitized provider errors, output validation, cancellation, and a real MCP stdio handshake without paid calls. CI does not need an API key.

The public Sites deployment uses the Worker and assets from the production build. .openai/hosting.json contains this project's public deployment identity; forks should register their own Site rather than deploying to that ID. Hosted environment bindings are managed separately. Production requests must carry the visitor's key; setting an owner key does not enable anonymous usage.

The API route accepts only same-origin JSON POST requests and does not store explanation history. It caps request size and provider time/output. store: false disables Responses storage; it is not a guarantee of zero retention by hosting or model providers. See SECURITY.md.

License

MIT. Dependencies retain their respective licenses.