Code Explainer MCP

A Cloudflare Worker that explains source code. Given a snippet and its language, it returns a Markdown report containing an ASCII architecture diagram, a core-functionality summary, and a breakdown of the main classes and functions.

Analysis runs entirely inside the Worker using regex and pattern matching — there are no LLM calls and no external runtime dependencies. All logic lives in a single file, src/index.ts.

Features

- Architecture diagram: Generates an ASCII diagram showing classes (with inheritance), standalone functions, call relationships, and imported dependencies.
- Core-functionality analysis: Infers the primary and secondary purpose of the code (network, UI, data processing, database, authentication, testing, algorithm, file system) from weighted pattern matches.
- Component breakdown: Lists the main classes and functions, each with a short generated description.
- Multi-language support: Tailored class/function/import patterns for JavaScript, TypeScript, Python, Java, and C#, with a generic fallback for other languages.
- Documentation extraction: Reuses existing JSDoc, Python docstrings, and line comments when describing a component.
- Bearer-token auth: The POST endpoint is protected by a shared secret.

How it works

explainCode(code, language) orchestrates four helpers and assembles their output into a Markdown report:

1. generateArchitectureDiagram — extracts classes, functions, and imports with language-specific regexes and renders an ASCII diagram, including inherits/calls relationships.
2. extractCoreFunctionality — counts matches across purpose categories and produces a prose summary of the primary (and secondary) purpose.
3. extractComponents — collects the main classes and functions; extractBlock finds each declaration's body by brace matching (or by indentation for Python).
4. generateComponentDescription — prefers an existing doc comment for each component and otherwise infers a description from code patterns.

A note on "MCP"

The project is named for the Model Context Protocol and keeps workers-mcp in its deploy pipeline (workers-mcp docgen runs before wrangler deploy). However, the current src/index.ts does not use workers-mcp at runtime and does not implement the MCP JSON-RPC wire protocol. It serves a plain HTTP JSON endpoint with a custom { method, params } body, handled directly by the Worker's default fetch export. Clients call it as a regular HTTP API (see Usage).

Prerequisites

- Node.js 22 or higher
- Wrangler (installed locally via devDependencies)
- A Cloudflare account (for deployment)

Setup

1. Clone the repository:

   git clone https://github.com/BillDuke13/code-explainer-mcp.git
   cd code-explainer-mcp
   

2. Install dependencies:

   npm install
   

3. Configure the shared secret. For production, store it as a Worker secret (recommended):

   wrangler secret put SHARED_SECRET
   

The vars.SHARED_SECRET entry in wrangler.jsonc is only the placeholder "YOUR_SECRET_KEY_HERE"; never commit a real secret there. The Worker fails closed — while the secret is unset or still the placeholder, every POST returns 503, so a real secret must be set before the endpoint will serve. For local development, put the secret in .dev.vars (gitignored) instead — see Local development.

4. Deploy to Cloudflare Workers:

   npm run deploy
   

Usage

Endpoint

Send a POST request to your Worker URL with a JSON body:

{
	"method": "explainCode",
	"params": ["your code here", "programming language"]
}

Include the bearer token in the Authorization header:

```