@adhisang/minecraft-modding-mcp 6.3.0 → 7.0.0-rc.0

package/docs/tool-reference.md

@@ -37,9 +37,10 @@ Start here when you are not sure which tool to reach for. In every row, the left
 - Positive integer tool arguments accept numeric strings such as `"10"` for documented top-level parameters.
 - When a parameter has a fixed safe default, `tools/list` exposes it through the JSON Schema `default` field so clients can rely on schema metadata instead of prose notes.
 - Retryable `suggestedCall` payloads omit parameters when the supplied value already matches the tool default, keeping recovery calls smaller without changing behavior.
-- `ERR_CLASS_NOT_FOUND` errors from the class tools carry a top-level `didYouMean` array (parallel to `suggestedCall`) with ranked near-miss candidates from the artifact's symbol index: each entry is `{ className, matchReason }` where `matchReason` is `"exact-simple-name"` (same simple name in another package — the moved-class case, ranked first), `"case-insensitive"`, or `"edit-distance:N"`. Candidates are hints, never assertions that the class exists at the suggested location; the array is empty when the index has nothing usable. All same-simple-name FQNs are enumerated rather than collapsed.
+- `ERR_CLASS_NOT_FOUND` errors from the class tools carry a top-level `didYouMean` array (parallel to `suggestedCall`) with ranked near-miss candidates from the artifact's symbol index: each entry is `{ className, matchReason }` where `matchReason` is `"exact-simple-name"` (same simple name in another package — the moved-class case, ranked first), `"case-insensitive"`, or `"edit-distance:N"`. Candidates come from the symbol index of the artifact the caller REQUESTED first, followed by any the artifact the lookup ended on contributes, deduplicated by FQN. A candidate found outside the requested artifact carries an extra `artifactId` naming where it was found; an entry WITHOUT that field is always from the artifact the caller asked about. The union matters because the requested artifact is, in the partial-source fallback scenario, the one with no `net.minecraft` symbols — which is why the fallback fired — so collecting from it alone returns `[]` in exactly the case the fallback exists to serve. Candidates are hints, never assertions that the class exists at the suggested location; the array is empty when neither index has anything usable. All same-simple-name FQNs are enumerated rather than collapsed. When an internal redirect resolved a different artifact while trying to answer the call — the binary fallback, or the nested-jar redirect that follows a shell jar's bundled inner jar — the error carries `details.fallbackArtifactId` naming it, alongside `details.binaryFallbackAttempted` for the binary case. `details.artifactId`, `details.mapping` and `details.qualityFlags` all describe the REQUESTED artifact, so identity, namespace and quality never disagree about which artifact is being reported. `fallbackArtifactId` and `binaryFallbackAttempted` are internal `AppError.details` fields for diagnosis and are NOT published on the wire; the envelope reports the requested artifact as `error.context.artifactId`.
 - `find-class` searches the nested `.class` inventories of Jar-in-Jar shell artifacts such as the Fabric API umbrella JAR. It accepts simple or qualified names, returns dotted names for inner classes, deduplicates a class bundled more than once, and honors `limit`. The returned source path is inferred from the outer class. For top-level matches, `get-class-source` and `get-class-members` resolve the actual containing nested JAR before reading content; dotted inner-class matches are also readable through `get-class-source`.
 - Source-oriented tools expose `artifactContents` so callers can tell whether the backing artifact is a `source-jar` or a `decompiled-binary`. `get-class-source`, `get-class-members`, `search-class-source`, and `get-artifact-file` also expose `returnedNamespace`.
+- When `mapping` is omitted, `get-class-source`, `get-class-members`, and `batch-class-members` all inherit the mapping the target artifact was resolved with, and report it as `returnedNamespace`. The `mapping` parameter's advertised schema description still says the default is `obfuscated`; that wording is pinned by the frozen legacy `inputSchema` bytes and is accurate only for targets that carry no resolved mapping of their own. An explicit `mapping` is never overridden.
 - Cache-backed source, mapping, validation, batch, and workflow tools accept `gradleUserHome?: string` when they need Loom cache data. Use it for builds that used an isolated `GRADLE_USER_HOME`; the server searches `<gradleUserHome>/loom-cache` and `<gradleUserHome>/caches/fabric-loom` before the MCP process default. The value selects a Gradle User Home, not arbitrary Loom cache roots.
 - `get-class-members` returns `decompiledFallback` (with `constructors`, `fields`, `methods`, each entry is `{ name, line, kind }`) and `decompiledMemberCounts` whenever bytecode enumeration yields zero but the decompiled source for the class is already indexed. The bytecode-derived `members` / `counts` are preserved as-is; the fallback is additive and carries no descriptor or access modifier. `qualityFlags` gains `"members-from-decompiled-source"` in that case. Use `get-class-source` for descriptors and full context.
 - `get-class-members` also returns an additive `status: "ok" | "members_unavailable" | "partial"` field so callers can distinguish "really 0 members" from "extraction unavailable":
@@ -72,6 +73,8 @@ Use `subject.kind="workspace"` when `inspect-minecraft` should resolve Minecraft
 
 `task="auto"` is structured dispatch based on `subject.kind` and `focus.kind`; it is not a natural-language planner and does not interpret prose. A string `focus` remains invalid and returns `ERR_INVALID_INPUT` with three schema-validated class/search/file `exampleCalls`; the server never guesses which object shape the text meant.
 
