@adhisang/minecraft-modding-mcp 1.2.1 → 2.1.0

package/dist/mcp-helpers.d.ts

@@ -1,5 +1,13 @@
 import type { CallToolResult, ReadResourceResult } from "@modelcontextprotocol/sdk/types.js";
-export declare function objectResult<T extends Record<string, unknown>>(data: T): CallToolResult;
+import { type ErrorCode } from "./errors.js";
+type ObjectResultOptions = {
+    isError?: boolean;
+};
+export declare function objectResult<T extends Record<string, unknown>>(data: T, options?: ObjectResultOptions): CallToolResult;
 export declare function textResource(uri: string, value: string): ReadResourceResult;
 export declare function objectResource(uri: string, data: Record<string, unknown>): ReadResourceResult;
-export declare function errorResource(uri: string, message: string): ReadResourceResult;
+export declare function errorResource(uri: string, error: string | {
+    message: string;
+    code?: ErrorCode;
+}): ReadResourceResult;
+export {};

package/dist/mcp-helpers.js

@@ -1,13 +1,67 @@
-export function objectResult(data) {
-    return { content: [{ type: "text", text: JSON.stringify(data) }] };
+import { ERROR_CODES } from "./errors.js";
+export function objectResult(data, options = {}) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(data) }],
+        structuredContent: data,
+        ...(options.isError ? { isError: true } : {})
+    };
 }
 export function textResource(uri, value) {
     return { contents: [{ uri, text: value }] };
 }
 export function objectResource(uri, data) {
-    return { contents: [{ uri, text: JSON.stringify(data) }] };
+    return {
+        contents: [
+            {
+                uri,
+                mimeType: "application/json",
+                text: JSON.stringify({
+                    result: data,
+                    meta: { uri }
+                })
+            }
+        ]
+    };
 }
