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:
```
npm install
```
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:
```
npm run deploy
```

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

Response Format

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:
```
wrangler dev
```

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.