+A workspace subject resolves through `target.kind="workspace"`, the same synthesizing target `resolve-artifact` uses for a directory, so version detection, the project's compile mapping, and the loader-derived scope all apply and `inspect-minecraft` and `resolve-artifact` return the SAME artifact for the same project. Previously `inspect-minecraft` re-derived a `{ kind: "version" }` target with no mapping; because the mapping feeds the remap gate and the mapping variant is hashed into the `artifactId`, that resolved a DIFFERENT artifact — and skipped Loom source-jar discovery. An explicit `subject.mapping` / `subject.scope` still wins, and `WORKSPACE_TARGET_OFF=1` restores the previous version-target routing.
+
 Class source from a workspace:
 
 ```json
@@ -168,7 +171,7 @@ Workspace detection is memoised in a process-resident `WorkspaceContextCache` (1
 ## Common Pitfalls
 
 - Flat-`artifactId` tools (`find-class`, `get-artifact-file`, `list-artifact-files`, `search-class-source`, `index-artifact`) also accept the shared `target` shape (`{ kind: "version" | "jar" | "coordinate" | "artifact" | "dependency", ... }`) instead of `artifactId` — exactly one of the two must be supplied. The target is resolved (and ingested if needed) before the lookup, so a fresh `resolve-artifact` round-trip is unnecessary. `{ kind: "artifact", artifactId }` passes through directly. Targets that need workspace context beyond their own fields — `kind: "workspace"`, or `kind: "dependency"` without an explicit `version` — cannot supply a `projectPath` through these tools; resolve them with `resolve-artifact` first and pass the `artifactId`.
-- `analyze-symbol` infers an omitted `version` from `projectPath` (gradle.properties `minecraft_version`/`mc_version`); the response then carries `versionInference { version, source }` and a warning. An explicit `version` always wins. `inspect-minecraft` direct subjects without `subject.artifact` auto-resolve only when exactly one workspace is known to the process (provenance warning attached); several candidates are refused with `workspaceCandidates`.
+- `analyze-symbol` infers an omitted `version` from `projectPath` (gradle.properties `minecraft_version`/`mc_version`); the response then carries `versionInference { version, source }` and a warning. An explicit `version` always wins. `inspect-minecraft` direct subjects without `subject.artifact` auto-resolve only when exactly one workspace is known to the process (provenance warning attached); several candidates are refused with `workspaceCandidates`. That unique workspace is then resolved through `target.kind="workspace"` like any other workspace subject, so it picks up the project's compile mapping and loader scope; the separately detected Minecraft version is retained only as the "is this workspace usable at all" guard.
 
 - Loom split-source workspaces publish a version as a `minecraft-common` / `minecraft-clientOnly` sources-jar pair with no merged jar. Version-target resolution indexes both halves (the companion jar appears in `provenance.companionSourceJars`), so client-only classes are queryable under the merged scope. If a class still cannot be found, the error's `exampleCalls` carries a `scope: "vanilla"` retry — the decompiled client jar also contains client-only classes.
 - `mapping="mojang"` requires source-backed artifacts on legacy obfuscated versions. For unobfuscated releases such as `26.1+`, the runtime/decompile path is accepted directly for version and versioned-coordinate targets. When source jars are not available but the version's Mojang tiny mappings, the tiny-remapper jar, and `MappingService.checkMappingHealth` are all healthy, `resolve-artifact` with `target.kind="version"` will transparently tiny-remap the binary jar (`obfuscated -> mojang`) and decompile the result, and the response carries `qualityFlags` `"binary-remapped"` and `"decompiled"` plus `provenance.transformChain` `"binary-remap:obf->mojang"` and `"decompile:vineflower"`. Coordinate and jar targets are not eligible for this fallback and still surface `ERR_MAPPING_NOT_APPLIED`. Source-backed and obfuscated artifacts keep their existing `artifactId` hashes — only the new mojang-remapped variant lives in a separate cache slot.
@@ -305,7 +308,7 @@ Every per-entry `suggestedCall` is validated through the same `tool-schema-regis
 
 If the **shared resolution itself** fails (e.g. `target.kind="version"` with an unknown version), the batch returns a top-level error envelope (no `results[]`). `failFast` does not apply because no entries ran.
 
-Rollback: `BATCH_TOOLS_OFF=1` removes all four batch tools from `tools/list`. Direct `tools/call` for any of them returns the SDK-level "Method not found" tool-result envelope (`{ content: [{ type: "text", text: "MCP error -32602: Tool <name> not found" }], isError: true }`) — no `ProblemDetails` is produced, so callers cannot rely on `error.code === "ERR_*"` for disabled tools.
+Rollback: `BATCH_TOOLS_OFF=1` removes all four batch tools from `tools/list`. Direct `tools/call` for any of them is answered per era: legacy clients receive a SUCCESSFUL tool-result envelope (`{ content: [{ type: "text", text: "MCP error -32602: Tool <name> not found" }], isError: true }`, no `structuredContent` key), while modern clients receive a raw JSON-RPC `-32602` error (see `## MCP Protocol Support` → Rejection and error table). Neither shape carries `ProblemDetails`, so callers cannot rely on `error.code === "ERR_*"` for disabled tools.
 
 ### batch-class-source
 
@@ -323,6 +326,34 @@ Probe symbol existence for many entries against one shared Minecraft-version art
 
 Translate symbols across mapping namespaces with one shared Minecraft version. Per-entry: `{ kind, name, owner?, descriptor?, sourceMapping, targetMapping, signatureMode?, disambiguation?, maxCandidates? }`. Shared: top-level `version` (required) plus `sourcePriority` / `projectPath`. Per-entry `version` is rejected with an `unrecognized_keys` zod issue; the batch shape is intentionally single-version. There is no shared artifact resolution — each entry hits the mapping graph directly — so `summary.sharedArtifactId` is omitted.
 
+## Typed NBT document shape
+
+`json-to-nbt` and `nbt-apply-json-patch` take a `typedJson` argument whose advertised JSON Schema is the empty object `{}`. Those bytes are pinned for legacy wire parity and cannot change, so the required shape is documented here instead — the same workaround already applied to `get-class-members.mapping`. A `typedJson` that does not match is rejected with `ERR_NBT_INVALID_TYPED_JSON`.
+
+A document is:
+
+```jsonc
+{
+  "rootName": "Level",            // string; the NBT root compound's name (may be "")
+  "root": { "type": "compound", "value": { /* nodes */ } }
+}
+```
+
+Every node is `{ "type": <nbt-type>, "value": <payload> }`, where `<nbt-type>` is one of `byte`, `short`, `int`, `long`, `float`, `double`, `byteArray`, `string`, `list`, `compound`, `intArray`, `longArray`. Payloads by type:
+
+| `type` | `value` | Notes |
+| --- | --- | --- |
+| `byte` / `short` / `int` | number | Integer, in the JVM range for that width (`byte` is signed, −128..127). |
+| `long` | **string** | Decimal digits, `-9223372036854775808`..`9223372036854775807`. Never a JSON number. |
+| `float` / `double` | number, or the strings `"NaN"` / `"Infinity"` / `"-Infinity"` | A raw non-finite JSON number is rejected; use the string sentinels. |
+| `string` | string | |
+| `byteArray` / `intArray` | number[] | Each element must fit the element width. |
+| `longArray` | string[] | Same decimal-string rule as `long`. |
+| `list` | node[] | Also carries `"elementType"`: any node type, and every element's `type` must equal it. `"end"` is allowed only for an empty list. |
+| `compound` | object of name → node | Keys are the NBT tag names. |
+
+Rejections name the offending node twice: `error.fieldErrors[0].path` is the RFC6901 JSON pointer into the document (for example `/root/value/health/value`, `typedJson` when the whole document is wrong), and `error.hints` states the expected and received types plus this shape. `error.exampleCalls[0]` points at `nbt-to-json`, which produces a document this format accepts from any real NBT payload — the reliable way to obtain a valid `typedJson` to edit.
+
 ## Errors
 
 `ProblemDetails.code` may carry the codes below in addition to the existing tool-specific values.
