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

package/dist/error-mapping.js

@@ -17,14 +17,75 @@ export function extractDidYouMean(details) {
         if (!entry || typeof entry !== "object") {
             return undefined;
         }
-        const { className, matchReason } = entry;
+        const { className, matchReason, artifactId } = entry;
         if (typeof className !== "string" || typeof matchReason !== "string") {
             return undefined;
         }
-        cleaned.push({ className, matchReason });
+        // `artifactId` marks a candidate found in an artifact the caller did not name
+        // (the internal binary fallback or nested-jar redirect). It is optional and
+        // dropped when malformed, so a bad value cannot suppress the whole array.
+        cleaned.push({
+            className,
+            matchReason,
+            ...(typeof artifactId === "string" && artifactId ? { artifactId } : {})
+        });
     }
     return cleaned.slice(0, MAX_DID_YOU_MEAN_ENTRIES);
 }
+// A shell jar bundles a handful of inner jars, not hundreds; the cap only
+// bounds a pathological inventory, it is not an expected truncation point.
+const MAX_NESTED_JAR_ENTRIES = 64;
+/**
+ * Validates and extracts a `nestedJars` inventory from error details.
+ * `buildClassSourceNotFoundError` records it whenever the lookup ran against a
+ * shell jar, but `context` is primitive-only, so without this the inventory
+ * never left the process. Malformed payloads are dropped whole rather than
+ * partially published, matching {@link extractDidYouMean}. An empty inventory
+ * is dropped too: the producing site omits the key entirely in that case, so an
+ * empty array carries no information a caller could act on.
+ */
+export function extractNestedJars(details) {
+    const raw = details?.nestedJars;
+    if (!Array.isArray(raw) || raw.length === 0) {
+        return undefined;
+    }
+    const cleaned = [];
+    for (const entry of raw) {
+        if (typeof entry !== "string" || !entry) {
+            return undefined;
+        }
+        cleaned.push(entry);
+    }
+    return cleaned.slice(0, MAX_NESTED_JAR_ENTRIES);
+}
+const ISSUE_ORIGIN_VALUES = new Set([
+    "code_issue",
+    "tool_issue",
+    "environment"
+]);
+/**
+ * Per-throw-site {@link IssueOrigin} override carried on an AppError's
+ * `details.issueOrigin`.
+ *
+ * The default classification is keyed purely on the error CODE, which is right
+ * for codes whose every throw site shares one origin. A few codes do not:
+ * `ERR_CONTEXT_UNRESOLVED` covers both a caller naming a version no artifact
+ * carries (genuinely `code_issue`) and the tool resolving an artifact with no
+ * binary jar behind the caller's back (`tool_issue`). Publishing the latter as
+ * caller-fixable sends an agent into a retry loop over input it cannot repair.
+ *
+ * This override is deliberately opt-in and per-error: `issueOriginForErrorCode`
+ * and its default sets stay untouched, so the exhaustive classification map in
+ * tests/runtime/error-mapping.test.ts keeps forcing a conscious decision for
+ * every new code. The key is not in `CONTEXT_ALLOWLIST`, so it cannot leak into
+ * the public `context` blob.
+ */
+export function extractIssueOriginOverride(details) {
+    const raw = details?.issueOrigin;
+    return typeof raw === "string" && ISSUE_ORIGIN_VALUES.has(raw)
+        ? raw
+        : undefined;
+}
 export function statusForErrorCode(code) {
     if (code === ERROR_CODES.BATCH_ABORTED) {
         return 412;
@@ -193,6 +254,51 @@ export function issueOriginForErrorCode(code) {
     }
     return "tool_issue";
 }
+/**
+ * The single source of truth for a ProblemDetails classification pair, and the
+ * ONLY supported way to compute one for an error the server caught. Every site
+ * that turns a caught error into a published envelope spreads this result — the
+ * tool envelope (`mapErrorToProblem`), batch entries, the batch-aborted
+ * sentinel, and the `mc://` resource read — so one failure always publishes the
+ * same `{ retryClass, issueOrigin }` no matter which access path the caller
+ * used.
+ *
+ * KNOWN EXCEPTION — the synthetic supervisor replies in `src/stdio-supervisor.ts`
+ * (`buildSupervisorQueueLimitReply`, `buildValidateProjectTimeoutReply`) write
+ * the pair as literals and never import this builder. They are not emission
+ * sites for a caught error at all: the supervisor answers a request the worker
+ * never got to run, so there is no source `AppError` whose `details` could carry
+ * an override and nothing to pass as the required `details` argument. Their
+ * literals are `transient` / `tool_issue`, which is exactly what this function
+ * returns for `ERR_LIMIT_EXCEEDED` and `ERR_TOOL_TIMEOUT` today — but that is a
+ * duplicated value held in agreement by hand, not a second call into this
+ * classifier. Reclassifying either code here must be mirrored there.
+ *
+ * It exists because that pair used to be assembled by hand at each site. The
+ * `issueOrigin` half has a per-throw-site override (see
+ * {@link extractIssueOriginOverride}), and honouring it was copy-pasted into
+ * some sites and forgotten in others — which is exactly how one identical
+ * AppError came to publish `tool_issue` through a tool call and `code_issue`
+ * through a resource read. Composing the pair here removes the opportunity:
+ * emission modules import this function and no longer reach the component
+ * classifiers at all.
+ *
+ * `details` is REQUIRED, deliberately without a default. A site that genuinely
+ * has no AppError behind it (a ZodError, a sanitized non-AppError, the
+ * batch-aborted sentinel) must pass `undefined` explicitly, so skipping the
+ * override can only ever be a written-down decision rather than an omission.
+ *
+ * Only `issueOrigin` is overridable per throw site. `retryClass` stays purely
+ * code-derived: it is a documented wire contract, and changing the value an
+ * existing code publishes is a Breaking change, so a `retryClass` override seam
+ * was deliberately deferred rather than added alongside this one.
+ */
+export function problemClassification(code, details) {
+    return {
+        retryClass: retryClassForErrorCode(code),
+        issueOrigin: extractIssueOriginOverride(details) ?? issueOriginForErrorCode(code)
+    };
+}
 // Non-sensitive AppError.details fields that are safe to echo to callers as
 // machine-readable repair context. Filesystem paths and free-form text are
 // intentionally excluded.
@@ -275,6 +381,7 @@ export function errorToBatchEntryProblem(caughtError, instance, options) {
         const fieldErrors = extractFieldErrors(caughtError.details);
         const context = extractAllowlistedContext(caughtError.details);
         const didYouMean = extractDidYouMean(caughtError.details);
+        const nestedJars = extractNestedJars(caughtError.details);
         return {
             type: `https://minecraft-modding-mcp.dev/problems/${caughtError.code.toLowerCase()}`,
             title: "Tool execution error",
@@ -282,12 +389,12 @@ export function errorToBatchEntryProblem(caughtError, instance, options) {
             status: statusForErrorCode(caughtError.code),
             code: caughtError.code,
             instance,
-            retryClass: retryClassForErrorCode(caughtError.code),
-            issueOrigin: issueOriginForErrorCode(caughtError.code),
+            ...problemClassification(caughtError.code, caughtError.details),
             ...(fieldErrors ? { fieldErrors } : {}),
             ...(baseHints ? { hints: baseHints } : {}),
             ...(options?.suggestedCall ? { suggestedCall: options.suggestedCall } : {}),
             ...(didYouMean ? { didYouMean } : {}),
+            ...(nestedJars ? { nestedJars } : {}),
             ...(context ? { context } : {})
         };
     }
@@ -307,8 +414,9 @@ export function errorToBatchEntryProblem(caughtError, instance, options) {
         status: 500,
         code: ERROR_CODES.INTERNAL,
         instance,
-        retryClass: retryClassForErrorCode(ERROR_CODES.INTERNAL),
-        issueOrigin: issueOriginForErrorCode(ERROR_CODES.INTERNAL),
+        // No AppError behind this envelope: the throw was sanitized away, so there
+        // is no per-site override to honour.
+        ...problemClassification(ERROR_CODES.INTERNAL, undefined),
         ...(options?.suggestedCall ? { suggestedCall: options.suggestedCall } : {})
     };
 }
@@ -320,8 +428,8 @@ export function buildBatchAbortedProblem(instance) {
         status: 412,
         code: ERROR_CODES.BATCH_ABORTED,
         instance,
-        retryClass: retryClassForErrorCode(ERROR_CODES.BATCH_ABORTED),
-        issueOrigin: issueOriginForErrorCode(ERROR_CODES.BATCH_ABORTED)
+        // Synthesized sentinel, not a caught AppError: no per-site override exists.
+        ...problemClassification(ERROR_CODES.BATCH_ABORTED, undefined)
     };
 }
 //# sourceMappingURL=error-mapping.js.map

