@adhisang/minecraft-modding-mcp 3.2.0 → 4.0.0

package/dist/response-utils.d.ts

@@ -7,29 +7,63 @@
 export declare const COMPACT_ENABLED_TOOL_NAMES: Set<string>;
 /** Mapping-oriented tools that get additional field projection via compactMappingResponse. */
 export declare const COMPACT_MAPPING_TOOL_NAMES: Set<string>;
+/** Source-oriented tools (get-class-source) that get compactSourceResponse projection. */
+export declare const COMPACT_SOURCE_TOOL_NAMES: Set<string>;
+/** Member-listing tools (get-class-members) that get compactMembersResponse projection. */
+export declare const COMPACT_MEMBERS_TOOL_NAMES: Set<string>;
+/**
+ * Tools that only need the light artifactContents projection (search hits,
+ * file listing). The primary payload is already small; the projection just
+ * drops the artifact-level summary that callers rarely consume.
+ */
+export declare const COMPACT_LIGHT_TOOL_NAMES: Set<string>;
 /**
  * Double-gated compact check: tool must be in the allowlist AND parsedInput.compact must be true.
  * Prevents activation on passthrough schemas where Zod doesn't strip unknown keys.
  */
 export declare function isCompactEnabled(tool: string, parsedInput: unknown): boolean;
+/**
+ * Primary-payload keys that compact mode must preserve per tool, even when
+ * the value is an empty array (no hits, no files, no members). Without this
+ * the generic {@link compactResponse} path would strip `hits: []` / `items: []`
+ * from successful zero-result responses and callers could not distinguish
+ * "empty success" from "field missing".
+ *
+ * Only tools whose primary payload can legitimately be an empty array need
+ * an entry here. `get-class-source` returns `sourceText: string` which is
+ * never stripped by compactResponse.
+ */
+export declare const TOOL_PRESERVE_PAYLOAD_KEYS: Record<string, ReadonlySet<string>>;
 /**
  * Shallow-strip empty values from a response object.
  * Only operates on the top level — nested structures are preserved as-is.
  * Non-plain objects (Date, Map, class instances) are never treated as empty.
+ *
+ * `preserveKeys` names keys whose values MUST survive the strip even if
+ * empty (used by tools whose primary payload is an array that can legitimately
+ * be empty — e.g. zero-hit search, empty file listing). `null` / `undefined`
+ * values are still dropped even for preserved keys, so absent optional
+ * payload fields do not leak through as explicit nulls.
  */
-export declare function compactResponse(obj: Record<string, unknown>): Record<string, unknown>;
+export declare function compactResponse(obj: Record<string, unknown>, preserveKeys?: ReadonlySet<string>): Record<string, unknown>;
 /** resolve-artifact compact: omit debug/diagnostic fields. */
 export declare function compactArtifactResponse(obj: Record<string, unknown>): Record<string, unknown>;
+/** get-class-source compact: drop provenance, artifactContents, qualityFlags. */
+export declare function compactSourceResponse(obj: Record<string, unknown>): Record<string, unknown>;
+/** get-class-members compact: drop provenance, artifactContents, qualityFlags, context. */
+export declare function compactMembersResponse(obj: Record<string, unknown>): Record<string, unknown>;
+/** Light compact projection: drop the artifactContents summary only. */
+export declare function compactLightResponse(obj: Record<string, unknown>): Record<string, unknown>;
 /**
- * Mapping tool compact: omit candidates only when provably redundant.
+ * Mapping tool compact: project candidates for size reduction.
+ *
+ * Resolved-exact path: omit candidates entirely when provably redundant.
+ *   All of: resolved===true, resolvedSymbol exists, single exact candidate, not truncated,
+ *           confidence missing or 1.
  *
- * Candidates are omitted when ALL of:
- * 1. resolved === true
- * 2. resolvedSymbol exists
- * 3. candidates is an array of length 1
- * 4. candidateCount === 1
- * 5. candidatesTruncated is falsy
- * 6. candidates[0].matchKind === "exact"
- * 7. candidates[0].confidence is undefined or 1
+ * Unresolved/ambiguous path: keep top {@link UNRESOLVED_FULL_DETAIL_LIMIT} candidates with full
+ *   metadata, slim the tail to {kind,symbol,owner,name,descriptor,confidence,matchKind}, and
+ *   surface `candidatesTruncated:true` + `totalCandidateCount` so the caller knows what it's
+ *   seeing.
  */
 export declare function compactMappingResponse(obj: Record<string, unknown>): Record<string, unknown>;