@@ -331,14 +362,18 @@ Translate symbols across mapping namespaces with one shared Minecraft version. P
 - `ERR_TOOL_TIMEOUT` — Synthetic `CallToolResult` produced only for `validate-project` when its supervisor-owned end-to-end deadline expires. The default is 120,000 ms and includes supervisor queue time. `meta.timeout.phase` is `"queue"` when the call expired before dispatch and `"running"` after dispatch. A queue timeout does not restart the worker; a running timeout isolates the worker process tree, initiates replacement, and sets `meta.timeout.workerRestartInitiated: true`. Cancellation suppresses the timeout result while retaining the deadline for worker cleanup.
 - `ERR_MIXIN_PARSE_FAILED` — Reserved code for `validate-mixin` parse-stage failures in single / inline mode. Today the runtime parser is permissive (no hard parse failure path), but emitting this code keeps the contract stable for future strict-parse modes.
 - `ERR_STAGE_BUDGET_PRE_PARSE` — Raised when a pre-parse stage (`resolve`, `mapping-health`, or `parse` itself) exhausts its independent soft-deadline before validation can proceed. The error carries `failedStage: <stage name>`, `meta.stageBudgetExhausted: true`, and the `budgetMs` / `elapsedMs` for the offending stage. Recovery: shrink `mixinConfigPath` (e.g. validate one config file at a time) or set `MIXIN_STAGE_BUDGETS_OFF=1` to disable budgets for diagnostic reruns.
-- `ERR_WORKSPACE_VERSION_UNRESOLVED` — Raised by `resolve-artifact`, `get-class-source`, and `get-class-members` when `target.kind="workspace"` cannot detect a Minecraft version from `gradle.properties`. Both `strict: true` and `strict: false` raise; `details.strict` records which value was supplied. The error carries `details.projectPath` and a `suggestedCall` with `target: { kind: "version", value: "<your-mc-version>" }` so the caller can fall back to an explicit version target.
+- `ERR_WORKSPACE_VERSION_UNRESOLVED` — Raised by `resolve-artifact`, `get-class-source`, `get-class-members`, and `inspect-minecraft` (workspace subject, every artifact-context task) when `target.kind="workspace"` cannot detect a Minecraft version from `gradle.properties`. Both `strict: true` and `strict: false` raise; `details.strict` records which value was supplied. The error carries `details.projectPath` and a `suggestedCall` with `target: { kind: "version", value: "<your-mc-version>" }` so the caller can fall back to an explicit version target.
 - `ERR_DEPENDENCY_VERSION_UNRESOLVED` — Raised by the same three tools when `target.kind="dependency"` cannot infer a version from `gradle.properties` or `~/.gradle/caches/modules-2/files-2.1/<group>/<name>/`. Multiple non-snapshot entries in modules-2 also raise this error: the synthesizer refuses to pick without project-specific evidence, sets `details.ambiguous=true`, and lists the cached versions in `details.candidatesSeen`. The error carries `details.attempts` (the gradle.properties keys that were probed) plus a `suggestedCall` with `target: { kind: "dependency", group, name, version: "<your-version>" }`.
 
 ### `suggestedCall` schema validation gate
 
-Every `ProblemDetails.suggestedCall` payload an agent receives is validated against the registered `zod` schema for the named tool BEFORE it leaves the process. Invalid payloads (e.g. a `target.value` that holds a JSON-stringified inner target — the bug in v3 chains where round-tripping the suggestion produced `ERR_INVALID_INPUT`) are dropped from the published envelope. When the gate drops a primary suggestion AND no `exampleCalls[]` fallback is available, `error.hints` gains the literal sentence `"suggested call payload failed schema validation; using fallback examples"` so the caller can observe that a suggestion was elided.
+Every `ProblemDetails.suggestedCall` payload an agent receives is validated against the registered `zod` schema for the named tool BEFORE it leaves the process. Invalid payloads (e.g. a `target.value` that holds a JSON-stringified inner target — the bug in v3 chains where round-tripping the suggestion produced `ERR_INVALID_INPUT`) are dropped from the published envelope.
+
+The gate drops a primary suggestion for TWO reasons, and both are reported the same way. Either the payload failed schema validation, or — the common case — the guidance handed the gate a TEMPLATE whose values are still `<...>` placeholders, which is by design and never reached the schema at all. Whenever a primary suggestion is dropped and no `suggestedCall` survives, `error.hints` gains the literal sentence `"suggested call payload failed schema validation; using fallback examples"`. Read that sentence as "no directly-replayable suggestion is being published", not as evidence that a schema check failed: it is emitted for the placeholder-template case too. It also does NOT mean the envelope is empty of guidance — it coexists with `exampleCalls[]`, and in practice every recorded tool-contract envelope that carries the sentence also carries `exampleCalls`. Branch on the presence of `suggestedCall` / `exampleCalls`, never on this text.
 
-The optional `error.exampleCalls?: Array<{ tool: string; params: Record<string, unknown>; reason: string }>` field carries one or more **always-valid** alternative payloads when the primary is dropped. Each entry already passed the schema gate at construction time and is safe to re-call as-is.
+The wording is deliberately retained verbatim even though it is inaccurate for the placeholder case: it is frozen inside the pre-migration envelope evidence under `tests/fixtures/premigration/` (six tool-contract envelope samples and four ProblemDetails goldens), which was captured against an untouched pre-migration build and cannot be re-recorded. Rewording the sentence — or splitting the single drop marker into two — breaks those goldens with no way to regenerate them. Fix the reader, not the string.
+
+The optional `error.exampleCalls?: Array<{ tool: string; params: Record<string, unknown>; reason: string }>` field carries one or more alternative payloads when the primary is dropped. Each entry is **schema-valid**: it names a real tool and passes that tool's registered schema, so the argument names and types are right. It is NOT necessarily replayable as-is. Examples are explicitly permitted to be TEMPLATES — the same `<...>` placeholders that cause a primary `suggestedCall` to be dropped are allowed to survive here, because an example's job is to show the shape when no fillable suggestion exists. Recorded envelopes carry such templates today (the `analyze-mod` sample publishes `subject.jarPath: "<mod-jar-path>"`, and the typed-NBT recovery example publishes `nbtBase64: "<base64-encoded-nbt-payload>"`, which the NBT pipeline would reject as invalid base64 if sent verbatim). Scan the params for `<...>` values and fill them before sending; only `suggestedCall` is guaranteed placeholder-free.
 
 `suggestedCall.params` is published **byte-identical** to the caller-supplied object — the gate validates emit-vs-drop only and never injects schema defaults into the published payload. Internal consumers that want the schema-normalized form read `validateToolParams(name, params).data` directly from `tool-schema-registry`.
 
