@adhisang/minecraft-modding-mcp 3.2.0 → 4.1.0

package/dist/entry-tools/batch-symbol-exists-service.d.ts

@@ -0,0 +1,46 @@
+import type { CheckSymbolExistsInput, CheckSymbolExistsOutput, ResolveArtifactInput, ResolveArtifactOutput } from "../source-service.js";
+import type { ArtifactScope, MappingSourcePriority, SourceMapping, WorkspaceTargetInput, SourceTargetInput } from "../types.js";
+export type BatchSymbolExistsDeps = {
+    resolveArtifact: (input: ResolveArtifactInput) => Promise<ResolveArtifactOutput>;
+    checkSymbolExists: (input: CheckSymbolExistsInput) => Promise<CheckSymbolExistsOutput>;
+};
+import { type BatchOutput } from "./batch-runner.js";
+type SymbolKind = "class" | "field" | "method";
+export type BatchSymbolExistsEntry = {
+    kind: SymbolKind;
+    name: string;
+    owner?: string;
+    descriptor?: string;
+    nameMode?: "fqcn" | "auto";
+    signatureMode?: "exact" | "name-only";
+    maxCandidates?: number;
+};
+/**
+ * Subset of `ResolveArtifactTargetInput` accepted by `batch-symbol-exists`.
+ * Library/jar/coordinate targets carry the library's own version, not the
+ * Minecraft version, so querying the Minecraft mapping graph with that value
+ * would be a category error. The zod schema rejects the disallowed kinds.
+ */
+export type BatchSymbolExistsTarget = (SourceTargetInput & {
+    kind: "version";
+}) | WorkspaceTargetInput;
+export type BatchSymbolExistsInput = {
+    target: BatchSymbolExistsTarget;
+    mapping?: SourceMapping;
+    sourcePriority?: MappingSourcePriority;
+    allowDecompile?: boolean;
+    projectPath?: string;
+    scope?: ArtifactScope;
+    preferProjectVersion?: boolean;
+    strictVersion?: boolean;
+    concurrency?: number;
+    failFast?: boolean;
+    compact?: boolean;
+    entries: readonly BatchSymbolExistsEntry[];
+};
+export declare class BatchSymbolExistsService {
+    private readonly deps;
+    constructor(deps: BatchSymbolExistsDeps);
+    execute(input: BatchSymbolExistsInput): Promise<BatchOutput<Record<string, unknown>>>;
+}
+export {};

package/dist/entry-tools/batch-symbol-exists-service.js

