Code Explainer MCP
A Cloudflare Worker that serves as an MCP (Model Context Protocol) server for code explanation. It analyzes and explains code with a comprehensive breakdown of structure and functionality.
Features
- Architecture Diagram: Generates an ASCII diagram showing the overall structure, relationships between components, and data flow.
- Core Functionality Analysis: Identifies and explains the primary purpose of the code based on pattern recognition.
- Component Breakdown: Lists all main classes and functions with brief descriptions of their roles.
- Multi-language Support: Analyzes code in various programming languages including JavaScript, TypeScript, Python, Java, C#, and more.
- JSDoc/Docstring Recognition: Extracts and utilizes existing documentation in the code.
- Secure API: Bearer token authentication to secure your endpoints.
How It Works
The Code Explainer analyzes source code using a combination of techniques:
- Pattern Recognition: Identifies code structures and common patterns
- Relationship Analysis: Maps dependencies between components
- Documentation Extraction: Prioritizes existing documentation comments
- Architecture Visualization: Creates ASCII diagrams of the code structure
- Component Description: Provides semantic descriptions of functions and classes
All processing happens within the Cloudflare Worker with no external dependencies.
Installation
Prerequisites
- Node.js (version 12 or higher)
- Wrangler (Cloudflare Workers CLI)
- A Cloudflare account
Setup
- Clone this repository:
git clone https://github.com/BillDuke13/code-explainer-mcp.git
cd code-explainer-mcp
- Install dependencies:
- Configure your secret key:
- Edit
wrangler.jsonc and replace YOUR_SECRET_KEY_HERE with your chosen secret key, or - Use Cloudflare secrets (recommended for production):
wrangler secret put SHARED_SECRET
- Deploy to Cloudflare Workers:
Usage
API Endpoint
Send a POST request to your worker URL with the following JSON body:
{
"method": "explainCode",
"params": ["your code here", "programming language"]
}
Include the Authorization header with your secret key:
Authorization: Bearer YOUR_SECRET_KEY_HERE
The response will be a JSON object with a result field containing the code analysis:
{
"result": "# Code Analysis for JavaScript Code\n\n## Architecture Diagram\n...\n\n## Core Functionality\n..."
}
Example Usage
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;
}
// Example usage
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
import json
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']
# Example usage
code = "def hello(): 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) {
try {
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;
} catch (error) {
console.error('Error:', error.response ? error.response.data : error.message);
throw error;
}
}
// Example usage
const codeToAnalyze = `
class Person {
constructor(name) {
this.name = name;
}
sayHello() {
return \`Hello, my name is \${this.name}\`;
}
}
`;
explainCode(codeToAnalyze, 'javascript')
.then(explanation => console.log(explanation))
.catch(err => console.error('Failed to explain code:', err));
Local Development
- Clone the repository and install dependencies:
git clone https://github.com/BillDuke13/code-explainer-mcp.git
cd code-explainer-mcp
npm install
- Run the development server:
- Test the endpoint locally:
curl -X POST http://localhost:8787 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_SECRET_KEY_HERE" \
-d '{"method":"explainCode","params":["function hello() { return \"Hello World\"; }","javascript"]}'
Development Guidelines
- Follow TypeScript best practices
- Add comments for complex logic
- Update documentation for public API changes
- Add tests for new features
Security
- The API is secured with Bearer token authentication
- Use environment secrets for storing the shared secret in production
- Do not commit your actual secret key to version control
- Rate limiting is recommended for production deployments
License
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.