Code Explainer MCP

代码解释器 MCP

一个用于解释源代码的 Cloudflare Worker。提供代码片段及其语言后，它会返回一份 Markdown 报告，其中包含 ASCII 架构图、核心功能摘要，以及主要类和函数的详细说明。

分析完全在 Worker 内部通过正则表达式和模式匹配运行——不会调用大模型，也没有外部运行时依赖。所有逻辑都位于单个文件 src/index.ts 中。

功能

• 架构图：生成 ASCII 图，展示类（含继承关系）、独立函数、调用关系和导入的依赖。
• 核心功能分析：根据加权模式匹配，推断代码的主要和次要用途（网络、UI、数据处理、数据库、身份验证、测试、算法、文件系统）。
• 组件分解：列出主要类和函数，并为每项生成简短说明。
• 多语言支持：针对 JavaScript、TypeScript、Python、Java 和 C# 提供专门的类、函数和导入模式；其他语言则使用通用回退方案。
• 文档提取：在描述组件时，复用现有的 JSDoc、Python 文档字符串和行注释。
• Bearer 令牌身份验证：POST 端点受共享密钥保护。

工作原理

explainCode(code, language) 会协调四个辅助函数，并汇总其输出，生成 Markdown 报告：

1. generateArchitectureDiagram — 使用特定于语言的正则表达式提取类、函数和导入项，并生成 ASCII 图，其中包括 inherits/calls 关系。
2. extractCoreFunctionality — 统计各用途类别中的匹配项，并以文字总结主要（和次要）用途。
3. extractComponents — 收集主要类和函数；extractBlock 通过花括号匹配（或对 Python 使用缩进）查找每个声明的主体。
4. generateComponentDescription — 优先使用组件已有的文档注释，否则根据代码模式推断说明。

关于“MCP”的说明

该项目以模型上下文协议命名，并在部署流程中保留了 workers-mcp（在 wrangler deploy 之前运行 workers-mcp docgen）。不过，当前的 src/index.ts 在运行时不会使用 workers-mcp，也没有实现 MCP JSON-RPC 线协议。它通过 Worker 默认的 fetch 导出直接处理自定义 { method, params } 请求体，并提供普通的 HTTP JSON 端点。客户端将其作为常规 HTTP API 调用（参见用法）。

前提条件

• Node.js 22 或更高版本
• Wrangler（通过 devDependencies 在本地安装）
• Cloudflare 账户（用于部署）

设置

1. 克隆仓库：

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

2. 安装依赖：

   npm install
   

3. 配置共享密钥。生产环境中，请将其保存为 Worker 密钥（推荐）：

   wrangler secret put SHARED_SECRET
   

   wrangler.jsonc 中的 vars.SHARED_SECRET 条目仅为占位符 "YOUR_SECRET_KEY_HERE"；切勿在此处提交真实密钥。Worker 默认拒绝访问——密钥未设置或仍为占位符时，所有 POST 请求都会返回 503，因此必须先设置真实密钥，端点才能提供服务。本地开发时，请改为将密钥放入 .dev.vars（已加入 gitignore）——参见本地开发。

4. 部署到 Cloudflare Workers：

   npm run deploy
   

用法

端点

向 Worker URL 发送 POST 请求，并附上 JSON 请求体：

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

在 Authorization 标头中加入 bearer 令牌：

Authorization: Bearer <SHARED_SECRET>

向同一 URL 发送 GET 请求时，会返回一个简短的 HTML 信息页面，而不会运行分析。

响应

成功时，响应为 JSON 对象，其 result 字段包含 Markdown 报告：

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

状态码

状态	触发条件	响应正文
200	有效的 POST 请求，或 GET/HEAD 请求	{ "result": "<markdown>" } / HTML
401	POST 请求缺少 Authorization 标头，或标头不正确	Unauthorized
503	SHARED_SECRET 未设置或仍是占位符（Worker 会拒绝所有请求）	Service not configured: …
400	method 不是 explainCode、params 少于两个，或 params 中包含非字符串值	Invalid method or parameters
413	代码（params[0]）超过最大长度（100,000 个字符）	Code exceeds the maximum length …
405	请求方法不是 POST、GET 或 HEAD	Method Not Allowed
500	请求正文不是有效的 JSON，或发生其他错误	Error processing request

示例

JavaScript（浏览器）

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;
}

本地开发

1. 如果尚未安装依赖，请运行 npm install。

2. 提供本地密钥。创建 .dev.vars 文件（已在 gitignore 中排除），以便 wrangler dev 注入密钥：

   SHARED_SECRET=your-local-secret
   

   Worker 会拒绝所有请求，因此 .dev.vars 必须包含真实密钥：如果使用 wrangler.jsonc 中的占位符（或未设置密钥），所有 POST 请求都会返回 503。

3. 启动开发服务器（http://localhost:8787）：

   npm run dev
   

4. 发送请求：

   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"]}'
   

质量检查

• 测试（基于 @cloudflare/vitest-pool-workers 的 Vitest）：运行 npm test。test/ 中的测试套件通过 SELF.fetch 调用 Worker，覆盖 GET 信息页、身份验证失败、JavaScript 和 Python 的 explainCode 契约、空输入以及请求验证。
• Lint（ESLint flat config）：运行 npm run lint，或运行 npm run lint:fix 自动修复。
• 类型检查：npx tsc --noEmit 会检查 src/。根目录的 tsconfig.json 排除了 test/，因此需要单独运行 npx tsc -p test/tsconfig.json --noEmit 检查测试。
• 重新生成绑定类型：更改 wrangler.jsonc 中的绑定或变量后，运行 npm run cf-typegen 以重写 worker-configuration.d.ts。

格式由 Prettier 负责（.prettierrc：制表符、单引号、分号，printWidth 为 140）——运行 npx prettier --write .。

项目结构

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

文档

详细且可浏览的文档位于 docs/index.html——在浏览器中打开，即可查看架构概览、分析流程、完整的 API 参考以及已知限制。

安全

• POST 端点受 Authorization: Bearer <SHARED_SECRET> 保护。
• Worker 会拒绝所有请求：在 SHARED_SECRET 被设置为真实值（而非占位符）之前，它会返回 503。因此，配置错误的部署会拒绝请求，而不是接受公开的默认值。
• 生产环境请使用 wrangler secret put SHARED_SECRET 存储密钥，本地开发则存储在 .dev.vars 中；切勿将真实值提交到 wrangler.jsonc。
• 令牌通过以恒定时间比较 SHA-256 摘要进行校验，不会通过响应耗时泄露密钥内容或长度。对于需要更高保障的部署，请在 Worker 前添加速率限制。
• 请求大小受到限制：超大请求正文会被拒绝并返回 413（通过 Content-Length 判断），超过 100,000 个字符的代码会在开始分析前被拒绝。

许可证

本项目基于 Apache License 2.0 授权——详情请参阅 LICENSE 文件。