package/dist/response-utils.js

@@ -9,7 +9,11 @@ export const COMPACT_ENABLED_TOOL_NAMES = new Set([
     "find-mapping",
     "resolve-method-mapping-exact",
     "resolve-workspace-symbol",
-    "check-symbol-exists"
+    "check-symbol-exists",
+    "get-class-source",
+    "get-class-members",
+    "search-class-source",
+    "list-artifact-files"
 ]);
 /** Mapping-oriented tools that get additional field projection via compactMappingResponse. */
 export const COMPACT_MAPPING_TOOL_NAMES = new Set([
@@ -18,6 +22,23 @@ export const COMPACT_MAPPING_TOOL_NAMES = new Set([
     "resolve-workspace-symbol",
     "check-symbol-exists"
 ]);
+/** Source-oriented tools (get-class-source) that get compactSourceResponse projection. */
+export const COMPACT_SOURCE_TOOL_NAMES = new Set([
+    "get-class-source"
+]);
+/** Member-listing tools (get-class-members) that get compactMembersResponse projection. */
+export const COMPACT_MEMBERS_TOOL_NAMES = new Set([
+    "get-class-members"
+]);
+/**
+ * Tools that only need the light artifactContents projection (search hits,
+ * file listing). The primary payload is already small; the projection just
+ * drops the artifact-level summary that callers rarely consume.
+ */
+export const COMPACT_LIGHT_TOOL_NAMES = new Set([
+    "search-class-source",
+    "list-artifact-files"
+]);
 /**
  * Double-gated compact check: tool must be in the allowlist AND parsedInput.compact must be true.
  * Prevents activation on passthrough schemas where Zod doesn't strip unknown keys.
@@ -39,18 +60,44 @@ function isPlainObject(v) {
     const proto = Object.getPrototypeOf(v);
     return proto === Object.prototype || proto === null;
 }
+/**
+ * Primary-payload keys that compact mode must preserve per tool, even when
+ * the value is an empty array (no hits, no files, no members). Without this
+ * the generic {@link compactResponse} path would strip `hits: []` / `items: []`
+ * from successful zero-result responses and callers could not distinguish
+ * "empty success" from "field missing".
+ *
+ * Only tools whose primary payload can legitimately be an empty array need
+ * an entry here. `get-class-source` returns `sourceText: string` which is
+ * never stripped by compactResponse.
+ */
+export const TOOL_PRESERVE_PAYLOAD_KEYS = {
+    "search-class-source": new Set(["hits"]),
+    "list-artifact-files": new Set(["items"]),
+    "get-class-members": new Set(["members", "counts", "decompiledFallback", "decompiledMemberCounts"])
+};
 /**
  * Shallow-strip empty values from a response object.
  * Only operates on the top level — nested structures are preserved as-is.
  * Non-plain objects (Date, Map, class instances) are never treated as empty.
+ *
+ * `preserveKeys` names keys whose values MUST survive the strip even if
+ * empty (used by tools whose primary payload is an array that can legitimately
+ * be empty — e.g. zero-hit search, empty file listing). `null` / `undefined`
+ * values are still dropped even for preserved keys, so absent optional
+ * payload fields do not leak through as explicit nulls.
  */
-export function compactResponse(obj) {
+export function compactResponse(obj, preserveKeys) {
     if (!isPlainObject(obj))
         return {};
     const result = {};
     for (const [key, value] of Object.entries(obj)) {
         if (value === null || value === undefined)
             continue;
+        if (preserveKeys?.has(key)) {
+            result[key] = value;
+            continue;
+        }
         if (Array.isArray(value) && value.length === 0)
             continue;
         if (isPlainObject(value) && Object.keys(value).length === 0)
@@ -59,6 +106,15 @@ export function compactResponse(obj) {
     }
     return result;
 }
+function projectOmitKeys(obj, omit) {
+    const projected = {};
+    for (const [key, value] of Object.entries(obj)) {
+        if (omit.has(key))
+            continue;
+        projected[key] = value;
+    }
+    return projected;
+}
 /** Fields to omit from resolve-artifact in compact mode. */
 const ARTIFACT_COMPACT_OMIT_KEYS = new Set([
     "provenance",
@@ -72,25 +128,69 @@ const ARTIFACT_COMPACT_OMIT_KEYS = new Set([
 ]);
 /** resolve-artifact compact: omit debug/diagnostic fields. */
 export function compactArtifactResponse(obj) {
-    const projected = {};
-    for (const [key, value] of Object.entries(obj)) {
-        if (ARTIFACT_COMPACT_OMIT_KEYS.has(key))
-            continue;
-        projected[key] = value;
+    return projectOmitKeys(obj, ARTIFACT_COMPACT_OMIT_KEYS);
+}
+/** Fields to omit from get-class-source in compact mode. */
+const SOURCE_COMPACT_OMIT_KEYS = new Set([
+    "provenance",
+    "artifactContents",
+    "qualityFlags"
+]);
+/** get-class-source compact: drop provenance, artifactContents, qualityFlags. */
+export function compactSourceResponse(obj) {
+    return projectOmitKeys(obj, SOURCE_COMPACT_OMIT_KEYS);
+}
+/** Fields to omit from get-class-members in compact mode. */
+const MEMBERS_COMPACT_OMIT_KEYS = new Set([
+    "provenance",
+    "artifactContents",
+    "qualityFlags",
+    "context"
+]);
+/** get-class-members compact: drop provenance, artifactContents, qualityFlags, context. */
+export function compactMembersResponse(obj) {
+    return projectOmitKeys(obj, MEMBERS_COMPACT_OMIT_KEYS);
+}
+/** Fields to omit from search-class-source / list-artifact-files in compact mode. */
+const LIGHT_COMPACT_OMIT_KEYS = new Set([
+    "artifactContents"
+]);
+/** Light compact projection: drop the artifactContents summary only. */
+export function compactLightResponse(obj) {
+    return projectOmitKeys(obj, LIGHT_COMPACT_OMIT_KEYS);
+}
+/** Max number of unresolved candidates that get full metadata in compact mode. */
+const UNRESOLVED_FULL_DETAIL_LIMIT = 3;
+/**
+ * Slim projection of a candidate: retains only identification + confidence fields.
+ *
+ * `kind` and `symbol` are part of the public `SymbolReference` / candidate contract that
+ * clients branch on and use as rendering keys, so they MUST survive the slim. The heavy
+ * fields removed here are the cycle-local diagnostic metadata (provenance, context,
+ * ambiguityReasons, warnings on the candidate, etc.) — not the identity fields.
+ */
+function slimCandidate(candidate) {
+    if (!isPlainObject(candidate))
+        return candidate;
+    const picked = {};
+    for (const key of ["kind", "symbol", "owner", "name", "descriptor", "confidence", "matchKind"]) {
+        if (candidate[key] !== undefined) {
+            picked[key] = candidate[key];
+        }
     }
-    return projected;
+    return picked;
 }
 /**
- * Mapping tool compact: omit candidates only when provably redundant.
+ * Mapping tool compact: project candidates for size reduction.
+ *
+ * Resolved-exact path: omit candidates entirely when provably redundant.
+ *   All of: resolved===true, resolvedSymbol exists, single exact candidate, not truncated,
+ *           confidence missing or 1.
  *
- * Candidates are omitted when ALL of:
- * 1. resolved === true
- * 2. resolvedSymbol exists
- * 3. candidates is an array of length 1
- * 4. candidateCount === 1
- * 5. candidatesTruncated is falsy
- * 6. candidates[0].matchKind === "exact"
- * 7. candidates[0].confidence is undefined or 1
+ * Unresolved/ambiguous path: keep top {@link UNRESOLVED_FULL_DETAIL_LIMIT} candidates with full
+ *   metadata, slim the tail to {kind,symbol,owner,name,descriptor,confidence,matchKind}, and
+ *   surface `candidatesTruncated:true` + `totalCandidateCount` so the caller knows what it's
+ *   seeing.
  */
 export function compactMappingResponse(obj) {
     const projected = { ...obj };
@@ -106,8 +206,22 @@ export function compactMappingResponse(obj) {
             candidate.matchKind === "exact" &&
             (candidate.confidence === undefined || candidate.confidence === 1)) {
             delete projected.candidates;
+            return projected;
         }
     }
+    if (projected.resolved === false &&
+        Array.isArray(candidates) &&
+        candidates.length > UNRESOLVED_FULL_DETAIL_LIMIT) {
+        const head = candidates.slice(0, UNRESOLVED_FULL_DETAIL_LIMIT);
+        const tail = candidates.slice(UNRESOLVED_FULL_DETAIL_LIMIT).map(slimCandidate);
+        projected.candidates = [...head, ...tail];
+        // Tail slimming keeps the full candidate array; only metadata was dropped. Use a
+        // dedicated `candidateDetailsTruncated` signal so clients do not confuse it with the
+        // existing `candidatesTruncated` semantics ("more candidates exist than this response
+        // contains"). If the upstream already reported list-level truncation via
+        // `candidatesTruncated`, that value is preserved unchanged.
+        projected.candidateDetailsTruncated = true;
+    }
     return projected;
 }
 //# sourceMappingURL=response-utils.js.map

package/dist/source-resolver.d.ts

@@ -1,8 +1,16 @@
-import type { Config, ResolvedSourceArtifact, SourceTargetInput } from "./types.js";
+import type { Config, MappingVariant, ResolvedSourceArtifact, SourceTargetInput } from "./types.js";
+export type { MappingVariant } from "./types.js";
 export interface ResolveSourceTargetOptions {
     allowDecompile: boolean;
     preferBinaryOnly?: boolean;
     preferredRepos?: string[];
+    /**
+     * When set to "mojang-remapped", the artifactId hash gets a dedicated
+     * suffix so the mojang-remapped variant of an otherwise binary-only artifact
+     * occupies its own cache slot. Defaults to "pass" which preserves the
+     * legacy hash for obfuscated and source-backed artifacts.
+     */
+    mappingVariant?: MappingVariant;
     onRepoFailover?: (event: {
         stage: "source" | "binary";
         repoUrl: string;

package/dist/source-resolver.js

@@ -133,11 +133,19 @@ async function resolveGradleCacheCoordinateCandidate(coordinate) {
 function resolveRemoteBinaryCandidate(coordinate, repos) {
     return buildRemoteBinaryUrls(repos, coordinate);
 }
-function artifactIdForJar(inputKind, artifactPath, signature, suffix) {
-    return stableArtifactId([inputKind, artifactPath, signature, suffix ?? "source"]);
+function artifactIdForJar(inputKind, artifactPath, signature, suffix, mappingVariant = "pass") {
+    const parts = [inputKind, artifactPath, signature, suffix ?? "source"];
+    if (mappingVariant === "mojang-remapped") {
+        parts.push("mojang-remapped");
+    }
+    return stableArtifactId(parts);
 }
-function artifactIdForCoordinate(coordinate, source, signature) {
-    return stableArtifactId(["coord", coordinate, source, signature]);
+function artifactIdForCoordinate(coordinate, source, signature, mappingVariant = "pass") {
+    const parts = ["coord", coordinate, source, signature];
+    if (mappingVariant === "mojang-remapped") {
+        parts.push("mojang-remapped");
+    }
+    return stableArtifactId(parts);
 }
 function resolvedAtNow() {
     return new Date().toISOString();
@@ -191,7 +199,7 @@ export async function resolveSourceTarget(input, options, explicitConfig) {
             });
         }
         return {
-            artifactId: artifactIdForJar("jar", resolvedJarPath, `${binarySignature}:decompile`),
+            artifactId: artifactIdForJar("jar", resolvedJarPath, `${binarySignature}:decompile`, undefined, options.mappingVariant ?? "pass"),
             artifactSignature: `${binarySignature}:decompile`,
             origin: "decompiled",
             binaryJarPath: resolvedJarPath,
@@ -326,7 +334,7 @@ export async function resolveSourceTarget(input, options, explicitConfig) {
             }
             const signature = readStatsSignature(downloaded.path);
             return {
-                artifactId: artifactIdForCoordinate(coordinate, "decompiled", signature),
+                artifactId: artifactIdForCoordinate(coordinate, "decompiled", signature, options.mappingVariant ?? "pass"),
                 artifactSignature: signature,
                 origin: "decompiled",
                 binaryJarPath: downloaded.path,

package/dist/source-service.d.ts

@@ -18,9 +18,11 @@ export type ResolveArtifactInput = {
     scope?: ArtifactScope;
     preferProjectVersion?: boolean;
     strictVersion?: boolean;
+    compact?: boolean;
 };
 export type ResolveArtifactOutput = {
     artifactId: string;
+    artifactAlias: string;
     origin: "local-jar" | "local-m2" | "remote-repo" | "decompiled";
     isDecompiled: boolean;
     resolvedSourceJarPath?: string;
@@ -74,6 +76,8 @@ export type SearchClassSourceInput = {
     queryMode?: QueryMode;
     limit?: number;
     cursor?: string;
+    queryNamespace?: SourceMapping;
+    sourcePriority?: MappingSourcePriority;
 };
 export type SearchClassSourceOutput = {
     hits: SearchSourceHit[];
@@ -81,6 +85,13 @@ export type SearchClassSourceOutput = {
     mappingApplied: SourceMapping;
     returnedNamespace: SourceMapping;
     artifactContents: ArtifactContentsSummary;
+    translatedQuery?: {
+        original: string;
+        translated: string;
+        fromNamespace: SourceMapping;
+        toNamespace: SourceMapping;
+    };
+    warnings?: string[];
 };
 export type GetArtifactFileInput = {
     artifactId: string;
@@ -207,6 +218,17 @@ export type GetClassMembersInput = {
     preferProjectVersion?: boolean;
     strictVersion?: boolean;
 };
+export type DecompiledMember = {
+    name: string;
+    line: number;
+    kind: "constructor" | "field" | "method";
+};
+export type DecompiledFallback = {
+    constructors: DecompiledMember[];
+    fields: DecompiledMember[];
+    methods: DecompiledMember[];
+    origin: "source-extracted";
+};
 export type GetClassMembersOutput = {
     className: string;
     members: {
@@ -230,6 +252,13 @@ export type GetClassMembersOutput = {
     provenance: ArtifactProvenance;
     qualityFlags: string[];
     artifactContents: ArtifactContentsSummary;
+    decompiledFallback?: DecompiledFallback;
+    decompiledMemberCounts?: {
+        constructors: number;
+        fields: number;
+        methods: number;
+        total: number;
+    };
     warnings: string[];
 };
 export type TraceSymbolLifecycleInput = {
@@ -455,7 +484,12 @@ export declare class SourceService {
     private readonly versionDiffService;
     private readonly modDecompileService;
     private readonly modSearchService;
-    private cacheMetricsState;
+    private readonly lru;
+    private cacheTotalContentBytes;
+    private readonly remappedJarBytes;
+    /** In-flight binary-remap jobs keyed by remapped jar path so concurrent
+     * resolveArtifact calls for the same artifactId share a single tiny-remapper run. */
+    private readonly inflightRemaps;
     constructor(explicitConfig?: Config, metrics?: RuntimeMetrics);
     private discoverVersionSourceJar;
     private discoverAccessWidenerRuntimeCandidates;
@@ -464,6 +498,19 @@ export declare class SourceService {
     private resolveAccessTransformerNamespace;
     private resolveAccessTransformerRuntimeArtifact;
     private buildVersionSourceRecoveryCommand;
+    /**
+     * Decide whether the upcoming resolveArtifact call may transparently remap a
+     * binary-only artifact (obfuscated -> mojang) and decompile it. The gate
+     * succeeds only when:
+     *   - the requested mapping is "mojang" on a still-obfuscated runtime
+     *   - tiny-remapper jar is downloadable / available locally
+     *   - the version's Mojang tiny mapping file can be produced
+     *   - checkMappingHealth reports mojang mappings are usable
+     * On any failure the variant defaults to "pass" so the legacy
+     * MAPPING_NOT_APPLIED fallback (or the existing source-backed flow) keeps
+     * its existing artifactId hash.
+     */
+    private computeBinaryRemapGate;
     private buildArtifactContentsSummary;
     private inferVersionFromContext;
     private resolveVersionContext;
@@ -488,11 +535,14 @@ export declare class SourceService {
     findClass(input: FindClassInput): FindClassOutput;
     getClassSource(input: GetClassSourceInput): Promise<GetClassSourceOutput>;
     getClassMembers(input: GetClassMembersInput): Promise<GetClassMembersOutput>;
+    private buildDecompiledFallback;
     validateMixin(input: ValidateMixinInput): Promise<ValidateMixinOutput>;
+    private runValidateMixinDispatcher;
     private createProjectValidateMixinConfigInput;
     private shouldRetryValidateMixinWithMavenFirst;
     private findValidateMixinClassMapping;
     private validateMixinSingle;
+    private runValidateMixinPipeline;
     private resolveMixinInputPath;
     private resolveMixinConfigSources;
     private validateMixinMany;
@@ -500,6 +550,7 @@ export declare class SourceService {
     private buildValidateMixinOutput;
     validateAccessWidener(input: ValidateAccessWidenerInput): Promise<ValidateAccessWidenerOutput>;
     validateAccessTransformer(input: ValidateAccessTransformerInput): Promise<ValidateAccessTransformerOutput>;
+    recordToolCall(tool: string, durationMs: number): void;
     getRuntimeMetrics(): RuntimeMetricSnapshot;
     indexArtifact(input: IndexArtifactInput): Promise<IndexArtifactOutput>;
     private searchSymbolIntent;
@@ -511,6 +562,11 @@ export declare class SourceService {
     private indexedCandidateLimit;
     private indexedCandidateLimitForMatch;
     private extractClassMetadata;
+    private extractDecompiledMembers;
+    private computeLineBraceDepths;
+    private computeBraceRange;
+    private scanBraceRange;
+    private computeNestedTypeRanges;
     private resolveClassFilePath;
     private resolveBinaryFallbackArtifact;
     private buildProvenance;
@@ -529,13 +585,53 @@ export declare class SourceService {
     private buildRebuiltArtifactData;
     getArtifact(artifactId: string): ArtifactRow;
     private ingestIfNeeded;
+    /**
+     * If the resolved artifact's transformChain promised an "obf -> mojang"
+     * binary remap, run tiny-remapper now and return the remapped jar path.
+     * Otherwise return the original binaryJarPath unchanged.
+     *
+     * Cache safety: writes to a per-attempt temp file then atomic-renames into
+     * <cacheDir>/remapped/<artifactId>.jar. A per-target inflight Promise map
+     * collapses concurrent calls so two simultaneous resolveArtifact calls for
+     * the same artifactId share one tiny-remapper run instead of racing on the
+     * same output path.
+     */
+    private maybeRemapBinaryForMojang;
+    private recordRemappedJarBytesFromDisk;
+    /**
+     * Best-effort structural check that `path` is a non-empty file beginning with
+     * the ZIP local-file-header magic (`50 4B 03 04`). Used to drop partial /
+     * corrupt remap-cache entries before they reach Vineflower. False positives
+     * are acceptable (Vineflower will surface a clearer error); false negatives
+     * are not (a corrupt cache hit must be evicted).
+     */
+    private isUsableJarFile;
+    private runBinaryRemap;
     private loadFromSourceJar;
     private hasAnyFiles;
+    /**
+     * Best-effort cleanup of `<cacheDir>/remapped/<artifactId>.jar` written by
+     * `maybeRemapBinaryForMojang`. Called from cache-eviction paths so the
+     * Mojang-remapped binary jar does not outlive the artifact row that owns it.
+     * Also releases the jar's bytes from `cacheTotalContentBytes`. Errors are
+     * swallowed: orphaned jars remain visible to `manage-cache` under the
+     * `binary-remap` cache kind and can be reclaimed there.
+     */
+    private unlinkRemappedJarForArtifact;
+    /**
+     * Add the remapped jar's on-disk size to `cacheTotalContentBytes` so the
+     * `enforceCacheLimits` byte gate sees the jar before deciding to evict.
+     * Without this, a Mojang-remapped client jar (tens of MB) can accumulate
+     * silently while the indexed-source byte total stays below `maxCacheBytes`.
+     */
+    private recordRemappedJarBytes;
+    private releaseRemappedJarBytes;
     private enforceCacheLimits;
     private refreshCacheMetrics;
     private touchCacheMetrics;
     private upsertCacheMetrics;
     private removeCacheMetrics;
     private publishCacheMetrics;
+    private snapshotLruAccounting;
 }
 export {};