@adhisang/minecraft-modding-mcp 1.2.1 → 2.0.0

package/dist/index.js

@@ -3,8 +3,9 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { ZodError, z } from "zod";
 import { CompatStdioServerTransport } from "./compat-stdio-transport.js";
 import { objectResult } from "./mcp-helpers.js";
+import { prepareToolInput } from "./tool-input.js";
 import { loadConfig } from "./config.js";
-import { ERROR_CODES, isAppError } from "./errors.js";
+import { createError, ERROR_CODES, isAppError } from "./errors.js";
 import { log } from "./logger.js";
 import { applyNbtJsonPatch, nbtBase64ToTypedJson, typedJsonToNbtBase64 } from "./nbt/pipeline.js";
 import { analyzeModJar } from "./mod-analyzer.js";
@@ -14,7 +15,7 @@ import { SourceService } from "./source-service.js";
 if (!process.env.NODE_ENV) {
     process.env.NODE_ENV = "production";
 }
-const SOURCE_MAPPINGS = ["official", "mojang", "intermediary", "yarn"];
+const SOURCE_MAPPINGS = ["obfuscated", "mojang", "intermediary", "yarn"];
 const SOURCE_PRIORITIES = ["loom-first", "maven-first"];
 const TARGET_KINDS = ["version", "jar", "coordinate"];
 const SEARCH_INTENTS = ["symbol", "text", "path"];
@@ -43,63 +44,50 @@ const sourceModeSchema = z.enum(SOURCE_MODES);
 const artifactScopeSchema = z.enum(ARTIFACT_SCOPES);
 const decodeCompressionSchema = z.enum(DECODE_COMPRESSIONS);
 const encodeCompressionSchema = z.enum(ENCODE_COMPRESSIONS);