-export function errorResource(uri, message) {
-    return { contents: [{ uri, text: JSON.stringify({ error: message }) }] };
+function statusForResourceErrorCode(code) {
+    if (code === ERROR_CODES.INVALID_INPUT) {
+        return 400;
+    }
+    if (code === ERROR_CODES.FILE_NOT_FOUND ||
+        code === ERROR_CODES.SOURCE_NOT_FOUND ||
+        code === ERROR_CODES.CLASS_NOT_FOUND ||
+        code === ERROR_CODES.VERSION_NOT_FOUND ||
+        code === ERROR_CODES.JAR_NOT_FOUND) {
+        return 404;
+    }
+    if (code === ERROR_CODES.MAPPING_UNAVAILABLE ||
+        code === ERROR_CODES.MAPPING_NOT_APPLIED ||
+        code === ERROR_CODES.NAMESPACE_MISMATCH) {
+        return 422;
+    }
+    return 500;
+}
+export function errorResource(uri, error) {
+    const detail = typeof error === "string" ? error : error.message;
+    const code = typeof error === "string" ? ERROR_CODES.INVALID_INPUT : error.code ?? ERROR_CODES.INTERNAL;
+    return {
+        contents: [
+            {
+                uri,
+                mimeType: "application/json",
+                text: JSON.stringify({
+                    error: {
+                        type: "https://minecraft-modding-mcp.dev/problems/resource",
+                        title: "Resource read failed",
+                        detail,
+                        status: statusForResourceErrorCode(code),
+                        code,
+                        instance: uri
+                    },
+                    meta: { uri }
+                })
+            }
+        ]
+    };
 }
 //# sourceMappingURL=mcp-helpers.js.map

package/dist/minecraft-explorer-service.d.ts

@@ -1,5 +1,5 @@
 import type { Config } from "./types.js";
-export type MappingNamespace = "official" | "mojang" | "yarn";
+export type MappingNamespace = "obfuscated" | "mojang" | "yarn";
 type SignatureAccess = "public" | "all";
 export interface ResponseContext {
     minecraftVersion: string;
@@ -38,6 +38,5 @@ export declare class MinecraftExplorerService {
     getSignature(input: GetSignatureInput): Promise<GetSignatureOutput>;
     private contextForJar;
     private normalizeJarPathOrThrow;
-    private trimSignatureCache;
 }
 export {};

package/dist/minecraft-explorer-service.js

@@ -68,7 +68,7 @@ function modifierPrefix(flags, category) {
     }
     return parts.join(" ");
 }
-function parseFieldType(descriptor, position = 0) {
+function parseFieldType(descriptor, position = 0, options = {}) {
     if (position >= descriptor.length) {
         throw createError({
             code: ERROR_CODES.INVALID_INPUT,
@@ -95,6 +95,13 @@ function parseFieldType(descriptor, position = 0) {
         case "Z":
             return { type: "boolean", next: position + 1 };
         case "V":
+            if (!options.allowVoid) {
+                throw createError({
+                    code: ERROR_CODES.INVALID_INPUT,
+                    message: options.invalidVoidMessage ?? `Invalid field descriptor "${descriptor}".`,
+                    details: { descriptor, position }
+                });
+            }
             return { type: "void", next: position + 1 };
         case "L": {
             const end = descriptor.indexOf(";", position);
@@ -109,7 +116,7 @@ function parseFieldType(descriptor, position = 0) {
             return { type, next: end + 1 };
         }
         case "[": {
-            const inner = parseFieldType(descriptor, position + 1);
+            const inner = parseFieldType(descriptor, position + 1, options);
             return { type: `${inner.type}[]`, next: inner.next };
         }
         default:
@@ -131,7 +138,10 @@ function parseMethodDescriptor(descriptor) {
     const args = [];
     let cursor = 1;
     while (cursor < descriptor.length && descriptor[cursor] !== ")") {
-        const parsed = parseFieldType(descriptor, cursor);
+        const parsed = parseFieldType(descriptor, cursor, {
+            allowVoid: false,
+            invalidVoidMessage: `Invalid method descriptor "${descriptor}": void is not allowed in this position.`
+        });
         args.push(parsed.type);
         cursor = parsed.next;
     }
@@ -142,7 +152,15 @@ function parseMethodDescriptor(descriptor) {
             details: { descriptor, cursor }
         });
     }
-    const returnType = parseFieldType(descriptor, cursor + 1).type;
+    const parsedReturn = parseFieldType(descriptor, cursor + 1, { allowVoid: true });
+    if (parsedReturn.next !== descriptor.length) {
+        throw createError({
+            code: ERROR_CODES.INVALID_INPUT,
+            message: `Invalid method descriptor "${descriptor}".`,
+            details: { descriptor, cursor: parsedReturn.next }
+        });
+    }
+    const returnType = parsedReturn.type;
     return { args, returnType };
 }
 function hasPublicVisibility(flags) {
@@ -154,6 +172,80 @@ function toInternalName(fqn) {
 function extractVersionFromPath(inputPath) {
     return inputPath.match(/(\d+\.\d+(?:\.\d+)?)/)?.[1];
 }
+class SignatureCacheStore {
+    maxEntries;
+    nodes = new Map();
+    oldest;
+    newest;
+    constructor(maxEntries) {
+        this.maxEntries = maxEntries;
+    }
+    get(key) {
+        const node = this.nodes.get(key);
+        if (!node) {
+            return undefined;
+        }
+        this.promote(node);
+        return node.value;
+    }
+    set(key, value) {
+        const existing = this.nodes.get(key);
+        if (existing) {
+            existing.value = value;
+            this.promote(existing);
+            return;
+        }
+        const node = { key, value, older: this.newest };
+        if (this.newest) {
+            this.newest.newer = node;
+        }
+        else {
+            this.oldest = node;
+        }
+        this.newest = node;
+        this.nodes.set(key, node);
+        while (this.nodes.size > this.maxEntries) {
+            this.evictOldest();
+        }
+    }
+    promote(node) {
+        if (this.newest === node) {
+            return;
+        }
+        if (node.older) {
+            node.older.newer = node.newer;
+        }
+        else {
+            this.oldest = node.newer;
+        }
+        if (node.newer) {
+            node.newer.older = node.older;
+        }
+        node.older = this.newest;
+        node.newer = undefined;
+        if (this.newest) {
+            this.newest.newer = node;
+        }
+        else {
+            this.oldest = node;
+        }
+        this.newest = node;
+    }
+    evictOldest() {
+        const node = this.oldest;
+        if (!node) {
+            return;
+        }
+        this.oldest = node.newer;
+        if (this.oldest) {
+            this.oldest.older = undefined;
+        }
+        else {
+            this.newest = undefined;
+        }
+        this.nodes.delete(node.key);
+    }
+}
 class ByteReader {
     offset = 0;
     buffer;
@@ -321,9 +413,10 @@ function parseClassFile(buffer) {
 }
 export class MinecraftExplorerService {
     config;
-    signatureCache = new Map();
+    signatureCache;
     constructor(explicitConfig) {
         this.config = explicitConfig ?? loadConfig();
+        this.signatureCache = new SignatureCacheStore(Math.max(1, this.config.maxSignatureCache ?? 2_000));
     }
     async getSignature(input) {
         const jarPath = this.normalizeJarPathOrThrow(input.jarPath);
@@ -348,10 +441,11 @@ export class MinecraftExplorerService {
         ].join("|");
         const cached = this.signatureCache.get(cacheKey);
         if (cached) {
-            this.signatureCache.delete(cacheKey);
-            this.signatureCache.set(cacheKey, cached);
             return {
-                ...cached,
+                constructors: cached.constructors,
+                methods: cached.methods,
+                fields: cached.fields,
+                warnings: cached.warnings,
                 context: this.contextForJar(jarPath)
             };
         }
@@ -446,7 +540,15 @@ export class MinecraftExplorerService {
         }
         const toSignatureMember = (ownerFqn, ownerSimpleClassName, member, category) => {
             if (category === "field") {
-                const fieldType = parseFieldType(member.descriptor).type;
+                const parsedField = parseFieldType(member.descriptor, 0, { allowVoid: false });
+                if (parsedField.next !== member.descriptor.length) {
+                    throw createError({
+                        code: ERROR_CODES.INVALID_INPUT,
+                        message: `Invalid field descriptor "${member.descriptor}".`,
+                        details: { descriptor: member.descriptor, position: parsedField.next }
+                    });
+                }
+                const fieldType = parsedField.type;
                 const modifiers = modifierPrefix(member.accessFlags, "field");
                 return {
                     ownerFqn,
@@ -520,18 +622,22 @@ export class MinecraftExplorerService {
             constructors,
             methods,
             fields,
-            warnings,
-            context: this.contextForJar(jarPath)
+            warnings
         };
         this.signatureCache.set(cacheKey, output);
-        this.trimSignatureCache();
-        return output;
+        return {
+            constructors: output.constructors,
+            methods: output.methods,
+            fields: output.fields,
+            warnings: output.warnings,
+            context: this.contextForJar(jarPath)
+        };
     }
     contextForJar(jarPath) {
         return {
             minecraftVersion: extractVersionFromPath(jarPath) ?? "unknown",
             mappingType: "unknown",
-            mappingNamespace: "official",
+            mappingNamespace: "obfuscated",
             jarHash: artifactSignatureFromFile(jarPath).sourceArtifactId,
             generatedAt: new Date().toISOString()
         };
@@ -548,15 +654,5 @@ export class MinecraftExplorerService {
             });
         }
     }
-    trimSignatureCache() {
-        const maxEntries = Math.max(1, this.config.maxSignatureCache ?? 2_000);
-        while (this.signatureCache.size > maxEntries) {
-            const oldest = this.signatureCache.keys().next().value;
-            if (!oldest) {
-                return;
-            }
-            this.signatureCache.delete(oldest);
-        }
-    }
 }
 //# sourceMappingURL=minecraft-explorer-service.js.map

package/dist/mixin-validator.d.ts

@@ -16,10 +16,11 @@ export type MappingHealthReport = {
     degradations: string[];
 };
 export type IssueConfidence = "definite" | "likely" | "uncertain";
+export type ValidationStatus = "full" | "partial" | "invalid";
 export type ResolutionPath = "member-remap-failed" | "target-mapping-failed" | "target-class-missing" | "source-signature-unavailable";
 export type ValidationIssue = {
     severity: "error" | "warning";
-    kind: "target-not-found" | "target-mapping-failed" | "method-not-found" | "field-not-found" | "descriptor-mismatch" | "access-mismatch" | "unknown-annotation";
+    kind: "target-not-found" | "validation-incomplete" | "target-mapping-failed" | "method-not-found" | "field-not-found" | "descriptor-mismatch" | "access-mismatch" | "unknown-annotation";
     annotation: string;
     target: string;
     message: string;
@@ -42,6 +43,9 @@ export type ValidationSummary = {
     shadows: number;
     accessors: number;
     total: number;
+    membersValidated: number;
+    membersSkipped: number;
+    membersMissing: number;
     errors: number;
     warnings: number;
     definiteErrors: number;
@@ -54,8 +58,12 @@ export type MixinValidationProvenance = {
     jarPath: string;
     requestedMapping: SourceMapping;
     mappingApplied: SourceMapping;
+    requestedScope?: "vanilla" | "merged" | "loader";
+    appliedScope?: "vanilla" | "merged" | "loader";
+    requestedSourcePriority?: "loom-first" | "maven-first";
+    appliedSourcePriority?: "loom-first" | "maven-first";
     resolutionNotes?: string[];
-    jarType?: "vanilla-client" | "merged" | "unknown";
+    jarType?: "vanilla-client" | "merged" | "loader" | "unknown";
     mappingChain?: string[];
     remapFailures?: number;
     mappingAutoDetected?: boolean;
@@ -91,11 +99,23 @@ export type AggregatedWarningGroup = {
     count: number;
     samples: string[];
 };
+export type ConfidencePenalty = {
+    reason: string;
+    points: number;
+};
+export type ConfidenceBreakdown = {
+    baseScore: number;
+    score: number;
+    penalties: ConfidencePenalty[];
+};
 export type MixinValidationResult = {
     className: string;
     targets: string[];
     priority?: number;
+    /** Legacy coarse pass/fail flag. Prefer validationStatus for the primary outcome. */
     valid: boolean;
+    /** full = fully validated, partial = tool-limited/incomplete, invalid = definite validation errors. */
+    validationStatus: ValidationStatus;
     issues: ValidationIssue[];
     summary: ValidationSummary;
     unfilteredSummary?: ValidationSummary;
@@ -106,6 +126,7 @@ export type MixinValidationResult = {
     resolvedMembers?: ResolvedMember[];
     toolHealth?: MappingHealthReport;
     confidenceScore?: number;
+    confidenceBreakdown?: ConfidenceBreakdown;
     quickSummary?: string;
 };
 export type ResolvedTargetMembers = {
@@ -141,6 +162,7 @@ export declare function extractMethodName(ref: string): string;
  *   "tick"                                                      → undefined
  */
 export declare function extractMethodDescriptor(ref: string): string | undefined;
+export declare function refreshMixinValidationOutcome(result: MixinValidationResult): MixinValidationResult;
 export declare function validateParsedMixin(parsed: ParsedMixin, targetMembers: Map<string, ResolvedTargetMembers>, warnings: string[], provenance?: MixinValidationProvenance, confidence?: IssueConfidence, mappingFailedTargets?: Set<string>, explain?: boolean, remapFailedMembers?: Map<string, Set<string>>, signatureFailedTargets?: Set<string>, suggestedCallContext?: {
     scope?: string;
     sourcePriority?: string;