@@ -0,0 +1,113 @@
+import { buildSuggestedCall } from "../build-suggested-call.js";
+import { createError, ERROR_CODES } from "../errors.js";
+import { compactResponse, compactMappingResponse } from "../response-utils.js";
+import { runBatch, splitEntryWarnings } from "./batch-runner.js";
+function deriveMinecraftVersion(resolvedVersion, workspaceVersion) {
+    const candidate = resolvedVersion?.trim() || workspaceVersion?.trim();
+    if (!candidate) {
+        throw createError({
+            code: ERROR_CODES.WORKSPACE_VERSION_UNRESOLVED,
+            message: "batch-symbol-exists could not derive a Minecraft version from the shared artifact (use target.kind=version or set projectPath so the workspace resolution detects it).",
+            details: {
+                nextAction: "Pass target.kind=\"version\" with the desired Minecraft version, or ensure target.kind=\"workspace\" projectPath points to a Loom/Forge project whose gradle.properties carries minecraft_version."
+            }
+        });
+    }
+    return candidate;
+}
+export class BatchSymbolExistsService {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async execute(input) {
+        const concurrency = input.concurrency ?? 4;
+        const failFast = input.failFast ?? false;
+        const compact = input.compact ?? true;
+        return runBatch({
+            entries: input.entries,
+            concurrency,
+            failFast,
+            resolveSharedArtifact: async () => {
+                const resolved = await this.deps.resolveArtifact({
+                    target: input.target,
+                    mapping: input.mapping,
+                    sourcePriority: input.sourcePriority,
+                    allowDecompile: input.allowDecompile,
+                    projectPath: input.projectPath,
+                    scope: input.scope,
+                    preferProjectVersion: input.preferProjectVersion,
+                    strictVersion: input.strictVersion
+                });
+                const provenance = resolved.provenance;
+                const workspaceVersion = provenance?.workspaceResolution?.detected?.minecraftVersion;
+                const version = deriveMinecraftVersion(resolved.version, workspaceVersion);
+                return {
+                    artifactId: resolved.artifactId,
+                    provenance: resolved.provenance,
+                    version,
+                    sourceMapping: resolved.mappingApplied,
+                    ...(Array.isArray(resolved.warnings) && resolved.warnings.length > 0
+                        ? { warnings: [...resolved.warnings] }
+                        : {})
+                };
+            },
+            artifactSummary: (artifact) => ({
+                sharedArtifactId: artifact.artifactId,
+                ...(artifact.provenance ? { sharedArtifactProvenance: artifact.provenance } : {}),
+                ...(artifact.warnings && artifact.warnings.length > 0
+                    ? { sharedArtifactWarnings: artifact.warnings }
+                    : {})
+            }),
+            perEntry: async (entry, _index, sharedArtifact) => {
+                if (!sharedArtifact) {
+                    throw new Error("shared artifact not resolved");
+                }
+                const raw = (await this.deps.checkSymbolExists({
+                    version: sharedArtifact.version,
+                    kind: entry.kind,
+                    name: entry.name,
+                    owner: entry.owner,
+                    descriptor: entry.descriptor,
+                    sourceMapping: sharedArtifact.sourceMapping,
+                    sourcePriority: input.sourcePriority,
+                    nameMode: entry.nameMode,
+                    signatureMode: entry.signatureMode,
+                    maxCandidates: entry.maxCandidates,
+                    projectPath: input.projectPath
+                }));
+                const { result, warnings } = splitEntryWarnings(raw);
+                const projected = compact
+                    ? compactResponse(compactMappingResponse(result))
+                    : result;
+                return { result: projected, warnings };
+            },
+            buildErrorSuggestedCall: (entry, sharedArtifact) => {
+                if (!sharedArtifact)
+                    return undefined;
+                const params = {
+                    version: sharedArtifact.version,
+                    kind: entry.kind,
+                    name: entry.name,
+                    sourceMapping: sharedArtifact.sourceMapping
+                };
+                if (entry.owner !== undefined)
+                    params.owner = entry.owner;
+                if (entry.descriptor !== undefined)
+                    params.descriptor = entry.descriptor;
+                if (entry.nameMode !== undefined)
+                    params.nameMode = entry.nameMode;
+                if (entry.signatureMode !== undefined)
+                    params.signatureMode = entry.signatureMode;
+                if (entry.maxCandidates !== undefined)
+                    params.maxCandidates = entry.maxCandidates;
+                const { suggestedCall } = buildSuggestedCall({
+                    tool: "check-symbol-exists",
+                    params
+                });
+                return suggestedCall;
+            }
+        });
+    }
+}
+//# sourceMappingURL=batch-symbol-exists-service.js.map

package/dist/entry-tools/compare-minecraft-service.d.ts