package/dist/index.d.ts

@@ -1,10 +1,48 @@
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { McpServer, type McpRequestContext } from "@modelcontextprotocol/server";
 import { SourceService } from "./source-service.js";
+import { SERVER_VERSION } from "./server-identity.js";
 import { applyErrorMetaExtensions, mapErrorToProblem } from "./tool-guidance.js";
 export { mapErrorToProblem, applyErrorMetaExtensions };
-declare const SERVER_VERSION: string;
-declare const server: McpServer;
 declare const config: import("./types.js").Config;
 declare const sourceService: SourceService;
+/**
+ * Builds a fully-registered McpServer instance. serveStdio calls its factory
+ * PER INSTANCE, not per connection: a modern `server/discover` opening builds
+ * a probe instance which a following legacy `initialize` DISCARDS
+ * (`product.close()`) before calling the factory again — and the probe path
+ * MUTATES the instance (installModernOnlyHandlers adds "2026-07-28" support
+ * and a server/discover handler). Every call therefore constructs a FRESH
+ * McpServer so probe-instance mutations can never leak onto the re-pinned
+ * legacy instance (frozen negotiate-down contract). Module-scope services,
+ * config, and helpers stay shared; only the McpServer and its registrations
+ * are per-instance.
+ *
+ * Tool registration ORDER: the CALL-SITE order inside this function is the
+ * frozen legacy tools/list order — do not reorder the call sites. The calls
+ * are captured as deferred thunks and executed at the bottom of the
+ * function: in call-site order for legacy/ctx-less instances (byte-frozen
+ * golden contract), and in raw tool-name-ascending order when serveStdio
+ * constructs a MODERN-era instance (`ctx.era === "modern"` — the SDK's
+ * documented era-parameterized factory seam; the v2 SDK itself emits
+ * registration order and never sorts). Each instance serves exactly one era,
+ * so the two orders can never mix on one connection. (Adopted ordering
+ * policy.)
+ *
+ * Cache hints (adopted policy, src/cache-policy.ts): the constructor options
+ * configure the non-zero resources/list + resources/templates/list rows;
+ * per-resource rows live in registerResources(); all hints ride the SDK's
+ * never-serialized carrier, so 2025-era responses are unaffected.
+ *
+ * NOTE: the function body below intentionally keeps the original module-scope
+ * indentation of the registration block to preserve a reviewable minimal diff.
+ */
+declare function buildServer(ctx?: McpRequestContext): McpServer;
+/**
+ * Module-scope singleton: populates the register-once tool-schema registry at
+ * load time and serves in-process consumers (tests drive its request handlers
+ * directly). The stdio wire path does NOT serve this instance — serveStdio's
+ * factory builds a fresh one per pinned/probe instance (see buildServer).
+ */
+declare const server: McpServer;
 export declare function startServer(): Promise<void>;
-export { server, sourceService, config, SERVER_VERSION };
+export { server, sourceService, config, SERVER_VERSION, buildServer };