@adhisang/minecraft-modding-mcp 3.2.0 → 4.1.0

package/CHANGELOG.md

@@ -5,6 +5,78 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.1.0] - 2026-05-09
+
+### Documentation
+- README onboarding and the Japanese README now clarify MCP client setup and packaged documentation links, and the npm package includes the Markdown docs those links reference.
+
+### Added
+- `validate-project task="project-summary"` now returns an additive `tasks` per-probe status report alongside the existing `summary` / `project` / `workspace` blocks. The seven probes (`workspace.detected`, `gradle.readable`, `loom.cache.found`, `minecraft.artifact.resolved`, `mixins.validated`, `accessWideners.validated`, `accessTransformers.validated`) each carry `status: "ok" | "skipped" | "missing" | "error"` plus optional sub-fields (e.g. `evidence`, `propertiesPath`, `buildScripts`, `cachePath`, `artifactId`, `mapping`, `counts`). The headline `result.summary.status` is unchanged; the new field surfaces which probes succeeded even when the overall status is `blocked`. With `detail: "summary"` (or when `include` does not contain `"workspace"`), each entry is slimmed to `status` / `error?` / `warnings?`. Set `VALIDATE_PROJECT_TASKS_OFF=1` to omit the field entirely.
+- `get-class-members` now returns an additive `status: "ok" | "members_unavailable" | "partial"` field. `"ok"` covers both populated classes (`counts.total > 0`) and genuinely empty classes whose binary signature parsed without error and produced no decompiled fallback. `"partial"` fires whenever `decompiledFallback` is populated (bytecode returned zero but indexed source supplied member names; `qualityFlags` includes `"members-from-decompiled-source"`). `"members_unavailable"` fires when binary signature extraction throws a non-`ERR_CLASS_NOT_FOUND` error and no decompiled fallback is available; the response then carries `unavailableReason: string` and a `suggestedCall: { tool: "get-class-source", params }` whose params validate against `get-class-source`'s input schema. `ERR_CLASS_NOT_FOUND` still propagates as a thrown error. The shape is purely additive — `members` / `counts` / `decompiledFallback` / `decompiledMemberCounts` / `qualityFlags` are unchanged for callers that ignore `status`. Set `MEMBERS_STATUS_LEGACY=1` to omit the new fields entirely (legacy shape).
+- `verify-mixin-target` (new tool): single-call probe that answers "does this owner / member exist, and which `@Shadow` / `@Accessor` / `@Invoker` should the mixin use?" Inputs accept `target.kind="workspace" | "version" | "coordinate" | "dependency" | "jar"`, an optional `mixinMemberName` (caller-authored mixin field/method name), and a discriminated `member: { kind: "method" | "field", name, descriptor? }`. Output carries `exists`, `matches[]`, `candidates[]` (descriptor-mismatch and Levenshtein-near misses via the same `suggestSimilar` helper used by `validate-mixin`), and an `accessorAdvice` block with `suggestedAnnotation` (`"@Shadow"` / `"@Accessor"` / `"@Invoker"` / `"@Inject-only"` / `null`), a deterministic `exampleSnippet`, and `candidates` when the rule table cannot decide between `@Shadow` and `@Invoker`. `accessorAdvice` is emitted only when `matches.length === 1` (a single unique match): descriptor-mismatch / nearest-neighbor / candidate-only responses carry no advice, and ambiguous overload responses (descriptor omitted, multiple matches) also carry no advice — re-call with an explicit `descriptor` to disambiguate. `@Accessor` setter templates (when `mixinMemberName` matches `^set[A-Z]`) emit `void name(<type> value);` instead of the zero-arg getter shape. `"@Inject-only"` is a pseudo-tag — not a real annotation — that signals "target already visible, no `@Shadow` required". Owner-not-found surfaces `ERR_CLASS_NOT_FOUND` with `details.suggestedCall.tool === "find-class"`. Namespace mismatch (explicit `mapping` differs from resolved `mappingApplied`) surfaces `ERR_NAMESPACE_MISMATCH` with `details.requestedMapping` and `details.mappingApplied` rather than silently returning a misleading `exists:false`; auto-translation of owner/member names across namespaces is deferred. Set `VERIFY_MIXIN_TARGET_OFF=1` to remove the tool from `tools/list` entirely (direct calls then return the SDK "Tool not found" tool-result envelope — `{ content: [{ type: "text", text: "MCP error -32602: Tool verify-mixin-target not found" }], isError: true }` — so callers cannot rely on `error.code === "ERR_*"` while the toggle is set).
+- `ProblemDetails.code` may now be `ERR_WORKER_RESTART`, `ERR_MIXIN_PARSE_FAILED`, `ERR_STAGE_BUDGET_PRE_PARSE`, `ERR_WORKSPACE_VERSION_UNRESOLVED`, `ERR_DEPENDENCY_VERSION_UNRESOLVED`, or `ERR_BATCH_ABORTED`. Restart envelopes are produced by the supervisor when a worker exits while handling `tools/call`; `ERR_STAGE_BUDGET_PRE_PARSE` is raised by `validate-mixin` when a pre-parse stage exhausts its soft-deadline; `ERR_WORKSPACE_VERSION_UNRESOLVED` / `ERR_DEPENDENCY_VERSION_UNRESOLVED` carry structured `suggestedCall` payloads for caller-side recovery; `ERR_BATCH_ABORTED` (HTTP 412) fills un-started slots in batch tools when `failFast: true` and an earlier entry already failed.
+- `validate-mixin` now reports `result.targetOutcomes[]` (per-target `status: "ok" | "deferred-budget" | "tool-issue"` plus optional `slowTarget` / `elapsedMs` / `budgetMs`) and `summary.targetsDeferredBudget` / `summary.degradedReason: "stage-budget" | "stage-budget-pre-target"` so callers can distinguish completed work from work skipped by the soft-deadline.
+- `meta.restart` (synthetic worker-restart responses only) carries `tool` / `durationMs` / `lastStage` / `lastStageElapsedMs` / `lastStageMeta` / `exit` / `retryRecommendation` for caller diagnostics. `meta.stageBudgetExhausted` / `meta.budgetMs` / `meta.elapsedMs` accompany `ERR_STAGE_BUDGET_PRE_PARSE` error envelopes so callers can detect budget-driven failures from the public envelope without parsing the message string.
+- `validate-mixin` batch-mode results (`paths` / `config` / `project`) now preserve typed AppError metadata on per-entry errors: each `results[i]` carries optional `errorCode` and `errorDetails` (`failedStage`, `stageBudgetExhausted`, `budgetMs`, `elapsedMs`, …) so callers can distinguish budget-driven failures from generic per-file processing errors.
+- `target.kind="workspace"` is now accepted by `resolve-artifact`, `get-class-source`, and `get-class-members`. The synthesizer reads `gradle.properties` and `build.gradle(.kts)` from `projectPath` to detect Minecraft version, compile mapping, and loader, then rewrites the call to the resolved `target.kind="version"` shape. Detected facts and a `cacheHit` flag surface on `provenance.workspaceResolution`.
+- `target.kind="dependency"` (with optional `versionFromProject`) is now accepted by the same three tools. It probes four de-duplicated `gradle.properties` keys (`name_version`, `camelCaseVersion`, `group_name_version`, `groupNameVersion`) and falls back to `~/.gradle/caches/modules-2/files-2.1/<group>/<name>/`, picking the semver-newest non-snapshot. Dependency JARs disable the Mojang binary-remap path; mapping mismatches between the caller's `mapping` and the artifact namespace surface as warnings instead of being remapped.
+- `provenance.workspaceResolution` and `provenance.dependencyResolution` are emitted whenever the new target kinds are used. The new target kinds and the `manage-cache` workspace integration are scoped to the three tools whose input shape carries a `target` field; `find-class`, `search-class-source`, `list-artifact-files`, and `find-mapping` keep their existing `artifactId` / `version`-based shapes unchanged in this release.
+- `manage-cache` exposes a new `cacheKinds: "workspace"` for the in-memory `WorkspaceContextCache`. Listing returns one entry per cached `projectPath`; `delete` invalidates entries by `selector.projectPath`. `prune` / `rebuild` / `verify` are no-ops for this kind.
+- `ProblemDetails.exampleCalls?: Array<{ tool: string; params: Record<string, unknown>; reason: string }>` — additive always-valid fallback emitted when the primary `suggestedCall` payload fails the schema-validation gate. Each entry already passed `getToolSchema(tool).safeParse(params)` at construction time and is safe for the agent to re-call as-is. Construction sites supply alternatives via the `examples: [{ params, reason }]` argument to `buildSuggestedCall(...)`.
+- `tool-schema-registry` runtime registry (internal module exporting `registerToolSchema` / `getToolSchema` / `validateToolParams` / `listRegisteredTools`) populated at server startup from the same zod schemas already used by the `server.tool(...)` registrations. Powers the new `suggestedCall` validation gate; a registry-completeness test in `tests/tool-schema-registry.test.ts` asserts every tool name from `EXPECTED_TOOLS` has a registered schema.
+- `batch-class-source`, `batch-class-members`, `batch-symbol-exists`, and `batch-mappings` (4 new tools) read source / list members / probe symbol existence / translate mappings for fixed shortlists (1..50 entries) in a single call. Each batch shares one resolved artifact (`summary.sharedArtifactId`) instead of paying N artifact-resolution round-trips, dispatches per entry through the existing bounded worker pool (`concurrency: 1..8`, default 4), and returns a per-entry `{ index, status: "ok" | "error", result?, error?, warnings, durationMs }` envelope plus an aggregate `summary: { total, ok, error }`. `failFast: true` halts dispatch on the first entry error — un-started entries are returned with `error.code === "ERR_BATCH_ABORTED"` while in-flight workers complete (no AbortSignal wiring). `compact: true` (default) applies the matching single-tool's compact projection per entry. Per-entry errors carry a `suggestedCall` proposing the matching single tool (`get-class-source` / `get-class-members` / `check-symbol-exists` / `find-mapping`) with the shared artifact threaded through; the suggestion is validated through the same schema gate as single-tool errors. `batch-symbol-exists` accepts only `target.kind="workspace" | "version"` because library/coordinate/jar artifacts carry library versions, not Minecraft versions, which would corrupt the mapping query (rejected at the schema gate with `ERR_INVALID_INPUT`). `batch-mappings` requires top-level `version` (single-version batch); per-entry `version` is rejected as an unrecognized key. `batch-class-source` rejects duplicate `entries[].outputFile` values at the schema gate with `ERR_INVALID_INPUT` (`fieldErrors[0].path === "entries.<i>.outputFile"`), since concurrent worker dispatch would otherwise race on the same file. The shared envelope, `failFast` semantics, per-entry retry mapping, and disabled-tool envelope shape are documented in the new `Batch lookup contract` section of `docs/tool-reference.md`. Set `BATCH_TOOLS_OFF=1` to remove all four tools from `tools/list` (rollback path); direct calls then return the SDK "Tool not found" tool-result envelope (`{ content: [{ type: "text", text: "MCP error -32602: Tool <name> not found" }], isError: true }`), so callers cannot rely on `error.code === "ERR_*"` while the toggle is set.
+
+### Changed
+- `ERR_MAPPING_NOT_APPLIED` now returns a `suggestedCall` of `{ target: { kind: "workspace" }, projectPath, mapping: <detected> }` whenever `projectPath` is supplied, the workspace's compile mapping is non-obfuscated, the failed target was `target.kind="version"`, AND the workspace's detected `minecraftVersion` matches the failed `value`. Coordinate, jar, synthesized dependency failures, and version-mismatched workspaces all keep the legacy obfuscated retry so the suggested retry never silently redirects to a different artifact. Cache hits short-circuit; cache misses now run bounded detection of both compile mapping and Minecraft version (build.gradle / gradle.properties reads only) before deciding whether to suggest the workspace retry. Set `WORKSPACE_FALLBACK_LEGACY=1` to restore the previous obfuscated retry shape.
+- `target.kind="workspace"` now honors a top-level `scope` field. The precedence is `target.scope` → top-level `scope` → loader-derived default (`merged` when a loader is detected, otherwise `vanilla`); previously the loader-derived default silently shadowed the caller's top-level `scope`.
+- Dependency targets (`target.kind="dependency"`) no longer fail with `ERR_MAPPING_NOT_APPLIED` when the caller asks for `mojang` / `intermediary` / `yarn` against a binary-only artifact. The synthesizer keeps `forceBinaryRemapDisabled=true`, but the resolver now bypasses Mojang remap enforcement on dependency-origin failures, returns the JAR with `mappingApplied: "obfuscated"` and `qualityFlags: ["dependency-mapping-unverified"]`, and surfaces a warning that the requested mapping is not enforced. Callers MUST treat the artifact as namespace-unknown and validate symbol availability themselves; `mappingApplied` is no longer fabricated to the requested mapping value.
+- `target.kind="dependency"` now rejects unsafe Maven version tokens before synthesizing the coordinate. `gradle.properties` values that contain path separators, `..`, NUL, control characters, or any character outside `[A-Za-z0-9._+-]` are filtered out (the next configured property key is tried instead, with the rejection recorded under `attempts[]` as `gradle.properties:<key>:rejected-unsafe-version`). Modules-2 directory entries that fail the same validation are excluded from candidates. Explicit `target.version` strings that fail validation raise `ERR_INVALID_INPUT` with `fieldErrors[0].path === "target.version"`.
+- `target.kind="workspace"` no longer falls back to the latest stable Minecraft version when `gradle.properties` does not declare one. Both `strict: true` and `strict: false` now raise `ERR_WORKSPACE_VERSION_UNRESOLVED` when the workspace version cannot be detected, so callers cannot silently resolve and index the wrong Minecraft API surface. The `details.strict` flag records which strict value was supplied.
+- `target.kind="dependency"` no longer picks the semver-newest entry when `~/.gradle/caches/modules-2/files-2.1/<group>/<name>/` contains multiple cached versions. The synthesizer now raises `ERR_DEPENDENCY_VERSION_UNRESOLVED` with `details.ambiguous=true` and `details.candidatesSeen[]` enumerating the cached versions, so a global cache populated by unrelated projects cannot resolve a version the workspace does not actually use. Single-entry caches and `gradle.properties` matches keep their previous behavior.
+- `get-class-members` now passes the caller's raw `mapping` (preserving `undefined`) into the resolver, mirroring `get-class-source`. A workspace target with an omitted `mapping` now resolves through the workspace's detected compile mapping instead of the obfuscated normalization, eliminating the silent obfuscated-result regression.
+- When the worker process exits while handling `tools/call`, the supervisor returns a structured `{ error, meta }` envelope (synthetic `CallToolResult` with `isError: true`) instead of the previous raw JSON-RPC `-32603` error. Non-`tools/call` requests (`initialize`, `tools/list`, etc.) still receive the legacy envelope.
+- `validate-mixin` runs each stage against an independent soft-deadline. When the `target-lookup` stage exhausts its budget mid-loop, the response is `validationStatus: "partial"` with completed targets retained and remaining ones recorded as `deferred-budget`. Pre-parse stages that exhaust their budget surface as `ERR_STAGE_BUDGET_PRE_PARSE` errors.
+- `validate-mixin` budget-driven partial results no longer trigger the `loom-first → maven-first` retry heuristic. The retry path targets mapping infrastructure failures, not soft-deadline cuts; without this guard a stage-budget partial would re-run the full validation under `maven-first` and defeat the cooperative-deadline contract.
+- `stdio-supervisor` records one worker-exit timestamp per `tool` per actual exit, regardless of how many concurrent `tools/call` requests were in flight. Per-pending-request recording inflated `recentRestarts` to N for a single crash and produced false `retryRecommendation: "report-bug"` under concurrent load.
+- `validate-mixin` `targetOutcomes[]` now emits the `tool-issue` status with a `reason` for completed-but-unreliable targets (mapping / signature / remap failures). Previously the per-target outcome was unconditionally `status: "ok"` even when the underlying target classified as `validation-incomplete`, hiding per-target failures from `includeIssues=false` callers. Whole member-remap exceptions (the entire batch failing) now also flag the target as `tool-issue` with `reason: "member-remap-failed-whole"`; previously only per-member remap failures triggered the classifier.
+- `stdio-supervisor` `lastStageStartedAt` is now refreshed only when the worker emits a different stage name (or on the first emit). Per-target progress notifications during `target-lookup` no longer reset the stage timer, so synthetic worker-restart envelopes report `meta.restart.lastStageElapsedMs` measured from stage entry — not from the most recent per-target update — restoring the documented diagnostic contract.
+- `validate-mixin` now enforces the `inputValidation` stage budget (default 5_000 ms): a slow `sourcePath` read, version normalization, or related input-stage I/O surfaces as `ERR_STAGE_BUDGET_PRE_PARSE` with `failedStage: "input-validation"` instead of hanging the call. Previously the budget was declared in `MixinStageBudgets` but never checked.
+- Synthetic worker-restart envelopes no longer expose `error.suggestedCall` when redaction modified the captured tool arguments (truncated long strings, redacted secret-bearing keys, or trimmed arrays / objects). The redacted form is still emitted on the diagnostic-only `meta.restart.redactedToolArgs` field along with `meta.restart.redactedToolArgsModified` so debug surfaces can inspect the placeholder values without granting them retry semantics.
+- Every `ProblemDetails.suggestedCall` payload an agent receives is now validated against the registered zod schema for the named tool BEFORE leaving the process. Invalid payloads (e.g. the bug shape where `target.value` held a JSON-stringified inner target, producing chained `ERR_INVALID_INPUT` on retry) are dropped from the published envelope; when the gate drops a primary suggestion, `error.hints` gains the literal sentence `"suggested call payload failed schema validation; using fallback examples"` so the caller can observe the elision. Construction sites can pass `examples: [{ params, reason }]` to the new `buildSuggestedCall(...)` helper to surface always-valid fallbacks via `error.exampleCalls[]`. `suggestedCall.params` is published byte-identical to the caller-supplied object — the gate never injects schema defaults into the published payload. Set `SUGGESTED_CALL_VALIDATE_OFF=1` at process start to bypass the gate entirely (raw payloads pass through; the fallback hint is not added) as an emergency rollback path.
+- The `validate-mixin` issue construction (`mixin-validator.ts` × 6 sites) and the supervisor's worker-restart envelope synthesis (`stdio-supervisor.ts` × 1 site) now route their result-level `suggestedCall` payloads through the same `buildSuggestedCall(...)` schema gate as error-side suggestions. Previously these 7 assignment-style construction sites (`obj.suggestedCall = { tool, params }`) bypassed the gate's literal-only invariant test, so a malformed payload would have been published unchanged. The invariant test (`tests/suggested-call-invariant.test.ts`) now also rejects assignment-style construction in `src/`, with `[literal]` / `[assign]` markers in offender reports.
+- `buildSyntheticCallToolResult` now skips the `suggestedCall` synthesis entirely when `ctx.toolName` is missing (the supervisor's `tool = ctx.toolName ?? "unknown"` fallback path). Previously the synthesized `tool: "unknown"` flowed through `buildSuggestedCall`'s fail-open unknown-tool branch and published a `suggestedCall: { tool: "unknown", params: {...} }` payload that was not re-callable by the agent — violating the gate's stated invariant. The diagnostic-only `meta.restart.redactedToolArgs` field still surfaces the args so debug surfaces can inspect them. The `buildSuggestedCall` helper's fail-open behavior for unregistered tools is preserved because many service-level tests exercise code without booting `src/index.ts` and expect the fail-open contract; the fix is targeted at the one production code path (the supervisor) that was actually leaking unre-callable payloads.
+- `batch-class-source`'s schema-level duplicate-`outputFile` guard now normalizes paths via `path.resolve` (mirroring the writer's `getClassSource` semantics) before comparing entries. Previously the guard keyed by `entry.outputFile.trim()` only, so semantically-equivalent aliases (`out.java` vs `./out.java` vs `dir/../out.java`) bypassed the check and concurrent writes still raced on the same physical file. The error message now cites the canonical resolved path so the user sees what collided.
+- `errorToBatchEntryProblem` for non-`AppError` failures now emits a fixed sanitized `detail: "Unexpected server error."` to clients (matching the single-tool `mapErrorToProblem` generic-error contract) and logs the raw message server-side (`log("error", "batch.entry.unhandled", { instance, reason })`) for diagnostics. Previously the public per-entry `error.detail` carried `Error.message` verbatim, which could expose internal filesystem paths, parser internals, or assertion text through the public envelope while the top-level batch call still returned a normal result envelope.
+- `buildSyntheticCallToolResult` now also drops `suggestedCall` when `ctx.toolName` is present but unregistered (typo, disabled tool, or version-skewed name from an older server run). The supervisor consults `getToolSchema` itself before invoking the gate; `buildSuggestedCall` continues to fail open for unregistered names by design (service-level tests that do not boot `src/index.ts` rely on the fail-open contract). The diagnostic-only `meta.restart.redactedToolArgs` field still surfaces the args.
+- Batch lookup `summary` now carries `sharedArtifactWarnings?: string[]` populated from the one-shot shared `resolveArtifact` call. Previously the resolution warnings (version approximation, mapping fallback, source coverage gaps, workspace/dependency resolution caveats) were captured into the batch service's local `SharedArtifact` object and discarded, while per-entry calls dispatched by `artifactId` never re-ran the resolution. The field is omitted when no warnings were produced. Applies to `batch-class-source`, `batch-class-members`, and `batch-symbol-exists`; `batch-mappings` does not run a shared artifact resolution and is unaffected.
+- `statusForErrorCode` now maps `ERR_STAGE_BUDGET_PRE_PARSE` to HTTP-style status 408 (Request Timeout). Previously the code fell through to status 500, misclassifying a controlled `validate-mixin` budget exhaustion (caller-recoverable via `mixinConfigPath` shrink, budget raise, or `MIXIN_STAGE_BUDGETS_OFF=1`) as an internal server failure.
+- `statusForErrorCode` now maps `ERR_WORKSPACE_VERSION_UNRESOLVED` and `ERR_DEPENDENCY_VERSION_UNRESOLVED` to HTTP-style status 422 (Unprocessable Entity). Previously they fell through to status 500, misclassifying a caller-recoverable input gap (caller can retry by passing `target.kind="version"` with an explicit Minecraft version, or by pointing `projectPath` at a workspace whose `gradle.properties` carries `minecraft_version`) as an internal server failure. `batch-symbol-exists` is the most likely surface for this gap because workspace targets without a detectable Minecraft version are the new path's primary failure mode.
+
+## [4.0.0] - 2026-04-18
+
+### Changed
+- BREAKING: `resolve-artifact`, `find-mapping`, `resolve-method-mapping-exact`, `resolve-workspace-symbol`, and `check-symbol-exists` now default `compact` to `true` (was `false`). Pass `compact: false` to restore the full diagnostic shape.
+- BREAKING: `find-mapping`, `resolve-method-mapping-exact`, `resolve-workspace-symbol`, `check-symbol-exists`, and `analyze-symbol` now default `maxCandidates` to `5` (was `200`; `200` is still the upper bound).
+- BREAKING: `find-mapping` now defaults `signatureMode` to `"name-only"` (was effectively `"exact"`). `kind="method"` lookups without a `descriptor` no longer fail; pass `signatureMode: "exact"` explicitly for strict descriptor matching.
+- BREAKING: `resolve-artifact` with `mapping="mojang"` and `target.kind="version"` against a still-obfuscated Minecraft version now succeeds by tiny-remapping the binary jar and decompiling the result, tagged `qualityFlags: ["binary-remapped", "decompiled"]` and `provenance.transformChain: ["binary-remap:obf->mojang", "decompile:vineflower"]`. The remapped jar is cached at `<cacheDir>/remapped/<artifactId>.jar`. Coordinate and jar targets are not eligible. `ERR_MAPPING_NOT_APPLIED` is still raised when tiny-remapper, the Mojang tiny mapping file, or the version's Mojang mappings are missing.
+- `find-mapping` and `check-symbol-exists` accept an empty `descriptor` as equivalent to omitting it.
+- Compact mode on mapping tools keeps the top three unresolved candidates with full metadata and slims the tail to `{kind, symbol, owner, name, descriptor, confidence, matchKind}`. A new `candidateDetailsTruncated` flag signals this slim, distinct from the existing `candidatesTruncated` (upstream truncation).
+
+### Added
+- `find-mapping` exposes `signatureMode` as a first-class input. `"exact"` matches `owner + name + descriptor`; `"name-only"` matches by `owner + name` and ranks overloads by confidence. `resolve-method-mapping-exact` retains strict exact-triple semantics.
+- `get-class-source`, `get-class-members`, `search-class-source`, and `list-artifact-files` accept an opt-in `compact` parameter (default `false`). It strips diagnostic envelopes (`provenance`, `artifactContents`, `qualityFlags`, plus `context` for `get-class-members`) while preserving primary payloads (`sourceText`, `members`/`counts`, `hits`, `items`).
+- `manage-cache` exposes the Mojang remapped jar under a new `binary-remap` cache kind with `selector.artifactId` filtering. LRU eviction unlinks the matching remapped jar so cache accounting stays consistent.
+- `validate-mixin` top-level errors now carry `failedStage` on the `ProblemDetails` envelope (one of `input-validation | resolve | mapping-health | parse | target-lookup`), so callers can branch without parsing `message`.
+- `validate-mixin` `quickSummary` appends notes when `provenance.scopeFallback` fires or `toolHealth.overallHealthy` is false.
+- Ambiguous mapping responses in `find-mapping`, `resolve-method-mapping-exact`, and `check-symbol-exists` include recovery guidance in `warnings` (descriptor hints, `signatureMode="exact"` retries, `disambiguation.ownerHint`, raising `maxCandidates`).
+- `docs/tool-reference.md` includes a "Which Tool for Which Question" decision table; `README.md` links to it from the Documentation section.
+
+### Fixed
+- `check-symbol-exists` projects the caller's JVM descriptor to the obfuscated namespace before filtering method overloads, so `signatureMode="exact"` retries work with descriptors that reference remapped Minecraft classes. Mixed descriptors such as `(Lnet/minecraft/world/item/ItemStack;Ljava/lang/String;)V` resolve via partial projection instead of falling back to the unprojected source descriptor.
+- `find-mapping` with `signatureMode="exact"` and `kind="method"` filters resolved candidates by the (projected) requested descriptor. A caller who supplied `foo(Z)V` is no longer told that `foo(I)V` is the exact mapping.
+- Compact mode slim candidate projection retains `kind` and `symbol` alongside `owner`, `name`, `descriptor`, `confidence`, and `matchKind`, so clients keying off `kind` or `symbol` are no longer silently broken.
+- `normalizeMethodDescriptor` rejects descriptors with more than 255 leading `[` (JVM §4.3.2) and rejects malformed shapes such as `()`, `(I)`, and `(L;)V` with `ERR_INVALID_INPUT`.
+
 ## [3.2.0] - 2026-04-12
 
 ### Added

