@adhisang/minecraft-modding-mcp 1.0.0 → 1.1.1

package/CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.1] - 2026-03-02
+
+### Fixed
+- `search-class-source` now safely supports recursive `fileGlob` patterns such as `**` without regex construction failures.
+- `get-class-source` now rejects package-incompatible fallback matches and preserves canonical inner-class (`Outer.Inner`) lookup support.
+
+## [1.1.0] - 2026-03-01
+
+### Changed
+- Migrate stdio transport from mcp-use to @modelcontextprotocol/sdk.
+
+### Fixed
+- Restore Codex startup handshake compatibility by accepting both newline-delimited and `Content-Length` stdio framing.
+
+### Documentation
+- Add Quick Start setup for Claude Code, OpenAI Codex CLI, and Gemini CLI.
+
 ## [1.0.0] - 2026-03-01
 
 ### Added

package/README.md

@@ -39,6 +39,45 @@ It lets you explore decompiled Minecraft source, convert symbol names across fou
 npx @adhisang/minecraft-modding-mcp
 ```
 
+### CLI Agent Tools
+
+#### Claude Code
+
+```bash
+claude mcp add minecraft-modding -- npx -y @adhisang/minecraft-modding-mcp
+claude mcp list
+```
+
+#### OpenAI Codex CLI
+
+```bash
+codex mcp add minecraft-modding -- npx -y @adhisang/minecraft-modding-mcp
+codex mcp list
+```
+
+The stdio transport auto-detects both newline-delimited and `Content-Length` framing, so Codex and newline-based MCP clients can use the same server command.
+
+#### Gemini CLI
+
+Add the following to `~/.gemini/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "minecraft-modding": {
+      "command": "npx",
+      "args": ["-y", "@adhisang/minecraft-modding-mcp"]
+    }
+  }
+}
+```
+
+Then run this command in Gemini CLI:
+
+```text
+/mcp list
+```
+
 ### For Developers (Repository)
 ```bash
 pnpm install
@@ -213,6 +252,8 @@ Tools for querying generated registry data and inspecting server runtime state.
 `get-class-members` requires either `artifactId` or `targetKind`+`targetValue`, and needs a binary jar (`binaryJarPath`) to read `.class` entries.
 `search-class-source` uses `limit: 20` by default; `snippetLines` defaults to `8` and is clamped to `1..80`; `includeDefinition` and `includeOneHop` default to `false`.
 `search-class-source` with `match=regex` enforces `query.length <= 200` and a strict result cap of `100`.
+`search-class-source` `fileGlob` supports `*`, `**`, and `?`; recursive patterns such as `net/minecraft/**/*.java` are supported.
+`get-class-source` fallback matching enforces package compatibility and returns `ERR_CLASS_NOT_FOUND` when only name-colliding classes from other packages exist.
 `resolve-artifact` with `targetKind=jar` only auto-adopts the exact sibling `"<jar-basename>-sources.jar"`. Other adjacent `*-sources.jar` files are returned as `adjacentSourceCandidates` info only and are never auto-selected.
 Mod tool `jarPath` inputs are normalized to a canonical local `.jar` file path before existence checks, cache keying, and processing.
 `search-mod-source` enforces `query.length <= 200` and `limit <= 200`.
@@ -745,7 +786,7 @@ Use `resolve-workspace-symbol` when you need compile-visible names from actual G
 | Component | Technology |
 | --- | --- |
 | Runtime | Node.js 22+ (native `node:sqlite`) |