@@ -357,17 +392,17 @@ These environment variables are read once at worker startup and provide rollback
 
 | Env | Effect | Acceptance test |
 |---|---|---|
-| `MIXIN_STAGE_BUDGETS_OFF=1` | Sets every `validate-mixin` stage budget (including the per-target soft cap) to `Number.POSITIVE_INFINITY`. Restores the pre-budget run-to-completion behaviour. | `tests/source-service-validate-mixin-budget.test.ts` (`MIXIN_STAGE_BUDGETS_OFF=1 disables all budgets`) |
+| `MIXIN_STAGE_BUDGETS_OFF=1` | Sets every `validate-mixin` stage budget (including the per-target soft cap) to `Number.POSITIVE_INFINITY`. Restores the pre-budget run-to-completion behaviour. | `tests/source-service/validate-mixin-budget.test.ts` (`MIXIN_STAGE_BUDGETS_OFF=1 disables all budgets`) |
 | `SUPERVISOR_STRUCTURED_RESTART_OFF=1` | Suppresses synthetic `CallToolResult` envelopes; `tools/call` requests killed by a worker exit fall back to the legacy raw JSON-RPC `-32603` error. | `tests/stdio/stdio-supervisor.test.ts` (`buildWorkerRestartReply returns raw -32603 when structuredRestartDisabled`) |
-| `MIXIN_STAGE_PROGRESS_OFF=1` | Replaces the worker stage emitter with a no-op so `$/stageUpdate` notifications are never sent. Use as a fallback when the active SDK build does not surface `extra.requestId`. | `tests/stage-emitter.test.ts` (`makeStageEmitter is a no-op when disabled option is true`) |
-| `WORKSPACE_TARGET_OFF=1` | Rejects `target.kind="workspace"` on `resolve-artifact`, `get-class-source`, and `get-class-members` with `ERR_INVALID_INPUT`. Restores the pre-workspace-target behaviour where callers must always supply `target.kind="version"`/`"jar"`/`"coordinate"`. | `tests/source-service-workspace-target.test.ts` (`synthesizeWorkspaceTarget rejects target.kind=workspace when WORKSPACE_TARGET_OFF is set`) |
-| `DEPENDENCY_TARGET_OFF=1` | Rejects `target.kind="dependency"` on the same three tools with `ERR_INVALID_INPUT`. | `tests/source-service-dependency-target.test.ts` (`synthesizeDependencyTarget rejects target.kind=dependency when DEPENDENCY_TARGET_OFF is set`) |
-| `WORKSPACE_FALLBACK_LEGACY=1` | Forces the `ERR_MAPPING_NOT_APPLIED` `suggestedCall` back to the pre-workspace shape (`{ target, mapping: "obfuscated" }` with the legacy scope flip on `vanilla`+`mojang`). Use when an integration relies on the legacy retry payload. | `tests/source-service-mapping-not-applied-fallback.test.ts` (`buildMappingFallbackSuggestedCall returns the legacy obfuscated retry when WORKSPACE_FALLBACK_LEGACY is set`) |
-| `VALIDATE_PROJECT_TASKS_OFF=1` | Omits the additive `tasks` per-probe status report from `validate-project task="project-summary"` results. The headline `result.summary.status`, `result.project`, and `result.workspace` blocks are unchanged. Use as a rollback path while the per-probe contract stabilizes. | `tests/entry-tools-validate-project-tasks.test.ts` (`validate-project tasks A5: VALIDATE_PROJECT_TASKS_OFF=1 omits the tasks field`) |
-| `MEMBERS_STATUS_LEGACY=1` | Omits the additive `status` / `unavailableReason` / `suggestedCall` fields from `get-class-members` results. Restores the pre-status response shape for callers that pre-date the new enum. | `tests/source-service-get-class-members-status.test.ts` (`B7: MEMBERS_STATUS_LEGACY=1 strips the new fields`) |
-| `VERIFY_MIXIN_TARGET_OFF=1` | Removes `verify-mixin-target` from `tools/list` and rejects direct invocations with `ERR_INVALID_INPUT`. Use as a rollback path while the accessor-inference rules stabilize. | `tests/entry-tools-verify-mixin-target.test.ts` (`C11: VERIFY_MIXIN_TARGET_OFF=1 hides the tool from tools/list and rejects direct calls`) |
-| `SUGGESTED_CALL_VALIDATE_OFF=1` | Bypasses the `ProblemDetails.suggestedCall` schema validation gate. Raw caller-supplied payloads are emitted unchanged (matching the pre-gate behaviour); `error.hints` does not gain the fallback line. Use only as an emergency rollback if the gate causes unexpected drops in production. | `tests/build-suggested-call.test.ts` (`D11: SUGGESTED_CALL_VALIDATE_OFF=1 bypasses validation`) |
-| `BATCH_TOOLS_OFF=1` | Removes the 4 batch lookup tools (`batch-class-source`, `batch-class-members`, `batch-symbol-exists`, `batch-mappings`) from `tools/list`. Direct calls return the SDK "Tool not found" tool-result envelope (`isError: true`, no `ProblemDetails`). Use as an emergency rollback while the batch contract stabilizes. | `tests/manual/stdio-client-smoke.manual.ts` (`runBatchToolsOffProbe`) |
+| `MIXIN_STAGE_PROGRESS_OFF=1` | Replaces the worker stage emitter with a no-op so `$/stageUpdate` notifications are never sent. Use as a fallback when the active SDK build does not surface `extra.requestId`. | `tests/utils/stage-emitter.test.ts` (`makeStageEmitter is a no-op when disabled option is true`) |
+| `WORKSPACE_TARGET_OFF=1` | Rejects `target.kind="workspace"` on `resolve-artifact`, `get-class-source`, and `get-class-members` with `ERR_INVALID_INPUT`. Restores the pre-workspace-target behaviour where callers must always supply `target.kind="version"`/`"jar"`/`"coordinate"`. | `tests/source-service/workspace-target.test.ts` (`synthesizeWorkspaceTarget rejects target.kind=workspace when WORKSPACE_TARGET_OFF is set`) |
+| `DEPENDENCY_TARGET_OFF=1` | Rejects `target.kind="dependency"` on the same three tools with `ERR_INVALID_INPUT`. | `tests/source-service/dependency-target.test.ts` (`synthesizeDependencyTarget rejects target.kind=dependency when DEPENDENCY_TARGET_OFF is set`) |
+| `WORKSPACE_FALLBACK_LEGACY=1` | Forces the `ERR_MAPPING_NOT_APPLIED` `suggestedCall` back to the pre-workspace shape (`{ target, mapping: "obfuscated" }` with the legacy scope flip on `vanilla`+`mojang`). Use when an integration relies on the legacy retry payload. | `tests/source-service/mapping-not-applied-fallback.test.ts` (`buildMappingFallbackSuggestedCall returns the legacy obfuscated retry when WORKSPACE_FALLBACK_LEGACY is set`) |
+| `VALIDATE_PROJECT_TASKS_OFF=1` | Omits the additive `tasks` per-probe status report from `validate-project task="project-summary"` results. The headline `result.summary.status`, `result.project`, and `result.workspace` blocks are unchanged. Use as a rollback path while the per-probe contract stabilizes. | `tests/entry-tools/validate-project/validate-project-tasks.test.ts` (`validate-project tasks A5: VALIDATE_PROJECT_TASKS_OFF=1 omits the tasks field`) |
+| `MEMBERS_STATUS_LEGACY=1` | Omits the additive `status` / `unavailableReason` / `suggestedCall` fields from `get-class-members` results. Restores the pre-status response shape for callers that pre-date the new enum. | `tests/source-service/get-class-members-status.test.ts` (`B7: MEMBERS_STATUS_LEGACY=1 strips the new fields`) |
+| `VERIFY_MIXIN_TARGET_OFF=1` | Removes `verify-mixin-target` from `tools/list` and rejects direct invocations with `ERR_INVALID_INPUT`. Use as a rollback path while the accessor-inference rules stabilize. | `tests/entry-tools/verify-mixin-target/verify-mixin-target.test.ts` (`C11: VERIFY_MIXIN_TARGET_OFF=1 hides the tool from tools/list and rejects direct calls`) |
+| `SUGGESTED_CALL_VALIDATE_OFF=1` | Bypasses the `ProblemDetails.suggestedCall` schema validation gate. Raw caller-supplied payloads are emitted unchanged (matching the pre-gate behaviour); `error.hints` does not gain the fallback line. Use only as an emergency rollback if the gate causes unexpected drops in production. | `tests/contracts/build-suggested-call.test.ts` (`D11: SUGGESTED_CALL_VALIDATE_OFF=1 bypasses validation`) |
+| `BATCH_TOOLS_OFF=1` | Removes the 4 batch lookup tools (`batch-class-source`, `batch-class-members`, `batch-symbol-exists`, `batch-mappings`) from `tools/list`. Direct calls answer per era: legacy gets the successful `isError: true` "Tool not found" envelope, modern gets a raw JSON-RPC `-32602` (no `ProblemDetails` in either shape; see `## MCP Protocol Support`). Use as an emergency rollback while the batch contract stabilizes. | `tests/manual/stdio-client-smoke.manual.ts` (`runBatchToolsOffProbe`); `tests/stdio/stdio-error-code-inventory.test.ts` |
 
 
 ## Migration Notes
