dejared-mcp 0.0.1

package/.claude-plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "dejared",
+  "version": "0.0.1",
+  "description": "Explore, analyze, and decompile Java JAR files with structured workflows.",
+  "author": {
+    "name": "HuynhKhanh1402"
+  },
+  "repository": "https://github.com/HuynhKhanh1402/dejared-mcp",
+  "license": "MIT",
+  "keywords": ["java", "jar", "decompiler", "bytecode", "reverse-engineering", "mcp"]
+}

package/.mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "dejared": {
+      "command": "npx",
+      "args": ["-y", "dejared-mcp"],
+      "env": {}
+    }
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Huynh Quoc Khanh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,102 @@
+# dejared-mcp
+
+An MCP (Model Context Protocol) server that lets AI assistants explore, analyze, and decompile Java JAR files.
+
+## Quick Start
+
+Add to your MCP client configuration:
+
+```json
+{
+  "mcpServers": {
+    "dejared": {
+      "command": "npx",
+      "args": ["-y", "dejared-mcp"]
+    }
+  }
+}
+```
+
+That's it. The wrapper automatically downloads the server JAR on first run.
+
+### Custom Java Path
+
+If Java is not in your system PATH, set the `DEJARED_JAVA_PATH` environment variable:
+
+```json
+{
+  "mcpServers": {
+    "dejared": {
+      "command": "npx",
+      "args": ["-y", "dejared-mcp"],
+      "env": {
+        "DEJARED_JAVA_PATH": "/path/to/java"
+      }
+    }
+  }
+}
+```
+
+## Requirements
+
+- Node.js 18+
+- Java 21+ (JRE is sufficient)
+
+## Features
+
+**Discovery** - Browse JAR structure:
+- `dejared_list_packages` - List all packages with class counts
+- `dejared_list_classes` - List classes in a specific package
+- `dejared_list_resources` - List non-class resource files
+- `dejared_read_resource` - Read text resources (yml, xml, properties, json, etc.)
+
+**Hunting** - Search inside JARs:
+- `dejared_search_class` - Search classes by name
+- `dejared_search_string` - Search string literals in bytecode (URLs, SQL, error messages, etc.)
+
+**Deep Analysis** - Inspect and decompile:
+- `dejared_get_metadata` - Extract class metadata via ASM (fast, no decompilation)
+- `dejared_dump_package_metadata` - Batch metadata for entire packages
+- `dejared_decompile_class` - Decompile `.class` to Java source code
+
+## Decompiler Engines
+
+| Engine | Description |
+|--------|-------------|
+| **CFR** (default) | Reliable general-purpose decompiler |
+| **Vineflower** | Modern fork of FernFlower, good with newer Java features |
+| **Procyon** | Alternative engine, can handle some edge cases better |
+
+## How It Works
+
+The npm package is a thin Node.js wrapper. On first run it:
+1. Checks `~/.dejared-mcp/` for a cached JAR matching the current version
+2. Downloads the JAR from GitHub Releases if not cached
+3. Spawns `java -jar` with stdio inherited for MCP transport
+
+The server communicates over stdio.
+
+## Configuration
+
+| Property | Default | Description |
+|----------|---------|-------------|
+| `dejared.cache.max-size` | `500` | Max entries in the decompilation LRU cache |
+| `dejared.security.max-resource-size` | `5242880` | Max resource file size (bytes) |
+| `dejared.security.decompile-timeout-seconds` | `30` | Timeout per decompilation |
+
+## Third-Party Licenses
+
+This project uses the following open-source libraries:
+
+| Library | License |
+|---------|---------|
+| [Spring Boot](https://spring.io/projects/spring-boot) | Apache 2.0 |
+| [Spring AI](https://spring.io/projects/spring-ai) | Apache 2.0 |
+| [ASM](https://asm.ow2.io/) | BSD 3-Clause |
+| [CFR](https://github.com/leibnitz27/cfr) | MIT |
+| [Vineflower](https://github.com/Vineflower/vineflower) | Apache 2.0 |
+| [Procyon](https://github.com/mstrobel/procyon) | Apache 2.0 |
+
+## License
+
+[MIT](LICENSE)

package/bin/dejared-mcp.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+"use strict";
+
+const { run } = require("../lib/jar-runner.js");
+run();

package/lib/jar-runner.js

@@ -0,0 +1,113 @@
+"use strict";
+
+const { spawn, execFileSync } = require("node:child_process");
+const fs = require("node:fs");
+const https = require("node:https");
+const path = require("node:path");
+const os = require("node:os");
+
+const PACKAGE = require(path.join(__dirname, "..", "package.json"));
+const JAR_VERSION = PACKAGE.jarVersion;
+const JAR_NAME = `dejared-mcp-${JAR_VERSION}.jar`;
+const CACHE_DIR = path.join(os.homedir(), ".dejared-mcp");
+const JAR_PATH = path.join(CACHE_DIR, JAR_NAME);
+const DOWNLOAD_URL = `https://github.com/HuynhKhanh1402/dejared-mcp/releases/download/v${JAR_VERSION}/${JAR_NAME}`;
+
+function log(msg) {
+  process.stderr.write(`[dejared-mcp] ${msg}\n`);
+}
+
+function resolveJava() {
+  const envJava = process.env.DEJARED_JAVA_PATH;
+  if (envJava) {
+    if (!fs.existsSync(envJava)) {
+      log(`DEJARED_JAVA_PATH points to "${envJava}" but it does not exist.`);
+      process.exit(1);
+    }
+    return envJava;
+  }
+  try {
+    execFileSync("java", ["-version"], { stdio: "ignore" });
+    return "java";
+  } catch {
+    log("Java not found. Set DEJARED_JAVA_PATH or install Java 21+.");
+    process.exit(1);
+  }
+}
+
+function download(url, dest, redirects = 5) {
+  return new Promise((resolve, reject) => {
+    if (redirects <= 0) return reject(new Error("Too many redirects"));
+
+    https.get(url, (res) => {
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        res.resume();
+        return resolve(download(res.headers.location, dest, redirects - 1));
+      }
+
+      if (res.statusCode !== 200) {
+        res.resume();
+        return reject(new Error(`HTTP ${res.statusCode} from ${url}`));
+      }
+
+      const tmp = dest + ".tmp";
+      const file = fs.createWriteStream(tmp);
+      res.pipe(file);
+      file.on("finish", () => {
+        file.close(() => {
+          const stat = fs.statSync(tmp);
+          if (stat.size === 0) {
+            fs.unlinkSync(tmp);
+            return reject(new Error("Downloaded file is empty"));
+          }
+          fs.renameSync(tmp, dest);
+          resolve();
+        });
+      });
+      file.on("error", (err) => {
+        fs.unlink(tmp, () => {});
+        reject(err);
+      });
+    }).on("error", reject);
+  });
+}
+
+async function ensureJar() {
+  if (fs.existsSync(JAR_PATH)) {
+    const stat = fs.statSync(JAR_PATH);
+    if (stat.size > 0) return;
+    log("Cached JAR is corrupted (0 bytes). Re-downloading...");
+    fs.unlinkSync(JAR_PATH);
+  }
+
+  fs.mkdirSync(CACHE_DIR, { recursive: true });
+  log(`Downloading dejared-mcp v${JAR_VERSION}...`);
+  try {
+    await download(DOWNLOAD_URL, JAR_PATH);
+    log("Download complete.");
+  } catch (err) {
+    log(`Failed to download JAR: ${err.message}`);
+    log(`URL: ${DOWNLOAD_URL}`);
+    process.exit(1);
+  }
+}
+
+async function run() {
+  const javaPath = resolveJava();
+  await ensureJar();
+
+  const child = spawn(javaPath, ["-jar", JAR_PATH], {
+    stdio: "inherit",
+  });
+
+  child.on("error", (err) => {
+    log(`Failed to start Java: ${err.message}`);
+    process.exit(1);
+  });
+
+  child.on("exit", (code) => {
+    process.exit(code ?? 1);
+  });
+}
+
+module.exports = { run };

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "dejared-mcp",
+  "version": "0.0.1",
+  "description": "Explore, analyze, and decompile Java JAR files via MCP",
+  "bin": {
+    "dejared-mcp": "bin/dejared-mcp.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "skills/",
+    ".claude-plugin/",
+    ".mcp.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "jarVersion": "0.0.1",
+  "license": "MIT",
+  "author": "HuynhKhanh1402",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/HuynhKhanh1402/dejared-mcp"
+  },
+  "keywords": [
+    "mcp",
+    "java",
+    "jar",
+    "decompiler",
+    "bytecode",
+    "reverse-engineering"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}

package/skills/jar-analysis/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: jar-analysis
+description: >
+  Explore, search, and decompile Java JAR files. Three workflows: Explore
+  (top-down structure mapping), Hunt (search for specific code/strings),
+  and Deep Analysis (single-class investigation). Use the workflow that
+  matches the task.
+---
+
+# JAR Analysis
+
+Three workflows for working with Java JAR files. Pick the one that fits your goal.
+
+## Available Tools
+
+| Tool | Cost | Purpose |
+|------|------|---------|
+| `dejared_list_packages` | Cheap | List all packages with class counts |
+| `dejared_list_classes` | Cheap | List classes in a package (`recursive=true` for sub-packages) |
+| `dejared_list_resources` | Cheap | List all non-class resource files with sizes |
+| `dejared_read_resource` | Cheap | Read a resource file (yml, properties, xml, json, txt, sql, conf) |
+| `dejared_dump_package_metadata` | Cheap | Batch metadata for multiple packages at once (annotations, fields, methods via ASM) |
+| `dejared_get_metadata` | Cheap | Single class metadata (ASM-based, no decompilation) |
+| `dejared_search_class` | Cheap | Find classes by name keyword (case-insensitive) |
+| `dejared_search_string` | Cheap | Find string literals in bytecode constant pools (case-insensitive) |
+| `dejared_decompile_class` | **Expensive** | Full source code decompilation (CFR/vineflower/procyon) |
+
+## Shared Rules
+
+- All tool calls require the **absolute path** to the JAR file.
+- NEVER decompile a class without checking its metadata first.
+- Default decompiler: CFR. If output is broken, try `vineflower` or `procyon`.
+- Report results in structured format.
+
+---
+
+## Workflow 1: Explore
+
+Use when exploring unknown JARs or understanding JAR architecture. Top-down approach: cheap tools first, decompilation last.
+
+### Step 1: Map Package Structure
+Call `dejared_list_packages` to get the full layout.
+- Identify the root application package (highest class count, deepest nesting).
+- Distinguish app code from shaded/third-party dependencies.
+
+### Step 2: List Classes
+Call `dejared_list_classes` with `recursive=true` on the root application package to get all classes in one call.
+- For targeted exploration of specific packages, use `recursive=false`.
+
+### Step 3: Discover Resources
+Call `dejared_list_resources` to see what non-class files exist in the JAR.
+
+### Step 4: Read Configuration
+Call `dejared_read_resource` for files discovered in Step 3:
+- `application.yml` / `application.yaml` / `application.properties`
+- `META-INF/spring.factories` or `META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports`
+- `logback.xml` / `log4j2.xml`
+
+### Step 5: Batch Metadata
+Call `dejared_dump_package_metadata` with **all important packages at once** (it accepts a list).
+Example: `packageNames: ["com.example.service", "com.example.config", "com.example.controller"]`
+- Returns annotations, fields, and method signatures for every class.
+- One call replaces dozens of individual `dejared_get_metadata` calls.
+
+### Step 6: Selective Decompilation
+Call `dejared_decompile_class` ONLY for classes where you need method body logic.
+- You MUST have reviewed metadata from Step 5 first.
+- Decompile one class at a time; summarize before continuing.
+- For JARs with >20 packages, group by prefix and summarize before diving in.
+
+---
+
+## Workflow 2: Hunt
+
+Use when looking for specific functionality, URLs, SQL, error messages, or credentials. Search-driven approach.
+
+### Search Tools
+
+**`dejared_search_class`** -- Find by class name.
+Case-insensitive keyword match against simple class names.
+- Find specific classes: "UserService", "DatabaseConfig"
+- Find patterns: "Controller", "Repository", "Factory", "Handler"
+
+**`dejared_search_string`** -- Find by string literal.
+Scans bytecode constant pools across all classes (case-insensitive).
+- URLs, endpoints, API paths
+- SQL queries, table names
+- Error messages, log messages
+- Config keys, credentials, secrets
+- Useful keywords for security audits: "password", "secret", "token", "key", "jdbc", "http://"
+
+### Steps
+
+1. **Search** -- Pick the right search tool based on the goal.
+2. **Triage** -- Review results, identify most relevant matches.
+3. **Inspect** -- Call `dejared_get_metadata` on promising classes to understand their role (annotations, fields, methods).
+4. **Decompile** -- Call `dejared_decompile_class` ONLY on classes where you need to see method body logic. Never skip step 3.
+5. **Report** -- Summarize findings with context and implications.
+
+Note: String search finds compiled constants only, not runtime-generated strings.
+
+---
+
+## Workflow 3: Deep Analysis
+
+Use when investigating a single class in detail. Combines metadata extraction with multi-engine decompilation.
+
+### Step 1: Metadata First
+Call `dejared_get_metadata` to extract:
+- Class hierarchy (superclass, interfaces)
+- Annotations (`@Service`, `@Entity`, `@Controller`, etc.)
+- Fields (state the class holds)
+- Methods (behavior -- names, return types, parameters)
+
+This tells you the class's role and size before decompiling.
+
+### Step 2: Decompile
+Call `dejared_decompile_class` (default engine: CFR). Analyze:
+- Constructor logic and dependency injection
+- Method implementations and business logic
+- Error handling patterns
+- Interactions with other classes
+
+### Step 3: Cross-Reference (if needed)
+If decompiled code references important classes:
+- `dejared_search_class` to find them by name.
+- `dejared_dump_package_metadata` on the same package to see sibling classes (accepts a list of packages).
+
+### Step 4: Try Alternative Engine (if needed)
+If CFR output has problems (broken lambdas, goto statements, placeholder bodies):
+- `vineflower` -- best for modern Java features.
+- `procyon` -- good for edge cases.
+
+### Report Structure
+1. **Role** -- What this class does (one sentence).
+2. **Framework Integration** -- Annotations, Spring beans, injection points.
+3. **Key Methods** -- Important methods and what they do.
+4. **Dependencies** -- Other classes/services it uses.
+5. **Notable Patterns** -- Design patterns, security concerns, performance notes.