-| Transport | stdio (MCP standard) |
+| Transport | stdio (MCP standard, auto-detects newline + `Content-Length` framing) |
 | Storage | SQLite — artifact metadata, source index, mapping cache |
 | Decompilation | [Vineflower](https://github.com/Vineflower/vineflower) (auto-downloaded) |
 | Remapping | [tiny-remapper](https://github.com/FabricMC/tiny-remapper) (requires Java) |

package/dist/cli.js

@@ -1,4 +1,9 @@
 #!/usr/bin/env node
 import { startServer } from "./index.js";
-startServer();
+startServer()
+    .then(() => undefined)
+    .catch((err) => {
+    console.error("Fatal: server failed to start", err);
+    process.exit(1);
+});
 //# sourceMappingURL=cli.js.map

package/dist/compat-stdio-transport.d.ts

@@ -0,0 +1,27 @@
+import { type JSONRPCMessage } from "@modelcontextprotocol/sdk/types.js";
+type StdioReadable = NodeJS.ReadStream;
+type StdioWritable = NodeJS.WriteStream;
+export declare class CompatStdioServerTransport {
+    private readonly stdin;
+    private readonly stdout;
+    private started;
+    private closed;
+    private mode;
+    private buffer;
+    onclose?: () => void;
+    onerror?: (error: Error) => void;
+    onmessage?: (message: JSONRPCMessage) => void;
+    constructor(stdin?: StdioReadable, stdout?: StdioWritable);
+    start(): Promise<void>;
+    send(message: JSONRPCMessage): Promise<void>;
+    close(): Promise<void>;
+    private readonly handleData;
+    private readonly handleStreamError;
+    private readonly handleStreamClosed;
+    private emitCloseOnce;
+    private processReadBuffer;
+    private detectMode;
+    private readLineDelimitedMessage;
+    private readContentLengthMessage;
+}
+export {};

package/dist/compat-stdio-transport.js

@@ -0,0 +1,217 @@
+import process from "node:process";
+import { JSONRPCMessageSchema } from "@modelcontextprotocol/sdk/types.js";
+function findHeaderBoundary(buffer) {
+    const crlfBoundary = buffer.indexOf("\r\n\r\n");
+    if (crlfBoundary !== -1) {
+        return { index: crlfBoundary, delimiterBytes: 4 };
+    }
+    const lfBoundary = buffer.indexOf("\n\n");
+    if (lfBoundary !== -1) {
+        return { index: lfBoundary, delimiterBytes: 2 };
+    }
+    return undefined;
+}
+function parseJsonRpcMessage(json) {
+    return JSONRPCMessageSchema.parse(JSON.parse(json));
+}
+function asError(value) {
+    return value instanceof Error ? value : new Error(String(value));
+}
+export class CompatStdioServerTransport {
+    stdin;
+    stdout;
+    started = false;
+    closed = false;
+    mode = "unknown";
+    buffer = Buffer.alloc(0);
+    onclose;
+    onerror;
+    onmessage;
+    constructor(stdin = process.stdin, stdout = process.stdout) {
+        this.stdin = stdin;
+        this.stdout = stdout;
+    }
+    async start() {
+        if (this.started) {
+            throw new Error("CompatStdioServerTransport already started. connect() should be called only once.");
+        }
+        this.started = true;
+        this.stdin.on("data", this.handleData);
+        this.stdin.on("error", this.handleStreamError);
+        this.stdin.on("end", this.handleStreamClosed);
+        this.stdin.on("close", this.handleStreamClosed);
+        this.stdin.resume();
+    }
+    async send(message) {
+        const json = JSON.stringify(message);
+        const frame = this.mode === "content-length"
+            ? `Content-Length: ${Buffer.byteLength(json, "utf8")}\r\n\r\n${json}`
+            : `${json}\n`;
+        await new Promise((resolve) => {
+            if (this.stdout.write(frame)) {
+                resolve();
+                return;
+            }
+            this.stdout.once("drain", resolve);
+        });
+    }
+    async close() {
+        this.stdin.off("data", this.handleData);
+        this.stdin.off("error", this.handleStreamError);
+        this.stdin.off("end", this.handleStreamClosed);
+        this.stdin.off("close", this.handleStreamClosed);
+        if (this.stdin.listenerCount("data") === 0) {
+            this.stdin.pause();
+        }
+        this.buffer = Buffer.alloc(0);
+        this.emitCloseOnce();
+    }
+    handleData = (chunk) => {
+        if (chunk.length === 0) {
+            return;
+        }
+        this.buffer = Buffer.concat([this.buffer, chunk]);
+        this.processReadBuffer();
+    };
+    handleStreamError = (error) => {
+        this.onerror?.(error);
+    };
+    handleStreamClosed = () => {
+        this.emitCloseOnce();
+    };
+    emitCloseOnce() {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        this.onclose?.();
+    }
+    processReadBuffer() {
+        while (true) {
+            try {
+                if (this.mode === "unknown") {
+                    const detected = this.detectMode();
+                    if (!detected) {
+                        return;
+                    }
+                    this.mode = detected;
+                    continue;
+                }
+                const modeBefore = this.mode;
+                const message = this.mode === "content-length"
+                    ? this.readContentLengthMessage()
+                    : this.readLineDelimitedMessage();
+                if (!message) {
+                    // readLineDelimitedMessage may switch mode to "content-length"
+                    // mid-stream; retry with the new parser instead of stopping.
+                    if (this.mode !== modeBefore) {
+                        continue;
+                    }
+                    return;
+                }
+                this.onmessage?.(message);
+            }
+            catch (caughtError) {
+                this.onerror?.(asError(caughtError));
+                this.mode = "unknown";
+            }
+        }
+    }
+    detectMode() {
+        // Skip blank leading lines that some clients may emit.
+        while (this.buffer.length > 0) {
+            if (this.buffer[0] === 0x0a) {
+                this.buffer = this.buffer.subarray(1);
+                continue;
+            }
+            if (this.buffer.length >= 2 && this.buffer[0] === 0x0d && this.buffer[1] === 0x0a) {
+                this.buffer = this.buffer.subarray(2);
+                continue;
+            }
+            break;
+        }
+        if (this.buffer.length === 0) {
+            return undefined;
+        }
+        const prefix = this.buffer
+            .subarray(0, Math.min(this.buffer.length, 32))
+            .toString("utf8")
+            .toLowerCase();
+        if (prefix.startsWith("content-length")) {
+            return "content-length";
+        }
+        const firstNewline = this.buffer.indexOf(0x0a);
+        if (firstNewline === -1) {
+            return undefined;
+        }
+        const firstLine = this.buffer.subarray(0, firstNewline).toString("utf8").replace(/\r$/, "");
+        if (/^\s*content-length\s*:/i.test(firstLine)) {
+            return "content-length";
+        }
+        return "line";
+    }
+    readLineDelimitedMessage() {
+        while (true) {
+            const newlineIndex = this.buffer.indexOf(0x0a);
+            if (newlineIndex === -1) {
+                return undefined;
+            }
+            const line = this.buffer.subarray(0, newlineIndex).toString("utf8").replace(/\r$/, "");
+            this.buffer = this.buffer.subarray(newlineIndex + 1);
+            if (line.trim().length === 0) {
+                continue;
+            }
+            if (/^\s*content-length\s*:/i.test(line)) {
+                // Reconstruct the header with the correct line ending so that
+                // findHeaderBoundary can locate \r\n\r\n or \n\n reliably.
+                const sep = this.buffer.length > 0 && this.buffer[0] === 0x0d ? "\r\n" : "\n";
+                this.buffer = Buffer.concat([Buffer.from(`${line}${sep}`, "utf8"), this.buffer]);
+                this.mode = "content-length";
+                return undefined;
+            }
+            return parseJsonRpcMessage(line);
+        }
+    }
+    readContentLengthMessage() {
+        const headerBoundary = findHeaderBoundary(this.buffer);
+        if (!headerBoundary) {
+            return undefined;
+        }
+        const headersRaw = this.buffer.subarray(0, headerBoundary.index).toString("utf8");
+        const headerLines = headersRaw
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0);
+        let contentLength;
+        for (const headerLine of headerLines) {
+            const separatorIndex = headerLine.indexOf(":");
+            if (separatorIndex === -1) {
+                this.buffer = this.buffer.subarray(headerBoundary.index + headerBoundary.delimiterBytes);
+                throw new Error(`Malformed header line: ${headerLine}`);
+            }
+            const headerName = headerLine.slice(0, separatorIndex).trim().toLowerCase();
+            const headerValue = headerLine.slice(separatorIndex + 1).trim();
+            if (headerName === "content-length") {
+                const parsed = Number.parseInt(headerValue, 10);
+                if (!Number.isFinite(parsed) || parsed < 0) {
+                    this.buffer = this.buffer.subarray(headerBoundary.index + headerBoundary.delimiterBytes);
+                    throw new Error(`Invalid Content-Length header value: ${headerValue}`);
+                }
+                contentLength = parsed;
+            }
+        }
+        if (contentLength === undefined) {
+            this.buffer = this.buffer.subarray(headerBoundary.index + headerBoundary.delimiterBytes);
+            throw new Error("Missing Content-Length header.");
+        }
+        const messageStart = headerBoundary.index + headerBoundary.delimiterBytes;
+        const frameEnd = messageStart + contentLength;
+        if (this.buffer.length < frameEnd) {
+            return undefined;
+        }
+        const body = this.buffer.subarray(messageStart, frameEnd).toString("utf8");
+        this.buffer = this.buffer.subarray(frameEnd);
+        return parseJsonRpcMessage(body);
+    }
+}
+//# sourceMappingURL=compat-stdio-transport.js.map

package/dist/index.d.ts

@@ -1,7 +1,8 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { SourceService } from "./source-service.js";
 declare const SERVER_VERSION: string;
-declare const server: import("mcp-use/server").McpServerInstance<false>;
+declare const server: McpServer;
 declare const config: import("./types.js").Config;
 declare const sourceService: SourceService;
-export declare function startServer(): void;
+export declare function startServer(): Promise<void>;
 export { server, sourceService, config, SERVER_VERSION };