@adhisang/minecraft-modding-mcp 4.2.1 → 6.0.0

package/dist/types.d.ts

@@ -112,6 +112,7 @@ export interface Config {
     fetchTimeoutMs: number;
     fetchRetries: number;
     searchScanPageSize: number;
+    searchScanMaxBytes: number;
     indexInsertChunkSize: number;
     maxMappingGraphCache: number;
     maxSignatureCache: number;

package/dist/version-diff-service.js

@@ -145,6 +145,11 @@ export class VersionDiffService {
             });
         }
         const warnings = [];
+        if (input.maxClassResults != null &&
+            Number.isFinite(input.maxClassResults) &&
+            input.maxClassResults > MAX_CLASS_RESULTS_LIMIT) {
+            warnings.push(`maxClassResults was clamped to ${MAX_CLASS_RESULTS_LIMIT} from ${input.maxClassResults}.`);
+        }
         const startedAt = Date.now();
         log("info", "version-diff.start", { fromVersion, toVersion, category });
         const includeClasses = category === "classes" || category === "all";

package/dist/version-service.d.ts

@@ -16,6 +16,7 @@ export type ListVersionsOutput = {
     snapshots?: VersionEntry[];
     cached: string[];
     totalAvailable: number;
+    warnings?: string[];
 };
 export type ResolvedVersionJar = {
     version: string;
@@ -47,6 +48,7 @@ export declare class VersionService {
     private manifestCache;
     private readonly versionDetailCache;
     private readonly resolveLocks;
+    private indexWriteChain;
     constructor(config: Config, fetchFn?: typeof fetch);
     listVersions(input?: ListVersionsInput): Promise<ListVersionsOutput>;
     listVersionIds(input?: ListVersionIdsInput): Promise<string[]>;
@@ -60,6 +62,7 @@ export declare class VersionService {
     private cacheIndexPath;
     private loadCacheIndex;
     private recordCacheEntry;
+    private recordCacheEntryInternal;
     private trimVersionDetailCache;
 }
 /**

package/dist/version-service.js

@@ -38,6 +38,9 @@ export class VersionService {
     manifestCache;
     versionDetailCache = new Map();
     resolveLocks = new Map();
+    // Serializes index.json read-modify-write so parallel resolutions of different
+    // versions can't clobber each other (resolveLocks only guards the same version).
+    indexWriteChain = Promise.resolve();
     constructor(config, fetchFn = globalThis.fetch) {
         this.config = config;
         this.fetchFn = fetchFn;
@@ -47,6 +50,10 @@ export class VersionService {
         const manifest = await this.fetchManifest();
         const includeSnapshots = input.includeSnapshots ?? false;
         const limit = clampLimit(input.limit, 20, 200);
+        const warnings = [];
+        if (input.limit != null && Number.isFinite(input.limit) && input.limit > 200) {
+            warnings.push(`limit was clamped to 200 from ${input.limit}.`);
+        }
         const versions = manifest.versions ?? [];
         const releases = versions
             .filter((entry) => entry.type === "release")
@@ -65,7 +72,8 @@ export class VersionService {
             releases,
             snapshots: includeSnapshots ? snapshots : undefined,
             cached: Array.from(new Set(cached)).sort((a, b) => a.localeCompare(b)),
-            totalAvailable: versions.length
+            totalAvailable: versions.length,
+            ...(warnings.length ? { warnings } : {})
         };
     }
     async listVersionIds(input = {}) {
@@ -389,7 +397,15 @@ export class VersionService {
             return { entries: [] };
         }
     }
-    async recordCacheEntry(entry) {
+    recordCacheEntry(entry) {
+        // Chain onto the previous write so reads and writes never interleave. The
+        // caller still awaits its own write's result, but the shared chain swallows
+        // failures so one rejected write cannot poison subsequent writes.
+        const next = this.indexWriteChain.then(() => this.recordCacheEntryInternal(entry));
+        this.indexWriteChain = next.catch(() => undefined);
+        return next;
+    }
+    async recordCacheEntryInternal(entry) {
         const indexPath = this.cacheIndexPath();
         const existing = await this.loadCacheIndex();
         const deduped = existing.entries.filter((candidate) => candidate.version !== entry.version);

package/dist/warning-details.d.ts

@@ -0,0 +1,30 @@
+export type WarningCategory = "pagination" | "mapping" | "coverage" | "validation" | "general";
+export type WarningSeverity = "warning" | "info";
+export type WarningDetail = {
+    /** Stable machine code for the warning family. */
+    code: string;
+    category: WarningCategory;
+    severity: WarningSeverity;
+    /** Index into `meta.warnings[]` that holds the original human-readable text. */
+    index: number;
+    /** Input fields a caller can adjust to address the warning, when applicable. */
+    affectedFields?: string[];
+};
+/**
+ * Build the structured `warningDetails[]` companion for a list of warning strings.
+ * The mapping is 1:1 and order-preserving, so each entry's `index` equals its
+ * position and dereferences the text via `warnings[index]`.
+ */
+export declare function classifyWarnings(warnings: string[]): WarningDetail[];
+/**
+ * Cap of structured warningDetails entries emitted at `detail:"summary"`.
+ */
+export declare const SUMMARY_WARNING_DETAIL_CAP = 5;
+/**
+ * At `detail:"summary"` the structured warningDetails companion is capped to a small
+ * representative set to keep responses lean. The full human-readable text still lives
+ * in `meta.warnings[]`, and each kept entry's `index` continues to dereference it, so
+ * no information is lost — only the redundant structured duplicate is trimmed. Standard
+ * and full detail return the companion unchanged.
+ */
+export declare function capWarningDetailsForSummary(warningDetails: WarningDetail[], isSummary: boolean): WarningDetail[];

package/dist/warning-details.js

@@ -0,0 +1,80 @@
+// Structured companion to the string `meta.warnings`. Each warning string is
+// classified into a high-value family so agents can branch on category/severity
+// without parsing prose. The original text is NOT duplicated here; each entry
+// references its warning by position via `index` (read `meta.warnings[index]`).
+// First matching rule wins; more specific patterns precede broader ones.
+const WARNING_RULES = [
+    {
+        test: /Member list was truncated|truncated to \d+ (entries|rows)|Raise maxCandidates|Raise maxRows/i,
+        code: "result_truncated",
+        category: "pagination",
+        severity: "info",
+        affectedFields: ["maxMembers", "maxRows", "maxCandidates", "cursor"]
+    },
+    {
+        test: /\bwas clamped to\b/i,
+        code: "input_clamped",
+        category: "validation",
+        severity: "info"
+    },
+    {
+        test: /are not indexed|non-Java resources are not indexed/i,
+        code: "resource_not_indexed",
+        category: "coverage",
+        severity: "info"
+    },
+    {
+        test: /namespace translation requires a version|could not be applied because the artifact has no version|Could not (re)?map .* (from .* to|to .* namespace)|Remap failed for|Mapping lookup failed|No exact class symbol matched|Unsupported .* namespace/i,
+        code: "namespace_fallback",
+        category: "mapping",
+        severity: "warning",
+        affectedFields: ["mapping", "version"]
+    },
+    {
+        test: /falling back to vanilla|resolution failed; falling back|sources jar\.?\s*Falling back|does not include net\.minecraft/i,
+        code: "partial_coverage",
+        category: "coverage",
+        severity: "warning",
+        affectedFields: ["scope"]
+    }
+];
+function classifyWarning(message, index) {
+    for (const rule of WARNING_RULES) {
+        if (rule.test.test(message)) {
+            return {
+                code: rule.code,
+                category: rule.category,
+                severity: rule.severity,
+                index,
+                ...(rule.affectedFields ? { affectedFields: rule.affectedFields } : {})
+            };
+        }
+    }
+    return { code: "general", category: "general", severity: "info", index };
+}
+/**
+ * Build the structured `warningDetails[]` companion for a list of warning strings.
+ * The mapping is 1:1 and order-preserving, so each entry's `index` equals its
+ * position and dereferences the text via `warnings[index]`.
+ */
+export function classifyWarnings(warnings) {
+    return warnings.map((message, index) => classifyWarning(message, index));
+}
+/**
+ * Cap of structured warningDetails entries emitted at `detail:"summary"`.
+ */
+export const SUMMARY_WARNING_DETAIL_CAP = 5;
+/**
+ * At `detail:"summary"` the structured warningDetails companion is capped to a small
+ * representative set to keep responses lean. The full human-readable text still lives
+ * in `meta.warnings[]`, and each kept entry's `index` continues to dereference it, so
+ * no information is lost — only the redundant structured duplicate is trimmed. Standard
+ * and full detail return the companion unchanged.
+ */
+export function capWarningDetailsForSummary(warningDetails, isSummary) {
+    if (!isSummary || warningDetails.length <= SUMMARY_WARNING_DETAIL_CAP) {
+        return warningDetails;
+    }
+    return warningDetails.slice(0, SUMMARY_WARNING_DETAIL_CAP);
+}
+//# sourceMappingURL=warning-details.js.map

package/dist/workspace-mapping-service.js

@@ -65,6 +65,15 @@ function buildDependencyPropertyKeys(group, name) {
         `${groupSegment}_${name}_version`,
         `${camelGroupName}Version`
     ];
+    // Umbrella fallback: submodules of an umbrella package (e.g. Fabric API's
+    // net.fabricmc.fabric-api:fabric-screen-handler-api-v1) rarely declare their own
+    // version — the parent declares a single umbrella property (fabric_api_version /
+    // fabricApiVersion) that all submodules inherit. When the artifact name differs from
+    // the group's last segment, append the umbrella's keys as LOWER-priority candidates so
+    // submodule version detection no longer fails with ERR_DEPENDENCY_VERSION_UNRESOLVED.
+    if (groupSegment !== name) {
+        keys.push(`${groupSegment.replace(/-/g, "_")}_version`, `${camelCaseDependencyName(groupSegment)}Version`);
+    }
     const seen = new Set();
     const deduped = [];
     for (const key of keys) {

package/docs/README-ja.md

@@ -15,7 +15,7 @@
 
 stdio で動作し、Claude Desktop、Claude Code、VS Code、Codex CLI、Gemini CLI などの MCP 対応クライアントから利用できます。
 
-**37 ツール**（6 エントリー + 31 エキスパート） | **7 リソース** | **4 マッピング名前空間** | **SQLite ベースのキャッシュ**
+**41 ツール**（6 エントリー + 35 エキスパート） | **9 リソース** | **4 マッピング名前空間** | **SQLite ベースのキャッシュ**
 
 ## 特長
 
@@ -301,7 +301,7 @@ Minecraft バージョン間でのクラス / レジストリ変更比較と、
 | ツール | 役割 |
 | --- | --- |
 | `find-mapping` | クラス、フィールド、メソッドのシンボルに対するマッピング候補を調べる |
-| `resolve-method-mapping-exact` | owner、name、descriptor の厳密一致で 1 つのメソッドマッピングを解決する |
+| `resolve-method-mapping-exact` | `find-mapping`（kind=method, signatureMode=exact）の厳密版ショートカット。owner+name+descriptor の三つ組が必須 |
 | `get-class-api-matrix` | 1 つのクラス API を `obfuscated`、`mojang`、`intermediary`、`yarn` で見比べる |
 | `resolve-workspace-symbol` | Gradle ワークスペースからコンパイル時に見えるシンボル名を解決する |
 | `check-symbol-exists` | 名前空間内でクラス、フィールド、メソッドが存在するかを確認する |

package/docs/examples.md

@@ -105,7 +105,7 @@ Start with these top-level workflow tools when possible. They cover the common w
   "tool": "get-class-source",
   "arguments": {
     "target": {
-      "type": "artifact",
+      "kind": "artifact",
       "artifactId": "<artifact-id>"
     },
     "className": "net.minecraft.server.Main",
@@ -137,7 +137,7 @@ Start with these top-level workflow tools when possible. They cover the common w
   "tool": "get-class-members",
   "arguments": {
     "target": {
-      "type": "artifact",
+      "kind": "artifact",
       "artifactId": "<artifact-id>"
     },
     "className": "net.minecraft.server.Main",
@@ -395,6 +395,30 @@ Start with these top-level workflow tools when possible. They cover the common w
 
 If the input JAR was already built with Mojang mappings, use `targetMapping: "mojang"` to get a copied output JAR and a `fromMapping: "mojang"` result.
 
+### Bridge a mod hit to a Minecraft-side check
+
+When `search-mod-source` or `get-mod-class-source` surfaces a class or member that
+looks like a Minecraft target (for example a Mixin `@Shadow`/`@Inject` target, or a
+symbol from a crash stack), verify it against the target Minecraft version before
+trusting it. Feed the owner/member into `verify-mixin-target`. When your owner/member
+are in a readable namespace (e.g. `mojang`/`yarn`) but the resolved artifact is
+obfuscated, set `autoRemap: true` to translate them automatically in one call:
+
+```json
+{
+  "tool": "verify-mixin-target",
+  "arguments": {
+    "target": { "kind": "version", "value": "1.21.10" },
+    "owner": "net.minecraft.world.entity.LivingEntity",
+    "member": { "kind": "method", "name": "tickServer", "descriptor": "()V" },
+    "mapping": "mojang",
+    "autoRemap": true
+  }
+}
+```
+
+For a plain "does this symbol exist in this version?" question, use `analyze-symbol task="exists"` instead.
+
 ## Validation
 
 ### Validate Mixin source

package/docs/tool-reference.md

@@ -23,15 +23,15 @@ Start here when you are not sure which tool to reach for. In every row, the left
 | "Does this Mixin target the right class and descriptor?" | `validate-mixin` (works standalone with `version=1.21.10`; provide inline source, a path, or a mixin config). |
 | "Validate every Mixin / Access Widener / Access Transformer in a workspace." | `validate-project` (`task="project-summary"` discovers everything; `task="mixin"|"access-widener"|"access-transformer"` validates a single subject). |
 | "Inspect the Minecraft workspace or an artifact without picking a lower-level tool." | `inspect-minecraft` — use this when you want the server to resolve the artifact and pick the right sub-tool. |
-| "Trace when a symbol was added, renamed, or removed across versions." | `trace-symbol-lifecycle` (or `analyze-symbol task="lifecycle"` for the summarized 5-version window). |
-| "Compare two MC versions or two class versions." | `compare-minecraft` (`task="class"` for a single class diff; `task="versions"` for a full summary). |
+| "Trace when a symbol was added, renamed, or removed across versions." | `trace-symbol-lifecycle` (or `analyze-symbol task="lifecycle"`, which now exposes `fromVersion`/`toVersion`/`maxVersions`/`includeTimeline`). |
+| "Compare two MC versions or two class versions." | `compare-minecraft` (`task="class-diff"` for a single class diff; `task="versions"` for a full summary). |
 | "Inspect or remap an existing `.jar` file." | `analyze-mod` / `analyze-mod-jar` / `remap-mod-jar`. |
 
 ## Essential Conventions
 
 - Start with the top-level workflow tools when possible. `inspect-minecraft`, `analyze-symbol`, `compare-minecraft`, `analyze-mod`, `validate-project`, and `manage-cache` cover the common workflows and return summary-first results with follow-up hints.
 - `resolve-artifact` uses `target: { kind, value }`. `kind` is one of `"version"`, `"jar"`, `"coordinate"`, `"workspace"`, or `"dependency"` (see "Workspace and dependency target shapes" below).
-- `get-class-source` and `get-class-members` use `target: { type: "artifact", artifactId }` or `target: { type: "resolve", kind, value }` (the same `kind` set as `resolve-artifact`).
+- `get-class-source` and `get-class-members` use `target: { kind, value }` — the same `kind`-based shape as `resolve-artifact` (`"version"`, `"jar"`, `"coordinate"`, `"workspace"`, `"dependency"`), plus `target: { kind: "artifact", artifactId }` to reuse an already-resolved artifact.
 - `find-class`, `search-class-source`, `list-artifact-files`, and `find-mapping` keep their existing input shapes (an `artifactId` or a `version`); they do not currently accept `target.kind="workspace"` or `target.kind="dependency"`.
 - `validate-mixin` and `validate-project task="mixin"` use `input.mode="inline" | "path" | "paths" | "config" | "project"`.
 - Positive integer tool arguments accept numeric strings such as `"10"` for documented top-level parameters.
@@ -46,12 +46,14 @@ Start here when you are not sure which tool to reach for. In every row, the left
   | --- | --- | --- |
   | `"ok"` | `counts.total > 0`, OR `counts.total === 0` AND binary extraction succeeded AND `decompiledFallback` did not fire (genuinely empty class). | none |
   | `"partial"` | `decompiledFallback` is populated (bytecode returned zero but the indexed decompiled source supplied member names; `qualityFlags` includes `"members-from-decompiled-source"`). | `decompiledFallback`, `decompiledMemberCounts` |
-  | `"members_unavailable"` | Binary signature extraction threw a non-`ERR_CLASS_NOT_FOUND` error AND no decompiled fallback was available. | `unavailableReason: string`, `suggestedCall: { tool: "get-class-source", params: { target: { type: "artifact", artifactId }, className, mode: "snippet", mapping } }` (the params validate against `get-class-source`'s input schema). |
+  | `"members_unavailable"` | Binary signature extraction threw a non-`ERR_CLASS_NOT_FOUND` error AND no decompiled fallback was available. | `unavailableReason: string`, `suggestedCall: { tool: "get-class-source", params: { target: { kind: "artifact", artifactId }, className, mode: "snippet", mapping } }` (the params validate against `get-class-source`'s input schema). |
 
   The shape is purely additive: `members` / `counts` / `decompiledFallback` / `decompiledMemberCounts` / `qualityFlags` are unchanged for callers that ignore `status`. `ERR_CLASS_NOT_FOUND` still propagates as a thrown error rather than as `members_unavailable`. Set `MEMBERS_STATUS_LEGACY=1` at process start to omit `status` / `unavailableReason` / `suggestedCall` entirely (legacy shape).
 - `search-class-source` accepts `queryNamespace`. When set and the artifact's `mappingApplied` differs, `intent="symbol"` queries for fully-qualified class names are translated through `find-mapping` (source=`queryNamespace`, target=artifact namespace) before the indexed search runs; the response carries a `translatedQuery` block describing the rewrite. `intent="text"` / `intent="path"` do not translate — text search is a literal match against the artifact namespace; the response surfaces a `warnings` array instead. `sourcePriority` is only consulted during translation.
-- `resolve-artifact`, `find-mapping`, `resolve-method-mapping-exact`, `resolve-workspace-symbol`, and `check-symbol-exists` default `compact` to `true`. Pass `compact: false` for the full diagnostic shape. When enabled, compact mode strips empty arrays, null values, and empty objects from the response. For `resolve-artifact`, compact mode also omits `provenance`, `artifactContents`, `sampleEntries`, `adjacentSourceCandidates`, `binaryJarPath`, `coordinate`, `repoUrl`, and `resolvedSourceJarPath`. For mapping tools, compact mode has two projections: (1) the redundant `candidates` array is omitted entirely when the result is a single full-confidence exact-match resolution; (2) when the result is unresolved with more than three candidates, the top three keep full metadata while the tail is slimmed to `{kind, symbol, owner, name, descriptor, confidence, matchKind}` and the response surfaces `candidateDetailsTruncated: true`. `candidatesTruncated` retains its pre-compact meaning ("more candidates exist upstream than this response returned") and is set independently by the service when `maxCandidates` clipped the list — the two signals can both appear.
-- `get-class-source`, `get-class-members`, `search-class-source`, and `list-artifact-files` accept `compact: true` (opt-in, default `false`) to strip debug/diagnostic metadata and empty fields. `get-class-source` omits `provenance`, `artifactContents`, and `qualityFlags`. `get-class-members` omits `provenance`, `artifactContents`, `qualityFlags`, and `context`; `decompiledFallback` and `decompiledMemberCounts` are preserved. `search-class-source` and `list-artifact-files` omit `artifactContents` only — the primary `hits` / `items` payload is always preserved.
+- All expert and batch tools share the entry-tool **`detail`** (`summary` | `standard` | `full`) + **`include[]`** response contract (the per-tool `compact` boolean is gone). `summary` is the terse shape (drops diagnostics/empties, slims candidates), `standard` keeps fields but drops heavy diagnostics, `full` keeps everything. Per-tool defaults are chosen so the default response is unchanged: `resolve-artifact`, `find-mapping`, `resolve-method-mapping-exact`, `resolve-workspace-symbol`, `check-symbol-exists`, and the four `batch-*` tools default **`summary`**; `get-class-source`, `get-class-members`, `search-class-source`, and `list-artifact-files` default **`standard`**. (Migration: `compact: true` → `detail: "summary"`; `compact: false` → `detail: "full"`.)
+- At `detail: "summary"`, empty arrays / null / empty objects are stripped. For `resolve-artifact` it also omits `provenance`, `artifactContents`, `sampleEntries`, `adjacentSourceCandidates`, `binaryJarPath`, `coordinate`, `repoUrl`, and `resolvedSourceJarPath` — `include: ["provenance"|"artifact"|"samples"|"candidates"|"paths"]` re-adds the matching field(s). For mapping tools, `summary` (1) omits the redundant `candidates` array on a single full-confidence exact-match resolution and (2) slims the tail to `{kind, symbol, owner, name, descriptor, confidence, matchKind}` with `candidateDetailsTruncated: true` when an unresolved result has more than three candidates; `include: ["candidates"]` keeps the full candidate list. `candidatesTruncated` keeps its independent meaning ("more candidates exist upstream than returned").
+- `get-class-source` and `get-class-members` omit the diagnostic fields `provenance`, `artifactContents`, and `qualityFlags` at `detail: "summary"` and `detail: "standard"` (the lean common path). Pass `include: ["provenance"]` (or the legacy alias `includeProvenance: true`) or use `detail: "full"` to include all three. `detail: "summary"` additionally strips empty fields, and for `get-class-members` also strips `context`; `decompiledFallback` and `decompiledMemberCounts` are preserved. `search-class-source` and `list-artifact-files` omit `artifactContents` at `detail: "summary"` (re-add via `include: ["artifact"]`) — the primary `hits` / `items` payload is always preserved.
+- `get-class-members` returns a slim member shape: `accessFlags` is dropped (modifiers are in `javaSignature`), `ownerFqn` is hoisted to a single block-level `members.ownerFqn` when all members share one owner (per-member only when `includeInherited` surfaces multiple owners), and **field** `jvmDescriptor` is omitted by default. Method/constructor `jvmDescriptor` is always present for overload disambiguation. Pass `include: ["descriptors"]` (or the legacy alias `includeDescriptors: true`) to also emit field descriptors.
 - Windows and WSL path forms are normalized for `jarPath`, `projectPath`, and environment-variable path overrides.
 - Heavy analysis tools are serialized in-process to protect stdio stability. Queue overflow returns `ERR_LIMIT_EXCEEDED`.
 - All tools and JSON resources use the standard `{ result?, error?, meta }` envelope. `class-source` and `artifact-file` resources return raw text on success and structured JSON on failure.
@@ -90,7 +92,7 @@ Workspace detection is memoised in a process-resident `WorkspaceContextCache` (1
 - `remap-mod-jar` requires Java and supports Fabric/Quilt inputs. Mojang-mapped inputs can only be copied through `targetMapping="mojang"`.
 - `search-mod-source` enforces `query.length <= 200` and `limit <= 200`.
 - `get-registry-data` can return names and counts only with `includeData=false`, or clip detailed payloads with `maxEntriesPerRegistry`.
-- `validate-mixin` summary-first workflows should combine `includeIssues=false`, `reportMode="compact"`, and `warningMode="aggregated"`.
+- `validate-mixin` defaults `reportMode="summary-first"`: it hoists shared provenance/warnings/incomplete reasons and drops per-result `resolvedMembers`/`toolHealth`/`structuredWarnings`. Pass `reportMode="full"` (or `explain=true`) to get per-result `resolvedMembers`/`toolHealth`/`resolutionTrace` back. For the leanest output combine `includeIssues=false`, `reportMode="compact"`, and `warningMode="aggregated"`.
 - `validate-mixin` top-level failures expose `failedStage` as a first-class field on the serialized `error` envelope (alongside `code`, `hints`, `suggestedCall`) — one of `"input-validation" | "resolve" | "mapping-health" | "parse" | "target-lookup"`. Branch on that before inspecting `message` to recover automatically (e.g. retry `resolve` failures with `scope="vanilla"`, retry `target-lookup` failures with a different `mapping`). Nested errors that already carry a `failedStage` are preserved so upstream tags (e.g. from `resolve-artifact`) surface unchanged.
 - `validate-mixin` per-result `quickSummary` appends `Scope fell back from "<requested>" to "<applied>" (<reason>).` when `provenance.scopeFallback` is set and `Mapping health degraded: <degradations>.` when `toolHealth.overallHealthy === false`. Clean validations keep the original one-line summary; the extra notes only attach when the pipeline actually fell back or detected a degraded mapping.
 - `mapping-health` stays lightweight for `obfuscated` and `mojang` requests. It avoids full Tiny mapping graph loads unless the caller requests `intermediary` or `yarn`, where Tiny namespace availability is part of the health check.
@@ -148,7 +150,7 @@ Common input fields:
 - `entries: Array<...>` — 1..50 per-entry payloads. Tool-specific shape (see each subsection).
 - `concurrency: number` (1..8, default 4) — passed to the worker pool. Above 8 is rejected with `ERR_INVALID_INPUT` (`fieldErrors[0].path === "concurrency"`).
 - `failFast: boolean` (default `false`) — when `true`, the first per-entry error sets an abort flag. Workers that have not yet picked up an entry short-circuit with `error.code === "ERR_BATCH_ABORTED"`. **In-flight workers continue to completion** — they are not cancelled (no AbortSignal wiring). Already-completed `ok` entries are still returned in `results`.
-- `compact: boolean` (default `true`) — applies the same per-tool projection that the corresponding single tool's `compact: true` mode applies. When `false`, per-entry `result` is byte-identical to the single tool's `compact: false` output.
+- `detail: "summary" | "standard" | "full"` (default `summary`) + `include[]` — applies the same per-tool projection the corresponding single tool applies at that detail level to each entry's `result`. `detail: "summary"` matches the old `compact: true` per-entry shape; `detail: "full"` matches the old `compact: false` (byte-identical to the single tool's full output).
 - Per-tool shared inputs (`target`, `mapping`, `projectPath`, `version`, etc.) follow the same shape as the matching single tool.
 
 Resource behavior: `concurrency` limits per-entry dispatch for one batch call. Within one MCP server process, entries or calls that need the same artifact index or decompiled fallback share the in-flight rebuild by `artifactId`. Separate MCP server processes sharing the same cache are not coordinated by this process-local guard.
@@ -191,8 +193,8 @@ Per-entry retry semantics: each `error.suggestedCall` proposes the **matching si
 
 | Batch tool | Single tool retry |
 |---|---|
-| `batch-class-source` | `get-class-source` (with `target: { type: "artifact", artifactId: <shared> }`) |
-| `batch-class-members` | `get-class-members` (with `target: { type: "artifact", artifactId: <shared> }`) |
+| `batch-class-source` | `get-class-source` (with `target: { kind: "artifact", artifactId: <shared> }`) |
+| `batch-class-members` | `get-class-members` (with `target: { kind: "artifact", artifactId: <shared> }`) |
 | `batch-symbol-exists` | `check-symbol-exists` (with `version` derived from the resolved artifact) |
 | `batch-mappings` | `find-mapping` (with `version` carried from the top-level batch input) |
 
@@ -208,7 +210,7 @@ Read source for many classes against one shared resolved artifact. Per-entry: `{
 
 ### batch-class-members
 
-List members for many classes against one shared resolved artifact. Per-entry: `{ className, access?, includeSynthetic?, includeInherited?, memberPattern?, maxMembers? }`. Shared inputs match `batch-class-source`. Result shape per entry mirrors `get-class-members`, including the `status` field (`"available"` / `"unavailable"` / etc.).
+List members for many classes against one shared resolved artifact. Per-entry: `{ className, access?, includeSynthetic?, includeInherited?, memberPattern?, maxMembers? }`. Shared inputs match `batch-class-source`. Result shape per entry mirrors `get-class-members`, including the `status` field (`"ok"` / `"partial"` / `"members_unavailable"`).
 
 ### batch-symbol-exists
 
@@ -265,7 +267,8 @@ These environment variables are read once at worker startup and provide rollback
 
 - Start with `inspect-minecraft` for version, artifact, class, file, and search workflows before dropping to `list-versions`, `resolve-artifact`, `get-class-source`, `get-class-members`, `search-class-source`, `get-artifact-file`, or `list-artifact-files`.
 - Start with `analyze-symbol` for symbol mapping, existence, lifecycle, workspace, and API overview workflows before using `find-mapping`, `resolve-method-mapping-exact`, `check-symbol-exists`, `trace-symbol-lifecycle`, `resolve-workspace-symbol`, or `get-class-api-matrix` directly.
-- `analyze-symbol task="lifecycle"` treats its required `version` as the upper bound for the lifecycle scan and intentionally limits the high-level helper to a recent 5-version window. Use `trace-symbol-lifecycle` directly when you need explicit `fromVersion` / `toVersion` control or a wider history.
+- `analyze-symbol task="lifecycle"` accepts `fromVersion`/`toVersion`/`maxVersions`/`includeTimeline`/`includeSnapshots` (lifecycle-only; rejected on other tasks). The legacy `version` field is a back-compat alias for `toVersion` (range end). The default scan window is the service default of 120 versions (max 400); pass `maxVersions: 5` for the old narrow window. Use `trace-symbol-lifecycle` directly only for parity with the expert tool.
+- `analyze-symbol` `subject.kind` accepts `"symbol"` to auto-detect the concrete kind from the selector (owner+descriptor ⇒ method, owner only ⇒ field, otherwise ⇒ class); the inferred kind is surfaced as a warning. For `task="api-overview"` the inferred kind is always class.
 - Start with `compare-minecraft` for version-pair, class diff, registry diff, and migration-summary flows before using `compare-versions`, `diff-class-signatures`, or `get-registry-data` directly.
 - Start with `analyze-mod` for metadata-first mod inspection and safe remap preview/apply flows before using `analyze-mod-jar`, `decompile-mod-jar`, `get-mod-class-source`, `search-mod-source`, or `remap-mod-jar` directly.
 - Start with `validate-project` for workspace summaries and direct Mixin, Access Widener, or Access Transformer validation before using `validate-mixin`, `validate-access-widener`, or `validate-access-transformer` directly.
@@ -289,7 +292,7 @@ These environment variables are read once at worker startup and provide rollback
 - `validate-access-transformer` accepts `atNamespace="srg" | "mojang" | "obfuscated"`. When `projectPath` points at a Forge or NeoForge workspace, the tool can infer that namespace automatically and validate against loader/runtime artifacts for `scope="loader"`.
 - Start with `manage-cache` for cache inventory and safe cleanup. Use `executionMode="preview"` before `executionMode="apply"`.
 - Replace `resolve-artifact` `targetKind` and `targetValue` with `target: { kind, value }`.
-- Replace `get-class-source` and `get-class-members` top-level `artifactId`, `targetKind`, and `targetValue` with `target: { type: "artifact", artifactId }` or `target: { type: "resolve", kind, value }`.
+- Replace `get-class-source` and `get-class-members` top-level `artifactId`, `targetKind`, and `targetValue` with `target: { kind, value }` (same shape as `resolve-artifact`) or `target: { kind: "artifact", artifactId }`. The earlier `target: { type: "artifact", artifactId }` form is gone — use `{ kind: "artifact", artifactId }`; the redundant `{ type: "resolve", ... }` wrapper is still accepted but `type` is ignored.
 - `resolve-method-mapping-exact` is method-only and no longer accepts `kind`.
 - Replace `validate-mixin` `source`, `sourcePath`, `sourcePaths`, `mixinConfigPath`, and `sourceRoot` with `input.mode` plus `input.source`, `input.path`, `input.paths[]`, `input.configPaths[]`, and `sourceRoots[]`.
 - `search-class-source` removed snippet, definition, and relation expansion. Responses now contain compact `hits[]` plus `nextCursor?`, and `symbolKind` is only valid with `intent="symbol"`.
@@ -309,13 +312,15 @@ MCP resources provide URI-based access to Minecraft data for clients that suppor
 
 | Resource | URI Template | Description |
 | --- | --- | --- |
-| `class-source` | `mc://source/{artifactId}/{className}` | Java source code for a class within a resolved artifact |
+| `class-source` | `mc://source/{artifactId}/{className}` | Java source code for a class within a resolved artifact (raw text). |
+| `class-source-json` | `mc://source-json/{artifactId}/{className}` | Full class source plus metadata (`artifactId`, `mappingApplied`, `totalLines`, `returnedRange`, `provenance`, `warnings`) as a structured JSON envelope — easier to cite and continue than the raw-text `class-source`. |
 | `artifact-file` | `mc://artifact/{artifactId}/files/{filePath}` | Raw content of a file within a resolved artifact |
-| `find-mapping` | `mc://mappings/{version}/{sourceMapping}/{targetMapping}/{kind}/{name}` | Look up a mapping between two naming namespaces |
+| `find-mapping` | `mc://mappings/{version}/{sourceMapping}/{targetMapping}/{kind}/{name}` | Look up a **class** mapping between two naming namespaces. The URI carries no `owner`, so use `find-member-mapping` (or the `find-mapping` tool) for field/method lookups. |
+| `find-member-mapping` | `mc://mappings/{version}/{sourceMapping}/{targetMapping}/{kind}/{owner}/{name}` | Look up a **field or method** mapping, including the `owner` class the member belongs to. For exact method overload resolution use the `find-mapping` tool with a `descriptor`. |
 | `class-members` | `mc://artifact/{artifactId}/members/{className}` | List constructors, methods, and fields for a class |
 | `artifact-metadata` | `mc://artifact/{artifactId}` | Metadata for a previously resolved artifact |
 
-`versions-list`, `runtime-metrics`, `find-mapping`, `class-members`, and `artifact-metadata` return structured JSON envelopes on success (`{ result, meta }`) and failure (`{ error, meta }`).
+`versions-list`, `runtime-metrics`, `find-mapping`, `find-member-mapping`, `class-source-json`, `class-members`, and `artifact-metadata` return structured JSON envelopes on success (`{ result, meta }`) and failure (`{ error, meta }`).
 
 `class-source` and `artifact-file` keep raw text responses on success, but still return structured JSON errors on failure.
 
@@ -380,7 +385,7 @@ If `find-class` or `get-class-source` returns no hit on an `obfuscated` artifact
 
 Method descriptor precision is best on Tiny-backed paths (`intermediary` and `yarn`). For `obfuscated <-> mojang`, Mojang `client_mappings` do not carry JVM descriptors, so descriptor queries may fall back to name matching and emit a warning.
 
-Use `resolve-method-mapping-exact` when candidate ranking is not enough and the workflow needs strict `owner + name + descriptor` certainty.
+Use `resolve-method-mapping-exact` when candidate ranking is not enough and the workflow needs strict `owner + name + descriptor` certainty. It is a strict shortcut for `find-mapping` (kind=method, signatureMode=exact) that additionally requires a **complete** descriptor projection — it returns `mapping_unavailable` when the descriptor's class references cannot all be projected to the target namespace, whereas `find-mapping`'s exact mode resolves those leniently. Prefer `find-mapping kind=method signatureMode=exact` unless you specifically need that strict-completeness guarantee.
 
 Use `find-mapping` `disambiguation.ownerHint` and `disambiguation.descriptorHint` to narrow ambiguous candidate sets.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhisang/minecraft-modding-mcp",
-  "version": "4.2.1",
+  "version": "6.0.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",