@@ -31,14 +31,14 @@ export declare const compareMinecraftShape: {
         className: string;
         fromVersion: string;
         toVersion: string;
-        mapping?: "intermediary" | "mojang" | "yarn" | "obfuscated" | undefined;
+        mapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
         sourcePriority?: "loom-first" | "maven-first" | undefined;
     }, {
         kind: "class";
         className: string;
         fromVersion: string;
         toVersion: string;
-        mapping?: "intermediary" | "mojang" | "yarn" | "obfuscated" | undefined;
+        mapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
         sourcePriority?: "loom-first" | "maven-first" | undefined;
     }>, z.ZodObject<{
         kind: z.ZodLiteral<"registry">;
@@ -92,14 +92,14 @@ export declare const compareMinecraftSchema: z.ZodObject<{
         className: string;
         fromVersion: string;
         toVersion: string;
-        mapping?: "intermediary" | "mojang" | "yarn" | "obfuscated" | undefined;
+        mapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
         sourcePriority?: "loom-first" | "maven-first" | undefined;
     }, {
         kind: "class";
         className: string;
         fromVersion: string;
         toVersion: string;
-        mapping?: "intermediary" | "mojang" | "yarn" | "obfuscated" | undefined;
+        mapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
         sourcePriority?: "loom-first" | "maven-first" | undefined;
     }>, z.ZodObject<{
         kind: z.ZodLiteral<"registry">;
@@ -135,7 +135,7 @@ export declare const compareMinecraftSchema: z.ZodObject<{
         className: string;
         fromVersion: string;
         toVersion: string;
-        mapping?: "intermediary" | "mojang" | "yarn" | "obfuscated" | undefined;
+        mapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
         sourcePriority?: "loom-first" | "maven-first" | undefined;
     } | {
         kind: "registry";
@@ -160,7 +160,7 @@ export declare const compareMinecraftSchema: z.ZodObject<{
         className: string;
         fromVersion: string;
         toVersion: string;
-        mapping?: "intermediary" | "mojang" | "yarn" | "obfuscated" | undefined;
+        mapping?: "obfuscated" | "mojang" | "intermediary" | "yarn" | undefined;
         sourcePriority?: "loom-first" | "maven-first" | undefined;
     } | {
         kind: "registry";

package/dist/entry-tools/inspect-minecraft/handlers/artifact.d.ts

@@ -0,0 +1,5 @@
+import { type DetailLevel } from "../../response-contract.js";
+import { type Subject, type InspectMinecraftDeps } from "../internal.js";
+export declare function handleArtifact(deps: InspectMinecraftDeps, subject: Subject, detail: DetailLevel, include: string[]): Promise<{
+    warnings: string[];
+}>;

package/dist/entry-tools/inspect-minecraft/handlers/artifact.js

@@ -0,0 +1,83 @@
+import { buildEntryToolResult, createNextAction, createSummarySubject } from "../../response-contract.js";
+import { nextActionsOrUndefined } from "../../request-normalizers.js";
+import { resolveArtifactReference } from "../internal.js";
+export async function handleArtifact(deps, subject, detail, include) {
+    const resolved = await resolveArtifactReference(deps, subject);
+    if (!resolved.artifactId) {
+        const summary = {
+            status: "blocked",
+            headline: "Could not resolve an artifact without a Minecraft version.",
+            subject: createSummarySubject({
+                task: "artifact",
+                requested: subject
+            }),
+            nextActions: nextActionsOrUndefined([
+                createNextAction("inspect-minecraft", {
+                    task: "artifact",
+                    subject: {
+                        kind: "version",
+                        version: "1.21.10"
+                    }
+                })
+            ])
+        };
+        return {
+            ...buildEntryToolResult({
+                task: "artifact",
+                summary,
+                detail,
+                include,
+                blocks: {
+                    subject: {
+                        requested: subject
+                    }
+                },
+                alwaysBlocks: ["subject"]
+            }),
+            warnings: resolved.warnings
+        };
+    }
+    const summary = {
+        status: "ok",
+        headline: `Resolved artifact ${resolved.artifactId}.`,
+        subject: createSummarySubject({
+            task: "artifact",
+            requested: subject,
+            artifactId: resolved.artifactId,
+            version: resolved.version
+        }),
+        counts: {
+            warnings: resolved.warnings.length
+        }
+    };
+    return {
+        ...buildEntryToolResult({
+            task: "artifact",
+            summary,
+            detail,
+            include,
+            blocks: {
+                subject: {
+                    requested: subject,
+                    resolved: {
+                        artifactId: resolved.artifactId,
+                        version: resolved.version
+                    }
+                },
+                artifact: resolved.artifact
+                    ? {
+                        artifactId: resolved.artifact.artifactId,
+                        artifactAlias: resolved.artifact.artifactAlias,
+                        origin: resolved.artifact.origin,
+                        mappingApplied: resolved.artifact.mappingApplied,
+                        version: resolved.artifact.version,
+                        artifactContents: resolved.artifact.artifactContents
+                    }
+                    : { artifactId: resolved.artifactId }
+            },
+            alwaysBlocks: ["subject"]
+        }),
+        warnings: resolved.warnings
+    };
+}
+//# sourceMappingURL=artifact.js.map

package/dist/entry-tools/inspect-minecraft/handlers/class-members.d.ts

@@ -0,0 +1,6 @@
+import { type DetailLevel } from "../../response-contract.js";
+import { type Subject, type InspectMinecraftDeps } from "../internal.js";
+export declare function handleClassMembers(deps: InspectMinecraftDeps, subject: Subject, detail: DetailLevel, include: string[], limit: number | undefined): Promise<{
+    meta?: Record<string, unknown> | undefined;
+    warnings: string[];
+}>;

package/dist/entry-tools/inspect-minecraft/handlers/class-members.js

@@ -0,0 +1,80 @@
+import { buildEntryToolResult, buildEntryToolMeta, createNextAction, createSummarySubject, createTruncationMeta } from "../../response-contract.js";
+import { buildClassSubject, resolveClassArtifactReference, invalidTaskSubjectError } from "../internal.js";
+export async function handleClassMembers(deps, subject, detail, include, limit) {
+    if (subject.kind !== "class" && !(subject.kind === "workspace" && subject.focus?.kind === "class")) {
+        invalidTaskSubjectError("class-members", subject);
+    }
+    const classSubject = buildClassSubject(subject);
+    const artifact = await resolveClassArtifactReference(deps, subject, classSubject, "class-members");
+    const members = await deps.getClassMembers({
+        className: classSubject.className,
+        artifactId: artifact.artifactId || undefined,
+        mapping: classSubject.mapping,
+        scope: classSubject.scope,
+        projectPath: classSubject.projectPath,
+        preferProjectVersion: classSubject.preferProjectVersion,
+        strictVersion: classSubject.strictVersion,
+        maxMembers: limit
+    });
+    const summary = {
+        status: members.truncated ? "partial" : "ok",
+        headline: `Collected ${members.counts.total} members for ${members.className}.`,
+        subject: createSummarySubject({
+            task: "class-members",
+            requested: subject,
+            className: members.className,
+            artifactId: members.artifactId
+        }),
+        counts: members.counts
+    };
+    return {
+        ...buildEntryToolResult({
+            task: "class-members",
+            summary,
+            detail,
+            include,
+            blocks: {
+                subject: {
+                    requested: subject,
+                    resolved: {
+                        artifactId: members.artifactId,
+                        className: members.className
+                    }
+                },
+                members: include.includes("members") || detail !== "summary"
+                    ? {
+                        ...members.members,
+                        ...(members.decompiledFallback ? { decompiledFallback: members.decompiledFallback } : {}),
+                        ...(members.decompiledMemberCounts ? { decompiledMemberCounts: members.decompiledMemberCounts } : {})
+                    }
+                    : {
+                        counts: members.counts,
+                        ...(members.decompiledMemberCounts ? { decompiledMemberCounts: members.decompiledMemberCounts } : {})
+                    }
+            },
+            alwaysBlocks: ["subject"]
+        }),
+        warnings: [...artifact.warnings, ...members.warnings],
+        ...(members.truncated
+            ? {
+                meta: buildEntryToolMeta({
+                    detail,
+                    include,
+                    warnings: [...artifact.warnings, ...members.warnings],
+                    truncated: createTruncationMeta({
+                        omittedGroups: ["members"],
+                        nextActions: [
+                            createNextAction("inspect-minecraft", {
+                                task: "class-members",
+                                detail: "full",
+                                include: ["members"],
+                                subject
+                            })
+                        ]
+                    })
+                })
+            }
+            : {})
+    };
+}
+//# sourceMappingURL=class-members.js.map

package/dist/entry-tools/inspect-minecraft/handlers/class-overview.d.ts

@@ -0,0 +1,5 @@
+import { type DetailLevel } from "../../response-contract.js";
+import { type Subject, type InspectMinecraftDeps } from "../internal.js";
+export declare function handleClassOverview(deps: InspectMinecraftDeps, subject: Subject, detail: DetailLevel, include: string[]): Promise<{
+    warnings: string[];
+}>;

package/dist/entry-tools/inspect-minecraft/handlers/class-overview.js

@@ -0,0 +1,248 @@
+import { buildEntryToolResult, createNextAction, createSummarySubject } from "../../response-contract.js";
+import { nextActionsOrUndefined } from "../../request-normalizers.js";
+import { hasPartialVanillaCoverage, buildClassSubject, resolveClassArtifactReference, invalidTaskSubjectError, resolveBinaryBackedClass } from "../internal.js";
+export async function handleClassOverview(deps, subject, detail, include) {
+    if (subject.kind !== "class" && !(subject.kind === "workspace" && subject.focus?.kind === "class")) {
+        invalidTaskSubjectError("class-overview", subject);
+    }
+    const classSubject = buildClassSubject(subject);
+    const className = classSubject.className;
+    const artifact = await resolveClassArtifactReference(deps, subject, classSubject, "class-overview");
+    if (!artifact.artifactId) {
+        const summary = {
+            status: "blocked",
+            headline: `Could not resolve artifact context for ${className}.`,
+            subject: createSummarySubject({
+                task: "class-overview",
+                requested: subject,
+                className
+            })
+        };
+        return {
+            ...buildEntryToolResult({
+                task: "class-overview",
+                summary,
+                detail,
+                include,
+                blocks: {
+                    subject: {
+                        requested: subject
+                    }
+                },
+                alwaysBlocks: ["subject"]
+            }),
+            warnings: artifact.warnings
+        };
+    }
+    const matches = await deps.findClass({
+        artifactId: artifact.artifactId,
+        className,
+        limit: 10
+    });
+    if (matches.total === 0) {
+        const partialSourceFallback = subject.kind === "workspace" && hasPartialVanillaCoverage(artifact.artifact)
+            ? await resolveBinaryBackedClass(deps, className, {
+                version: artifact.version,
+                mapping: classSubject.mapping
+            })
+            : undefined;
+        if (partialSourceFallback) {
+            const metadata = await deps.getClassSource({
+                className: partialSourceFallback.className,
+                artifactId: artifact.artifactId,
+                mapping: classSubject.mapping,
+                scope: classSubject.scope,
+                projectPath: classSubject.projectPath,
+                preferProjectVersion: classSubject.preferProjectVersion,
+                strictVersion: classSubject.strictVersion,
+                mode: "metadata"
+            });
+            const summary = {
+                status: "ok",
+                headline: `Resolved class overview for ${partialSourceFallback.className}.`,
+                subject: createSummarySubject({
+                    task: "class-overview",
+                    requested: subject,
+                    className: partialSourceFallback.className,
+                    artifactId: metadata.artifactId
+                }),
+                counts: {
+                    totalLines: metadata.totalLines
+                },
+                notes: [
+                    "Source coverage was partial, so inspect-minecraft confirmed the vanilla class through binary-backed symbol lookup."
+                ]
+            };
+            return {
+                ...buildEntryToolResult({
+                    task: "class-overview",
+                    summary,
+                    detail,
+                    include,
+                    blocks: {
+                        subject: {
+                            requested: subject,
+                            resolved: {
+                                artifactId: metadata.artifactId,
+                                className: partialSourceFallback.className
+                            }
+                        },
+                        class: {
+                            className: partialSourceFallback.className,
+                            totalLines: metadata.totalLines,
+                            returnedNamespace: metadata.returnedNamespace
+                        }
+                    },
+                    alwaysBlocks: ["subject"]
+                }),
+                warnings: [
+                    ...artifact.warnings,
+                    ...matches.warnings,
+                    ...partialSourceFallback.warnings,
+                    ...metadata.warnings
+                ]
+            };
+        }
+        const summary = {
+            status: "not_found",
+            headline: `No class match was found for ${className}.`,
+            subject: createSummarySubject({
+                task: "class-overview",
+                requested: subject,
+                className,
+                artifactId: artifact.artifactId
+            })
+        };
+        return {
+            ...buildEntryToolResult({
+                task: "class-overview",
+                summary,
+                detail,
+                include,
+                blocks: {
+                    subject: {
+                        requested: subject,
+                        resolved: {
+                            artifactId: artifact.artifactId
+                        }
+                    }
+                },
+                alwaysBlocks: ["subject"]
+            }),
+            warnings: [...artifact.warnings, ...matches.warnings]
+        };
+    }
+    if (matches.total > 1) {
+        const candidateActions = matches.matches.slice(0, 3).map((match) => createNextAction("inspect-minecraft", {
+            task: "class-source",
+            subject: {
+                kind: "class",
+                className: match.qualifiedName,
+                artifact: {
+                    type: "resolved-id",
+                    artifactId: artifact.artifactId
+                }
+            },
+            include: ["source"]
+        }));
+        const summary = {
+            status: "ambiguous",
+            headline: `Found ${matches.total} class matches for ${className}.`,
+            subject: createSummarySubject({
+                task: "class-overview",
+                requested: subject,
+                className,
+                artifactId: artifact.artifactId
+            }),
+            counts: {
+                matches: matches.total
+            },
+            nextActions: nextActionsOrUndefined(candidateActions)
+        };
+        return {
+            ...buildEntryToolResult({
+                task: "class-overview",
+                summary,
+                detail,
+                include,
+                blocks: {
+                    subject: {
+                        requested: subject,
+                        resolved: {
+                            artifactId: artifact.artifactId
+                        }
+                    },
+                    candidates: matches.matches
+                },
+                alwaysBlocks: ["subject"]
+            }),
+            warnings: [...artifact.warnings, ...matches.warnings]
+        };
+    }
+    const match = matches.matches[0];
+    const metadata = await deps.getClassSource({
+        className: match.qualifiedName,
+        artifactId: artifact.artifactId,
+        mode: "metadata"
+    });
+    const summary = {
+        status: "ok",
+        headline: `Resolved class overview for ${match.qualifiedName}.`,
+        subject: createSummarySubject({
+            task: "class-overview",
+            requested: subject,
+            className: match.qualifiedName,
+            artifactId: artifact.artifactId
+        }),
+        counts: {
+            totalLines: metadata.totalLines
+        },
+        nextActions: nextActionsOrUndefined([
+            createNextAction("inspect-minecraft", {
+                task: "class-source",
+                subject: {
+                    kind: "class",
+                    className: match.qualifiedName,
+                    artifact: {
+                        type: "resolved-id",
+                        artifactId: artifact.artifactId
+                    }
+                },
+                include: ["source"]
+            })
+        ])
+    };
+    return {
+        ...buildEntryToolResult({
+            task: "class-overview",
+            summary,
+            detail,
+            include,
+            blocks: {
+                subject: {
+                    requested: subject,
+                    resolved: {
+                        artifactId: artifact.artifactId,
+                        className: match.qualifiedName
+                    }
+                },
+                artifact: artifact.artifact
+                    ? {
+                        artifactId: artifact.artifact.artifactId,
+                        version: artifact.artifact.version,
+                        origin: artifact.artifact.origin
+                    }
+                    : { artifactId: artifact.artifactId },
+                class: {
+                    className: match.qualifiedName,
+                    filePath: match.filePath,
+                    totalLines: metadata.totalLines,
+                    returnedNamespace: metadata.returnedNamespace
+                }
+            },
+            alwaysBlocks: ["subject"]
+        }),
+        warnings: [...artifact.warnings, ...matches.warnings, ...metadata.warnings]
+    };
+}
+//# sourceMappingURL=class-overview.js.map

package/dist/entry-tools/inspect-minecraft/handlers/class-source.d.ts

@@ -0,0 +1,5 @@
+import { type DetailLevel } from "../../response-contract.js";
+import { type Subject, type InspectMinecraftDeps } from "../internal.js";
+export declare function handleClassSource(deps: InspectMinecraftDeps, subject: Subject, detail: DetailLevel, include: string[]): Promise<{
+    warnings: string[];
+}>;