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](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:

Authorization: Bearer

A GET request to the same URL returns a small HTML info page instead of running an analysis.

Response

On success the response is a JSON object whose result field holds the Markdown report:

{
	"result": "# Code Analysis for javascript Code\n\n## Architecture Diagram\n...\n\n## Core Functionality\n..."
}

Status codes

Examples

JavaScript (browser)

async function explainCode(code, language) {
	const response = await fetch('https://your-worker-url.workers.dev', {
		method: 'POST',
		headers: {
			'Content-Type': 'application/json',
			Authorization: 'Bearer YOUR_SECRET_KEY_HERE',
		},
		body: JSON.stringify({
			method: 'explainCode',
			params: [code, language],
		}),
	});

	if (!response.ok) {
		throw new Error(`HTTP error! status: ${response.status}`);
	}

	const data = await response.json();
	return data.result;
}

const jsCode = `function add(a, b) { return a + b; }`;
explainCode(jsCode, 'javascript')
	.then((explanation) => console.log(explanation))
	.catch((error) => console.error('Error:', error));

Python (requests)

import requests

def explain_code(code, language, api_url, secret_key):
    headers = {
        'Content-Type': 'application/json',
        'Authorization': f'Bearer {secret_key}',
    }
    payload = {
        'method': 'explainCode',
        'params': [code, language],
    }
    response = requests.post(api_url, headers=headers, json=payload)
    response.raise_for_status()
    return response.json()['result']

code = "def hello():\n    print('Hello, world!')"
explanation = explain_code(code, 'python', 'https://your-worker-url.workers.dev', 'YOUR_SECRET_KEY_HERE')
print(explanation)

Node.js (axios)

const axios = require('axios');

async function explainCode(code, language) {
	const response = await axios.post(
		'https://your-worker-url.workers.dev',
		{ method: 'explainCode', params: [code, language] },
		{
			headers: {
				'Content-Type': 'application/json',
				Authorization: 'Bearer YOUR_SECRET_KEY_HERE',
			},
		},
	);
	return response.data.result;
}

Local development

1. Install dependencies (npm install) if you have not already.

2. Provide the local secret. Create a .dev.vars file (gitignored) so wrangler dev injects it:

SHARED_SECRET=your-local-secret

The Worker fails closed, so .dev.vars must hold a real secret: with the wrangler.jsonc placeholder (or no secret at all), every POST returns 503.

3. Start the dev server (http://localhost:8787):

npm run dev

4. Send a request:

curl -X POST http://localhost:8787 \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer your-local-secret" \
     -d '{"method":"explainCode","params":["function hello() { return \"Hello World\"; }","javascript"]}'

Quality checks

• Tests (Vitest on @cloudflare/vitest-pool-workers): npm test. The suite in test/ drives the Worker through SELF.fetch, covering the GET info page, auth failures, the explainCode contract for JavaScript and Python, empty input, and request validation.
• Lint (ESLint flat config): npm run lint, or npm run lint:fix to auto-fix.
• Type-check: npx tsc --noEmit checks src/. The root tsconfig.json excludes test/, so type-check the tests separately with npx tsc -p test/tsconfig.json --noEmit.
• Regenerate binding types: after changing bindings or vars in wrangler.jsonc, run npm run cf-typegen to rewrite worker-configuration.d.ts.

Formatting is owned by Prettier (.prettierrc: tabs, single quotes, semicolons, printWidth 140) — run npx prettier --write ..

Project layout

src/index.ts        Worker entry point and all analysis logic
test/index.spec.ts  Vitest suite exercising the HTTP contract
docs/index.html     Browsable HTML documentation
wrangler.jsonc      Worker configuration

Documentation

Detailed, browsable documentation lives in [docs/index.html](docs/index.html) — open it in a browser for the architecture overview, the analysis pipeline, the full API reference, and known limitations.

Security

• The POST endpoint is protected by Authorization: Bearer .
• The Worker fails closed: it returns 503 until SHARED_SECRET is set to a real value (not the placeholder), so a misconfigured deploy refuses requests instead of accepting the public default.
• Store the secret with wrangler secret put SHARED_SECRET for production and in .dev.vars for local development; never commit a real value to wrangler.jsonc.
• The token is checked by comparing SHA-256 digests in constant time, leaking neither the secret's content nor its length through response timing. For higher-assurance deployments, add rate limiting in front of the Worker.
• Request size is bounded: oversized bodies are rejected with 413 (via Content-Length), and code longer than 100,000 characters is rejected before any analysis runs.

License

This project is licensed under the Apache License 2.0 — see the LICENSE file for details.