-function validateTargetPair(value, ctx) {
-    const hasArtifactId = Boolean(value.artifactId);
-    const hasTargetKind = value.targetKind !== undefined;
-    const hasTargetValue = value.targetValue !== undefined;
-    if (hasArtifactId && (hasTargetKind || hasTargetValue)) {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            message: "artifactId and targetKind/targetValue are mutually exclusive.",
-            path: ["artifactId"]
-        });
-        return;
-    }
-    if (hasTargetKind !== hasTargetValue) {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            message: "targetKind and targetValue must be provided together.",
-            path: [hasTargetKind ? "targetValue" : "targetKind"]
-        });
-        return;
-    }
-    if (!hasArtifactId && !hasTargetKind) {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            message: "Either artifactId or targetKind+targetValue must be provided.",
-            path: ["artifactId"]
-        });
-    }
-}
+const resolveArtifactTargetSchema = z.object({
+    kind: targetKindSchema,
+    value: nonEmptyString
+});
+const sourceLookupTargetSchema = z.discriminatedUnion("type", [
+    z.object({
+        type: z.literal("artifact"),
+        artifactId: nonEmptyString
+    }),
+    z.object({
+        type: z.literal("resolve"),
+        kind: targetKindSchema,
+        value: nonEmptyString
+    })
+]);
 const listVersionsShape = {
     includeSnapshots: z.boolean().optional().describe("default false"),
     limit: optionalPositiveInt.describe("default 20, max 200")
 };
 const listVersionsSchema = z.object(listVersionsShape);
 const resolveArtifactShape = {
-    targetKind: targetKindSchema.describe("version | jar | coordinate"),
-    targetValue: nonEmptyString,
-    mapping: sourceMappingSchema.optional().describe("official | mojang | intermediary | yarn"),
+    target: z.object({
+        kind: targetKindSchema,
+        value: nonEmptyString
+    }).describe("Resolve target: { kind: version|jar|coordinate, value }"),
+    mapping: sourceMappingSchema.optional().describe("obfuscated | mojang | intermediary | yarn"),
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
     allowDecompile: z.boolean().optional().describe("default true"),
     projectPath: optionalNonEmptyString.describe("Optional workspace root path for Loom cache-assisted source resolution"),
     scope: artifactScopeSchema.optional().describe("vanilla = Mojang client jar only; merged = Loom cache discovery (default); loader = loader-specific"),
-    preferProjectVersion: z.boolean().optional().describe("When true, detect MC version from gradle.properties and override targetValue"),
+    preferProjectVersion: z.boolean().optional().describe("When true, detect MC version from gradle.properties and override target.value"),
     strictVersion: z.boolean().optional().describe("When true, reject version-approximated results instead of returning them. Default false.")
 };
 const resolveArtifactSchema = z.object(resolveArtifactShape);
 const getClassSourceShape = {
     className: nonEmptyString,
     mode: sourceModeSchema.optional().describe("metadata (default) = symbol outline only; snippet = source with default maxLines=200; full = entire source"),
-    artifactId: optionalNonEmptyString,
-    targetKind: targetKindSchema.optional().describe("version | jar | coordinate"),
-    targetValue: optionalNonEmptyString,
-    mapping: sourceMappingSchema.optional().describe("official | mojang | intermediary | yarn"),
+    target: sourceLookupTargetSchema.describe("Either { type: 'artifact', artifactId } or { type: 'resolve', kind, value }"),
+    mapping: sourceMappingSchema.optional().describe("obfuscated | mojang | intermediary | yarn"),
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
     allowDecompile: z.boolean().optional().describe("default true"),
     projectPath: optionalNonEmptyString.describe("Optional workspace root path for Loom cache-assisted source resolution"),
     scope: artifactScopeSchema.optional().describe("vanilla = Mojang client jar only; merged = Loom cache discovery (default); loader = loader-specific"),
-    preferProjectVersion: z.boolean().optional().describe("When true, detect MC version from gradle.properties and override targetValue"),
+    preferProjectVersion: z.boolean().optional().describe("When true, detect MC version from gradle.properties and override target.value"),
     strictVersion: z.boolean().optional().describe("When true, reject version-approximated results instead of returning them. Default false."),
     startLine: optionalPositiveInt,
     endLine: optionalPositiveInt,
@@ -110,11 +98,6 @@ const getClassSourceShape = {
 const getClassSourceSchema = z
     .object(getClassSourceShape)
     .superRefine((value, ctx) => {
-    validateTargetPair({
-        artifactId: value.artifactId,
-        targetKind: value.targetKind,
-        targetValue: value.targetValue
-    }, ctx);
     if (value.startLine !== undefined &&
         value.endLine !== undefined &&
         value.startLine > value.endLine) {
@@ -127,10 +110,8 @@ const getClassSourceSchema = z
 });
 const getClassMembersShape = {
     className: nonEmptyString,
-    artifactId: optionalNonEmptyString,
-    targetKind: targetKindSchema.optional().describe("version | jar | coordinate"),
-    targetValue: optionalNonEmptyString,
-    mapping: sourceMappingSchema.optional().describe("official | mojang | intermediary | yarn (default official)"),
+    target: sourceLookupTargetSchema.describe("Either { type: 'artifact', artifactId } or { type: 'resolve', kind, value }"),
+    mapping: sourceMappingSchema.optional().describe("obfuscated | mojang | intermediary | yarn (default obfuscated)"),
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
     allowDecompile: z.boolean().optional().describe("default true"),
     access: memberAccessSchema.optional().describe("public | all (default public)"),
@@ -143,15 +124,7 @@ const getClassMembersShape = {
     preferProjectVersion: z.boolean().optional().describe("When true, detect MC version from gradle.properties and override version"),
     strictVersion: z.boolean().optional().describe("When true, reject version-approximated results instead of returning them. Default false.")
 };
-const getClassMembersSchema = z
-    .object(getClassMembersShape)
-    .superRefine((value, ctx) => {
-    validateTargetPair({
-        artifactId: value.artifactId,
-        targetKind: value.targetKind,
-        targetValue: value.targetValue
-    }, ctx);
-});
+const getClassMembersSchema = z.object(getClassMembersShape);
 const searchClassSourceShape = {
     artifactId: nonEmptyString,
     query: nonEmptyString,
@@ -160,14 +133,19 @@ const searchClassSourceShape = {
     packagePrefix: optionalNonEmptyString,
     fileGlob: optionalNonEmptyString,
     symbolKind: searchSymbolKindSchema.optional().describe("class | interface | enum | record | method | field"),
-    snippetLines: optionalPositiveInt.describe("default 8, clamp 1..80"),
-    includeDefinition: z.boolean().optional().describe("default false"),
-    includeOneHop: z.boolean().optional().describe("default false"),
     queryMode: z.enum(["auto", "token", "literal"]).optional().describe("auto (default): FTS5 with literal fallback for separator queries; token: FTS5 only; literal: substring scan only"),
     limit: optionalPositiveInt.describe("default 20"),
     cursor: optionalNonEmptyString
 };
-const searchClassSourceSchema = z.object(searchClassSourceShape);
+const searchClassSourceSchema = z.object(searchClassSourceShape).superRefine((value, ctx) => {
+    if (value.symbolKind && value.intent && value.intent !== "symbol") {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["symbolKind"],
+            message: 'symbolKind filter is only supported when intent="symbol".'
+        });
+    }
+});
 const getArtifactFileShape = {
     artifactId: nonEmptyString,
     filePath: nonEmptyString,
@@ -186,7 +164,7 @@ const traceSymbolLifecycleShape = {
     descriptor: optionalNonEmptyString.describe('optional JVM descriptor, e.g. "(I)V"'),
     fromVersion: optionalNonEmptyString,
     toVersion: optionalNonEmptyString,
-    mapping: sourceMappingSchema.optional().describe("official | mojang | intermediary | yarn (default official)"),
+    mapping: sourceMappingSchema.optional().describe("obfuscated | mojang | intermediary | yarn (default obfuscated)"),
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
     includeSnapshots: z.boolean().optional().describe("default false"),
     maxVersions: optionalPositiveInt.describe("default 120, max 400"),
@@ -197,7 +175,7 @@ const diffClassSignaturesShape = {
     className: nonEmptyString,
     fromVersion: nonEmptyString,
     toVersion: nonEmptyString,
-    mapping: sourceMappingSchema.optional().describe("official | mojang | intermediary | yarn (default official)"),
+    mapping: sourceMappingSchema.optional().describe("obfuscated | mojang | intermediary | yarn (default obfuscated)"),
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first")
 };
 const diffClassSignaturesSchema = z.object(diffClassSignaturesShape);
@@ -207,8 +185,8 @@ const findMappingShape = {
     name: nonEmptyString,
     owner: optionalNonEmptyString,
     descriptor: optionalNonEmptyString,
-    sourceMapping: sourceMappingSchema.describe("official | mojang | intermediary | yarn"),
-    targetMapping: sourceMappingSchema.describe("official | mojang | intermediary | yarn"),
+    sourceMapping: sourceMappingSchema.describe("obfuscated | mojang | intermediary | yarn"),
+    targetMapping: sourceMappingSchema.describe("obfuscated | mojang | intermediary | yarn"),
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
     disambiguation: z
         .object({
@@ -277,42 +255,20 @@ const findMappingSchema = z.object(findMappingShape).superRefine((value, ctx) =>
 });
 const resolveMethodMappingExactShape = {
     version: nonEmptyString,
-    kind: workspaceSymbolKindSchema.describe("class | field | method"),
     name: nonEmptyString,
-    owner: optionalNonEmptyString,
-    descriptor: optionalNonEmptyString.describe("required for kind=method"),
-    sourceMapping: sourceMappingSchema.describe("official | mojang | intermediary | yarn"),
-    targetMapping: sourceMappingSchema.describe("official | mojang | intermediary | yarn"),
+    owner: nonEmptyString,
+    descriptor: nonEmptyString.describe("required JVM descriptor"),
+    sourceMapping: sourceMappingSchema.describe("obfuscated | mojang | intermediary | yarn"),
+    targetMapping: sourceMappingSchema.describe("obfuscated | mojang | intermediary | yarn"),
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first")
 };
 const resolveMethodMappingExactSchema = z
     .object(resolveMethodMappingExactShape)
     .superRefine((value, ctx) => {
-    if (value.kind !== "method") {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            message: "resolve-method-mapping-exact requires kind=method.",
-            path: ["kind"]
-        });
-    }
-    if (!value.owner) {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            message: "owner is required when kind=method.",
-            path: ["owner"]
-        });
-    }
-    if (!value.descriptor) {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            message: "descriptor is required when kind=method.",
-            path: ["descriptor"]
-        });
-    }
     if (/[\s./()]/.test(value.name)) {
         ctx.addIssue({
             code: z.ZodIssueCode.custom,
-            message: "name must be a simple method name when kind=method.",
+            message: "name must be a simple method name.",
             path: ["name"]
         });
     }
@@ -340,7 +296,7 @@ const classApiKindsSchema = z.string().superRefine((value, ctx) => {
 const getClassApiMatrixShape = {
     version: nonEmptyString,
     className: nonEmptyString,
-    classNameMapping: sourceMappingSchema.describe("official | mojang | intermediary | yarn"),
+    classNameMapping: sourceMappingSchema.describe("obfuscated | mojang | intermediary | yarn"),
     includeKinds: classApiKindsSchema.optional().describe("comma-separated: class,field,method"),
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first")
 };
@@ -352,7 +308,7 @@ const resolveWorkspaceSymbolShape = {
     name: nonEmptyString,
     owner: optionalNonEmptyString,
     descriptor: optionalNonEmptyString,
-    sourceMapping: sourceMappingSchema.describe("official | mojang | intermediary | yarn"),
+    sourceMapping: sourceMappingSchema.describe("obfuscated | mojang | intermediary | yarn"),
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first")
 };
 const resolveWorkspaceSymbolSchema = z
@@ -420,7 +376,7 @@ const checkSymbolExistsShape = {
     owner: optionalNonEmptyString,
     name: nonEmptyString,
     descriptor: optionalNonEmptyString.describe("required for kind=method unless signatureMode=name-only"),
-    sourceMapping: sourceMappingSchema.describe("official | mojang | intermediary | yarn"),
+    sourceMapping: sourceMappingSchema.describe("obfuscated | mojang | intermediary | yarn"),
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
     nameMode: classNameModeSchema.optional().describe("fqcn | auto (default fqcn)"),
     signatureMode: z.enum(["exact", "name-only"]).optional()
@@ -511,15 +467,28 @@ const indexArtifactShape = {
 };
 const indexArtifactSchema = z.object(indexArtifactShape);
 const validateMixinShape = {
-    source: optionalNonEmptyString.describe("Mixin Java source text (mutually exclusive with sourcePath/sourcePaths/mixinConfigPath)"),
-    sourcePath: optionalNonEmptyString.describe("Path to Mixin .java file (alternative to source/sourcePaths/mixinConfigPath)"),
-    sourcePaths: z.array(z.string().min(1)).optional().describe("Array of Mixin .java file paths for batch validation"),
-    mixinConfigPath: z.union([nonEmptyString, z.array(nonEmptyString).min(1)]).optional().describe("Path (or array of paths) to mixin config JSON (e.g. modid.mixins.json); auto-discovers and batch-validates all listed classes"),
-    sourceRoot: optionalNonEmptyString.describe("Source root relative to projectPath (default 'src/main/java')"),
+    input: z.discriminatedUnion("mode", [
+        z.object({
+            mode: z.literal("inline"),
+            source: nonEmptyString.describe("Mixin Java source text")
+        }),
+        z.object({
+            mode: z.literal("path"),
+            path: nonEmptyString.describe("Path to a Mixin .java file")
+        }),
+        z.object({
+            mode: z.literal("paths"),
+            paths: z.array(nonEmptyString).min(1).describe("Array of Mixin .java file paths for batch validation")
+        }),
+        z.object({
+            mode: z.literal("config"),
+            configPaths: z.array(nonEmptyString).min(1).describe("Path array to mixin config JSON files (e.g. modid.mixins.json)")
+        })
+    ]),
     sourceRoots: z.array(z.string().min(1)).optional()
         .describe("Array of source roots for multi-module projects (e.g. ['common/src/main/java', 'neoforge/src/main/java'])"),
     version: nonEmptyString.describe("Minecraft version"),
-    mapping: sourceMappingSchema.optional().describe("official | mojang | intermediary | yarn"),
+    mapping: sourceMappingSchema.optional().describe("obfuscated | mojang | intermediary | yarn"),
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
     scope: artifactScopeSchema.optional().describe("vanilla | merged | loader"),
     projectPath: optionalNonEmptyString.describe("Optional workspace root path for Loom cache-assisted source resolution"),
@@ -541,18 +510,11 @@ const validateMixinShape = {
     treatInfoAsWarning: z.boolean().optional()
         .describe("When false, suppress info-severity structured warnings from output (default true)")
 };
-const validateMixinSchema = z.object(validateMixinShape).refine((d) => {
-    const hasSource = d.source != null;
-    const hasSourcePath = d.sourcePath != null;
-    const hasSourcePaths = d.sourcePaths != null && d.sourcePaths.length > 0;
-    const hasMixinConfig = d.mixinConfigPath != null && (typeof d.mixinConfigPath === "string" || (Array.isArray(d.mixinConfigPath) && d.mixinConfigPath.length > 0));
-    // Exactly one of the four must be provided
-    return [hasSource, hasSourcePath, hasSourcePaths, hasMixinConfig].filter(Boolean).length === 1;
-}, { message: "Exactly one of 'source', 'sourcePath', 'sourcePaths', or 'mixinConfigPath' must be provided." });
+const validateMixinSchema = z.object(validateMixinShape);
 const validateAccessWidenerShape = {
     content: nonEmptyString.describe("Access Widener file content"),
     version: nonEmptyString.describe("Minecraft version"),
-    mapping: sourceMappingSchema.optional().describe("official | mojang | intermediary | yarn"),
+    mapping: sourceMappingSchema.optional().describe("obfuscated | mojang | intermediary | yarn"),
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first")
 };
 const validateAccessWidenerSchema = z.object(validateAccessWidenerShape);
@@ -672,11 +634,16 @@ function attachProcessErrorHandlers() {
 function buildRequestId() {
     return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
 }
-function buildTarget(kind, value) {
-    if (!kind || !value) {
-        return undefined;
+function normalizeSourceLookupTarget(target) {
+    if (target.type === "artifact") {
+        return { artifactId: target.artifactId };
     }
-    return { kind, value };
+    return {
+        target: {
+            kind: target.kind,
+            value: target.value
+        }
+    };
 }
 function parseClassApiKinds(value) {
     if (value == null) {
@@ -857,7 +824,28 @@ async function runTool(tool, rawInput, schema, action) {
     const requestId = buildRequestId();
     const startedAt = Date.now();
     try {
-        const parsedInput = schema.parse(rawInput);
+        const { normalizedInput, removedOfficialPaths, suggestedReplacementInput } = prepareToolInput(rawInput);
+        if (removedOfficialPaths.length > 0) {
+            throw createError({
+                code: ERROR_CODES.INVALID_INPUT,
+                message: `The "official" mapping namespace was removed. Use "obfuscated" instead.`,
+                details: {
+                    fieldErrors: removedOfficialPaths.map((path) => ({
+                        path,
+                        message: `"official" is no longer supported for this field. Use "obfuscated".`,
+                        code: "invalid_enum_value"
+                    })),
+                    nextAction: `Replace "official" with "obfuscated" in mapping-related fields and retry.`,
+                    suggestedCall: suggestedReplacementInput
+                        ? {
+                            tool,
+                            params: suggestedReplacementInput
+                        }
+                        : undefined
+                }
+            });
+        }
+        const parsedInput = schema.parse(normalizedInput);
         const payload = await action(parsedInput);
         const { result, warnings } = splitWarnings(payload);
         return objectResult({
@@ -910,18 +898,15 @@ async function runTool(tool, rawInput, schema, action) {
                 durationMs: Date.now() - startedAt,
                 warnings: []
             }
-        });
+        }, { isError: true });
     }
 }
 server.tool("list-versions", "List available Minecraft versions from Mojang manifest and locally cached version jars.", listVersionsShape, { readOnlyHint: true }, async (args) => runTool("list-versions", args, listVersionsSchema, async (input) => sourceService.listVersions({
     includeSnapshots: input.includeSnapshots,
     limit: input.limit
 })));
-server.tool("resolve-artifact", "Resolve source artifact from version, jar path, or Maven coordinate and return artifact metadata. For targetKind=jar, only <basename>-sources.jar is auto-adopted; other adjacent *-sources.jar files are informational.", resolveArtifactShape, { readOnlyHint: true }, async (args) => runTool("resolve-artifact", args, resolveArtifactSchema, async (input) => sourceService.resolveArtifact({
-    target: {
-        kind: input.targetKind,
-        value: input.targetValue
-    },
+server.tool("resolve-artifact", "Resolve source artifact from a target object ({ kind, value }) and return artifact metadata. For target.kind=jar, only <basename>-sources.jar is auto-adopted; other adjacent *-sources.jar files are informational.", resolveArtifactShape, { readOnlyHint: true }, async (args) => runTool("resolve-artifact", args, resolveArtifactSchema, async (input) => sourceService.resolveArtifact({
+    target: input.target,
     mapping: input.mapping,
     sourcePriority: input.sourcePriority,
     allowDecompile: input.allowDecompile,
@@ -941,42 +926,48 @@ server.tool("find-class", "Resolve a simple or qualified class name to fully-qua
     artifactId: input.artifactId,
     limit: input.limit
 })));
-server.tool("get-class-source", "Get Java source for a class by artifactId or by resolving target (version/jar/coordinate). Default mode=metadata returns symbol outline only; use mode=snippet for bounded excerpts or mode=full for entire source.", getClassSourceShape, { readOnlyHint: true }, async (args) => runTool("get-class-source", args, getClassSourceSchema, async (input) => sourceService.getClassSource({
-    className: input.className,
-    mode: input.mode,
-    artifactId: input.artifactId,
-    target: buildTarget(input.targetKind, input.targetValue),
-    mapping: input.mapping,
-    sourcePriority: input.sourcePriority,
-    allowDecompile: input.allowDecompile,
-    projectPath: input.projectPath,
-    scope: input.scope,
-    preferProjectVersion: input.preferProjectVersion,
-    strictVersion: input.strictVersion,
-    startLine: input.startLine,
-    endLine: input.endLine,
-    maxLines: input.maxLines,
-    maxChars: input.maxChars,
-    outputFile: input.outputFile
-})));
-server.tool("get-class-members", "Get fields/methods/constructors for one class from binary bytecode by artifactId or by resolving target (version/jar/coordinate).", getClassMembersShape, { readOnlyHint: true }, async (args) => runTool("get-class-members", args, getClassMembersSchema, async (input) => sourceService.getClassMembers({
-    className: input.className,
-    artifactId: input.artifactId,
-    target: buildTarget(input.targetKind, input.targetValue),
-    mapping: input.mapping,
-    sourcePriority: input.sourcePriority,
-    allowDecompile: input.allowDecompile,
-    access: input.access,
-    includeSynthetic: input.includeSynthetic,
-    includeInherited: input.includeInherited,
-    memberPattern: input.memberPattern,
-    maxMembers: input.maxMembers,
-    projectPath: input.projectPath,
-    scope: input.scope,
-    preferProjectVersion: input.preferProjectVersion,
-    strictVersion: input.strictVersion
-})));
-server.tool("search-class-source", "Search indexed class source files for one artifact with symbol/text/path intent and optional one-hop relation expansion.", searchClassSourceShape, { readOnlyHint: true }, async (args) => runTool("search-class-source", args, searchClassSourceSchema, async (input) => {
+server.tool("get-class-source", "Get Java source for a class by target ({ type: 'artifact', artifactId } or { type: 'resolve', kind, value }). Default mode=metadata returns symbol outline only; use mode=snippet for bounded excerpts or mode=full for entire source.", getClassSourceShape, { readOnlyHint: true }, async (args) => runTool("get-class-source", args, getClassSourceSchema, async (input) => {
+    const normalizedTarget = normalizeSourceLookupTarget(input.target);
+    return sourceService.getClassSource({
+        className: input.className,
+        mode: input.mode,
+        artifactId: normalizedTarget.artifactId,
+        target: normalizedTarget.target,
+        mapping: input.mapping,
+        sourcePriority: input.sourcePriority,
+        allowDecompile: input.allowDecompile,
+        projectPath: input.projectPath,
+        scope: input.scope,
+        preferProjectVersion: input.preferProjectVersion,
+        strictVersion: input.strictVersion,
+        startLine: input.startLine,
+        endLine: input.endLine,
+        maxLines: input.maxLines,
+        maxChars: input.maxChars,
+        outputFile: input.outputFile
+    });
+}));
+server.tool("get-class-members", "Get fields/methods/constructors for one class from binary bytecode by target ({ type: 'artifact', artifactId } or { type: 'resolve', kind, value }).", getClassMembersShape, { readOnlyHint: true }, async (args) => runTool("get-class-members", args, getClassMembersSchema, async (input) => {
+    const normalizedTarget = normalizeSourceLookupTarget(input.target);
+    return sourceService.getClassMembers({
+        className: input.className,
+        artifactId: normalizedTarget.artifactId,
+        target: normalizedTarget.target,
+        mapping: input.mapping,
+        sourcePriority: input.sourcePriority,
+        allowDecompile: input.allowDecompile,
+        access: input.access,
+        includeSynthetic: input.includeSynthetic,
+        includeInherited: input.includeInherited,
+        memberPattern: input.memberPattern,
+        maxMembers: input.maxMembers,
+        projectPath: input.projectPath,
+        scope: input.scope,
+        preferProjectVersion: input.preferProjectVersion,
+        strictVersion: input.strictVersion
+    });
+}));
+server.tool("search-class-source", "Search indexed class source files for one artifact with symbol/text/path intent and compact hit output.", searchClassSourceShape, { readOnlyHint: true }, async (args) => runTool("search-class-source", args, searchClassSourceSchema, async (input) => {
     const scope = input.packagePrefix || input.fileGlob || input.symbolKind
         ? {
             packagePrefix: input.packagePrefix,
@@ -984,22 +975,12 @@ server.tool("search-class-source", "Search indexed class source files for one ar
             symbolKind: input.symbolKind
         }
         : undefined;
-    const include = input.snippetLines !== undefined ||
-        input.includeDefinition !== undefined ||
-        input.includeOneHop !== undefined
-        ? {
-            snippetLines: input.snippetLines,
-            includeDefinition: input.includeDefinition,
-            includeOneHop: input.includeOneHop
-        }
-        : undefined;
     return sourceService.searchClassSource({
         artifactId: input.artifactId,
         query: input.query,
         intent: input.intent,
         match: input.match,
         scope: scope,
-        include,
         queryMode: input.queryMode,
         limit: input.limit,
         cursor: input.cursor
@@ -1042,7 +1023,6 @@ server.tool("find-mapping", "Find symbol mapping candidates between namespaces u
 })));
 server.tool("resolve-method-mapping-exact", "Resolve one method mapping exactly by owner+name+descriptor between namespaces and report resolved/not_found/ambiguous.", resolveMethodMappingExactShape, { readOnlyHint: true }, async (args) => runTool("resolve-method-mapping-exact", args, resolveMethodMappingExactSchema, async (input) => sourceService.resolveMethodMappingExact({
     version: input.version,
-    kind: input.kind,
     name: input.name,
     owner: input.owner,
     descriptor: input.descriptor,
@@ -1050,7 +1030,7 @@ server.tool("resolve-method-mapping-exact", "Resolve one method mapping exactly
     targetMapping: input.targetMapping,
     sourcePriority: input.sourcePriority
 })));
-server.tool("get-class-api-matrix", "List class/member API rows across official/mojang/intermediary/yarn mappings for one class and Minecraft version.", getClassApiMatrixShape, { readOnlyHint: true }, async (args) => runTool("get-class-api-matrix", args, getClassApiMatrixSchema, async (input) => sourceService.getClassApiMatrix({
+server.tool("get-class-api-matrix", "List class/member API rows across obfuscated/mojang/intermediary/yarn mappings for one class and Minecraft version.", getClassApiMatrixShape, { readOnlyHint: true }, async (args) => runTool("get-class-api-matrix", args, getClassApiMatrixSchema, async (input) => sourceService.getClassApiMatrix({
     version: input.version,
     className: input.className,
     classNameMapping: input.classNameMapping,
@@ -1096,11 +1076,7 @@ server.tool("index-artifact", "Rebuild indexed files/symbols metadata for an exi
 })));
 server.tool("get-runtime-metrics", "Get runtime service counters and latency snapshots for cache/search/index diagnostics.", { readOnlyHint: true }, async (args) => runTool("get-runtime-metrics", args, emptySchema, async () => Promise.resolve(sourceService.getRuntimeMetrics())));
 server.tool("validate-mixin", "Validate Mixin source against Minecraft bytecode signatures for a given version.", validateMixinShape, { readOnlyHint: true }, async (args) => runTool("validate-mixin", args, validateMixinSchema, async (input) => sourceService.validateMixin({
-    source: input.source,
-    sourcePath: input.sourcePath,
-    sourcePaths: input.sourcePaths,
-    mixinConfigPath: input.mixinConfigPath,
-    sourceRoot: input.sourceRoot,
+    input: input.input,
     sourceRoots: input.sourceRoots,
     version: input.version,
     mapping: input.mapping,

package/dist/mapping-pipeline-service.d.ts

@@ -12,7 +12,7 @@ export interface MappingPipelineResult {
 /**
  * Mapping pipeline for v0.3.
  * Current implementation enforces explicit guarantees:
- * - official: always pass-through
+ * - obfuscated: always pass-through
  * - mojang: requires source-backed artifact; decompile-only artifacts are rejected
  */
 export declare function applyMappingPipeline(input: MappingPipelineInput): MappingPipelineResult;

package/dist/mapping-pipeline-service.js

@@ -2,14 +2,14 @@ import { createError, ERROR_CODES } from "./errors.js";
 /**
  * Mapping pipeline for v0.3.
  * Current implementation enforces explicit guarantees:
- * - official: always pass-through
+ * - obfuscated: always pass-through
  * - mojang: requires source-backed artifact; decompile-only artifacts are rejected
  */
 export function applyMappingPipeline(input) {
     const transformChain = [];
     const qualityFlags = [];
-    if (input.requestedMapping === "official") {
-        transformChain.push("mapping:official-pass-through");
+    if (input.requestedMapping === "obfuscated") {
+        transformChain.push("mapping:obfuscated-pass-through");
         if (input.resolved.isDecompiled) {
             qualityFlags.push("decompiled");
         }
@@ -17,7 +17,7 @@ export function applyMappingPipeline(input) {
             qualityFlags.push("source-backed");
         }
         return {
-            mappingApplied: "official",
+            mappingApplied: "obfuscated",
             qualityFlags,
             transformChain
         };
@@ -45,7 +45,7 @@ export function applyMappingPipeline(input) {
                 origin: input.resolved.origin,
                 binaryJarPath: input.resolved.binaryJarPath,
                 sourceJarPath: input.resolved.sourceJarPath,
-                nextAction: "Provide a source-backed artifact (source jar) or use mapping=official."
+                nextAction: "Provide a source-backed artifact (source jar) or use mapping=obfuscated."
             }
         });
     }

package/dist/mapping-service.d.ts

@@ -78,10 +78,9 @@ export type EnsureMappingAvailableOutput = {
 };
 export type ResolveMethodMappingExactInput = {
     version: string;
-    kind: SymbolQueryKind;
     name: string;
-    owner?: string;
-    descriptor?: string;
+    owner: string;
+    descriptor: string;
     sourceMapping: SourceMapping;
     targetMapping: SourceMapping;
     sourcePriority?: MappingSourcePriority;
@@ -104,7 +103,7 @@ export type ClassApiMatrixEntry = {
 export type ClassApiMatrixRow = {
     kind: ClassApiMatrixKind;
     descriptor?: string;
-    official?: ClassApiMatrixEntry;
+    obfuscated?: ClassApiMatrixEntry;
     mojang?: ClassApiMatrixEntry;
     intermediary?: ClassApiMatrixEntry;
     yarn?: ClassApiMatrixEntry;