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

package/dist/resources.js

@@ -1,4 +1,5 @@
-import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ResourceTemplate } from "@modelcontextprotocol/server";
+import { METRICS_READ_CACHE_HINT, RESOURCE_READ_CACHE_HINT, VERSIONS_LIST_READ_CACHE_HINT } from "./cache-policy.js";
 import { createError, ERROR_CODES, isAppError } from "./errors.js";
 import { textResource, objectResource, errorResource } from "./mcp-helpers.js";
 function decodeTemplateParam(params, key) {
@@ -21,32 +22,37 @@ function decodeTemplateParam(params, key) {
         });
     }
 }
+// Cache-hint rows (adopted policy, src/cache-policy.ts): per-registration
+// hints ride the SDK's never-serialized carrier and only surface on
+// 2026-07-28 results. The errorResource(...) calls also receive the request
+// ctx so the ProblemDetails-read override (ttlMs 0, unconditional precedence
+// over these class rows) can be applied structurally on the error path.
 export function registerResources(server, sourceService) {
     // ── Fixed resources ──────────────────────────────────────────────
-    server.resource("versions-list", "mc://versions/list", { description: "List all available Minecraft versions with their metadata.", mimeType: "application/json" }, async (uri) => {
+    server.registerResource("versions-list", "mc://versions/list", { description: "List all available Minecraft versions with their metadata.", mimeType: "application/json", cacheHint: VERSIONS_LIST_READ_CACHE_HINT }, async (uri, ctx) => {
         try {
             const result = await sourceService.listVersions();
             return objectResource(uri.href, result);
         }
         catch (e) {
             if (isAppError(e))
-                return errorResource(uri.href, { message: e.message, code: e.code, details: e.details });
+                return errorResource(uri.href, { message: e.message, code: e.code, details: e.details }, ctx);
             throw e;
         }
     });
-    server.resource("runtime-metrics", "mc://metrics", { description: "Runtime metrics and performance counters for the MCP server.", mimeType: "application/json" }, async (uri) => {
+    server.registerResource("runtime-metrics", "mc://metrics", { description: "Runtime metrics and performance counters for the MCP server.", mimeType: "application/json", cacheHint: METRICS_READ_CACHE_HINT }, async (uri, ctx) => {
         try {
             const result = sourceService.getRuntimeMetrics();
             return objectResource(uri.href, result);
         }
         catch (e) {
             if (isAppError(e))
-                return errorResource(uri.href, { message: e.message, code: e.code, details: e.details });
+                return errorResource(uri.href, { message: e.message, code: e.code, details: e.details }, ctx);
             throw e;
         }
     });
     // ── Template resources ───────────────────────────────────────────
-    server.resource("class-source", new ResourceTemplate("mc://source/{artifactId}/{className}", { list: undefined }), { description: "Java source code for a class within a resolved artifact. className may use dot or slash separators.", mimeType: "text/x-java" }, async (uri, params) => {
+    server.registerResource("class-source", new ResourceTemplate("mc://source/{artifactId}/{className}", { list: undefined }), { description: "Java source code for a class within a resolved artifact. className may use dot or slash separators.", mimeType: "text/x-java", cacheHint: RESOURCE_READ_CACHE_HINT }, async (uri, params, ctx) => {
         try {
             const result = await sourceService.getClassSource({
                 artifactId: params.artifactId,
@@ -59,11 +65,11 @@ export function registerResources(server, sourceService) {
         }
         catch (e) {
             if (isAppError(e))
-                return errorResource(uri.href, { message: e.message, code: e.code, details: e.details });
+                return errorResource(uri.href, { message: e.message, code: e.code, details: e.details }, ctx);
             throw e;
         }
     });
-    server.resource("class-source-json", new ResourceTemplate("mc://source-json/{artifactId}/{className}", { list: undefined }), { description: "JSON envelope of a class's full source plus metadata (artifactId, mappingApplied, totalLines, returnedRange, provenance, warnings) — the structured alternative to the raw-text class-source resource, easier to cite and continue.", mimeType: "application/json" }, async (uri, params) => {
+    server.registerResource("class-source-json", new ResourceTemplate("mc://source-json/{artifactId}/{className}", { list: undefined }), { description: "JSON envelope of a class's full source plus metadata (artifactId, mappingApplied, totalLines, returnedRange, provenance, warnings) — the structured alternative to the raw-text class-source resource, easier to cite and continue.", mimeType: "application/json", cacheHint: RESOURCE_READ_CACHE_HINT }, async (uri, params, ctx) => {
         try {
             const result = await sourceService.getClassSource({
                 artifactId: params.artifactId,
@@ -74,11 +80,11 @@ export function registerResources(server, sourceService) {
         }
         catch (e) {
             if (isAppError(e))
-                return errorResource(uri.href, { message: e.message, code: e.code, details: e.details });
+                return errorResource(uri.href, { message: e.message, code: e.code, details: e.details }, ctx);
             throw e;
         }
     });
-    server.resource("artifact-file", new ResourceTemplate("mc://artifact/{artifactId}/files/{filePath}", { list: undefined }), { description: "Raw content of a file within a resolved artifact. filePath is the archive-relative path.", mimeType: "text/plain" }, async (uri, params) => {
+    server.registerResource("artifact-file", new ResourceTemplate("mc://artifact/{artifactId}/files/{filePath}", { list: undefined }), { description: "Raw content of a file within a resolved artifact. filePath is the archive-relative path.", mimeType: "text/plain", cacheHint: RESOURCE_READ_CACHE_HINT }, async (uri, params, ctx) => {
         try {
             const result = await sourceService.getArtifactFile({
                 artifactId: params.artifactId,
@@ -88,11 +94,11 @@ export function registerResources(server, sourceService) {
         }
         catch (e) {
             if (isAppError(e))
-                return errorResource(uri.href, { message: e.message, code: e.code, details: e.details });
+                return errorResource(uri.href, { message: e.message, code: e.code, details: e.details }, ctx);
             throw e;
         }
     });
-    server.resource("find-mapping", new ResourceTemplate("mc://mappings/{version}/{sourceMapping}/{targetMapping}/{kind}/{name}", { list: undefined }), { description: "Look up a CLASS mapping between two naming namespaces. This URI carries no owner, so field/method lookups (which need an owner) must use the find-member-mapping resource or the find-mapping tool.", mimeType: "application/json" }, async (uri, params) => {
+    server.registerResource("find-mapping", new ResourceTemplate("mc://mappings/{version}/{sourceMapping}/{targetMapping}/{kind}/{name}", { list: undefined }), { description: "Look up a CLASS mapping between two naming namespaces. This URI carries no owner, so field/method lookups (which need an owner) must use the find-member-mapping resource or the find-mapping tool.", mimeType: "application/json", cacheHint: RESOURCE_READ_CACHE_HINT }, async (uri, params, ctx) => {
         try {
             const result = await sourceService.findMapping({
                 version: params.version,
@@ -105,11 +111,11 @@ export function registerResources(server, sourceService) {
         }
         catch (e) {
             if (isAppError(e))
-                return errorResource(uri.href, { message: e.message, code: e.code, details: e.details });
+                return errorResource(uri.href, { message: e.message, code: e.code, details: e.details }, ctx);
             throw e;
         }
     });
-    server.resource("find-member-mapping", new ResourceTemplate("mc://mappings/{version}/{sourceMapping}/{targetMapping}/{kind}/{owner}/{name}", { list: undefined }), { description: "Look up a FIELD or METHOD mapping between two naming namespaces, including the owner class the member belongs to (required for member lookups). For exact method overload resolution, use the find-mapping tool with a descriptor.", mimeType: "application/json" }, async (uri, params) => {
+    server.registerResource("find-member-mapping", new ResourceTemplate("mc://mappings/{version}/{sourceMapping}/{targetMapping}/{kind}/{owner}/{name}", { list: undefined }), { description: "Look up a FIELD or METHOD mapping between two naming namespaces, including the owner class the member belongs to (required for member lookups). For exact method overload resolution, use the find-mapping tool with a descriptor.", mimeType: "application/json", cacheHint: RESOURCE_READ_CACHE_HINT }, async (uri, params, ctx) => {
         try {
             const result = await sourceService.findMapping({
                 version: params.version,
@@ -123,11 +129,11 @@ export function registerResources(server, sourceService) {
         }
         catch (e) {
             if (isAppError(e))
-                return errorResource(uri.href, { message: e.message, code: e.code, details: e.details });
+                return errorResource(uri.href, { message: e.message, code: e.code, details: e.details }, ctx);
             throw e;
         }
     });
-    server.resource("class-members", new ResourceTemplate("mc://artifact/{artifactId}/members/{className}", { list: undefined }), { description: "List constructors, methods, and fields for a class within a resolved artifact.", mimeType: "application/json" }, async (uri, params) => {
+    server.registerResource("class-members", new ResourceTemplate("mc://artifact/{artifactId}/members/{className}", { list: undefined }), { description: "List constructors, methods, and fields for a class within a resolved artifact.", mimeType: "application/json", cacheHint: RESOURCE_READ_CACHE_HINT }, async (uri, params, ctx) => {
         try {
             const result = await sourceService.getClassMembers({
                 artifactId: params.artifactId,
@@ -137,18 +143,18 @@ export function registerResources(server, sourceService) {
         }
         catch (e) {
             if (isAppError(e))
-                return errorResource(uri.href, { message: e.message, code: e.code, details: e.details });
+                return errorResource(uri.href, { message: e.message, code: e.code, details: e.details }, ctx);
             throw e;
         }
     });
-    server.resource("artifact-metadata", new ResourceTemplate("mc://artifact/{artifactId}", { list: undefined }), { description: "Metadata for a previously resolved artifact (origin, coordinate, mapping, provenance).", mimeType: "application/json" }, async (uri, params) => {
+    server.registerResource("artifact-metadata", new ResourceTemplate("mc://artifact/{artifactId}", { list: undefined }), { description: "Metadata for a previously resolved artifact (origin, coordinate, mapping, provenance).", mimeType: "application/json", cacheHint: RESOURCE_READ_CACHE_HINT }, async (uri, params, ctx) => {
         try {
             const artifact = sourceService.getArtifact(params.artifactId);
             return objectResource(uri.href, artifact);
         }
         catch (e) {
             if (isAppError(e))
-                return errorResource(uri.href, { message: e.message, code: e.code, details: e.details });
+                return errorResource(uri.href, { message: e.message, code: e.code, details: e.details }, ctx);
             throw e;
         }
     });

package/dist/server-identity.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Canonical server identity — the single source of the {name, version}
+ * Implementation this process advertises.
+ *
+ * Consumers:
+ *  - src/index.ts constructs the McpServer from these values; the SDK stamps
+ *    that Implementation verbatim as `_meta["io.modelcontextprotocol/serverInfo"]`
+ *    on every modern result it produces (and it is the initialize/discover
+ *    serverInfo).
+ *  - src/synthetic-decorator.ts stamps the same identity onto modern-era
+ *    supervisor-synthesized results.
+ *
+ * Equality between live SDK results and synthetic decoration is therefore by
+ * construction; the live-SDK drift-guard test
+ * (tests/stdio/stdio-supervisor-synthetic-drift.test.ts) proves it end-to-end.
+ */
+export type ServerIdentity = {
+    name: string;
+    version: string;
+};
+export declare const SERVER_NAME = "@adhisang/minecraft-modding-mcp";
+export declare function getServerVersionFromPackageJson(): string;
+export declare const SERVER_VERSION: string;
+/** Frozen canonical identity; consumers needing a mutable object must copy. */
+export declare const SERVER_IDENTITY: Readonly<ServerIdentity>;
+/** Fresh, mutation-safe copy of the canonical identity. */
+export declare function serverIdentitySnapshot(): ServerIdentity;

package/dist/server-identity.js

@@ -0,0 +1,26 @@
+import { readFileSync } from "node:fs";
+export const SERVER_NAME = "@adhisang/minecraft-modding-mcp";
+export function getServerVersionFromPackageJson() {
+    try {
+        const packageJsonUrl = new URL("../package.json", import.meta.url);
+        const packageJson = JSON.parse(readFileSync(packageJsonUrl, "utf8"));
+        if (typeof packageJson.version === "string" && packageJson.version.trim()) {
+            return packageJson.version.trim();
+        }
+    }
+    catch {
+        // ignore and fallback
+    }
+    return "0.3.0";
+}
+export const SERVER_VERSION = getServerVersionFromPackageJson();
+/** Frozen canonical identity; consumers needing a mutable object must copy. */
+export const SERVER_IDENTITY = Object.freeze({
+    name: SERVER_NAME,
+    version: SERVER_VERSION
+});
+/** Fresh, mutation-safe copy of the canonical identity. */
+export function serverIdentitySnapshot() {
+    return { name: SERVER_IDENTITY.name, version: SERVER_IDENTITY.version };
+}
+//# sourceMappingURL=server-identity.js.map

package/dist/source/access-validate.js

@@ -30,6 +30,47 @@ function isSourceMappingNamespace(namespace) {
         namespace === "intermediary" ||
         namespace === "yarn");
 }
+/**
+ * Refuses a verdict that would be computed against another loader's bytecode,
+ * and marks a cross-version one as approximate.
+ *
+ * A runtime fallback could serve a NeoForge 1.21.10 AT-patched jar to a Fabric
+ * 1.21.11 workspace; validation then reported `valid: true` with a
+ * `resolvedRuntimeJavaSignature` taken from bytecode the project never runs.
+ * A different loader's access flags are simply not evidence about this one, so
+ * that case fails loudly. A same-loader version drift still yields a verdict —
+ * flagged, never silent.
+ */
+function guardRuntimeEvidence(provenance, warnings, subject) {
+    if (!provenance) {
+        return {};
+    }
+    if (provenance.loaderMismatch) {
+        throw createError({
+            code: ERROR_CODES.CONTEXT_UNRESOLVED,
+            message: `${subject} validation resolved a ${provenance.servedLoader} runtime jar for a ` +
+                `${provenance.expectedLoader} workspace; a different loader's bytecode cannot certify these entries.`,
+            details: {
+                jarPath: provenance.jarPath,
+                servedLoader: provenance.servedLoader,
+                expectedLoader: provenance.expectedLoader,
+                version: provenance.version,
+                ...(provenance.requestedVersion ? { requestedVersion: provenance.requestedVersion } : {}),
+                requestedScope: provenance.requestedScope,
+                appliedScope: provenance.appliedScope,
+                nextAction: `Point gradleUserHome at the Gradle home holding this workspace's own ${provenance.expectedLoader} runtime jars, ` +
+                    "or run the Gradle task that generates them. Omitting projectPath validates against the vanilla jar instead of another loader's."
+            }
+        });
+    }
+    if (!provenance.versionApproximated) {
+        return {};
+    }
+    const reason = `Runtime evidence comes from Minecraft ${provenance.version}, not the requested ` +
+        `${provenance.requestedVersion}; entries were checked against a different version's bytecode.`;
+    warnings.push(reason);
+    return { approximate: true, approximationReasons: [reason] };
+}
 export async function validateAccessWidener(svc, input) {
     const version = input.version.trim();
     if (!version) {
@@ -61,6 +102,7 @@ export async function validateAccessWidener(svc, input) {
     let jarPath;
     let lookupMapping = "obfuscated";
     let provenance;
+    let approximation = {};
     if (runtimeAware) {
         provenance = await svc.resolveAccessWidenerRuntimeArtifact({
             version,
@@ -70,6 +112,7 @@ export async function validateAccessWidener(svc, input) {
             scope: input.scope,
             preferProjectVersion: input.preferProjectVersion
         });
+        approximation = guardRuntimeEvidence(provenance, warnings, "Access Widener");
         resolvedVersion = provenance.version;
         jarPath = provenance.jarPath;
         lookupMapping = provenance.mappingApplied;
@@ -148,6 +191,10 @@ export async function validateAccessWidener(svc, input) {
     if (provenance) {
         result.provenance = provenance;
     }
+    if (approximation.approximate) {
+        result.approximate = true;
+        result.approximationReasons = approximation.approximationReasons;
+    }
     return result;
 }
 export async function validateAccessTransformer(svc, input) {
@@ -170,6 +217,7 @@ export async function validateAccessTransformer(svc, input) {
     let jarPath;
     let lookupMapping = "obfuscated";
     let provenance;
+    let approximation = {};
     if (runtimeAware) {
         provenance = await svc.resolveAccessTransformerRuntimeArtifact({
             version,
@@ -179,6 +227,7 @@ export async function validateAccessTransformer(svc, input) {
             scope: input.scope,
             preferProjectVersion: input.preferProjectVersion
         });
+        approximation = guardRuntimeEvidence(provenance, warnings, "Access Transformer");
         resolvedVersion = provenance.version;
         jarPath = provenance.jarPath;
         lookupMapping = provenance.mappingApplied;
@@ -263,6 +312,10 @@ export async function validateAccessTransformer(svc, input) {
     if (provenance) {
         result.provenance = provenance;
     }
+    if (approximation.approximate) {
+        result.approximate = true;
+        result.approximationReasons = approximation.approximationReasons;
+    }
     return result;
 }
 //# sourceMappingURL=access-validate.js.map

package/dist/source/artifact-resolver.d.ts

@@ -1,6 +1,6 @@
 import type { SourceService } from "../source-service.js";
 import type { ArtifactContentsSummary, ProbeMinecraftArtifactInput, ProbeMinecraftArtifactOutput, ResolveArtifactInput, ResolveArtifactOutput } from "../source-service.js";
-import type { AccessTransformerNamespace, ArtifactProvenance, ArtifactScope, ArtifactTargetKind, ResolvedSourceArtifact, RuntimeValidationProvenance, SourceMapping } from "../types.js";
+import type { AccessTransformerNamespace, ArtifactProvenance, ArtifactScope, ArtifactTargetKind, ResolvedSourceArtifact, RuntimeLoader, RuntimeValidationProvenance, SourceMapping } from "../types.js";
 import type { WorkspaceProjectLoader } from "../workspace-mapping-service.js";
 export type VersionSourceDiscovery = {
     searchedPaths: string[];
@@ -16,7 +16,19 @@ type RuntimeJarCandidate = {
     appliedScope: ArtifactScope;
     origin: RuntimeValidationProvenance["origin"];
     namespaceHint?: "intermediary" | "mojang" | "named";
+    /** How the candidate was tied to the requested Minecraft version. */
+    versionEvidence?: RuntimeVersionEvidence;
 };
+/**
+ * Why a runtime jar is believed to belong to the requested Minecraft version.
+ *
+ * - `exact-token`: the Minecraft version appears verbatim in the path.
+ * - `loader-token`: the path carries the loader version that maps 1:1 onto the
+ *   Minecraft version (NeoForge `21.11.x` <-> Minecraft `1.21.11`).
+ * - `project-anchored`: the jar sits inside the caller's own project build
+ *   directory and the project declares exactly the requested Minecraft version.
+ */
+export type RuntimeVersionEvidence = "exact-token" | "loader-token" | "project-anchored";
 export type MappingFallbackSuggestion = {
     suggestedCall?: {
         tool: string;
@@ -31,6 +43,58 @@ export type MappingFallbackSuggestion = {
     _suggestedCallPrimaryDropped?: boolean;
 };
 export declare function hasExactVersionToken(path: string, version: string): boolean;
+/**
+ * True when a path carries the NeoForge/Forge loader version that corresponds
+ * 1:1 to `mcVersion`.
+ *
+ * ModDevGradle names every artifact after the LOADER version and never after
+ * Minecraft: MC 1.21.11 produces `build/moddev/artifacts/neoforge-21.11.38-beta-merged.jar`.
+ * A plain `hasExactVersionToken(path, "1.21.11")` therefore rejected every
+ * artifact of the canonical NeoForge workspace, which made
+ * validate-access-transformer unusable there.
+ *
+ * NeoForge derives its version from Minecraft as `<minor>.<patch>.<build>`, so
+ * `1.21.11` -> `21.11.<build>` and `1.21` -> `21.0.<build>`. The trailing dot
+ * before the build number keeps `21.1.` from matching `21.10.5`.
+ */
+export declare function hasLoaderRuntimeVersionToken(path: string, mcVersion: string): boolean;
+/**
+ * Minecraft version a runtime jar path carries, or undefined when the path
+ * names none. Loom lays its cache out as
+ * `<gradle>/caches/fabric-loom/<mcVersion>/...`, so the first `1.x[.y]` token
+ * of the path is the version the jar was built for.
+ */
+export declare function inferRuntimeJarMinecraftVersion(path: string): string | undefined;
+/**
+ * Loader a runtime jar belongs to, read from its path.
+ *
+ * A Loom cache holds NeoForge-patched jars under a `/neoforge/` segment
+ * (`caches/fabric-loom/1.21.10/neoforge/21.10.50-beta/minecraft-merged-mojang-at-patched.jar`).
+ * Serving one of those to a Fabric workspace silently validated a Fabric access
+ * widener against NeoForge bytecode, so the loader has to travel with the jar.
+ */
+export declare function inferRuntimeJarLoader(path: string): RuntimeLoader;
+/**
+ * Fills in the truthful version/loader half of a runtime provenance record.
+ *
+ * `version` becomes the version the SERVED jar carries; the caller's original
+ * request is preserved under `requestedVersion` and flagged. A served loader
+ * that contradicts a KNOWN expected loader is flagged too — never silently
+ * dropped.
+ */
+export declare function describeServedRuntimeJar(input: {
+    jarPath: string;
+    requestedVersion: string;
+    expectedLoader?: RuntimeLoader;
+}): {
+    version: string;
+    requestedVersion?: string;
+    versionApproximated?: boolean;
+    servedLoader: RuntimeLoader;
+    expectedLoader?: RuntimeLoader;
+    loaderMismatch?: boolean;
+    notes: string[];
+};
 export declare function discoverVersionSourceJar(_svc: SourceService, input: {
     version: string;
     projectPath?: string;
@@ -54,6 +118,8 @@ export declare function discoverAccessTransformerRuntimeCandidates(_svc: SourceS
     requestedScope: ArtifactScope;
     atNamespace: AccessTransformerNamespace;
     loader: WorkspaceProjectLoader | "unknown";
+    /** Minecraft version the workspace itself declares, when it could be read. */
+    projectMinecraftVersion?: string;
 }): Promise<{
     searchedPaths: string[];
     candidateArtifacts: string[];
@@ -100,6 +166,8 @@ export declare function resolveBinaryFallbackArtifact(svc: SourceService, input:
     mappingApplied: SourceMapping;
     provenance?: ArtifactProvenance;
     qualityFlags: string[];
+    /** Forwarded from the caller; unset keeps the historical decompile-on-demand behaviour. */
+    allowDecompile?: boolean;
 }): Promise<ResolvedSourceArtifact | undefined>;
 export declare function buildArtifactContentsSummary(_svc: SourceService, input: {
     origin: ResolvedSourceArtifact["origin"];