@adhisang/minecraft-modding-mcp 6.1.1 → 6.3.0

package/dist/source-service.d.ts

@@ -140,6 +140,35 @@ export type GetArtifactFileOutput = {
     mappingApplied: SourceMapping;
     returnedNamespace: SourceMapping;
     artifactContents: ArtifactContentsSummary;
+    /**
+     * Present when the file was served directly from the backing jar instead of
+     * the source index (non-indexed assets/ and data/ text files).
+     */
+    deliveryMode?: "jar-read-through";
+    /** Set when content was withheld (e.g. a binary entry); explains why. */
+    contentOmittedReason?: string;
+};
+export type GetModClassMembersInput = {
+    jarPath: string;
+    className: string;
+};
+export type GetModClassMembersOutput = {
+    className: string;
+    jarPath: string;
+    members: {
+        constructors: SignatureMember[];
+        fields: SignatureMember[];
+        methods: SignatureMember[];
+    };
+    counts: {
+        constructors: number;
+        fields: number;
+        methods: number;
+        total: number;
+    };
+    /** Members are read from bytecode; no decompiler runs on this path. */
+    extractionMethod: "bytecode-only";
+    warnings: string[];
 };
 export type ListArtifactFilesInput = {
     artifactId: string;
@@ -256,6 +285,7 @@ export type GetClassMembersInput = {
     access?: MemberAccess;
     includeSynthetic?: boolean;
     includeInherited?: boolean;
+    includeAnnotations?: boolean;
     memberPattern?: string;
     maxMembers?: number;
     cursor?: string;
@@ -623,6 +653,12 @@ export declare class SourceService {
     getRegistryData(input: GetRegistryDataInput): Promise<GetRegistryDataOutput>;
     compareVersions(input: CompareVersionsInput): Promise<CompareVersionsOutput>;
     decompileModJar(input: DecompileModJarInput): Promise<DecompileModJarOutput>;
+    /**
+     * Member-level view of a third-party mod jar class, read from bytecode
+     * only — no decompiler is involved on this path, so it answers in
+     * milliseconds where a decompile-backed lookup costs a full Vineflower run.
+     */
+    getModClassMembers(input: GetModClassMembersInput): Promise<GetModClassMembersOutput>;
     getModClassSource(input: GetModClassSourceInput): Promise<GetModClassSourceOutput>;
     searchModSource(input: SearchModSourceInput): Promise<SearchModSourceOutput>;
     findMapping(input: FindMappingInput): Promise<FindMappingOutput>;
@@ -634,6 +670,7 @@ export declare class SourceService {
     traceSymbolLifecycle(input: TraceSymbolLifecycleInput): Promise<TraceSymbolLifecycleOutput>;
     diffClassSignatures(input: DiffClassSignaturesInput): Promise<DiffClassSignaturesOutput>;
     findClass(input: FindClassInput): FindClassOutput;
+    findClassIncludingNested(input: FindClassInput): Promise<FindClassOutput>;
     getClassSource(input: GetClassSourceInput): Promise<GetClassSourceOutput>;
     getClassMembers(input: GetClassMembersInput): Promise<GetClassMembersOutput>;
     validateMixin(input: ValidateMixinInput, options?: ValidateMixinOptions): Promise<ValidateMixinOutput>;

package/dist/source-service.js

@@ -1,4 +1,6 @@
 import { loadConfig } from "./config.js";
+import { ERROR_CODES, createError } from "./errors.js";
+import { validateAndNormalizeJarPath } from "./path-resolver.js";
 import { MinecraftExplorerService } from "./minecraft-explorer-service.js";
 import { MappingService } from "./mapping-service.js";
 import { openDatabase } from "./storage/db.js";
@@ -124,6 +126,47 @@ export class SourceService {
     async decompileModJar(input) {
         return this.modDecompileService.decompileModJar(input);
     }
+    /**
+     * Member-level view of a third-party mod jar class, read from bytecode
+     * only — no decompiler is involved on this path, so it answers in
+     * milliseconds where a decompile-backed lookup costs a full Vineflower run.
+     */
+    async getModClassMembers(input) {
+        const jarPath = validateAndNormalizeJarPath(input.jarPath);
+        const className = input.className.trim();
+        if (!className) {
+            throw createError({
+                code: ERROR_CODES.INVALID_INPUT,
+                message: "className must be non-empty."
+            });
+        }
+        const signature = await this.explorerService.getSignature({
+            fqn: className,
+            jarPath,
+            access: "all"
+        });
+        const counts = {
+            constructors: signature.constructors.length,
+            fields: signature.fields.length,
+            methods: signature.methods.length,
+            total: signature.constructors.length + signature.fields.length + signature.methods.length
+        };
+        // No context block: contextForJar derives minecraftVersion/namespace from
+        // the jar path, which for an arbitrary mod jar greps the MOD's own
+        // version (e.g. geckolib-fabric-26.2.jar -> "26.2") — misleading here.
+        return {
+            className,
+            jarPath,
+            members: {
+                constructors: signature.constructors,
+                fields: signature.fields,
+                methods: signature.methods
+            },
+            counts,
+            extractionMethod: "bytecode-only",
+            warnings: signature.warnings
+        };
+    }
     async getModClassSource(input) {
         return this.modDecompileService.getModClassSource(input);
     }
@@ -143,12 +186,12 @@ export class SourceService {
         const result = await this.mappingService.checkSymbolExists(input);
         // On unobfuscated versions the mapping graph is empty, so the mapping service can
         // only ever report symbols as missing. We then validate against runtime bytecode.
-        // Classes/fields surface as `mapping_unavailable` when the graph yields nothing, but
-        // a method query with a non-empty graph returns `not_found` (empty member lookup) —
-        // which previously skipped the runtime fallback and produced false negatives for
-        // methods that genuinely exist. Treat `not_found` methods as fallback-eligible.
-        const fallbackEligible = result.status === "mapping_unavailable" ||
-            (result.status === "not_found" && input.kind === "method");
+        // A non-empty graph that simply lacks the queried record returns `not_found` for
+        // ANY kind — methods, fields, and classes alike — and skipping the runtime check
+        // produced false negatives (e.g. a real EntityType.ITEM field reported missing).
+        // Every `not_found` is therefore fallback-eligible alongside `mapping_unavailable`;
+        // the runtime check itself keeps genuinely-missing symbols `not_found`.
+        const fallbackEligible = result.status === "mapping_unavailable" || result.status === "not_found";
         if (!fallbackEligible ||
             !isUnobfuscatedVersion(input.version) ||
             (input.sourceMapping !== "mojang" && input.sourceMapping !== "obfuscated")) {
@@ -172,6 +215,9 @@ export class SourceService {
     findClass(input) {
         return classSource.findClass(this, input);
     }
+    async findClassIncludingNested(input) {
+        return classSource.findClassIncludingNested(this, input);
+    }
     async getClassSource(input) {
         return classSource.getClassSource(this, input);
     }

package/dist/stage-emitter.js

@@ -15,15 +15,31 @@ export function makeStageEmitter(extra, options = {}) {
     if (requestId === undefined || typeof sendNotification !== "function") {
         return NOOP_STAGE_EMITTER;
     }
+    let deliveryPending = false;
     return async (stage, meta) => {
-        await sendNotification({
-            method: "$/stageUpdate",
-            params: {
-                stage,
-                meta: meta ?? null,
-                t: performance.now(),
-                requestId
-            }
+        if (deliveryPending) {
+            return;
+        }
+        let delivery;
+        try {
+            delivery = sendNotification({
+                method: "$/stageUpdate",
+                params: {
+                    stage,
+                    meta: meta ?? null,
+                    t: performance.now(),
+                    requestId
+                }
+            });
+        }
+        catch {
+            return;
+        }
+        deliveryPending = true;
+        void Promise.resolve(delivery)
+            .catch(() => undefined)
+            .finally(() => {
+            deliveryPending = false;
         });
     };
 }

package/dist/stdio-supervisor.d.ts

@@ -1,6 +1,36 @@
-import type { JSONRPCResponse } from "@modelcontextprotocol/sdk/types.js";
-type SupervisorOptions = {
+import { type ChildProcessWithoutNullStreams } from "node:child_process";
+import type { JSONRPCMessage, JSONRPCResponse } from "@modelcontextprotocol/sdk/types.js";
+export declare function loadValidateProjectTimeoutMs(value?: string | undefined): number;
+export declare function computeWorkerStartupWatchdogMs(validateProjectTimeoutMs: number): number;
+export declare function computeRestartBackoffMs(retryIndex: number): number;
+export declare function terminatePosixProcessGroup(pid: number, kill?: (pid: number, signal: NodeJS.Signals) => void): boolean;
+export declare function buildWindowsTreeKillArgs(pid: number): string[];
+export declare function shouldRetainUnavailableNotification(method: string): boolean;
+export type RestartReservation = {
+    epoch: number;
+    notBefore: number;
+    delayMs: number;
+};
+export declare class RestartBackoffState {
+    private retryIndex;
+    private epoch;
+    reserve(now: number): RestartReservation;
+    reset(): void;
+}
+export declare function retryPosixTreeToken(pid: number, kill?: (pid: number, signal: NodeJS.Signals) => void): boolean;
+export declare function settleTreeCleanupWithin(operation: Promise<boolean>, timeoutMs: number, onTimeout?: () => void): Promise<boolean>;
+export type SupervisorOptions = {
     entryFile: string;
+    validateProjectTimeoutMs?: number;
+    clientWriter?: (message: JSONRPCMessage) => void;
+    treeTokenRetrier?: (pid: number) => boolean | Promise<boolean>;
+    treeCleanupTimeoutMs?: number;
+    eventWriter?: (level: "warn" | "error" | "info", event: string, details?: Record<string, unknown>) => void;
+    monotonicNow?: () => number;
+    timerScheduler?: (callback: () => void, delayMs: number) => NodeJS.Timeout;
+    timerClearer?: (timer: NodeJS.Timeout) => void;
+    workerSpawner?: () => ChildProcessWithoutNullStreams;
+    treeTerminator?: (pid: number) => boolean | Promise<boolean>;
 };
 type RequestId = string | number;
 export type ExitInfo = {
@@ -39,6 +69,15 @@ export type RedactedToolArgs = {
     modified: boolean;
 };
 export declare function redactToolArgs(args: unknown): RedactedToolArgs;
+export declare function buildSupervisorQueueLimitReply(id: RequestId, method: string): JSONRPCResponse;
+export type BuildValidateProjectTimeoutReplyInput = {
+    request: PendingRequestSnapshot;
+    phase: "queue" | "running";
+    deadlineMs: number;
+    now: number;
+    workerRestartInitiated: boolean;
+};
+export declare function buildValidateProjectTimeoutReply(input: BuildValidateProjectTimeoutReplyInput): JSONRPCResponse;
 export declare function decideRetryRecommendation(ctx: Pick<RestartContext, "toolName" | "lastStage" | "lastStageMeta" | "exit">, recentRestartTimestamps: number[]): RetryRecommendation;
 export declare function buildSyntheticCallToolResult(id: RequestId, ctx: RestartContext): JSONRPCResponse;
 export declare function pruneRestartTimestamps(timestamps: number[], now: number, windowMs?: number): number[];
@@ -62,15 +101,40 @@ export declare function buildWorkerRestartReply(req: PendingRequestSnapshot, exi
 };
 export declare class StdioSupervisor {
     private readonly entryFile;
+    private readonly validateProjectTimeoutMs;
+    private readonly workerStartupWatchdogMs;
+    private readonly clientWriter;
+    private readonly treeTokenRetrier;
+    private readonly treeCleanupTimeoutMs;
+    private readonly eventWriter;
+    private readonly monotonicNow;
+    private readonly timerScheduler;
+    private readonly timerClearer;
+    private readonly workerSpawner;
+    private readonly treeTerminator;
     private readonly clientReader;
-    private readonly workerReader;
-    private readonly queuedMessages;
+    private readonly workerReaders;
+    private readonly queuedRequests;
+    private readonly queuedNotifications;
     private readonly pendingRequests;
     private readonly recentRestarts;
+    private readonly liveChildren;
+    private readonly staleChildren;
+    private readonly cleanupStates;
+    private readonly unresolvedTreeTokens;
+    private readonly restartBackoff;
+    private readonly terminalChildren;
     private child;
     private childReady;
     private shuttingDown;
     private restartTimer;
+    private startupWatchdog;
+    private validateBarrierKey;
+    private runningValidateKey;
+    private attemptToken;
+    private currentRetryEpoch;
+    private currentRetryReservation;
+    private retryPaused;
     private workerStderrBuffer;
     private clientMode;
     private initializeRequest;
@@ -85,11 +149,17 @@ export declare class StdioSupervisor {
     private readonly handleClientClosed;
     private readonly handleTerminateSignal;
     private handleClientMessage;
-    private forwardToWorker;
+    private createPendingRequest;
+    private canDispatchImmediately;
+    private forwardRequest;
+    private writeToWorker;
+    private handleCancellation;
+    private handleValidateProjectDeadline;
+    private drainQueue;
     private spawnWorker;
-    private readonly handleWorkerData;
-    private readonly handleWorkerStdinError;
-    private readonly handleWorkerStderr;
+    private handleWorkerData;
+    private handleWorkerStdinError;
+    private handleWorkerStderr;
     private handleWorkerProcessError;
     private handleWorkerExit;
     private handleWorkerMessage;
@@ -99,8 +169,21 @@ export declare class StdioSupervisor {
     private flushQueue;
     private failPendingRequestsOnWorkerExit;
     private writeToClient;
+    private clearInitialInitializationState;
+    private liveCapOccupancy;
+    private clearStartupWatchdog;
+    private adoptActiveChild;
+    private invalidateCurrentChild;
+    private detachCurrentChild;
+    private recoverTimedOutWorker;
+    private beginTreeTermination;
+    private finishTreeTermination;
+    private retryUnresolvedTreeToken;
+    private handleStartupFailure;
+    private failQueuedRequestsOnStartupFailure;
     private scheduleRestart;
-    private detachChild;
+    private armRestartReservation;
+    private resumePausedRestart;
     private shutdown;
 }
 export declare const STDIO_WORKER_MODE_ENV = "MCP_STDIO_WORKER_MODE";