@adhisang/minecraft-modding-mcp 6.0.0 → 6.1.0

package/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project aims to follow [Semantic Versioning](https://semver.org/spec/v2
 
 ## [Unreleased]
 
+## [6.1.0] - 2026-06-28
+
+### Added
+
+- `get-class-members` / `batch-class-members` accept a `projection` parameter — `"names"` (member names only), `"signatures"` (name + `javaSignature`, no `jvmDescriptor`), or `"full"` (default; the complete member shape). Use the leaner projections to cut response tokens for "does this member exist?" / signature-only checks. Default `"full"` output is unchanged.
+
+### Changed
+
+- `get-class-source` responses for a decompiled artifact now carry a `decompiled-source-signatures-unverified` quality flag and a warning that decompiled method/accessor names may differ from the jar the workspace actually compiles against (e.g. a decompiled `getGameRenderState()` vs the runtime `gameRenderState()`); confirm signatures with `get-class-members` (bytecode-derived) before copying names from the source.
+- Inspecting a Fabric / loader dependency class like vanilla is documented and surfaced: the `target` descriptions, `dependency` target fields, the `get-class-source` / `get-class-members` target-shape error guidance, and `docs/tool-reference.md` now show passing `target: { kind: "dependency", group, name, versionFromProject }` straight to the class tools (no separate lookup tool needed).
+
+### Fixed
+
+- `memberPattern` (`get-class-members` / `batch-class-members`) treats `"|"` as OR alternation, so a natural pattern like `"getStateForPlacement|canSurvive|setPlacedBy"` matches any of those members. Previously the pattern was matched as a single literal substring, so a piped pattern searched for a name containing a literal `"|"` and returned zero members on large vanilla classes such as `Block` and `EntityRenderer`. Single-token patterns keep their case-insensitive substring behavior. The parameter description now documents the substring + OR semantics.
+
+### Performance
+
+- `validate-project` (`project-summary`) validates discovered mixin configs with bounded concurrency (default 4) instead of one at a time; aggregate counts and warning order are identical to the previous sequential behavior.
+
 ## [6.0.0] - 2026-06-25
 
 ### Changed

package/dist/config.js

@@ -211,7 +211,7 @@ function aliasJarBase(jarPath) {
 // to earlier callers. Two distinct artifactIds whose readable tokens collide and
 // whose first 48 hash bits also collide would trip the schema-v4 alias UNIQUE
 // constraint at upsert time — a hard error, not silent drift.
-// Phase 3.1a: display-only. Phase 3.1b stores it for lookup.
+// Currently display-only; a later change stores it for lookup.
 export function buildArtifactAlias(input) {
     const tokens = [];
     if (input.kind === "version") {

package/dist/entry-tools/batch-class-members-service.d.ts

@@ -1,6 +1,7 @@
 import { type ResponseDetailLevel } from "../response-utils.js";
 import type { GetClassMembersInput, GetClassMembersOutput, ResolveArtifactInput, ResolveArtifactOutput } from "../source-service.js";
 import type { ArtifactScope, MappingSourcePriority, ResolveArtifactTargetInput, SourceMapping } from "../types.js";
+import type { MemberProjection } from "../source/class-source/members-builder.js";
 import { type BatchOutput } from "./batch-runner.js";
 export type BatchClassMembersDeps = {
     resolveArtifact: (input: ResolveArtifactInput) => Promise<ResolveArtifactOutput>;
@@ -27,6 +28,7 @@ export type BatchClassMembersInput = {
     concurrency?: number;
     failFast?: boolean;
     detail?: ResponseDetailLevel;
+    projection?: MemberProjection;
     include?: readonly string[];
     entries: readonly BatchClassMembersEntry[];
 };

package/dist/entry-tools/batch-class-members-service.js

@@ -54,6 +54,7 @@ export class BatchClassMembersService {
                     includeInherited: entry.includeInherited,
                     memberPattern: entry.memberPattern,
                     maxMembers: entry.maxMembers,
+                    projection: input.projection,
                     includeDescriptors: include.has("descriptors"),
                     mapping: input.mapping,
                     sourcePriority: input.sourcePriority,

package/dist/entry-tools/validate-project/cases/project-summary.js

@@ -1,4 +1,5 @@
 import { readFile } from "node:fs/promises";
+import { mapWithConcurrencyLimit } from "../../../concurrency.js";
 import { buildEntryToolResult, createSummarySubject } from "../../response-contract.js";
 import { ERROR_CODES, createError } from "../../../errors.js";
 import { buildEarlyTasksForBlocked, buildFullTaskStatusReport } from "../internal.js";
@@ -199,7 +200,14 @@ export async function handleProjectSummary(deps, input, detail, include, options
     await safeEmit(options.stageEmitter, "validate-project:mixin-validation", {
         targetTotal: mixinConfigs.length
     });
-    for (const [mixinIndex, configPath] of mixinConfigs.entries()) {
+    // Validate mixin configs with bounded concurrency (default 4, matching the
+    // batch tools). Each unit returns its own counts/warnings; aggregation happens
+    // afterward in input order so totals and warning order are identical to a
+    // sequential run. Concurrent validateMixin against one SourceService is already
+    // exercised by the batch-class-* tools (shared artifact resolution, idempotent
+    // caches, synchronous SQLite), so this adds no new shared-state hazard.
+    const MIXIN_VALIDATION_CONCURRENCY = 4;
+    const mixinResults = await mapWithConcurrencyLimit(mixinConfigs, MIXIN_VALIDATION_CONCURRENCY, async (configPath, mixinIndex) => {
         try {
             await safeEmit(options.stageEmitter, "validate-project:mixin-validation", {
                 targetIndex: mixinIndex + 1,
@@ -232,20 +240,30 @@ export async function handleProjectSummary(deps, input, detail, include, options
                 stageEmitter: wrappedEmitter
             });
             const summary = mixinResult.summary;
-            validMixins += summary?.valid ?? 0;
-            partialMixins += summary?.partial ?? 0;
-            invalidMixins += summary?.invalid ?? 0;
-            if (Array.isArray(mixinResult.warnings)) {
-                warnings.push(...mixinResult.warnings);
-            }
+            return {
+                valid: summary?.valid ?? 0,
+                partial: summary?.partial ?? 0,
+                invalid: summary?.invalid ?? 0,
+                caught: 0,
+                warnings: Array.isArray(mixinResult.warnings) ? [...mixinResult.warnings] : []
+            };
         }
         catch (error) {
-            invalidMixins += 1;
-            mixinCaughtErrors += 1;
-            if (error instanceof Error) {
-                warnings.push(`${configPath}: ${error.message}`);
-            }
+            return {
+                valid: 0,
+                partial: 0,
+                invalid: 1,
+                caught: 1,
+                warnings: error instanceof Error ? [`${configPath}: ${error.message}`] : []
+            };
         }
+    });
+    for (const result of mixinResults) {
+        validMixins += result.valid;
+        partialMixins += result.partial;
+        invalidMixins += result.invalid;
+        mixinCaughtErrors += result.caught;
+        warnings.push(...result.warnings);
     }
     const mixinDurationMs = Date.now() - mixinDurationStart;
     const awDurationStart = Date.now();

package/dist/index.js

@@ -573,6 +573,7 @@ expertTool("get-class-members", "Get fields/methods/constructors for one class f
         includeInherited: input.includeInherited,
         memberPattern: input.memberPattern,
         maxMembers: input.maxMembers,
+        projection: input.projection,
         cursor: input.cursor,
         projectPath: input.projectPath,
         gradleUserHome: input.gradleUserHome,

package/dist/mapping-service.js

@@ -581,7 +581,7 @@ export class MappingService {
         const nextCursor = rowsTruncated ? encodeOffsetCursor(consumedRows, rowCursorContext) : undefined;
         // Map ONLY the requested window. Per-row mapping cost is therefore O(window),
         // not O(rowCount). warnings/ambiguousRowCount are accordingly page-scoped on
-        // paginated calls (caveat B1) and byte-identical to the old full-set values when
+        // paginated calls and byte-identical to the old full-set values when
         // no maxRows/cursor narrows the window.
         const rows = [];
         let ambiguousRowCount = 0;

package/dist/minecraft-explorer-service.js

@@ -2,6 +2,7 @@ import { createError, ERROR_CODES } from "./errors.js";
 import { loadConfig } from "./config.js";
 import { artifactSignatureFromFile, normalizeJarPath } from "./path-resolver.js";
 import { createJarEntryReader } from "./source-jar-reader.js";
+import { matchesMemberPattern } from "./source/member-pattern.js";
 const CLASSFILE_MAGIC = 0xcafebabe;
 const MAX_INHERITANCE_DEPTH = 64;
 const ACC_PUBLIC = 0x0001;
@@ -603,7 +604,7 @@ export class MinecraftExplorerService {
             if (access === "public" && !hasPublicVisibility(member.accessFlags)) {
                 return false;
             }
-            if (memberPattern && !lower(member.name).includes(memberPattern)) {
+            if (memberPattern && !matchesMemberPattern(member.name, memberPattern)) {
                 return false;
             }
             return true;

package/dist/source/class-source/members-builder.d.ts

@@ -76,3 +76,29 @@ export declare function projectMembersForWire(slice: {
     fields: SignatureMember[];
     methods: SignatureMember[];
 }, includeInherited: boolean, keepFieldDescriptors?: boolean): WireMembersBlock;
+/**
+ * Token-projection level for a member listing, narrowing the per-member fields
+ * an agent receives:
+ * - `full` (default): the complete {@link WireMember} shape (current behavior).
+ * - `signatures`: name + javaSignature (drops jvmDescriptor) — enough to read
+ *   the API without overload descriptors.
+ * - `names`: member name only — enough for an "does this member exist?" check.
+ * The block-level hoisted `ownerFqn` and any per-member `ownerFqn` (the
+ * multi-owner / includeInherited case) are preserved in every level so members
+ * stay attributable.
+ */
+export type MemberProjection = "names" | "signatures" | "full";
+export type ProjectedMember = {
+    name: string;
+    javaSignature?: string;
+    jvmDescriptor?: string;
+    ownerFqn?: string;
+    isSynthetic?: boolean;
+};
+export type ProjectedMembersBlock = {
+    ownerFqn?: string;
+    constructors: ProjectedMember[];
+    fields: ProjectedMember[];
+    methods: ProjectedMember[];
+};
+export declare function projectMembersByLevel(block: WireMembersBlock, level: MemberProjection): ProjectedMembersBlock;

package/dist/source/class-source/members-builder.js

@@ -1,3 +1,4 @@
+import { matchesMemberPattern } from "../member-pattern.js";
 export async function remapAndCountMembers(svc, input) {
     const remap = async (members, kind) => {
         if (input.version == null) {
@@ -10,10 +11,10 @@ export async function remapAndCountMembers(svc, input) {
     let fields = await remap(input.signatureFields, "field");
     let methods = await remap(input.signatureMethods, "method");
     if (input.requestedMapping !== input.mappingApplied && input.memberPattern) {
-        const lowerPattern = input.memberPattern.toLowerCase();
-        constructors = constructors.filter((m) => m.name.toLowerCase().includes(lowerPattern));
-        fields = fields.filter((m) => m.name.toLowerCase().includes(lowerPattern));
-        methods = methods.filter((m) => m.name.toLowerCase().includes(lowerPattern));
+        const pattern = input.memberPattern;
+        constructors = constructors.filter((m) => matchesMemberPattern(m.name, pattern));
+        fields = fields.filter((m) => matchesMemberPattern(m.name, pattern));
+        methods = methods.filter((m) => matchesMemberPattern(m.name, pattern));
     }
     const counts = {
         constructors: constructors.length,
@@ -90,4 +91,30 @@ export function projectMembersForWire(slice, includeInherited, keepFieldDescript
         methods: slice.methods.map((m) => toWire(m, true))
     };
 }
+export function projectMembersByLevel(block, level) {
+    if (level === "full") {
+        return block;
+    }
+    const reduce = (m) => {
+        if (level === "names") {
+            return {
+                name: m.name,
+                ...(m.ownerFqn ? { ownerFqn: m.ownerFqn } : {})
+            };
+        }
+        // "signatures": keep the readable signature, drop the JVM descriptor.
+        return {
+            name: m.name,
+            javaSignature: m.javaSignature,
+            ...(m.ownerFqn ? { ownerFqn: m.ownerFqn } : {}),
+            ...(m.isSynthetic ? { isSynthetic: true } : {})
+        };
+    };
+    return {
+        ...(block.ownerFqn ? { ownerFqn: block.ownerFqn } : {}),
+        constructors: block.constructors.map(reduce),
+        fields: block.fields.map(reduce),
+        methods: block.methods.map(reduce)
+    };
+}
 //# sourceMappingURL=members-builder.js.map

package/dist/source/class-source.js

@@ -5,7 +5,8 @@ import { ERROR_CODES, createError, isAppError } from "../errors.js";
 import * as artifactResolver from "./artifact-resolver.js";
 import * as classSourceHelpers from "./class-source-helpers.js";
 import { buildClassSourceSnippet } from "./class-source/snippet-builder.js";
-import { remapAndCountMembers, sliceMembersWithLimit, projectMembersForWire } from "./class-source/members-builder.js";
+import { remapAndCountMembers, sliceMembersWithLimit, projectMembersForWire, projectMembersByLevel } from "./class-source/members-builder.js";
+import { matchesMemberPattern } from "./member-pattern.js";
 import { buildPageContextKey, encodeOffsetCursor, resolveCursorOffset } from "../page-cursor.js";
 import { dedupeQualityFlags, normalizeMapping, normalizeOptionalString, normalizePathStyle } from "./shared-utils.js";
 import { isUnobfuscatedVersion } from "../version-service.js";
@@ -239,8 +240,7 @@ export function buildDecompiledFallback(svc, artifactId, lookupClassName, member
         if (!memberPattern) {
             return list;
         }
-        const lower = memberPattern.toLowerCase();
-        return list.filter((entry) => entry.name.toLowerCase().includes(lower));
+        return list.filter((entry) => matchesMemberPattern(entry.name, memberPattern));
     };
     let constructors = filterByPattern(extracted.constructors);
     let fields = filterByPattern(extracted.fields);
@@ -280,6 +280,25 @@ export function buildDecompiledFallback(svc, artifactId, lookupClassName, member
         truncated: totalBefore > maxMembers
     };
 }
+/**
+ * Apply a member projection to the decompiled fallback so it honors the same
+ * `projection` contract as the bytecode members block. The fallback only carries
+ * names + source line + kind (no signatures), so any non-"full" level reduces to
+ * the member name (the array it lives in already conveys the kind). Keeps the
+ * full shape for the default "full" level.
+ */
+function projectDecompiledFallback(fallback, level) {
+    if (level === "full") {
+        return fallback;
+    }
+    const reduce = (member) => ({ name: member.name });
+    return {
+        constructors: fallback.constructors.map(reduce),
+        fields: fallback.fields.map(reduce),
+        methods: fallback.methods.map(reduce),
+        origin: fallback.origin
+    };
+}
 // The class-like symbol kinds findClass returns. MUST stay in sync with the JS-side
 // isTypeSymbol checks below; pushed down to SQL so non-type rows are never fetched.
 const TYPE_SYMBOL_KINDS = ["class", "interface", "enum", "record"];
@@ -652,6 +671,20 @@ export async function getClassSource(svc, input) {
             }
         })
         : undefined;
+    // Decompiled source text can use different method/accessor names than the jar
+    // the workspace actually compiles against (e.g. `getGameRenderState()` in the
+    // decompiled source vs `gameRenderState()` in the runtime jar). Flag it so
+    // callers verify names against get-class-members (bytecode-derived) before
+    // copying signatures out of this source.
+    if (activeOrigin === "decompiled") {
+        activeQualityFlags = dedupeQualityFlags([
+            ...activeQualityFlags,
+            "decompiled-source-signatures-unverified"
+        ]);
+        warnings.push("Source is decompiled: method/accessor names may differ from the jar the workspace "
+            + "compiles against. Confirm signatures with get-class-members (bytecode-derived) "
+            + "before copying names from this source.");
+    }
     return {
         className,
         mode,
@@ -889,7 +922,8 @@ export async function getClassMembers(svc, input) {
     // Slim the wire member shape: hoist a shared ownerFqn, drop accessFlags, omit
     // isSynthetic:false, and drop FIELD jvmDescriptor unless includeDescriptors.
     // Internal SignatureMember arrays above stay intact.
-    const projectedMembers = projectMembersForWire({ constructors, fields, methods }, includeInherited, input.includeDescriptors ?? false);
+    const projection = input.projection ?? "full";
+    const projectedMembers = projectMembersByLevel(projectMembersForWire({ constructors, fields, methods }, includeInherited, input.includeDescriptors ?? false), projection);
     const truncated = sliced.truncated;
     const nextCursor = sliced.nextOffset != null ? encodeOffsetCursor(sliced.nextOffset, memberCursorContext) : undefined;
     const normalizedProvenance = provenance ??
@@ -907,7 +941,7 @@ export async function getClassMembers(svc, input) {
         const fallbackPattern = namespaceMismatch ? undefined : memberPattern;
         const sourceFallback = buildDecompiledFallback(svc, artifactId, lookupClassName, fallbackPattern, maxMembers);
         if (sourceFallback) {
-            decompiledFallback = sourceFallback.fallback;
+            decompiledFallback = projectDecompiledFallback(sourceFallback.fallback, projection);
             decompiledMemberCounts = sourceFallback.counts;
             fallbackQualityFlags = dedupeQualityFlags([
                 ...qualityFlags,

package/dist/source/indexer.js

@@ -213,7 +213,7 @@ export async function buildRebuiltArtifactData(svc, resolved) {
                 // Decompilation failed BEFORE the artifact was ever upserted, so there is no
                 // queryable artifact. Deliberately omit artifactId from the error: exposing the
                 // would-be id led callers to pass it to find-class/get-class-*, which then failed
-                // with "Artifact not found. Resolve context first." (B5 state inconsistency).
+                // with "Artifact not found. Resolve context first." — a state inconsistency.
                 const priorDetails = { ...(caughtError.details ?? {}) };
                 delete priorDetails.artifactId;
                 throw createError({

package/dist/source/member-pattern.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Match a class-member name against a `memberPattern` filter.
+ *
+ * Matching is case-insensitive substring. A `|` splits the pattern into OR
+ * alternatives, so `"getStateForPlacement|canSurvive|setPlacedBy"` matches a
+ * name that contains ANY of those tokens. Before this, the pattern was matched
+ * as a single literal substring, so a piped pattern searched for a name
+ * containing a literal `|` and matched nothing — which made member listing
+ * return zero on large vanilla classes when callers used the natural OR syntax.
+ *
+ * Java member names never contain `|`, so treating `|` as OR never collides with
+ * a legitimate substring search. Empty or whitespace-only alternatives are
+ * dropped; a pattern with no usable alternative matches nothing (a non-empty
+ * filter that excludes everything), matching the prior empty-filter behavior.
+ */
+export declare function matchesMemberPattern(name: string, pattern: string): boolean;

package/dist/source/member-pattern.js

@@ -0,0 +1,27 @@
+/**
+ * Match a class-member name against a `memberPattern` filter.
+ *
+ * Matching is case-insensitive substring. A `|` splits the pattern into OR
+ * alternatives, so `"getStateForPlacement|canSurvive|setPlacedBy"` matches a
+ * name that contains ANY of those tokens. Before this, the pattern was matched
+ * as a single literal substring, so a piped pattern searched for a name
+ * containing a literal `|` and matched nothing — which made member listing
+ * return zero on large vanilla classes when callers used the natural OR syntax.
+ *
+ * Java member names never contain `|`, so treating `|` as OR never collides with
+ * a legitimate substring search. Empty or whitespace-only alternatives are
+ * dropped; a pattern with no usable alternative matches nothing (a non-empty
+ * filter that excludes everything), matching the prior empty-filter behavior.
+ */
+export function matchesMemberPattern(name, pattern) {
+    const alternatives = pattern
+        .split("|")
+        .map((part) => part.trim().toLowerCase())
+        .filter((part) => part.length > 0);
+    if (alternatives.length === 0) {
+        return false;
+    }
+    const lowerName = name.toLowerCase();
+    return alternatives.some((alt) => lowerName.includes(alt));
+}
+//# sourceMappingURL=member-pattern.js.map

package/dist/source-service.d.ts

@@ -11,7 +11,7 @@ import * as indexer from "./source/indexer.js";
 import * as workspaceTarget from "./source/workspace-target.js";
 import * as validateMixinModule from "./source/validate-mixin.js";
 import * as artifactResolver from "./source/artifact-resolver.js";
-import type { WireMembersBlock } from "./source/class-source/members-builder.js";
+import type { MemberProjection, ProjectedMembersBlock } from "./source/class-source/members-builder.js";
 import { type StageEmitter } from "./stage-emitter.js";
 import { WorkspaceMappingService, type WorkspaceCompileMappingOutput } from "./workspace-mapping-service.js";
 import { type WorkspaceContextCache } from "./workspace-context-cache.js";
@@ -266,11 +266,15 @@ export type GetClassMembersInput = {
     strictVersion?: boolean;
     /** When true, keep jvmDescriptor on FIELD members (always kept on methods/constructors). */
     includeDescriptors?: boolean;
+    /** Narrow the per-member fields returned: "names" | "signatures" | "full" (default "full"). */
+    projection?: MemberProjection;
 };
 export type DecompiledMember = {
     name: string;
-    line: number;
-    kind: "constructor" | "field" | "method";
+    /** Source line of the declaration. Omitted under a non-"full" projection. */
+    line?: number;
+    /** Member kind. Omitted under a non-"full" projection (the array conveys it). */
+    kind?: "constructor" | "field" | "method";
 };
 export type DecompiledFallback = {
     constructors: DecompiledMember[];
@@ -281,7 +285,7 @@ export type DecompiledFallback = {
 export type GetClassMembersStatus = "ok" | "members_unavailable" | "partial";
 export type GetClassMembersOutput = {
     className: string;
-    members: WireMembersBlock;
+    members: ProjectedMembersBlock;
     counts: {
         constructors: number;
         fields: number;

package/dist/source-service.js

@@ -146,7 +146,7 @@ export class SourceService {
         // 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 (B1). Treat `not_found` methods as fallback-eligible.
+        // methods that genuinely exist. Treat `not_found` methods as fallback-eligible.
         const fallbackEligible = result.status === "mapping_unavailable" ||
             (result.status === "not_found" && input.kind === "method");
         if (!fallbackEligible ||

package/dist/tool-guidance.js

@@ -672,7 +672,7 @@ export function buildInvalidInputGuidance(tool, normalizedInput) {
     }
     if (tool === "get-class-source" || tool === "get-class-members") {
         return gatedGuidance(tool, [
-            `${tool}.target must be an object: {"kind":"version|jar|coordinate","value":"..."} or {"kind":"artifact","artifactId":"..."} (same shape as resolve-artifact).`,
+            `${tool}.target must be an object: {"kind":"version|jar|coordinate","value":"..."}, {"kind":"workspace"}, {"kind":"dependency","group":"...","name":"...","versionFromProject":true} (inspect a Fabric/loader dependency like vanilla), or {"kind":"artifact","artifactId":"..."} (same shape as resolve-artifact).`,
             "Bare string targets are not accepted; wrap the value under target.kind/target.value."
         ], buildSourceLookupSuggestedParams(tool, normalizedInput));
     }

package/dist/tool-schemas.d.ts

@@ -211,9 +211,12 @@ export declare const sourceLookupTargetSchema: z.ZodDiscriminatedUnion<"kind", [
     kind: "artifact";
     artifactId: string;
 }>]>;
-export declare const RESOLVE_ARTIFACT_TARGET_DESCRIPTION = "Object, not string. e.g. {\"kind\":\"version\",\"value\":\"1.21.10\"}, {\"kind\":\"workspace\"}, {\"kind\":\"dependency\",\"group\":\"g\",\"name\":\"n\"}.";
-export declare const SOURCE_LOOKUP_TARGET_DESCRIPTION = "Same shape as resolve-artifact target, plus {\"kind\":\"artifact\",\"artifactId\":\"...\"} to reuse a resolved artifact. Object, not string.";
+export declare const RESOLVE_ARTIFACT_TARGET_DESCRIPTION = "Object, not string. e.g. {\"kind\":\"version\",\"value\":\"1.21.10\"}, {\"kind\":\"workspace\"}, or to inspect a loader/Fabric dependency like vanilla: {\"kind\":\"dependency\",\"group\":\"net.fabricmc.fabric-api\",\"name\":\"fabric-api\",\"versionFromProject\":true} (needs projectPath) or with an explicit \"version\".";
+export declare const SOURCE_LOOKUP_TARGET_DESCRIPTION = "Same shape as resolve-artifact target (incl. {\"kind\":\"dependency\",...} to read a Fabric/loader dependency class like vanilla), plus {\"kind\":\"artifact\",\"artifactId\":\"...\"} to reuse a resolved artifact. Object, not string.";
 export declare const SOURCE_SCOPE_DESCRIPTION = "vanilla = Mojang client jar only; merged = merged runtime discovery; loader = loader-transformed runtime jars.";
+export declare const MEMBER_PATTERN_DESCRIPTION = "Case-insensitive substring filter on member names. Use \"|\" for OR alternatives, e.g. \"getStateForPlacement|canSurvive|setPlacedBy\" (each token is matched as a substring, not a regex).";
+export declare const memberProjectionSchema: z.ZodEnum<["names", "signatures", "full"]>;
+export declare const MEMBER_PROJECTION_DESCRIPTION = "Per-member field projection: \"names\" (member name only), \"signatures\" (name + javaSignature, no jvmDescriptor), or \"full\" (default; complete member shape). Use \"names\"/\"signatures\" to cut response tokens for existence/signature checks.";
 export declare const SIGNATURE_MODE_DESCRIPTION = "exact: descriptor required for kind=method; name-only (default): match by owner+name only.";
 export declare const NAME_MODE_DESCRIPTION = "auto (default): FQCN, or dotless name where allowed; fqcn: require FQCN.";
 export declare const listVersionsShape: {
@@ -850,6 +853,7 @@ export declare const getClassMembersShape: {
     includeSynthetic: z.ZodDefault<z.ZodBoolean>;
     includeInherited: z.ZodDefault<z.ZodBoolean>;
     memberPattern: z.ZodOptional<z.ZodString>;
+    projection: z.ZodOptional<z.ZodEnum<["names", "signatures", "full"]>>;
     maxMembers: z.ZodOptional<z.ZodNumber>;
     cursor: z.ZodOptional<z.ZodString>;
     projectPath: z.ZodOptional<z.ZodString>;
@@ -938,6 +942,7 @@ export declare const getClassMembersSchema: z.ZodObject<{
     includeSynthetic: z.ZodDefault<z.ZodBoolean>;
     includeInherited: z.ZodDefault<z.ZodBoolean>;
     memberPattern: z.ZodOptional<z.ZodString>;
+    projection: z.ZodOptional<z.ZodEnum<["names", "signatures", "full"]>>;
     maxMembers: z.ZodOptional<z.ZodNumber>;
     cursor: z.ZodOptional<z.ZodString>;
     projectPath: z.ZodOptional<z.ZodString>;
@@ -992,6 +997,7 @@ export declare const getClassMembersSchema: z.ZodObject<{
     memberPattern?: string | undefined;
     include?: ("entries" | "workspace" | "warnings" | "source" | "registry" | "preview" | "files" | "samples" | "timings" | "issues" | "recovery" | "paths" | "members" | "provenance" | "artifact" | "candidates" | "classes" | "timeline" | "descriptors" | "diff" | "matrix" | "health" | "owners" | "cacheEntries")[] | undefined;
     gradleUserHome?: string | undefined;
+    projection?: "full" | "names" | "signatures" | undefined;
 }, {
     className: string;
     target: {
@@ -1034,6 +1040,7 @@ export declare const getClassMembersSchema: z.ZodObject<{
     include?: ("entries" | "workspace" | "warnings" | "source" | "registry" | "preview" | "files" | "samples" | "timings" | "issues" | "recovery" | "paths" | "members" | "provenance" | "artifact" | "candidates" | "classes" | "timeline" | "descriptors" | "diff" | "matrix" | "health" | "owners" | "cacheEntries")[] | undefined;
     gradleUserHome?: string | undefined;
     includeProvenance?: boolean | undefined;
+    projection?: "full" | "names" | "signatures" | undefined;
     includeDescriptors?: boolean | undefined;
 }>;
 export declare const verifyMixinTargetMemberSchema: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
@@ -1811,6 +1818,7 @@ export declare const batchClassMembersShape: {
     concurrency: z.ZodOptional<z.ZodNumber>;
     failFast: z.ZodOptional<z.ZodBoolean>;
     detail: z.ZodDefault<z.ZodEnum<["summary", "standard", "full"]>>;
+    projection: z.ZodOptional<z.ZodEnum<["names", "signatures", "full"]>>;
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<["warnings", "provenance", "candidates", "members", "descriptors", "source", "files", "samples", "diff", "issues", "timeline", "matrix", "entries", "workspace", "health", "recovery", "paths", "owners", "preview", "cacheEntries", "timings", "artifact", "classes", "registry"]>, "many">>;
     entries: z.ZodArray<z.ZodObject<{
         className: z.ZodString;
@@ -1905,6 +1913,7 @@ export declare const batchClassMembersSchema: z.ZodObject<{
     concurrency: z.ZodOptional<z.ZodNumber>;
     failFast: z.ZodOptional<z.ZodBoolean>;
     detail: z.ZodDefault<z.ZodEnum<["summary", "standard", "full"]>>;
+    projection: z.ZodOptional<z.ZodEnum<["names", "signatures", "full"]>>;
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<["warnings", "provenance", "candidates", "members", "descriptors", "source", "files", "samples", "diff", "issues", "timeline", "matrix", "entries", "workspace", "health", "recovery", "paths", "owners", "preview", "cacheEntries", "timings", "artifact", "classes", "registry"]>, "many">>;
     entries: z.ZodArray<z.ZodObject<{
         className: z.ZodString;
@@ -1967,6 +1976,7 @@ export declare const batchClassMembersSchema: z.ZodObject<{
     sourcePriority?: "loom-first" | "maven-first" | undefined;
     include?: ("entries" | "workspace" | "warnings" | "source" | "registry" | "preview" | "files" | "samples" | "timings" | "issues" | "recovery" | "paths" | "members" | "provenance" | "artifact" | "candidates" | "classes" | "timeline" | "descriptors" | "diff" | "matrix" | "health" | "owners" | "cacheEntries")[] | undefined;
     gradleUserHome?: string | undefined;
+    projection?: "full" | "names" | "signatures" | undefined;
     concurrency?: number | undefined;
     failFast?: boolean | undefined;
 }, {
@@ -2008,6 +2018,7 @@ export declare const batchClassMembersSchema: z.ZodObject<{
     detail?: "summary" | "standard" | "full" | undefined;
     include?: ("entries" | "workspace" | "warnings" | "source" | "registry" | "preview" | "files" | "samples" | "timings" | "issues" | "recovery" | "paths" | "members" | "provenance" | "artifact" | "candidates" | "classes" | "timeline" | "descriptors" | "diff" | "matrix" | "health" | "owners" | "cacheEntries")[] | undefined;
     gradleUserHome?: string | undefined;
+    projection?: "full" | "names" | "signatures" | undefined;
     concurrency?: number | undefined;
     failFast?: boolean | undefined;
 }>;

package/dist/tool-schemas.js

@@ -64,10 +64,10 @@ export const workspaceTargetSchema = z.object({
 });
 export const dependencyTargetSchema = z.object({
     kind: z.literal("dependency"),
-    group: nonEmptyString,
-    name: nonEmptyString,
-    version: z.string().trim().min(1).optional(),
-    versionFromProject: z.boolean().optional()
+    group: nonEmptyString.describe('Maven group, e.g. "net.fabricmc.fabric-api" or "dev.architectury".'),
+    name: nonEmptyString.describe('Maven artifact name, e.g. "fabric-api" or "architectury".'),
+    version: z.string().trim().min(1).optional().describe("Explicit version; omit and set versionFromProject to resolve it from the workspace."),
+    versionFromProject: z.boolean().optional().describe("Resolve the version from the project's gradle.properties / gradle cache (requires projectPath).")
 });
 export const resolveArtifactTargetSchema = z.discriminatedUnion("kind", [
     z.object({ kind: z.literal("version"), value: nonEmptyString }),
@@ -89,11 +89,14 @@ export const sourceLookupTargetSchema = z.discriminatedUnion("kind", [
     dependencyTargetSchema,
     z.object({ kind: z.literal("artifact"), artifactId: nonEmptyString })
 ]);
-export const RESOLVE_ARTIFACT_TARGET_DESCRIPTION = 'Object, not string. e.g. {"kind":"version","value":"1.21.10"}, {"kind":"workspace"}, {"kind":"dependency","group":"g","name":"n"}.';
-export const SOURCE_LOOKUP_TARGET_DESCRIPTION = 'Same shape as resolve-artifact target, plus {"kind":"artifact","artifactId":"..."} to reuse a resolved artifact. Object, not string.';
+export const RESOLVE_ARTIFACT_TARGET_DESCRIPTION = 'Object, not string. e.g. {"kind":"version","value":"1.21.10"}, {"kind":"workspace"}, or to inspect a loader/Fabric dependency like vanilla: {"kind":"dependency","group":"net.fabricmc.fabric-api","name":"fabric-api","versionFromProject":true} (needs projectPath) or with an explicit "version".';
+export const SOURCE_LOOKUP_TARGET_DESCRIPTION = 'Same shape as resolve-artifact target (incl. {"kind":"dependency",...} to read a Fabric/loader dependency class like vanilla), plus {"kind":"artifact","artifactId":"..."} to reuse a resolved artifact. Object, not string.';
 export const SOURCE_SCOPE_DESCRIPTION = "vanilla = Mojang client jar only; merged = merged runtime discovery; loader = loader-transformed runtime jars.";
 // Shared describe() text reused by every symbol-lookup tool so the contract reads
 // identically on find-mapping and check-symbol-exists (and any future sibling).
+export const MEMBER_PATTERN_DESCRIPTION = 'Case-insensitive substring filter on member names. Use "|" for OR alternatives, e.g. "getStateForPlacement|canSurvive|setPlacedBy" (each token is matched as a substring, not a regex).';
+export const memberProjectionSchema = z.enum(["names", "signatures", "full"]);
+export const MEMBER_PROJECTION_DESCRIPTION = 'Per-member field projection: "names" (member name only), "signatures" (name + javaSignature, no jvmDescriptor), or "full" (default; complete member shape). Use "names"/"signatures" to cut response tokens for existence/signature checks.';
 export const SIGNATURE_MODE_DESCRIPTION = "exact: descriptor required for kind=method; name-only (default): match by owner+name only.";
 export const NAME_MODE_DESCRIPTION = "auto (default): FQCN, or dotless name where allowed; fqcn: require FQCN.";
 export const listVersionsShape = {
@@ -158,7 +161,8 @@ export const getClassMembersShape = {
     access: memberAccessSchema.default("public"),
     includeSynthetic: z.boolean().default(false),
     includeInherited: z.boolean().default(false),
-    memberPattern: optionalNonEmptyString,
+    memberPattern: optionalNonEmptyString.describe(MEMBER_PATTERN_DESCRIPTION),
+    projection: memberProjectionSchema.optional().describe(MEMBER_PROJECTION_DESCRIPTION),
     maxMembers: optionalPositiveInt.describe("default 150, max 5000. Page beyond the first 150 with cursor."),
     cursor: optionalNonEmptyString.describe("nextCursor from the previous response."),
     projectPath: optionalNonEmptyString,
@@ -262,7 +266,7 @@ export const batchClassMembersEntrySchema = z.object({
     access: memberAccessSchema.optional(),
     includeSynthetic: z.boolean().optional(),
     includeInherited: z.boolean().optional(),
-    memberPattern: optionalNonEmptyString,
+    memberPattern: optionalNonEmptyString.describe(MEMBER_PATTERN_DESCRIPTION),
     maxMembers: optionalPositiveInt
 });
 export const batchClassMembersShape = {
@@ -278,6 +282,7 @@ export const batchClassMembersShape = {
     concurrency: z.number().int().min(1).max(8).optional(),
     failFast: z.boolean().optional(),
     detail: detailParam("summary"),
+    projection: memberProjectionSchema.optional().describe(MEMBER_PROJECTION_DESCRIPTION),
     include: responseIncludeParam,
     entries: z.array(batchClassMembersEntrySchema).min(1).max(50)
 };

package/docs/tool-reference.md

@@ -67,6 +67,29 @@ Start here when you are not sure which tool to reach for. In every row, the left
 | `{ kind: "workspace", scope?, strict? }` | When the caller already passes a `projectPath` and wants the tool to detect Minecraft version, compile mapping, and loader from `gradle.properties` and `build.gradle(.kts)`. | `projectPath` | Synthesised to `{ kind: "version", value: <detected> }`. Scope precedence is `target.scope` → top-level `scope` → loader-derived default (`"merged"` when a loader is detected, `"vanilla"` otherwise). When the version is not detected, raises `ERR_WORKSPACE_VERSION_UNRESOLVED` regardless of `strict`. Detected facts surface on `provenance.workspaceResolution`. |
 | `{ kind: "dependency", group, name, version?, versionFromProject? }` | When the caller wants to resolve a Maven-coordinate dependency (e.g. `dev.architectury:architectury`) without computing the exact version themselves. | `projectPath` (unless `version` is given) | Synthesised to `{ kind: "coordinate", value: "<group>:<name>:<version>" }`. The dependency JAR is treated as non-vanilla: binary remap is suppressed. When the caller asks for a non-obfuscated mapping the resolver returns the JAR with `mappingApplied: "obfuscated"` and `qualityFlags: ["dependency-mapping-unverified"]`, plus a warning that the caller must validate symbol availability. Resolution metadata appears on `provenance.dependencyResolution`. |
 
+### Inspecting a Fabric / loader dependency like vanilla
+
+To read members or source of a Fabric API (or any loader/Maven dependency) class
+the same way you read vanilla, pass a `dependency` target straight to
+`get-class-members` / `get-class-source` — no separate lookup tool is needed:
+
+```jsonc
+// members of a Fabric API class, version taken from the workspace
+{
+  "tool": "get-class-members",
+  "className": "net.fabricmc.fabric.api.event.player.UseEntityCallback",
+  "target": { "kind": "dependency", "group": "net.fabricmc.fabric-api", "name": "fabric-api", "versionFromProject": true },
+  "projectPath": "/path/to/workspace"
+}
+```
+
+Use an explicit `"version"` instead of `versionFromProject` when you already
+know it. Because dependency JARs are not remapped, members come back in the
+dependency's own namespace with `qualityFlags: ["dependency-mapping-unverified"]`;
+treat the names as the JAR's compiled names. For repeated lookups against the
+same dependency, call `resolve-artifact` once and reuse the returned
+`artifactId` via `target: { kind: "artifact", artifactId }`.
+
 Workspace detection is memoised in a process-resident `WorkspaceContextCache` (16-entry LRU, 5-minute TTL). The cache is observable through `manage-cache` with `cacheKinds: ["workspace"]`, and individual entries can be invalidated via `selector.projectPath`.
 
 `target.kind="dependency"` resolution probes four de-duplicated `gradle.properties` keys in order — `name_version`, `camelCaseVersion`, `lastSegment(group)_name_version`, and `camelCase(lastSegment(group)_name)Version` — before falling back to the modules-2 cache layout `~/.gradle/caches/modules-2/files-2.1/<group>/<name>/`. Version tokens that contain path separators, `..`, NUL, control characters, or any character outside `[A-Za-z0-9._+-]` are rejected; in `gradle.properties` the rejection is recorded under `attempts[]` as `gradle.properties:<key>:rejected-unsafe-version` and the next key is tried. Snapshot and dev directories are excluded by default. The modules-2 fallback only resolves when exactly one valid entry remains; multiple entries raise `ERR_DEPENDENCY_VERSION_UNRESOLVED` so a global cache cannot supply a version the workspace did not declare.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhisang/minecraft-modding-mcp",
-  "version": "6.0.0",
+  "version": "6.1.0",
   "description": "MCP server for AI-assisted Minecraft modding: inspect decompiled source, resolve Mojang/Yarn/Intermediary mappings, diff versions, analyze Fabric/Forge/NeoForge mod JARs, and validate Mixin, Access Widener, and Access Transformer files.",
   "type": "module",
   "main": "dist/index.js",