# Deobfuscate MCP Server
An **LLM-Optimized** Model Context Protocol (MCP) server designed to help Large Language Models reverse-engineer, navigate, and understand minified and bundled JavaScript code.
## Why this Server?
Standard "beautifiers" only format code, leaving LLMs to struggle with massive, linear text files that overflow context windows. This server treats minified code as a **searchable database**, allowing LLMs to:
1. **De-obfuscate & Unbundle**: Uses `webcrack` to split Webpack/Browserify bundles into individual modules.
2. **See the Architecture**: Returns a JSON summary of the file's structure (exports, functions) before reading the code.
3. **Navigate Randomly**: Read specific modules on-demand (`get_module`) instead of the whole file.
4. **Search Semantically**: Find where specific strings or patterns exist across thousands of unbundled modules.
## Features
- **`deobfuscate`**: The entry point. Unpacks bundles and caches them in memory.
- **`returnCode`** (default `false`): Returns a summary by default to save context. Set to `true` to see the full code.
- **`skipVendor`**: Filter out `node_modules` and webpack boilerplate to focus on app code.
- **`mangle`**: Shorten variable names to save tokens.
- **`jsx`**: Restore React JSX syntax.
- **`analyze_structure`**: Returns a high-level AST summary (functions, classes, exports) to save tokens.
- **`list_modules`**: Lists all modules found in the unpacked bundle.
- **`list_functions`**: Scans cached modules to list defined functions/classes with signatures and parameters.
- **`get_call_graph`**: Generates a call graph for a specific function, identifying what it calls and what calls it.
- **`get_module`**: Fetches the formatted source code of a single module.
- **`get_symbol_source`**: Extracts only a specific function, class, or variable to save tokens.
- **`search_modules`**: Regex/String search across all modules.
- **`format_code`**: Standard Prettier formatting for JS/HTML/CSS.
- **`get_help`**: Returns detailed documentation for any tool.
## Installation & Setup
### Install from npm (Recommended)
```bash
npm install -g deobfuscate-mcp-server
```
### Build from source
```bash
git clone https://github.com/ricardodeazambuja/deobfuscate-mcp-server.git
cd deobfuscate-mcp-server
npm install
npm run build
```
### Pack and Install (Optional)
To create a distributable tarball and install it globally:
```bash
npm pack
npm install -g ./deobfuscate-mcp-server-1.0.0.tgz
```
## Client Configuration
To use this server with your favorite LLM client, add the following configuration.
### Claude Code
Run the following command in your terminal:
```bash
claude mcp add deobfuscate-mcp-server -- npx -y deobfuscate-mcp-server
```
Alternatively, edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"deobfuscate-mcp-server": {
"command": "npx",
"args": ["-y", "deobfuscate-mcp-server"]
}
}
}
```
### Gemini CLI
Run the following command in your terminal:
```bash
gemini mcp add deobfuscate-mcp-server npx -y deobfuscate-mcp-server
```
Alternatively, edit `~/.gemini/settings.json`:
```json
{
"mcpServers": {
"deobfuscate-mcp-server": {
"command": "npx",
"args": ["-y", "deobfuscate-mcp-server"]
}
}
}
```
### Antigravity
Run the following command in your terminal:
```bash
antigravity --add-mcp '{"deobfuscate-mcp-server": {"command": "npx", "args": ["-y", "deobfuscate-mcp-server"]}}'
```
Alternatively, edit `~/.antigravity/settings.json`:
```json
{
"mcpServers": {
"deobfuscate-mcp-server": {
"command": "npx",
"args": ["-y", "deobfuscate-mcp-server"]
}
}
}
```
### Development / Local Usage
If you are running the server from the source code, replace the command with:
```json
"command": "node",
"args": ["ABSOLUTE_PATH_TO_DIST/index.js"]
```
*(Replace `ABSOLUTE_PATH_TO_DIST` with the actual absolute path to the `dist` folder on your machine)*
## Usage
Start the server:
```bash
node dist/index.js
```
### Example Workflow for an LLM
1. **User**: "Analyze this minified file: `bundle.min.js`..."
2. **LLM**: Calls `deobfuscate(code="...", skipVendor=true)`.
* *Server*: "Deobfuscation complete. Unbundled 15 modules. Skipped 45 vendor modules..."
3. **LLM**: "Okay, I see the entry point requires module 42. What is that?"
4. **LLM**: Calls `get_module(id="42")`.
* *Server*: Returns code for module 42.
5. **LLM**: "Where is the 'login' function defined?"
6. **LLM**: Calls `search_modules(query="function login")`.
* *Server*: "Found in module 88."
7. **LLM**: "I just want to see the login function logic."
8. **LLM**: Calls `get_symbol_source(symbolName="login", moduleId="88")`.
* *Server*: Returns only the source for the 'login' function.
## Development
- **Build**: `npm run build`
- **Test**: `npm test`
## Limits
- **File Size**: The server accepts input files (bundles) up to **50MB**.
- **Memory**: Unbundled modules are cached in RAM. Very large bundles (hundreds of MBs unpacked) may exhaust the server's available memory depending on your environment.