package/README.md

@@ -5,26 +5,27 @@
 [![Node.js >=22](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)](https://nodejs.org/)
 [![CI](https://github.com/adhi-jp/minecraft-modding-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/adhi-jp/minecraft-modding-mcp/actions/workflows/ci.yml)
 
-**[日本語](docs/README-ja.md)** | English
+**English** | [日本語](docs/README-ja.md)
+
+> **Note**: This project is entirely vibe-coded — built with AI-assisted development without formal specs.
 
 ---
 
-`@adhisang/minecraft-modding-mcp` is an [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that gives AI assistants structured access to Minecraft source code, mappings, mod JARs, registry data, and validation workflows.
+`@adhisang/minecraft-modding-mcp` is an MCP server for AI-assisted Minecraft modding workflows, built on the [Model Context Protocol](https://modelcontextprotocol.io/). Use it when an agent needs to inspect Minecraft source, resolve mappings, compare versions, analyze mod JARs, validate Mixin, Access Widener, or Access Transformer files, or work with NBT and registry data from an MCP client.
 
-[MCP](https://modelcontextprotocol.io/) is an open protocol that lets AI assistants call external tools through a structured interface. This server works with Claude Desktop, Claude Code, VS Code, Codex CLI, Gemini CLI, and other MCP-capable clients.
+It runs over stdio and works with Claude Desktop, Claude Code, VS Code, Codex CLI, Gemini CLI, and other MCP-capable clients.
 
-**35 tools** (6 entry + 29 expert) | **7 resources** | **4 namespace mappings** | **SQLite-backed cache**
+**37 tools** (6 entry + 31 expert) | **7 resources** | **4 namespace mappings** | **SQLite-backed cache**
 
 ## Features
 
-- **Source Exploration**: browse and search decompiled Minecraft source code with line-level precision and cursor-paginated file listing
-- **Multi-Mapping Conversion**: translate class, field, and method names between `obfuscated`, `mojang`, `intermediary`, and `yarn`
-- **Version Comparison**: diff class signatures and registry entries between Minecraft versions
-- **Mod JAR Analysis**: extract metadata, dependencies, entrypoints, Mixin configs, and packaged Access Transformer paths from Fabric, Forge, and NeoForge mod JARs
-- **Mixin, Access Widener, and Access Transformer Validation**: validate source, `.accesswidener`, and Forge/NeoForge access transformer files against a target Minecraft version
-- **NBT Round-Trip**: decode NBT binary to typed JSON, apply RFC 6902 patches, and encode it back to NBT
-- **Registry Data and Runtime Metrics**: query generated registry snapshots and inspect cache and latency counters
-- **MCP Resources**: expose versions, class source, artifact metadata, and mappings through URI-based resources
+- **Source exploration**: browse, list, and search decompiled Minecraft source with line-level context
+- **Mapping-aware symbol work**: convert class, field, and method names between `obfuscated`, `mojang`, `intermediary`, and `yarn`
+- **Version comparison**: compare class signatures, registry entries, and migration-oriented summaries across Minecraft versions
+- **Mod JAR analysis**: read Fabric, Forge, and NeoForge metadata, entrypoints, Mixin configs, dependencies, source, and remap previews
+- **Project validation**: validate Mixin source, `.accesswidener` files, and Forge/NeoForge Access Transformer files against the target version
+- **NBT, registry, cache, and diagnostics**: patch NBT payloads, inspect generated registry data, and manage cache/runtime state
+- **MCP resources**: expose versions, class source, artifact metadata, and mappings through URI-based resources
 
 ## Quick Start
 
@@ -41,18 +42,27 @@ Start the server locally:
 npx -y @adhisang/minecraft-modding-mcp
 ```
 
-If automatic JAR downloads are blocked in your environment, set `MCP_VINEFLOWER_JAR_PATH` and `MCP_TINY_REMAPPER_JAR_PATH` in the client configuration.
+Use this same command in MCP client configs. If automatic JAR downloads are blocked in your environment, set `MCP_VINEFLOWER_JAR_PATH` and `MCP_TINY_REMAPPER_JAR_PATH` there.
 
 ### Client Setup
 
-CLI clients:
+CLI clients can register the package command directly.
+
+Claude Code:
 
-- `Claude Code`: `claude mcp add minecraft-modding -- npx -y @adhisang/minecraft-modding-mcp`
-- `OpenAI Codex CLI`: `codex mcp add minecraft-modding -- npx -y @adhisang/minecraft-modding-mcp`
+```bash
+claude mcp add minecraft-modding -- npx -y @adhisang/minecraft-modding-mcp
+```
+
+OpenAI Codex CLI:
+
+```bash
+codex mcp add minecraft-modding -- npx -y @adhisang/minecraft-modding-mcp
+```
 
 Run `claude mcp list` or `codex mcp list` after registration to verify the server is available.
 
-The stdio transport auto-detects both newline-delimited and `Content-Length` framing, so the same server command works across Codex and standard MCP clients.
+The stdio transport auto-detects newline-delimited and `Content-Length` framing, so the same server command works across Codex and standard MCP clients.
 
 #### Claude Desktop
 
@@ -126,9 +136,9 @@ Pass environment variables to override defaults:
 
 ## Start Here
 
-These six top-level workflow tools cover the common workflows and return summary-first results, so they are the best default starting points for agents and MCP clients.
+These six top-level workflow tools cover the common paths and return summary-first results. They are the best default starting points for agents and MCP clients.
 
-All six return `result.summary` first, and can include `summary.nextActions` when there is a clear follow-up step. Use the table for tool selection, then use the examples and reference docs for exact payloads.
+All six return `result.summary` first and can include `summary.nextActions` when there is a clear follow-up step. Pick the tool from the table, then use the examples and reference docs for exact payloads.
 
 | Tool | Start here for |
 | --- | --- |
@@ -141,16 +151,14 @@ All six return `result.summary` first, and can include `summary.nextActions` whe
 
 ### Workflow Notes
 
-Keep only the high-frequency notes here. For the full pitfall list, exact contract details, migration notes, and environment variables, see [docs/tool-reference.md](docs/tool-reference.md).
+These notes cover high-frequency decisions during onboarding. For the full pitfall list, exact contracts, migration notes, and environment variables, see [docs/tool-reference.md](docs/tool-reference.md).
 
 - `search-class-source` defaults to `queryMode="auto"` and keeps separator queries such as `foo.bar`, `foo_bar`, and `foo$bar` on the indexed path. Use `queryMode="literal"` for an explicit full substring scan.
 - If you do not already have an artifact, prefer `subject.kind="workspace"` for `inspect-minecraft` instead of guessing artifact details. When artifact context is the only missing input, a retryable `suggestedCall` preserves the requested task.
 - `trace-symbol-lifecycle` expects `Class.method` in `symbol`. Keep exact overload matching in the separate `descriptor` field.
-- Workspace inspection can still confirm vanilla classes when source coverage is partial, and `inspect-minecraft task="list-files"` reports a partial result with follow-up guidance when that happens.
-- `check-symbol-exists` and `analyze-symbol task="exists"` now validate `mojang` lookups on unobfuscated releases such as `26.1+` against runtime bytecode when no mapping graph exists, preserve the original `mapping_unavailable` result if the runtime JAR itself cannot be resolved, and return a targeted warning when callers provide only a short class name.
-- `analyze-mod` and `validate-project` still require structured `subject` objects and canonical `include` groups, but stale string-subject or domain-include payloads now return `ERR_INVALID_INPUT` with a retryable `suggestedCall`.
-- `validate-project task="project-summary"` now pre-resolves `preferProjectVersion=true` consistently across discovered Access Widener, Access Transformer, and Mixin checks, and blocks with version-agnostic recovery guidance when discovered validators need a version but neither the request nor `gradle.properties` can supply one.
-- Local source-jar probing, decompiled mod source reads, and workspace discovery now avoid synchronous hot-path ZIP/file scans and use bounded concurrent reads where safe, so cold `resolve-artifact`, `analyze-mod`, and `validate-project` workflows stay more responsive on larger jars and multi-module workspaces.
+- For unobfuscated releases such as `26.1+`, `check-symbol-exists` and `analyze-symbol task="exists"` validate `mojang` lookups against runtime bytecode when no mapping graph exists, and return `mapping_unavailable` when the runtime JAR itself is unreachable.
+- `analyze-mod` and `validate-project` require structured `subject` objects and canonical `include` groups; stale string-subject or domain-include payloads return `ERR_INVALID_INPUT` with a retryable `suggestedCall`.
+- `validate-project task="project-summary"` propagates `preferProjectVersion=true` across discovered Mixin, Access Widener, and Access Transformer checks. If no version can be resolved from the request or `gradle.properties`, the summary returns recovery guidance instead of guessing.
 
 ### Inspect Minecraft source from a version
 
@@ -232,7 +240,7 @@ Workspace summaries still default to discovering mixins and access wideners. Add
 ## Documentation
 
 - [Detailed example requests](docs/examples.md) for copyable payloads and common workflows
-- [Tool and configuration reference](docs/tool-reference.md) for exact inputs, outputs, resource behavior, environment variables, and migration notes
+- [Tool and configuration reference](docs/tool-reference.md) for exact inputs, outputs, resource behavior, environment variables, and migration notes. Start with the [Which Tool for Which Question](docs/tool-reference.md#which-tool-for-which-question) decision table when you are not sure which tool to call.
 - [日本語 README](docs/README-ja.md) for a Japanese onboarding overview
 
 ## Tool Surface
@@ -270,7 +278,7 @@ Tools for browsing Minecraft versions, resolving source artifacts, and reading o
 | `index-artifact` | Rebuild indexed metadata for an existing artifact |
 <!-- END GENERATED TOOL TABLE: source-exploration -->
 
-For unobfuscated releases such as `26.1+`, `mapping="mojang"` now uses the runtime/decompile path directly for version and versioned-coordinate targets and skips Loom source-jar discovery entirely, while `intermediary` and `yarn` still fall back to `obfuscated` with a warning.
+For unobfuscated releases such as `26.1+`, `mapping="mojang"` uses the runtime/decompile path directly and skips Loom source-jar discovery, while `intermediary` and `yarn` fall back to `obfuscated` with a warning.
 
 ### Version Comparison & Symbol Tracking
 
@@ -298,7 +306,7 @@ Tools for converting symbol names between namespaces and checking symbol existen
 | `check-symbol-exists` | Check whether a class, field, or method exists in a namespace |
 <!-- END GENERATED TOOL TABLE: mapping-symbols -->
 
-`resolve-artifact`, `find-mapping`, `resolve-method-mapping-exact`, `resolve-workspace-symbol`, and `check-symbol-exists` accept an optional `compact` parameter (default `false`). When `true`, empty arrays, null values, and empty objects are stripped from the top-level response to reduce token overhead. For `resolve-artifact`, compact mode additionally omits diagnostic fields (`provenance`, `artifactContents`, `sampleEntries`, `adjacentSourceCandidates`, `binaryJarPath`, `coordinate`, `repoUrl`, `resolvedSourceJarPath`), returning only the essential fields needed for downstream tool calls. For mapping tools, compact mode omits the redundant `candidates` array when the result is a single full-confidence exact-match resolution (`resolved=true`, `resolvedSymbol` present, `candidates.length=1`, `candidateCount=1`, `!candidatesTruncated`, `matchKind="exact"`, `confidence` missing or `1`).
+Several lookup tools support `compact` result shaping for shorter responses. See [docs/tool-reference.md](docs/tool-reference.md) for defaults and the full per-tool field list.
 
 ### NBT Utilities
 
@@ -328,16 +336,15 @@ Tools for extracting metadata from mod JARs, decompiling mod source, searching m
 
 ### Validation
 
-Tools for validating Mixin source, Access Widener files, and Forge/NeoForge Access Transformer files against a target Minecraft version.
-`validate-access-widener` keeps vanilla bytecode validation by default, and now also supports runtime-aware validation through `projectPath`, `scope`, and `preferProjectVersion`, returning runtime `provenance` plus per-entry `resolvedRuntimeAccess` evidence when that mode is used. Runtime-aware method validation now preserves remapped JVM descriptors across namespace changes, searches Loom tiny mappings from workspace and Gradle user-home caches, and prefers explicit `*merged-intermediary*` / `*merged-mojang*` jars over ambiguous `minecraft-merged.jar` candidates.
-`validate-access-transformer` infers `atNamespace` from Forge or NeoForge workspace context when `projectPath` is provided, validates packaged or inline AT content, and uses loader/runtime artifacts for `scope="loader"` instead of treating loader as a merged-only alias.
+Tools for validating Mixin source, Access Widener files, and Forge/NeoForge Access Transformer files against a target Minecraft version. Workspace options let validation use loader/runtime context when a project path is available.
 
 <!-- BEGIN GENERATED TOOL TABLE: validation -->
 | Tool | Purpose |
 | --- | --- |
-| `validate-mixin` | Validate Mixin source against a target Minecraft version |
+| `validate-mixin` | Validate Mixin source against a target Minecraft version (returns `validationStatus: "partial"` with `targetOutcomes` when a stage budget defers work) |
 | `validate-access-widener` | Validate Access Widener content against a target Minecraft version, optionally using runtime-aware Loom artifacts |
 | `validate-access-transformer` | Validate Access Transformer content against a target Minecraft version, optionally using Forge/NeoForge runtime artifacts |
+| `verify-mixin-target` | Single-call probe for owner / member existence with `@Shadow` / `@Accessor` / `@Invoker` advice |
 <!-- END GENERATED TOOL TABLE: validation -->
 
 ### Registry & Diagnostics
@@ -351,6 +358,19 @@ Tools for querying generated registry data and inspecting server runtime state.
 | `get-runtime-metrics` | Inspect runtime metrics and latency snapshots |
 <!-- END GENERATED TOOL TABLE: registry-diagnostics -->
 
+### Batch Lookup
+
+Tools that share one resolved artifact or Minecraft version across a fixed shortlist. Results include one status per item plus an aggregate `summary`. See [Batch lookup contract](docs/tool-reference.md#batch-lookup-contract) for failure handling and retry mapping.
+
+<!-- BEGIN GENERATED TOOL TABLE: batch-lookup -->
+| Tool | Purpose |
+| --- | --- |
+| `batch-class-source` | Read source for many classes against one shared resolved artifact (1..50 entries per call) |
+| `batch-class-members` | List members for many classes against one shared resolved artifact (1..50 entries per call) |
+| `batch-symbol-exists` | Probe symbol existence for many entries against one shared Minecraft-version artifact (workspace / version targets only) |
+| `batch-mappings` | Translate many symbols across mapping namespaces with one shared Minecraft version (no shared artifact) |
+<!-- END GENERATED TOOL TABLE: batch-lookup -->
+
 Detailed parameter constraints, migration notes, resource behavior, and the full environment-variable matrix live in [docs/tool-reference.md](docs/tool-reference.md).
 
 ## Development

package/dist/build-suggested-call.d.ts

@@ -0,0 +1,29 @@
+export declare const SUGGESTED_CALL_VALIDATE_OFF: boolean;
+export type SuggestedCallExample = {
+    params: unknown;
+    reason: string;
+};
+export type SuggestedCallSpec = {
+    tool: string;
+    params: unknown;
+    examples?: SuggestedCallExample[];
+};
+export type ValidatedSuggestedCall = {
+    tool: string;
+    params: Record<string, unknown>;
+};
+export type ValidatedExampleCall = {
+    tool: string;
+    params: Record<string, unknown>;
+    reason: string;
+    valid: true;
+};
+export type SuggestedCallOutput = {
+    suggestedCall?: ValidatedSuggestedCall;
+    exampleCalls?: ValidatedExampleCall[];
+    /** Set to `true` when the caller supplied `params` but the gate dropped it.
+     * Spread into AppError `details`; `mapErrorToProblem` reads the marker to
+     * append the fallback hint to `error.hints` and strips it before emission. */
+    _suggestedCallPrimaryDropped?: true;
+};
+export declare function buildSuggestedCall(spec: SuggestedCallSpec): SuggestedCallOutput;

package/dist/build-suggested-call.js

@@ -0,0 +1,58 @@
+import { getToolSchema, validateToolParams } from "./tool-schema-registry.js";
+export const SUGGESTED_CALL_VALIDATE_OFF = process.env.SUGGESTED_CALL_VALIDATE_OFF === "1";
+function asParamsRecord(params) {
+    if (typeof params !== "object" || params === null || Array.isArray(params)) {
+        return undefined;
+    }
+    return params;
+}
+export function buildSuggestedCall(spec) {
+    if (SUGGESTED_CALL_VALIDATE_OFF) {
+        const rawParams = asParamsRecord(spec.params);
+        if (rawParams) {
+            return { suggestedCall: { tool: spec.tool, params: rawParams } };
+        }
+        return {};
+    }
+    const primaryParams = asParamsRecord(spec.params);
+    if (primaryParams) {
+        // Unknown-tool fail-open: the registry is populated at index.ts startup;
+        // service-level tests that do not boot index.ts run with an empty
+        // registry and rely on this pass-through. Callers that synthesize a tool
+        // name from runtime data (e.g. `?? "unknown"`) MUST skip this helper, or
+        // a non-callable payload escapes via this branch.
+        if (!getToolSchema(spec.tool)) {
+            return { suggestedCall: { tool: spec.tool, params: primaryParams } };
+        }
+        const primary = validateToolParams(spec.tool, primaryParams);
+        if (primary.valid) {
+            return { suggestedCall: { tool: spec.tool, params: primaryParams } };
+        }
+    }
+    const droppedMarker = spec.params !== undefined ? { _suggestedCallPrimaryDropped: true } : {};
+    if (spec.examples && spec.examples.length > 0) {
+        const validated = spec.examples
+            .map((example) => {
+            const exampleParams = asParamsRecord(example.params);
+            if (!exampleParams) {
+                return null;
+            }
+            const result = validateToolParams(spec.tool, exampleParams);
+            if (!result.valid) {
+                return null;
+            }
+            return {
+                tool: spec.tool,
+                params: exampleParams,
+                reason: example.reason,
+                valid: true
+            };
+        })
+            .filter((entry) => entry !== null);
+        if (validated.length > 0) {
+            return { exampleCalls: validated, ...droppedMarker };
+        }
+    }
+    return droppedMarker;
+}
+//# sourceMappingURL=build-suggested-call.js.map

package/dist/cache-registry.d.ts

@@ -1,5 +1,6 @@
 import { type PathRuntimeInfo } from "./path-converter.js";
-export declare const PUBLIC_CACHE_KINDS: readonly ["artifact-index", "downloads", "mapping", "registry", "decompiled-source", "mod-remap"];
+import { type WorkspaceContextCache } from "./workspace-context-cache.js";
+export declare const PUBLIC_CACHE_KINDS: readonly ["artifact-index", "downloads", "mapping", "registry", "decompiled-source", "mod-remap", "binary-remap", "workspace"];
 export type PublicCacheKind = (typeof PUBLIC_CACHE_KINDS)[number];
 export declare const CACHE_HEALTH_STATES: readonly ["healthy", "partial", "stale", "orphaned", "corrupt", "in_use"];
 export type CacheHealthState = (typeof CACHE_HEALTH_STATES)[number];
@@ -37,6 +38,7 @@ export type CacheRegistryConfig = {
     cacheDir: string;
     sqlitePath: string;
     pathRuntimeInfo?: PathRuntimeInfo;
+    workspaceContextCache?: WorkspaceContextCache;
 };
 export interface CacheRegistry {
     summarize(input: {

package/dist/cache-registry.js

@@ -4,13 +4,16 @@ import { join, resolve } from "node:path";
 import { createError, ERROR_CODES } from "./errors.js";
 import { normalizeOptionalPathForHost } from "./path-converter.js";
 import Database from "./storage/sqlite.js";
+import { getProcessWorkspaceContextCache } from "./workspace-context-cache.js";
 export const PUBLIC_CACHE_KINDS = [
     "artifact-index",
     "downloads",
     "mapping",
     "registry",
     "decompiled-source",
-    "mod-remap"
+    "mod-remap",
+    "binary-remap",
+    "workspace"
 ];
 export const CACHE_HEALTH_STATES = [
     "healthy",
@@ -37,6 +40,10 @@ function kindRoot(config, cacheKind) {
             return join(config.cacheDir, "decompiled");
         case "mod-remap":
             return join(config.cacheDir, "remapped-mods");
+        case "binary-remap":
+            return join(config.cacheDir, "remapped");
+        case "workspace":
+            return "<in-memory:workspace-context-cache>";
     }
 }
 async function listFilesRecursive(root) {
@@ -414,6 +421,26 @@ async function artifactIndexEntries(config) {
         db.close();
     }
 }
+function workspaceCacheEntries(workspaceCache) {
+    const contexts = workspaceCache.list();
+    return contexts.map((ctx) => ({
+        cacheKind: "workspace",
+        entryId: ctx.projectPath,
+        path: ctx.projectPath,
+        sizeBytes: 0,
+        status: "healthy",
+        meta: {
+            projectPath: ctx.projectPath,
+            minecraftVersion: ctx.minecraftVersion,
+            compileMapping: ctx.compileMapping,
+            loader: ctx.loader,
+            detectedAt: new Date(ctx.detectedAt).toISOString(),
+            updatedAt: new Date(ctx.detectedAt).toISOString(),
+            partial: ctx.partial === true,
+            dependencyVersionCount: ctx.dependencyVersions.size
+        }
+    }));
+}
 async function fileBackedEntries(config, cacheKind) {
     const root = kindRoot(config, cacheKind);
     const files = await listFilesRecursive(root);
@@ -439,25 +466,37 @@ async function fileBackedEntries(config, cacheKind) {
                 inUse: filePath.endsWith(".lock") ||
                     filePath.endsWith(".wal") ||
                     filePath.endsWith(".journal"),
-                ...(cacheKind === "downloads" || cacheKind === "mod-remap" ? { jarPath: filePath } : {})
+                ...(cacheKind === "downloads" || cacheKind === "mod-remap" || cacheKind === "binary-remap"
+                    ? { jarPath: filePath }
+                    : {}),
+                ...(cacheKind === "binary-remap"
+                    ? { artifactId: normalizedEntryId.replace(/\.jar$/i, "") }
+                    : {})
             }
         });
     }
     return entries;
 }
 export function createCacheRegistry(config) {
+    const workspaceCache = config.workspaceContextCache ?? getProcessWorkspaceContextCache();
     async function collectEntries(cacheKinds, selector) {
         const selectedKinds = cacheKinds?.length ? cacheKinds : [...PUBLIC_CACHE_KINDS];
         const preparedSelector = prepareSelector(selector, config.pathRuntimeInfo);
         const now = Date.now();
-        const entries = await Promise.all(selectedKinds.map((cacheKind) => cacheKind === "artifact-index"
-            ? artifactIndexEntries(config)
-            : fileBackedEntries(config, cacheKind)));
+        const entries = await Promise.all(selectedKinds.map((cacheKind) => {
+            if (cacheKind === "artifact-index") {
+                return artifactIndexEntries(config);
+            }
+            if (cacheKind === "workspace") {
+                return Promise.resolve(workspaceCacheEntries(workspaceCache));
+            }
+            return fileBackedEntries(config, cacheKind);
+        }));
         const enriched = entries
             .flat()
             .map((entry) => ({
             ...entry,
-            status: deriveEntryStatus(entry, config, now)
+            status: entry.cacheKind === "workspace" ? entry.status : deriveEntryStatus(entry, config, now)
         }));
         return sortEntries(enriched.filter((entry) => matchesSelector(entry, preparedSelector, config.pathRuntimeInfo)));
     }
@@ -467,8 +506,17 @@ export function createCacheRegistry(config) {
             const entries = await collectEntries(selectedKinds, input.selector);
             const kinds = {};
             for (const cacheKind of selectedKinds) {
-                const root = kindRoot(config, cacheKind);
                 const rows = entries.filter((entry) => entry.cacheKind === cacheKind);
+                if (cacheKind === "workspace") {
+                    kinds[cacheKind] = {
+                        cacheKind,
+                        entryCount: rows.length,
+                        totalBytes: 0,
+                        status: "healthy"
+                    };
+                    continue;
+                }
+                const root = kindRoot(config, cacheKind);
                 kinds[cacheKind] = {
                     cacheKind,
                     entryCount: rows.length,
@@ -511,6 +559,10 @@ export function createCacheRegistry(config) {
                             db?.prepare("DELETE FROM artifacts WHERE artifact_id = ?").run([entry.entryId]);
                             continue;
                         }
+                        if (entry.cacheKind === "workspace") {
+                            workspaceCache.invalidate(entry.entryId);
+                            continue;
+                        }
                         if (existsSync(entry.path)) {
                             await rm(entry.path, { force: true });
                         }

package/dist/config.d.ts

@@ -1,4 +1,4 @@
-import type { Config } from "./types.js";
+import type { ArtifactTargetKind, Config, MappingVariant } from "./types.js";
 declare const DEFAULTS: {
     readonly cacheDir: "~/.cache/minecraft-modding-mcp";
     readonly sourceRepos: readonly ["https://repo1.maven.org/maven2", "https://maven.fabricmc.net", "https://maven.minecraftforge.net", "https://maven.neoforged.net/releases"];
@@ -24,4 +24,13 @@ declare const DEFAULTS: {
 };
 export declare function loadConfig(): Config;
 export declare function stableArtifactId(parts: string[]): string;
+export interface ArtifactAliasInput {
+    artifactId: string;
+    kind: ArtifactTargetKind;
+    value: string;
+    mappingVariant?: MappingVariant;
+    resolvedVersion?: string;
+    coordinate?: string;
+}
+export declare function buildArtifactAlias(input: ArtifactAliasInput): string;
 export { DEFAULTS };

package/dist/config.js

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { homedir } from "node:os";
-import { isAbsolute, resolve } from "node:path";
+import { basename, isAbsolute, resolve } from "node:path";
 import { normalizePathForHost } from "./path-converter.js";
 const DEFAULTS = {
     cacheDir: "~/.cache/minecraft-modding-mcp",
@@ -182,5 +182,56 @@ export function stableArtifactId(parts) {
         .join("|");
     return createHash("sha256").update(normalizer).digest("hex");
 }
+// 12 hex chars (48 bits) of artifactId entropy keeps alias collisions astronomically
+// unlikely while staying short enough to copy/paste. A shorter prefix would let two
+// distinct artifacts whose readable tokens (kind, version, mapping, scope, variant)
+// happen to match share an alias and trip the schema-v4 UNIQUE constraint.
+const ARTIFACT_ALIAS_HASH_LEN = 12;
+function slugifyAliasPart(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+function aliasJarBase(jarPath) {
+    const base = basename(jarPath);
+    return base.toLowerCase().endsWith(".jar") ? base.slice(0, -4) : base;
+}
+// Generates a deterministic, human-readable alias canonical to the artifact row.
+// The alias is 1:1 with `artifactId`: only dimensions baked into `artifactId`
+// itself (kind, value/version/coordinate, mappingVariant) appear in the alias,
+// plus a 12-hex-char (48-bit) suffix taken from `artifactId`. Request-level
+// dimensions like `mapping` and `scope` are intentionally excluded — including
+// them would make resolveArtifact rotate the alias for the same row whenever
+// a caller passed a different mapping/scope, breaking aliases already returned
+// 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.
+export function buildArtifactAlias(input) {
+    const tokens = [];
+    if (input.kind === "version") {
+        tokens.push("mc", input.resolvedVersion ?? input.value);
+    }
+    else if (input.kind === "coordinate") {
+        tokens.push("coord", input.coordinate ?? input.value);
+    }
+    else {
+        tokens.push("jar", aliasJarBase(input.value));
+    }
+    // mappingVariant is canonical — `artifactIdForJar` / `artifactIdForCoordinate`
+    // bake "mojang-remapped" into the artifactId, so the same artifactId always
+    // produces the same alias regardless of how many times resolveArtifact is
+    // called. The token here is purely a human-readable hint; the 12-char hash
+    // suffix would already separate remapped artifacts from pass-through ones.
+    if (input.mappingVariant === "mojang-remapped") {
+        tokens.push("remapped");
+    }
+    tokens.push(input.artifactId.slice(0, ARTIFACT_ALIAS_HASH_LEN));
+    return tokens
+        .map(slugifyAliasPart)
+        .filter(Boolean)
+        .join("-");
+}
 export { DEFAULTS };
 //# sourceMappingURL=config.js.map