@@ -445,6 +480,134 @@ JSON resources follow the same `result/error/meta` pattern. Text resources retur
 
 The same JSON envelope is mirrored in MCP `structuredContent` for SDK-aware clients, and failures also set `isError=true`.
 
+The application-level `meta` field above is distinct from protocol-level `_meta`. Modern-era protocol fields (`resultType`, `ttlMs`, `cacheScope`, and the `io.modelcontextprotocol/serverInfo` identity echo in result `_meta`) sit at the MCP protocol result level, outside the application envelope, and appear only for modern-era clients (see `## MCP Protocol Support`).
+
+## MCP Protocol Support
+
+The stdio server implements MCP protocol revision `2026-07-28` and keeps the legacy initialize-based protocol fully supported in the same process. One process serves exactly one era; the first valid era signal selects it.
+
+### Era selection
+
+- A process starts with no era selected.
+- `initialize` selects the LEGACY era. Any `io.modelcontextprotocol/*` era-claim keys inside `initialize` `params._meta` are ignored for classification and stripped before the frame reaches the worker (other `_meta` keys pass through), so a hybrid client that attaches a modern claim to `initialize` still completes the legacy handshake.
+- A request whose `params._meta` carries BOTH `io.modelcontextprotocol/protocolVersion` (string) and `io.modelcontextprotocol/clientCapabilities` (object) selects the MODERN era. Selection is shallow: the era signal is a shape check only. The version VALUE is validated by the SUPERVISOR on EVERY modern request, so an unsupported version string still locks modern and then answers `-32022` — on that request and on every later one, regardless of which method pinned the connection.
+- The lock is one-way and survives internal worker restarts. There is no era-switch method; switching eras requires a fresh process (see the recovery sequence below).
+- `server/discover` is era-neutral: it never selects an era. Per-state outcomes are in the rejection table.
+- An ordinary request received before any era signal is rejected with `-32602` `data.kind: "missing_meta"`. A notification received before any era signal is consumed without a response and without forwarding.
+
+### Legacy era (initialize handshake)
+
+Supported protocol versions: `2025-11-25`, `2025-06-18`, `2025-03-26`, `2024-11-05`, `2024-10-07`. Each is echoed verbatim by `initialize`. Any other requested version negotiates down to `2025-11-25`.
+
+The supervisor caches the completed `initialize` / `notifications/initialized` pair and replays it into a replacement worker before queued requests are released; replay failure is a startup failure (see `ERR_WORKER_RESTART` in `## Errors`).
+
+The legacy wire contract is byte-compatible with the pre-migration (SDK v1) server, with these recorded exceptions:
+
+- `tools/call` with `arguments` omitted reaches the application validator as `{}`. Three outcome arms: (a) input-free tools succeed (`get-runtime-metrics`); (b) required-field schemas answer per-field `ERR_INVALID_INPUT` (`analyze-mod`); (c) a `{}`-accepting schema whose handler requires input answers that tool's own handler-level ProblemDetails — `json-to-nbt` answers `ERR_NBT_INVALID_TYPED_JSON` (status 400, `isError: true`) instead of the pre-migration validation-layer `ERR_INVALID_INPUT`.
+- Legacy `tools/list` entries omit the v1-only `execution: {"taskSupport":"forbidden"}` field (SDK v2 does not emit it); every other advertised field, including the `inputSchema` bytes, is identical to the pre-migration snapshots.
+- An unknown or disabled tool is answered immediately at the supervisor, before queueing: the reply bytes are identical to v1, but the reply consumes no queue slot and no worker round-trip, so reply ordering and queue-overflow outcomes can differ from v1 under concurrent load.
+- The unmatched-resource-URI error keeps the raw JSON-RPC `-32602` code, but its message changed from the pre-migration `MCP error -32602: Resource <uri> not found` to `Resource not found: <uri>`, and the error carries a `data.uri` field (SDK v2 wording).
+- The `initialize` result advertises `resources: { listChanged: false }` and `tools: { listChanged: false }`, where the pre-migration server advertised `true` for both. The suppression is deliberate and is NOT era-gated — both eras read one `getCapabilities()`, so gating it would leave one process advertising two different contracts; the reasoning is under the modern-era capability paragraph below. Every other byte of the `initialize` result is unchanged.
+
+### Modern era (2026-07-28, stateless)
+
+Modern clients never send `initialize`. Every request carries `params._meta`:
+
+| `_meta` key | Requirement | Value |
+| --- | --- | --- |
+| `io.modelcontextprotocol/protocolVersion` | required | `"2026-07-28"` |
+| `io.modelcontextprotocol/clientCapabilities` | required | object (for example `{}`) |
+| `io.modelcontextprotocol/clientInfo` | optional | `{ name, version }` |
+
+Recommended bootstrap probe (era-neutral — it never locks an era; per-state outcomes are under the rejection table):
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "server/discover",
+  "params": {
+    "_meta": {
+      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
+      "io.modelcontextprotocol/clientCapabilities": {}
+    }
+  }
+}
+```
+
+The discover result carries `supportedVersions: ["2026-07-28"]` (the modern per-request set — the legacy matrix is advertised through `initialize` negotiation, not through discover), `capabilities`, the server identity in `result._meta["io.modelcontextprotocol/serverInfo"]`, `resultType`, and the cache fields. `capabilities` advertises `resources: { listChanged: false }` and `tools: { listChanged: false }`, in that key order, and the legacy `initialize` result advertises the same payload — the two eras never disagree. The `false` is a deliberate suppression, not an SDK default: the SDK advertises `listChanged: true` for any registered tool or resource surface unless the server overrides it, and this server never emits `notifications/tools/list_changed` or `notifications/resources/list_changed` — the tool and resource surface is fixed at process start by environment flags — and there is no way to subscribe to those notifications either (see `subscriptions/listen` below). Treat both lists as static for the lifetime of the process; re-read them only across a restart.
+
+Probe fallback rule for clients: fall back to the legacy `initialize` handshake on ANY unrecognized probe error or on a probe timeout — never key the fallback to one specific error code. Back-to-back pipelining is safe: a modern-claim `server/discover` immediately followed by `initialize` in one stdin chunk is admitted atomically in stdin order — the discover is answered with a DiscoverResult, the initialize negotiates, and the process ends legacy-locked. One narrow exception: when the worker is down (restarting) as that pair arrives, the replayed `initialize` pins the replacement worker first and the queued discover is answered `-32601`; the any-error fallback rule covers this case.
+
+Every modern result — tool calls, resource reads, list methods, `server/discover`, and supervisor-synthesized results — carries `resultType: "complete"` and echoes the same server identity as discover in `result._meta["io.modelcontextprotocol/serverInfo"]`. `input_required` is never emitted. Raw JSON-RPC error responses never carry result-only fields.
+
+Absent modern surfaces: `prompts/list` is not advertised and answers `-32601`. `ping`, `logging/setLevel`, `tasks/list`, and `tasks/get` answer `-32601` in the modern era; legacy `ping` keeps its automatic `{}` pong. `subscriptions/listen` is intentionally absent in BOTH eras: no subscription capability is advertised — which is why `listChanged` is advertised as `false` above rather than `true` — the worker runs with `maxSubscriptions: 0`, the rejection is `-32601`, and it is non-retryable: there is no live update stream to wait for, and nothing would be pushed onto one. The server never sends `notifications/message`; logging goes to stderr.
+
+### Cache metadata (modern era only)
+
+Both `ttlMs` and `cacheScope` are returned by exactly these cacheable methods: `tools/list`, `resources/list`, `resources/read`, `resources/templates/list`, `server/discover`, and `prompts/list` were it exposed (it is not). This is the protocol's five-method cacheable list plus `server/discover` (SDK/schema default row). Values:
+
+| Surface | `cacheScope` | `ttlMs` |
+| --- | --- | ---: |
+| `tools/list` | `private` | `0` |
+| `server/discover` | `private` | `0` |
+| `resources/list`, `resources/templates/list` | `private` | `3600000` |
+| `mc://versions/list` read | `private` | `300000` |
+| `mc://metrics` read | `private` | `0` |
+| class source, artifact, mapping, member, and artifact-metadata reads | `private` | `60000` |
+| any successful read whose content is a ProblemDetails failure envelope | `private` | `0` |
+
+The ProblemDetails row takes precedence over the resource-class rows; otherwise an exact-URI row beats a class row. Legacy responses carry no cache fields, no `resultType`, and no protocol `_meta` identity echo.
+
+### Version negotiation
+
+| Client sends | Outcome |
+| --- | --- |
+| `initialize` with `2025-11-25`, `2025-06-18`, `2025-03-26`, `2024-11-05`, or `2024-10-07` | verbatim echo; legacy era |
+| `initialize` with any other version string | negotiates down to `2025-11-25`; legacy era |
+| modern `_meta` with `protocolVersion: "2026-07-28"` | served; modern era |
+| modern `_meta` with any other version string | LOCKS modern, then answers `-32022` with `data: { supported: ["2026-07-28"], requested }` — retry with a version from `data.supported`; do NOT fall back to `initialize` (the process is already modern-locked and would answer `-32601` `era_conflict`) |
+
+### Rejection and error table
+
+`-32602` reaches clients in distinct shapes. Branch on `error.data.kind` when present; the remaining shapes are distinguished by message family (most are data-less; the resource-miss row carries `data.uri`):
+
+| Producer | State / trigger | Method scope | Code | Discriminator |
+| --- | --- | --- | --- | --- |
+| supervisor | no era selected; request without a valid era signal | any non-`server/discover` request | `-32602` | `data.kind: "missing_meta"` with `data.missing[]` (plus `data.invalid[]` for wrong-typed keys); the message names both recovery paths |
+| supervisor | modern-locked; claim-less request | any request, including `server/discover` | `-32602` | `data.kind: "missing_meta"`; the message names the required keys |
+| worker (SDK) | modern-locked; shallow-valid claim with a deep-invalid `_meta` value | forwarded requests | `-32602` | data-less; message starts `Invalid _meta envelope for protocol revision 2026-07-28:` (pinned example: `Invalid _meta envelope for protocol revision 2026-07-28: Invalid input: expected object, received number`) |
+| worker (SDK) | params-schema violation, for example non-object `tools/call` `arguments` | both eras | `-32602` | data-less; message starts `Invalid tools/call request:`; the request never reaches the application validator |
+| worker (SDK) | unmatched resource URI | `resources/read`, both eras | `-32602` | message `Resource not found: <uri>` with `data.uri` (the pre-migration server answered `MCP error -32602: Resource <uri> not found` without `data` — code unchanged, message family changed) |
+| worker (SDK) | unknown or disabled tool, MODERN era | `tools/call` | `-32602` | raw JSON-RPC error (sanctioned modern contract; the modern era never had a v1 contract here) |
+| supervisor | unknown or disabled tool, LEGACY era | `tools/call` | none | SUCCESSFUL `CallToolResult` with `isError: true`, text `MCP error -32602: Tool <name> not found`, and NO `structuredContent` key — the missing `structuredContent` is the discriminator against a genuine tool failure |
+| supervisor | `initialize` that is not a valid MCP initialize request | `initialize` | `-32602` | `data.kind: "invalid_initialize"` with `data.required[]` and `data.eraSelected: false` — the era is NOT locked, so the client may retry a well-formed `initialize` or select the modern era instead |
+| supervisor | modern-locked; `initialize` arrives | `initialize` | `-32601` | `data.kind: "era_conflict"`, `selectedEra: "modern"`, `requestedEra: "legacy"`, `supported[]` = all six versions |
+| supervisor | legacy-locked; modern-claim request arrives | any modern-claim request | `-32600` | `data.kind: "era_conflict"`, `selectedEra: "legacy"`, `requestedEra: "modern"` |
+| supervisor / worker | `subscriptions/listen` | both eras | `-32601` | plain `Method not found` (no data). Non-legacy states reject at supervisor admission; a modern-signal listen still era-locks first, and a claim-less listen in non-legacy states fails the envelope check with `-32602` before the method rejection |
+| supervisor | modern request with an unsupported `protocolVersion` value | every modern request | `-32022` | `data.supported: ["2026-07-28"]`, `data.requested` |
+| supervisor | queue overflow, non-`tools/call` request | requests | `-32000` | message `MCP supervisor request queue is full.` (`tools/call` overflow receives the `ERR_LIMIT_EXCEEDED` `isError` result instead — see `## Meta fields`) |
+
+`server/discover` per state: a valid modern-claim discover never selects or changes the era. It receives a DiscoverResult in the unselected and modern-locked states; in the legacy-locked state it is forwarded to the legacy-pinned worker, which answers `-32601` (the probe's any-error fallback rule covers this). A claim-less discover: unselected → `-32602` `missing_meta`; modern-locked → `-32602` `missing_meta`; legacy-locked → forwarded → `-32601`.
+
+Era-conflict messages embed a launcher-neutral recovery sequence: close this transport, terminate and respawn the configured server command as a fresh stdio process, discard or re-issue any pending request ids, then perform the wanted era's opening (`initialize` + `notifications/initialized`, or a request carrying the required `io.modelcontextprotocol/*` `_meta` envelope).
+
+Notification variants: a modern-era notification without a valid claim (for example a claim-less `notifications/cancelled`) is never forwarded to the worker; it is dropped with a logged `supervisor.notification_dropped` warning and, like every notification, receives no response. Supervisor-side bookkeeping still applies: a claim-less cancellation still cancels ANY tracked in-flight request (not only `validate-project`), releasing its pending slot, its deadline timer, and the `validate-project` barrier if it held one, and the eventual worker response is suppressed per MCP cancellation semantics via the ordinary response-finality tombstone. An `initialize` in flight is the one exception — its handshake lifecycle owns that entry.
+
+### Synthetic terminal responses and retry semantics
+
+Supervisor-synthesized replies (queue overflow, worker restart, `validate-project` timeout, startup failure — shapes in `## Errors` and `## Meta fields`) are FINAL for that request instance: a late worker answer for the same id is discarded, so a client sees exactly one response per id. Retrying with the SAME id after a synthetic terminal reply is legal — the retry re-forwards and clears the finality bookkeeping. Era rejections synthesize no such finality (they answer without forwarding), and dropped notifications receive no response at all. Modern-era synthetic results are decorated like ordinary modern results (`resultType: "complete"` plus the identity `_meta` echo); legacy synthetic results remain byte-compatible with the pre-migration shapes.
+
+### Framing
+
+Standard framing is newline-delimited JSON-RPC (the MCP stdio standard). `Content-Length` header framing is a LOCAL, NONSTANDARD compatibility extension — it is not part of MCP. The reader auto-detects both and may switch mid-stream; every response, including synthetic replies and replies released after a worker restart, uses the framing of the request it answers. `MCP_MAX_FRAME_BYTES` bounds accepted frames (see `## Environment Variables`).
+
+### Adopted-policy note
+
+The 2026-07-28 revision does not mandate specific mixed-era conflict rules or unselected-state behavior for one stdio process. The era-conflict codes, `missing_meta` rejections, one-way lock, and discover neutrality documented here are this server's adopted policy, pinned by the committed wire suites (`tests/stdio/stdio-supervisor-era-state.test.ts`, `tests/stdio/stdio-supervisor-era-wire.test.ts`, `tests/stdio/stdio-supervisor-era-lifecycle.test.ts`). If a future protocol revision defines normative rules for these cases, those rules supersede this policy.
+
+Tooling note: `pnpm test:manual:stdio-smoke` runs against the production supervisor by default; its direct-worker bridge fallback mode bypasses the supervisor and therefore observes the worker-level raw `-32602` for disabled tools instead of the restored legacy `isError` envelope.
+
 ## Mapping Policy
 
 ### Namespace Definitions
@@ -495,6 +658,12 @@ Method descriptor precision is best on Tiny-backed paths (`intermediary` and `ya
 
 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.
 
+`resolve-method-mapping-exact` is **owner-strict**: the strict set is the candidates matching the query's full advertised triple `owner + name + descriptor`. The owner is compared after projecting it along the same mapping path the candidates travelled, so it is checked in the target namespace, not as a raw string. A same-signature method on a different class is therefore rejected rather than turned into an ambiguous verdict. The cost is that a method the owner INHERITS rather than declares now returns `not_found`: the mapping formats record declarations and carry no class hierarchy. That case is never silent — the result carries a warning naming the owner, the classes that do declare the member, and `find-mapping` as the owner-agnostic lookup.
+
+`resolve-method-mapping-exact` reports the candidate set its verdict was computed FROM, on every status. `candidates` and `candidateCount` are the strict matches — never the wider name-matched list, which previously put a `confidence: 1, matchKind: "exact"` candidate the strict filter had already rejected next to an ambiguous verdict with nothing to distinguish it. On `status: "resolved"` that set is the single match, so `candidates` duplicates `resolvedSymbol` and the default response projection omits it, leaving `resolvedSymbol` and `candidateCount: 1`. Candidates the strict filter dropped are accounted for in `warnings` as counts BY REASON (how many by owner, how many by descriptor); use `find-mapping` when you want the unfiltered list. An ambiguous verdict also carries `ambiguityReasons[]`, the same field `find-mapping` populates. The tool never picks a winner: `status: "resolved"` means exactly one strict match existed.
+
+`resolve-workspace-symbol` delegates its `kind: "method"` lookups to `resolve-method-mapping-exact` and spreads the result, so its method responses carry the same owner-strict semantics and the same `ambiguityReasons[]` on `status: "ambiguous"`. The field is present only on that status and always holds at least one reason, so it never serializes as an empty array.
+
 Use `find-mapping` `disambiguation.ownerHint` and `disambiguation.descriptorHint` to narrow ambiguous candidate sets.
 
 Use `resolve-workspace-symbol` when you need compile-visible names from actual Gradle Loom mappings in a workspace.
@@ -511,6 +680,8 @@ Path-based overrides treat blank values and the literal strings `undefined` and
 | --- | --- | --- |
 | `MCP_CACHE_DIR` | `~/.cache/minecraft-modding-mcp` | Cache root for downloads and SQLite |
 | `MCP_SQLITE_PATH` | `<cacheDir>/source-cache.db` | SQLite database path |
+| `MCP_SQLITE_CACHE_KB` | `8000` | SQLite page-cache size in KiB (applied as a negative `cache_size` pragma) |
+| `MCP_SQLITE_MMAP_SIZE` | `268435456` | SQLite `mmap_size` in bytes; `0` disables memory-mapped I/O |
 | `MCP_SOURCE_REPOS` | Maven Central + Fabric + Forge + NeoForge | Comma-separated Maven repository URLs |
 | `MCP_LOCAL_M2` | `~/.m2/repository` | Local Maven repository path |
 | `MCP_ENABLE_INDEXED_SEARCH` | `true` | Enable indexed query path for `search-class-source` |
@@ -524,6 +695,8 @@ Path-based overrides treat blank values and the literal strings `undefined` and
 | `MCP_MAX_CONTENT_BYTES` | `1000000` | Maximum bytes for file read operations |
 | `MCP_MAX_SEARCH_HITS` | `200` | Maximum search result count |
 | `MCP_SEARCH_SCAN_PAGE_SIZE` | `250` | Page size used by literal scan fallbacks |
+| `MCP_SEARCH_SCAN_MAX_BYTES` | `67108864` | Maximum bytes read by literal scan fallbacks before the scan stops |
+| `MCP_LOOM_TINY_MAX_INDEX_ENTRIES` | derived from the live V8 heap limit | Hard cap on index slots one Loom `.tiny` load may accumulate before it stops and warns instead of exhausting the heap. Unset, the budget is derived from free heap (so raising `--max-old-space-size` raises it automatically) and clamped to 1,000,000–64,000,000 slots. |
 | `MCP_INDEX_INSERT_CHUNK_SIZE` | `200` | Batch size for SQLite index inserts |
 | `MCP_MAX_ARTIFACTS` | `200` | Maximum cached artifacts |
 | `MCP_MAX_CACHE_BYTES` | `2147483648` | Maximum total cache size in bytes |
@@ -535,8 +708,9 @@ Path-based overrides treat blank values and the literal strings `undefined` and
 
 | Variable | Default | Description |
 | --- | --- | --- |
-| `MCP_FETCH_TIMEOUT_MS` | `15000` | HTTP request timeout in milliseconds |
+| `MCP_FETCH_TIMEOUT_MS` | `15000` | HTTP request timeout in milliseconds (also bounds version-manifest fetches) |
 | `MCP_FETCH_RETRIES` | `2` | HTTP request retry count |
+| `MCP_MAX_FRAME_BYTES` | `67108864` | Maximum accepted JSON-RPC frame size in bytes for the stdio supervisor and worker transport (clamped to at least 1 MiB); oversized frames are rejected with a diagnostic and skipped |
 
 ### Decompilation and Remapping
 
@@ -548,6 +722,7 @@ Path-based overrides treat blank values and the literal strings `undefined` and
 | `MCP_TINY_REMAPPER_VERSION` | `0.10.3` | tiny-remapper version to auto-download when no JAR path override is set |
 | `MCP_REMAP_TIMEOUT_MS` | `600000` | Remap operation timeout in milliseconds |
 | `MCP_REMAP_MAX_MEMORY_MB` | `4096` | Maximum JVM heap for remap operations |
+| `MCP_DECOMPILE_MAX_MEMORY_MB` | `4096` | Maximum JVM heap for Vineflower decompile operations |
 
 ### NBT Limits
 
@@ -570,8 +745,8 @@ Internal worker-mode environment variables are reserved for the transport implem
 
 | Component | Technology |
 | --- | --- |
-| Runtime | Node.js 22+ |
-| Transport | stdio with newline and `Content-Length` framing support |
+| Runtime | Node.js 22.13.0+ |
+| Transport | stdio, MCP protocol revision `2026-07-28` plus the legacy initialize protocol (dual-era, see `## MCP Protocol Support`); newline framing standard, `Content-Length` as a local extension |
 | Storage | SQLite for artifact metadata, source indexing, and cache bookkeeping |
 | Decompilation | [Vineflower](https://github.com/Vineflower/vineflower) |
 | Remapping | [tiny-remapper](https://github.com/FabricMC/tiny-remapper) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhisang/minecraft-modding-mcp",
-  "version": "6.3.0",
+  "version": "7.0.0-rc.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",
@@ -14,7 +14,9 @@
     "README.md",
     "LICENSE",
     "CHANGELOG.md",
-    "docs/**/*.md"
+    "docs/README-ja.md",
+    "docs/examples.md",
+    "docs/tool-reference.md"
   ],
   "scripts": {
     "dev": "tsx src/cli.ts",
@@ -61,16 +63,17 @@
   "bugs": "https://github.com/adhi-jp/minecraft-modding-mcp/issues",
   "homepage": "https://github.com/adhi-jp/minecraft-modding-mcp#readme",
   "engines": {
-    "node": ">=22"
+    "node": ">=22.13.0"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.27.1",
+    "@modelcontextprotocol/server": "2.0.0",
     "fast-glob": "^3.3.3",
     "smol-toml": "^1.3.0",
     "yauzl": "^3.2.0",
-    "zod": "^3.23.8"
+    "zod": "4.4.3"
   },
   "devDependencies": {
+    "@modelcontextprotocol/client": "2.0.0",
     "@types/node": "^22.13.5",
     "@types/yauzl": "^2.10.3",
     "tsx": "^4.19.2",