dejared-mcp 0.1.0 → 0.1.2

package/README.md

@@ -2,9 +2,151 @@
 
 An MCP (Model Context Protocol) server that lets AI assistants explore, analyze, and decompile Java JAR files.
 
+## Prerequisites
+
+- **Node.js 18+** - required for the `npx` wrapper (not needed for pure Java usage)
+- **Java 21+** - JRE is sufficient
+
 ## Quick Start
 
-Add to your MCP client configuration:
+Most MCP-compatible tools use a JSON configuration like this:
+
+```json
+{
+  "mcpServers": {
+    "dejared": {
+      "command": "npx",
+      "args": ["-y", "dejared-mcp"]
+    }
+  }
+}
+```
+
+See below for tool-specific instructions.
+
+## MCP Registry
+
+This server is published to the [MCP Registry](https://registry.modelcontextprotocol.io) as `io.github.huynhkhanh1402/dejared`.
+
+You can verify it via the registry API:
+
+```bash
+curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.huynhkhanh1402/dejared"
+```
+
+## Configuration by Tool
+
+<details>
+<summary><strong>Claude Desktop</strong></summary>
+
+Edit the Claude Desktop config file:
+
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "dejared": {
+      "command": "npx",
+      "args": ["-y", "dejared-mcp"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop after saving.
+
+</details>
+
+<details>
+<summary><strong>Claude Code (CLI)</strong></summary>
+
+Run this command in your terminal:
+
+```bash
+claude mcp add dejared -- npx -y dejared-mcp
+```
+
+Or add it to your project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "dejared": {
+      "command": "npx",
+      "args": ["-y", "dejared-mcp"]
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><strong>Cursor</strong></summary>
+
+Create or edit `.cursor/mcp.json` in your project root (project-level) or `~/.cursor/mcp.json` (global):
+
+```json
+{
+  "mcpServers": {
+    "dejared": {
+      "command": "npx",
+      "args": ["-y", "dejared-mcp"]
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><strong>VS Code (GitHub Copilot)</strong></summary>
+
+Create or edit `.vscode/mcp.json` in your project root:
+
+```json
+{
+  "servers": {
+    "dejared": {
+      "command": "npx",
+      "args": ["-y", "dejared-mcp"]
+    }
+  }
+}
+```
+
+Or add to your VS Code `settings.json` for global availability.
+
+After saving, click the **Start** button that appears in the MCP config file, then use Agent mode in Copilot Chat.
+
+</details>
+
+<details>
+<summary><strong>JetBrains IDEs (GitHub Copilot)</strong></summary>
+
+Go to **Settings** > **Tools** > **AI Assistant** > **Model Context Protocol (MCP)**.
+
+Click **+ Add** and configure:
+
+- **Name**: `dejared`
+- **Transport**: `Stdio`
+- **Command**: `npx`
+- **Arguments**: `-y dejared-mcp`
+
+</details>
+
+<details>
+<summary><strong>Gemini CLI</strong></summary>
+
+**Option A** - CLI command:
+
+```bash
+gemini mcp add dejared npx -y dejared-mcp
+```
+
+**Option B** - Edit `~/.gemini/settings.json` (global) or `.gemini/settings.json` (project):
 
 ```json
 {
@@ -17,11 +159,98 @@ Add to your MCP client configuration:
 }
 ```
 
-That's it. The wrapper automatically downloads the server JAR on first run.
+Use `/mcp` in a Gemini CLI session to verify the server is connected.
 
-### Custom Java Path
+</details>
 
-If Java is not in your system PATH, set the `DEJARED_JAVA_PATH` environment variable:
+<details>
+<summary><strong>Antigravity Editor</strong></summary>
+
+Edit `~/.gemini/antigravity/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "dejared": {
+      "command": "npx",
+      "args": ["-y", "dejared-mcp"]
+    }
+  }
+}
+```
+
+Or install through the MCP Store if available.
+
+</details>
+
+<details>
+<summary><strong>GitHub Copilot CLI</strong></summary>
+
+**Option A** - Interactive:
+
+```
+/mcp add
+```
+
+Then fill in:
+- **Server Name**: `dejared`
+- **Server Type**: `STDIO`
+- **Command**: `npx -y dejared-mcp`
+
+**Option B** - Edit `~/.copilot/mcp-config.json`:
+
+```json
+{
+  "mcpServers": {
+    "dejared": {
+      "type": "local",
+      "command": "npx",
+      "args": ["-y", "dejared-mcp"],
+      "tools": ["*"]
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><strong>Pure Java (no Node.js required)</strong></summary>
+
+If you prefer to run the server JAR directly without Node.js:
+
+1. Download the latest JAR from [GitHub Releases](https://github.com/HuynhKhanh1402/dejared-mcp/releases).
+
+   Direct link pattern:
+   ```
+   https://github.com/HuynhKhanh1402/dejared-mcp/releases/download/v{VERSION}/dejared-mcp-{VERSION}.jar
+   ```
+
+2. Run it:
+   ```bash
+   java -jar dejared-mcp-0.1.1.jar
+   ```
+
+3. Configure your MCP client to use the JAR directly instead of `npx`. For example, in Claude Desktop:
+
+   ```json
+   {
+     "mcpServers": {
+       "dejared": {
+         "command": "java",
+         "args": ["-jar", "/path/to/dejared-mcp-0.1.1.jar"]
+       }
+     }
+   }
+   ```
+
+   Replace `/path/to/dejared-mcp-0.1.1.jar` with the actual path where you saved the JAR. This works with any MCP client that supports stdio transport.
+
+</details>
+
+## Custom Java Path
+
+If Java is not in your system PATH, set the `DEJARED_JAVA_PATH` environment variable in your MCP config. This applies to all `npx`-based configurations:
 
 ```json
 {
@@ -37,11 +266,6 @@ If Java is not in your system PATH, set the `DEJARED_JAVA_PATH` environment vari
 }
 ```
 
-## Requirements
-
-- Node.js 18+
-- Java 21+ (JRE is sufficient)
-
 ## Features
 
 **Discovery** - Browse JAR structure:
@@ -70,13 +294,16 @@ If Java is not in your system PATH, set the `DEJARED_JAVA_PATH` environment vari
 ## 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
+1. Checks the platform cache directory for a cached JAR matching the current version
+   - Linux: `$XDG_CACHE_HOME/dejared-mcp` (default `~/.cache/dejared-mcp`)
+   - macOS: `~/Library/Caches/dejared-mcp`
+   - Windows: `%LOCALAPPDATA%\dejared-mcp`
 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
+## Server Configuration
 
 | Property | Default | Description |
 |----------|---------|-------------|

package/lib/jar-runner.js

@@ -1,3 +1,9 @@
+/**
+ * JAR runner for dejared-mcp.
+ *
+ * Downloads the matching JAR from GitHub Releases into a platform-specific
+ * cache directory, then launches it with the locally available Java runtime.
+ */
 "use strict";
 
 const { spawn, execFileSync } = require("node:child_process");
@@ -9,7 +15,32 @@ const os = require("node:os");
 const PACKAGE = require(path.join(__dirname, "..", "package.json"));
 const JAR_VERSION = PACKAGE.version;
 const JAR_NAME = `dejared-mcp-${JAR_VERSION}.jar`;
-const CACHE_DIR = path.join(os.homedir(), ".dejared-mcp");
+
+/**
+ * Returns the platform-specific cache directory for storing downloaded JARs.
+ *   - Linux/BSD : $XDG_CACHE_HOME/dejared-mcp  (default ~/.cache/dejared-mcp)
+ *   - macOS     : ~/Library/Caches/dejared-mcp
+ *   - Windows   : %LOCALAPPDATA%\dejared-mcp
+ */
+function getCacheDir() {
+  const env = process.env;
+  switch (os.platform()) {
+    case "win32":
+      return path.join(
+        env.LOCALAPPDATA || path.join(os.homedir(), "AppData", "Local"),
+        "dejared-mcp",
+      );
+    case "darwin":
+      return path.join(os.homedir(), "Library", "Caches", "dejared-mcp");
+    default:
+      return path.join(
+        env.XDG_CACHE_HOME || path.join(os.homedir(), ".cache"),
+        "dejared-mcp",
+      );
+  }
+}
+
+const CACHE_DIR = getCacheDir();
 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}`;
 
@@ -17,6 +48,10 @@ function log(msg) {
   process.stderr.write(`[dejared-mcp] ${msg}\n`);
 }
 
+/**
+ * Resolves the Java binary path.
+ * Honours the DEJARED_JAVA_PATH env var; falls back to `java` on PATH.
+ */
 function resolveJava() {
   const envJava = process.env.DEJARED_JAVA_PATH;
   if (envJava) {
@@ -35,6 +70,11 @@ function resolveJava() {
   }
 }
 
+/**
+ * Downloads a file over HTTPS, following up to {@link redirects} redirects.
+ * Writes to a temporary file first, then atomically renames to {@link dest}
+ * to avoid leaving a partial/corrupt file on disk.
+ */
 function download(url, dest, redirects = 5) {
   return new Promise((resolve, reject) => {
     if (redirects <= 0) return reject(new Error("Too many redirects"));
@@ -72,6 +112,7 @@ function download(url, dest, redirects = 5) {
   });
 }
 
+/** Ensures the JAR exists in cache, downloading it if missing or corrupted. */
 async function ensureJar() {
   if (fs.existsSync(JAR_PATH)) {
     const stat = fs.statSync(JAR_PATH);
@@ -92,6 +133,7 @@ async function ensureJar() {
   }
 }
 
+/** Entry point – resolves Java, ensures the JAR is cached, then spawns it. */
 async function run() {
   const javaPath = resolveJava();
   await ensureJar();

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "dejared-mcp",
-  "version": "0.1.0",
+  "version": "0.1.2",
+  "mcpName": "io.github.huynhkhanh1402/dejared",
   "description": "Explore, analyze, and decompile Java JAR files via MCP",
   "bin": {
     "dejared-mcp": "bin/dejared-mcp.js"