@adhisang/minecraft-modding-mcp 2.1.0 → 3.1.0

package/dist/index.js

@@ -13,6 +13,15 @@ import { remapModJar } from "./mod-remap-service.js";
 import { registerResources } from "./resources.js";
 import { SourceService } from "./source-service.js";
 import { ToolExecutionGate } from "./tool-execution-gate.js";
+import { WorkspaceMappingService } from "./workspace-mapping-service.js";
+import { InspectMinecraftService, inspectMinecraftSchema, inspectMinecraftShape } from "./entry-tools/inspect-minecraft-service.js";
+import { AnalyzeSymbolService, analyzeSymbolSchema, analyzeSymbolShape } from "./entry-tools/analyze-symbol-service.js";
+import { CompareMinecraftService, compareMinecraftSchema, compareMinecraftShape } from "./entry-tools/compare-minecraft-service.js";
+import { AnalyzeModService, analyzeModSchema, analyzeModShape } from "./entry-tools/analyze-mod-service.js";
+import { ValidateProjectService, validateProjectSchema, validateProjectShape, discoverWorkspaceAccessWideners, discoverWorkspaceMixins } from "./entry-tools/validate-project-service.js";
+import { ManageCacheService, manageCacheSchema, manageCacheShape } from "./entry-tools/manage-cache-service.js";
+import { createCacheRegistry } from "./cache-registry.js";
+import { buildEntryToolMeta } from "./entry-tools/response-contract.js";
 if (!process.env.NODE_ENV) {
     process.env.NODE_ENV = "production";
 }
@@ -38,6 +47,14 @@ const HEAVY_TOOL_NAMES = new Set([
     "get-class-api-matrix",
     "get-registry-data"
 ]);
+const ENTRY_TOOL_NAMES = new Set([
+    "inspect-minecraft",
+    "analyze-symbol",
+    "compare-minecraft",
+    "analyze-mod",
+    "validate-project",
+    "manage-cache"
+]);
 const heavyToolExecutionGate = new ToolExecutionGate({ maxConcurrent: 1, maxQueue: 2 });
 const nonEmptyString = z.string().trim().min(1);
 const optionalNonEmptyString = z.string().trim().min(1).optional();
@@ -73,9 +90,28 @@ const sourceLookupTargetSchema = z.discriminatedUnion("type", [
 const RESOLVE_ARTIFACT_TARGET_DESCRIPTION = "Object with kind and value. Example: {\"kind\":\"version\",\"value\":\"1.21.10\"}. Must be an object, not a string.";
 const SOURCE_LOOKUP_TARGET_DESCRIPTION = "Object: {\"type\":\"resolve\",\"kind\":\"version\",\"value\":\"1.21.10\"} or {\"type\":\"artifact\",\"artifactId\":\"...\"}. Must be an object, not a string.";
 const SOURCE_SCOPE_DESCRIPTION = 'vanilla = Mojang client jar only; merged = Loom cache discovery (default); loader = currently behaves the same as "merged".';
+const SUGGESTED_CALL_DEFAULTS = {
+    allowDecompile: true,
+    preferProjectVersion: false,
+    strictVersion: false,
+    mode: "metadata",
+    access: "public",
+    includeSynthetic: false,
+    includeInherited: false,
+    hideUncertain: false,
+    explain: false,
+    preferProjectMapping: false,
+    minSeverity: "all",
+    reportMode: "full",
+    treatInfoAsWarning: true,
+    includeIssues: true
+};
+function isSuggestedCallDefault(field, value) {
+    return value === SUGGESTED_CALL_DEFAULTS[field];
+}
 const listVersionsShape = {
-    includeSnapshots: z.boolean().optional().describe("default false"),
-    limit: optionalPositiveInt.describe("default 20, max 200")
+    includeSnapshots: z.boolean().default(false),
+    limit: optionalPositiveInt.default(20).describe("max 200")
 };
 const listVersionsSchema = z.object(listVersionsShape);
 const resolveArtifactShape = {
@@ -85,7 +121,7 @@ const resolveArtifactShape = {
     }).describe(RESOLVE_ARTIFACT_TARGET_DESCRIPTION),
     mapping: sourceMappingSchema.optional().describe("obfuscated | mojang | intermediary | yarn"),
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
-    allowDecompile: z.boolean().optional().describe("default true"),
+    allowDecompile: z.boolean().default(true),
     projectPath: optionalNonEmptyString.describe("Optional workspace root path for Loom cache-assisted source resolution"),
     scope: artifactScopeSchema.optional().describe(SOURCE_SCOPE_DESCRIPTION),
     preferProjectVersion: z.boolean().optional().describe("When true, detect MC version from gradle.properties and override target.value"),
@@ -94,11 +130,11 @@ const resolveArtifactShape = {
 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"),
+    mode: sourceModeSchema.default("metadata").describe("metadata = symbol outline only; snippet = source with default maxLines=200; full = entire source"),
     target: sourceLookupTargetSchema.describe(SOURCE_LOOKUP_TARGET_DESCRIPTION),
     mapping: sourceMappingSchema.optional().describe("obfuscated | mojang | intermediary | yarn"),
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
-    allowDecompile: z.boolean().optional().describe("default true"),
+    allowDecompile: z.boolean().default(true),
     projectPath: optionalNonEmptyString.describe("Optional workspace root path for Loom cache-assisted source resolution"),
     scope: artifactScopeSchema.optional().describe(SOURCE_SCOPE_DESCRIPTION),
     preferProjectVersion: z.boolean().optional().describe("When true, detect MC version from gradle.properties and override target.value"),
@@ -127,10 +163,10 @@ const getClassMembersShape = {
     target: sourceLookupTargetSchema.describe(SOURCE_LOOKUP_TARGET_DESCRIPTION),
     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)"),
-    includeSynthetic: z.boolean().optional().describe("default false"),
-    includeInherited: z.boolean().optional().describe("default false"),
+    allowDecompile: z.boolean().default(true),
+    access: memberAccessSchema.default("public").describe("public | all"),
+    includeSynthetic: z.boolean().default(false),
+    includeInherited: z.boolean().default(false),
     memberPattern: optionalNonEmptyString,
     maxMembers: optionalPositiveInt.describe("default 500, max 5000"),
     projectPath: optionalNonEmptyString,
@@ -147,8 +183,8 @@ const searchClassSourceShape = {
     packagePrefix: optionalNonEmptyString,
     fileGlob: optionalNonEmptyString,
     symbolKind: searchSymbolKindSchema.optional().describe("class | interface | enum | record | method | field"),
-    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"),
+    queryMode: z.enum(["auto", "token", "literal"]).default("auto").describe("auto: indexed search, including separator queries like foo.bar; token: indexed-only; literal: explicit substring scan only"),
+    limit: optionalPositiveInt.default(20),
     cursor: optionalNonEmptyString
 };
 const searchClassSourceSchema = z.object(searchClassSourceShape).superRefine((value, ctx) => {
@@ -180,9 +216,9 @@ const traceSymbolLifecycleShape = {
     toVersion: optionalNonEmptyString,
     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"),
-    includeTimeline: z.boolean().optional().describe("default false")
+    includeSnapshots: z.boolean().default(false),
+    maxVersions: optionalPositiveInt.default(120).describe("max 400"),
+    includeTimeline: z.boolean().default(false)
 };
 const traceSymbolLifecycleSchema = z.object(traceSymbolLifecycleShape);
 const diffClassSignaturesShape = {
@@ -191,7 +227,7 @@ const diffClassSignaturesShape = {
     toVersion: nonEmptyString,
     mapping: sourceMappingSchema.optional().describe("obfuscated | mojang | intermediary | yarn (default obfuscated)"),
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
-    includeFullDiff: z.boolean().optional().describe("When false, omit from/to snapshots from modified entries and keep only key+changed")
+    includeFullDiff: z.boolean().default(true).describe("When false, omit from/to snapshots from modified entries and keep only key+changed")
 };
 const diffClassSignaturesSchema = z.object(diffClassSignaturesShape);
 const findMappingShape = {
@@ -210,7 +246,7 @@ const findMappingShape = {
     })
         .partial()
         .optional(),
-    maxCandidates: optionalPositiveInt.describe("Limit returned candidates (default 200, max 200)")
+    maxCandidates: optionalPositiveInt.default(200).describe("Limit returned candidates (max 200)")
 };
 const findMappingSchema = z.object(findMappingShape).superRefine((value, ctx) => {
     if (value.kind === "class") {
@@ -277,7 +313,7 @@ const resolveMethodMappingExactShape = {
     sourceMapping: sourceMappingSchema.describe("obfuscated | mojang | intermediary | yarn"),
     targetMapping: sourceMappingSchema.describe("obfuscated | mojang | intermediary | yarn"),
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
-    maxCandidates: optionalPositiveInt.describe("Limit returned candidates (default 200, max 200)")
+    maxCandidates: optionalPositiveInt.default(200).describe("Limit returned candidates (max 200)")
 };
 const resolveMethodMappingExactSchema = z
     .object(resolveMethodMappingExactShape)
@@ -328,7 +364,7 @@ const resolveWorkspaceSymbolShape = {
     descriptor: optionalNonEmptyString,
     sourceMapping: sourceMappingSchema.describe("obfuscated | mojang | intermediary | yarn"),
     sourcePriority: mappingSourcePrioritySchema.optional().describe("loom-first | maven-first"),
-    maxCandidates: optionalPositiveInt.describe("Limit returned candidates for field/method lookups (default 200, max 200)")
+    maxCandidates: optionalPositiveInt.default(200).describe("Limit returned candidates for field/method lookups (max 200)")
 };
 const resolveWorkspaceSymbolSchema = z
     .object(resolveWorkspaceSymbolShape)
@@ -397,10 +433,10 @@ const checkSymbolExistsShape = {
     descriptor: optionalNonEmptyString.describe("required for kind=method unless signatureMode=name-only"),
     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()
-        .describe("exact (default): require descriptor for methods; name-only: match by owner+name only"),
-    maxCandidates: optionalPositiveInt.describe("Limit returned candidates (default 200, max 200)")
+    nameMode: classNameModeSchema.default("fqcn").describe("fqcn | auto"),
+    signatureMode: z.enum(["exact", "name-only"]).default("exact")
+        .describe("exact: require descriptor for methods; name-only: match by owner+name only"),
+    maxCandidates: optionalPositiveInt.default(200).describe("Limit returned candidates (max 200)")
 };
 const checkSymbolExistsSchema = z.object(checkSymbolExistsShape).superRefine((value, ctx) => {
     if (value.kind === "class") {
@@ -461,7 +497,7 @@ const checkSymbolExistsSchema = z.object(checkSymbolExistsShape).superRefine((va
 });
 const nbtToJsonShape = {
     nbtBase64: nonEmptyString,
-    compression: decodeCompressionSchema.optional().describe("none | gzip | auto (default auto)")
+    compression: decodeCompressionSchema.default("auto").describe("none | gzip | auto")
 };
 const nbtToJsonSchema = z.object(nbtToJsonShape);
 const nbtPatchOperationSchema = z
@@ -478,12 +514,12 @@ const nbtApplyJsonPatchShape = {
 const nbtApplyJsonPatchSchema = z.object(nbtApplyJsonPatchShape);
 const jsonToNbtShape = {
     typedJson: z.unknown(),
-    compression: encodeCompressionSchema.optional().describe("none | gzip (default none)")
+    compression: encodeCompressionSchema.default("none").describe("none | gzip")
 };
 const jsonToNbtSchema = z.object(jsonToNbtShape);
 const indexArtifactShape = {
     artifactId: nonEmptyString,
-    force: z.boolean().optional().describe("default false")
+    force: z.boolean().default(false)
 };
 const indexArtifactSchema = z.object(indexArtifactShape);
 const validateMixinShape = {
@@ -517,23 +553,23 @@ const validateMixinShape = {
     scope: artifactScopeSchema.optional().describe(SOURCE_SCOPE_DESCRIPTION),
     projectPath: optionalNonEmptyString.describe("Optional workspace root path for Loom cache-assisted source resolution"),
     preferProjectVersion: z.boolean().optional().describe("When true, detect MC version from gradle.properties and override version"),
-    minSeverity: z.enum(["error", "warning", "all"]).optional()
-        .describe("'error'=errors only, 'warning'=errors+warnings, 'all'=everything (default 'all')"),
-    hideUncertain: z.boolean().optional()
-        .describe("Omit issues with confidence='uncertain' (default false)"),
-    explain: z.boolean().optional()
-        .describe("When true, enrich each issue with explanation and suggestedCall for agent recovery (default false)"),
+    minSeverity: z.enum(["error", "warning", "all"]).default("all")
+        .describe("'error'=errors only, 'warning'=errors+warnings, 'all'=everything"),
+    hideUncertain: z.boolean().default(false)
+        .describe("Omit issues with confidence='uncertain'"),
+    explain: z.boolean().default(false)
+        .describe("When true, enrich each issue with explanation and suggestedCall for agent recovery"),
     warningMode: z.enum(["full", "aggregated"]).optional()
-        .describe("'full'=all warnings (default), 'aggregated'=group warnings by category with counts and samples"),
-    preferProjectMapping: z.boolean().optional()
+        .describe("'full'=all warnings; 'aggregated'=group warnings by category with counts and samples. Single validation uses the provided value as-is; batch validation defaults to 'aggregated'"),
+    preferProjectMapping: z.boolean().default(false)
         .describe("When true, auto-detect mapping from project config even if mapping is explicitly provided"),
-    reportMode: z.enum(["compact", "full", "summary-first"]).optional()
-        .describe("'compact' omits heavy per-result detail, 'summary-first' hoists shared provenance/warnings/incomplete reasons, 'full'=everything (default)"),
+    reportMode: z.enum(["compact", "full", "summary-first"]).default("full")
+        .describe("'compact' omits heavy per-result detail, 'summary-first' hoists shared provenance/warnings/incomplete reasons, 'full'=everything"),
     warningCategoryFilter: z.array(z.enum(["mapping", "configuration", "validation", "resolution", "parse"])).optional()
         .describe("Only include warnings/issues matching these categories (default: all)"),
-    treatInfoAsWarning: z.boolean().optional()
-        .describe("When false, suppress info-severity structured warnings from output (default true)"),
-    includeIssues: z.boolean().optional()
+    treatInfoAsWarning: z.boolean().default(true)
+        .describe("When false, suppress info-severity structured warnings from output"),
+    includeIssues: z.boolean().default(true)
         .describe("When false, keep summary fields but omit per-result issues[] payloads")
 };
 const validateMixinSchema = z.object(validateMixinShape);
@@ -546,13 +582,13 @@ const validateAccessWidenerShape = {
 const validateAccessWidenerSchema = z.object(validateAccessWidenerShape);
 const analyzeModJarShape = {
     jarPath: nonEmptyString.describe("Local path to the mod JAR file"),
-    includeClasses: z.boolean().optional().describe("Include full class listing (default false)")
+    includeClasses: z.boolean().default(false).describe("Include full class listing")
 };
 const analyzeModJarSchema = z.object(analyzeModJarShape);
 const getRegistryDataShape = {
     version: nonEmptyString.describe("Minecraft version (e.g. 1.21)"),
     registry: optionalNonEmptyString.describe('Optional registry name (e.g. "block", "item", "minecraft:biome"). Omit to list all registries.'),
-    includeData: z.boolean().optional().describe("When false, return registry names/counts without full entry bodies"),
+    includeData: z.boolean().default(true).describe("When false, return registry names/counts without full entry bodies"),
     maxEntriesPerRegistry: optionalPositiveInt.describe("Limit returned entries per registry body")
 };
 const getRegistryDataSchema = z.object(getRegistryDataShape);
@@ -561,15 +597,15 @@ const compareVersionsCategorySchema = z.enum(COMPARE_VERSIONS_CATEGORIES);
 const compareVersionsShape = {
     fromVersion: nonEmptyString.describe("Older Minecraft version (e.g. 1.20.4)"),
     toVersion: nonEmptyString.describe("Newer Minecraft version (e.g. 1.21)"),
-    category: compareVersionsCategorySchema.optional().describe("classes | registry | all (default all)"),
+    category: compareVersionsCategorySchema.default("all").describe("classes | registry | all"),
     packageFilter: optionalNonEmptyString.describe("Filter classes to a package prefix (e.g. net.minecraft.world.item)"),
-    maxClassResults: optionalPositiveInt.describe("Max class results per direction (default 500, max 5000)")
+    maxClassResults: optionalPositiveInt.default(500).describe("Max class results per direction (max 5000)")
 };
 const compareVersionsSchema = z.object(compareVersionsShape);
 const decompileModJarShape = {
     jarPath: nonEmptyString.describe("Local path to the mod JAR file"),
     className: optionalNonEmptyString.describe("Optional fully-qualified class name to view source. Omit to list all classes."),
-    includeFiles: z.boolean().optional().describe("When false, omit the full class list and return counts only"),
+    includeFiles: z.boolean().default(true).describe("When false, omit the full class list and return counts only"),
     maxFiles: optionalPositiveInt.describe("Limit returned class names when files are included")
 };
 const decompileModJarSchema = z.object(decompileModJarShape);
@@ -586,8 +622,8 @@ const modSearchTypeSchema = z.enum(MOD_SEARCH_TYPES);
 const searchModSourceShape = {
     jarPath: nonEmptyString.describe("Local path to the mod JAR file"),
     query: nonEmptyString.describe("Search pattern (regex or literal string)"),
-    searchType: modSearchTypeSchema.optional().describe("class | method | field | content | all (default all)"),
-    limit: optionalPositiveInt.describe("Max results (default 50, max 200)")
+    searchType: modSearchTypeSchema.default("all").describe("class | method | field | content | all"),
+    limit: optionalPositiveInt.default(50).describe("Max results (max 200)")
 };
 const searchModSourceSchema = z.object(searchModSourceShape);
 const REMAP_TARGETS = ["yarn", "mojang"];
@@ -639,6 +675,50 @@ const sourceService = new Proxy({}, {
         return typeof value === "function" ? value.bind(service) : value;
     }
 });
+const workspaceMappingService = new WorkspaceMappingService();
+const inspectMinecraftService = new InspectMinecraftService({
+    listVersions: (input) => sourceService.listVersions(input),
+    resolveArtifact: (input) => sourceService.resolveArtifact(input),
+    findClass: (input) => Promise.resolve(sourceService.findClass(input)),
+    getClassSource: (input) => sourceService.getClassSource(input),
+    getClassMembers: (input) => sourceService.getClassMembers(input),
+    searchClassSource: (input) => sourceService.searchClassSource(input),
+    getArtifactFile: (input) => sourceService.getArtifactFile(input),
+    listArtifactFiles: (input) => sourceService.listArtifactFiles(input),
+    detectProjectMinecraftVersion: (projectPath) => workspaceMappingService.detectProjectMinecraftVersion(projectPath)
+});
+const analyzeSymbolService = new AnalyzeSymbolService({
+    checkSymbolExists: (input) => sourceService.checkSymbolExists(input),
+    findMapping: (input) => sourceService.findMapping(input),
+    resolveMethodMappingExact: (input) => sourceService.resolveMethodMappingExact(input),
+    traceSymbolLifecycle: (input) => sourceService.traceSymbolLifecycle(input),
+    resolveWorkspaceSymbol: (input) => sourceService.resolveWorkspaceSymbol(input),
+    getClassApiMatrix: (input) => sourceService.getClassApiMatrix(input)
+});
+const compareMinecraftService = new CompareMinecraftService({
+    compareVersions: (input) => sourceService.compareVersions(input),
+    diffClassSignatures: (input) => sourceService.diffClassSignatures(input),
+    getRegistryData: (input) => sourceService.getRegistryData(input)
+});
+const analyzeModService = new AnalyzeModService({
+    analyzeModJar: (jarPath, options) => analyzeModJar(jarPath, options),
+    decompileModJar: (input) => sourceService.decompileModJar(input),
+    getModClassSource: (input) => sourceService.getModClassSource(input),
+    searchModSource: (input) => sourceService.searchModSource(input),
+    remapModJar: (input) => remapModJar(input, config)
+});
+const validateProjectService = new ValidateProjectService({
+    validateMixin: (input) => sourceService.validateMixin(input),
+    validateAccessWidener: (input) => sourceService.validateAccessWidener(input),
+    discoverMixins: discoverWorkspaceMixins,
+    discoverAccessWideners: discoverWorkspaceAccessWideners
+});
+const manageCacheService = new ManageCacheService({
+    registry: createCacheRegistry({
+        cacheDir: config.cacheDir,
+        sqlitePath: config.sqlitePath
+    })
+});
 registerResources(server, sourceService);
 let processHandlersAttached = false;
 let serverStarted = false;
@@ -847,7 +927,10 @@ function copySourceLookupSuggestionFields(tool, source) {
         : ["className", "mapping", "sourcePriority", "projectPath", "scope", "access", "memberPattern"];
     for (const field of stringFields) {
         const value = source[field];
-        if (typeof value === "string" && value.trim()) {
+        if (typeof value === "string" &&
+            value.trim() &&
+            (!Object.prototype.hasOwnProperty.call(SUGGESTED_CALL_DEFAULTS, field) ||
+                !isSuggestedCallDefault(field, value))) {
             result[field] = value;
         }
     }
@@ -865,7 +948,9 @@ function copySourceLookupSuggestionFields(tool, source) {
         : ["allowDecompile", "preferProjectVersion", "strictVersion", "includeSynthetic", "includeInherited"];
     for (const field of booleanFields) {
         const value = source[field];
-        if (typeof value === "boolean") {
+        if (typeof value === "boolean" &&
+            (!Object.prototype.hasOwnProperty.call(SUGGESTED_CALL_DEFAULTS, field) ||
+                !isSuggestedCallDefault(field, value))) {
             result[field] = value;
         }
     }
@@ -885,7 +970,10 @@ function copyValidateMixinSharedParams(source) {
     ];
     for (const field of stringFields) {
         const value = source[field];
-        if (typeof value === "string" && value.trim()) {
+        if (typeof value === "string" &&
+            value.trim() &&
+            (!Object.prototype.hasOwnProperty.call(SUGGESTED_CALL_DEFAULTS, field) ||
+                !isSuggestedCallDefault(field, value))) {
             result[field] = value;
         }
     }
@@ -899,7 +987,9 @@ function copyValidateMixinSharedParams(source) {
     ];
     for (const field of booleanFields) {
         const value = source[field];
-        if (typeof value === "boolean") {
+        if (typeof value === "boolean" &&
+            (!Object.prototype.hasOwnProperty.call(SUGGESTED_CALL_DEFAULTS, field) ||
+                !isSuggestedCallDefault(field, value))) {
             result[field] = value;
         }
     }
@@ -1037,7 +1127,8 @@ function buildResolveArtifactSuggestedParams(normalizedInput) {
     const booleanFields = ["allowDecompile", "preferProjectVersion", "strictVersion"];
     for (const field of booleanFields) {
         const value = record[field];
-        if (typeof value === "boolean") {
+        if (typeof value === "boolean" &&
+            !isSuggestedCallDefault(field, value)) {
             result[field] = value;
         }
     }
@@ -1146,18 +1237,27 @@ function mapErrorToProblem(caughtError, requestId, context) {
 }
 function splitWarnings(data) {
     const result = { ...data };
+    const warnings = [];
     const maybeWarnings = result.warnings;
-    if (!Array.isArray(maybeWarnings)) {
-        return {
-            result,
-            warnings: []
-        };
+    if (Array.isArray(maybeWarnings)) {
+        warnings.push(...maybeWarnings.filter((entry) => typeof entry === "string"));
+        delete result.warnings;
+    }
+    let meta = {};
+    const maybeMeta = result.meta;
+    if (maybeMeta && typeof maybeMeta === "object" && !Array.isArray(maybeMeta)) {
+        meta = { ...maybeMeta };
+        delete result.meta;
+        const metaWarnings = meta.warnings;
+        if (Array.isArray(metaWarnings)) {
+            warnings.push(...metaWarnings.filter((entry) => typeof entry === "string"));
+            delete meta.warnings;
+        }
     }
-    const warnings = maybeWarnings.filter((entry) => typeof entry === "string");
-    delete result.warnings;
     return {
         result,
-        warnings
+        warnings: [...new Set(warnings)],
+        meta
     };
 }
 async function runTool(tool, rawInput, schema, action) {
@@ -1192,10 +1292,28 @@ async function runTool(tool, rawInput, schema, action) {
         const payload = await (HEAVY_TOOL_NAMES.has(tool)
             ? heavyToolExecutionGate.run(tool, () => action(parsedInput))
             : action(parsedInput));
-        const { result, warnings } = splitWarnings(payload);
+        const { result, warnings, meta: resultMeta } = splitWarnings(payload);
+        const entryMeta = ENTRY_TOOL_NAMES.has(tool)
+            ? buildEntryToolMeta({
+                detail: normalizedInput &&
+                    typeof normalizedInput === "object" &&
+                    !Array.isArray(normalizedInput) &&
+                    typeof normalizedInput.detail === "string"
+                    ? normalizedInput.detail ?? "summary"
+                    : "summary",
+                include: normalizedInput &&
+                    typeof normalizedInput === "object" &&
+                    !Array.isArray(normalizedInput) &&
+                    Array.isArray(normalizedInput.include)
+                    ? normalizedInput.include
+                    : undefined
+            })
+            : undefined;
         return objectResult({
             result,
             meta: {
+                ...(entryMeta ?? {}),
+                ...resultMeta,
                 requestId,
                 tool,
                 durationMs: Date.now() - startedAt,
@@ -1253,6 +1371,12 @@ server.tool("list-versions", "List available Minecraft versions from Mojang mani
     includeSnapshots: input.includeSnapshots,
     limit: input.limit
 })));
+server.tool("inspect-minecraft", "High-level v3 entry tool for version discovery, artifact resolution, class inspection, source search, file reads, and file listings.", inspectMinecraftShape, { readOnlyHint: true }, async (args) => runTool("inspect-minecraft", args, inspectMinecraftSchema, async (input) => inspectMinecraftService.execute(input)));
+server.tool("analyze-symbol", "High-level v3 entry tool for symbol existence, mapping, lifecycle, workspace analysis, and API overview.", analyzeSymbolShape, { readOnlyHint: true }, async (args) => runTool("analyze-symbol", args, analyzeSymbolSchema, async (input) => analyzeSymbolService.execute(input)));
+server.tool("compare-minecraft", "High-level v3 entry tool for version comparisons, class diffs, registry diffs, and migration overviews.", compareMinecraftShape, { readOnlyHint: true }, async (args) => runTool("compare-minecraft", args, compareMinecraftSchema, async (input) => compareMinecraftService.execute(input)));
+server.tool("analyze-mod", "High-level v3 entry tool for mod metadata inspection, decompile/search flows, class source, and safe remap previews/applies.", analyzeModShape, { readOnlyHint: false }, async (args) => runTool("analyze-mod", args, analyzeModSchema, async (input) => analyzeModService.execute(input)));
+server.tool("validate-project", "High-level v3 entry tool for project summary, direct mixin validation, and access widener validation.", validateProjectShape, { readOnlyHint: true }, async (args) => runTool("validate-project", args, validateProjectSchema, async (input) => validateProjectService.execute(input)));
+server.tool("manage-cache", "High-level v3 entry tool for cache summaries, listing, verification, previewed mutation, and explicit apply operations.", manageCacheShape, { readOnlyHint: false }, async (args) => runTool("manage-cache", args, manageCacheSchema, async (input) => manageCacheService.execute(input)));
 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,

package/dist/observability.d.ts

@@ -3,12 +3,19 @@ export interface MetricTimingSnapshot {
     totalMs: number;
     avgMs: number;
     lastMs: number;
+    p95Ms: number;
+    p99Ms: number;
 }
 export interface CacheArtifactByteAccountingRow {
     artifact_id: string;
     content_bytes: number;
     updated_at: string;
 }
+type CacheArtifactByteAccountingRefRow = {
+    artifactId: string;
+    totalContentBytes: number;
+    updatedAt: string;
+};
 export interface RuntimeMetricSnapshot {
     resolve_duration_ms: MetricTimingSnapshot;
     search_duration_ms: MetricTimingSnapshot;
@@ -18,6 +25,10 @@ export interface RuntimeMetricSnapshot {
     search_intent_symbol_duration_ms: MetricTimingSnapshot;
     search_intent_text_duration_ms: MetricTimingSnapshot;
     search_intent_path_duration_ms: MetricTimingSnapshot;
+    search_query_mode_auto_count: number;
+    search_query_mode_token_count: number;
+    search_query_mode_literal_count: number;
+    search_literal_explicit_count: number;
     search_regex_fallback_count: number;
     search_token_bytes_returned: number;
     onehop_expand_count: number;
@@ -43,6 +54,10 @@ export declare class RuntimeMetrics {
     private cacheHits;
     private cacheMisses;
     private repoFailoverCount;
+    private searchQueryModeAutoCount;
+    private searchQueryModeTokenCount;
+    private searchQueryModeLiteralCount;
+    private searchLiteralExplicitCount;
     private searchRegexFallbackCount;
     private searchTokenBytesReturned;
     private oneHopExpandCount;
@@ -58,12 +73,13 @@ export declare class RuntimeMetrics {
     private cacheEvictions;
     private cacheEntries;
     private cacheTotalContentBytes;
-    private cacheArtifactBytesLru;
+    private cacheArtifactBytesLruRef;
     constructor();
     recordDuration(name: DurationMetricName, durationMs: number): void;
     recordArtifactCacheHit(): void;
     recordArtifactCacheMiss(): void;
     recordRepoFailover(): void;
+    recordSearchQueryMode(mode: "auto" | "token" | "literal"): void;
     recordSearchIntentDuration(intent: "symbol" | "text" | "path", durationMs: number): void;
     recordSearchRegexFallback(): void;
     recordSearchTokenBytesReturned(tokenBytes: number): void;
@@ -80,7 +96,7 @@ export declare class RuntimeMetrics {
     recordCacheEviction(count?: number): void;
     setCacheEntries(entries: number): void;
     setCacheTotalContentBytes(totalBytes: number): void;
-    setCacheArtifactByteAccounting(entries: CacheArtifactByteAccountingRow[]): void;
+    setCacheArtifactByteAccountingRef(entries: ReadonlyArray<CacheArtifactByteAccountingRefRow>): void;
     snapshot(): RuntimeMetricSnapshot;
     private toSnapshot;
     private resolveCacheHitRate;

package/dist/observability.js

@@ -1,8 +1,21 @@
+const MAX_TIMING_SAMPLES = 512;
+function percentile(samples, p) {
+    if (samples.length === 0) {
+        return 0;
+    }
+    const sorted = [...samples].sort((left, right) => left - right);
+    const index = Math.min(sorted.length - 1, Math.ceil((p / 100) * sorted.length) - 1);
+    return sorted[index] ?? 0;
+}
 export class RuntimeMetrics {
     timings = new Map();
     cacheHits = 0;
     cacheMisses = 0;
     repoFailoverCount = 0;
+    searchQueryModeAutoCount = 0;
+    searchQueryModeTokenCount = 0;
+    searchQueryModeLiteralCount = 0;
+    searchLiteralExplicitCount = 0;
     searchRegexFallbackCount = 0;
     searchTokenBytesReturned = 0;
     oneHopExpandCount = 0;
@@ -18,7 +31,7 @@ export class RuntimeMetrics {
     cacheEvictions = 0;
     cacheEntries = 0;
     cacheTotalContentBytes = 0;
-    cacheArtifactBytesLru = [];
+    cacheArtifactBytesLruRef = [];
     constructor() {
         const names = [
             "resolve_duration_ms",
@@ -31,7 +44,7 @@ export class RuntimeMetrics {
             "search_intent_path_duration_ms"
         ];
         for (const name of names) {
-            this.timings.set(name, { count: 0, totalMs: 0, lastMs: 0 });
+            this.timings.set(name, { count: 0, totalMs: 0, lastMs: 0, samples: [] });
         }
     }
     recordDuration(name, durationMs) {
@@ -43,6 +56,10 @@ export class RuntimeMetrics {
         timing.count += 1;
         timing.totalMs += normalizedDuration;
         timing.lastMs = normalizedDuration;
+        timing.samples.push(normalizedDuration);
+        if (timing.samples.length > MAX_TIMING_SAMPLES) {
+            timing.samples.shift();
+        }
     }
     recordArtifactCacheHit() {
         this.cacheHits += 1;
@@ -53,6 +70,20 @@ export class RuntimeMetrics {
     recordRepoFailover() {
         this.repoFailoverCount += 1;
     }
+    recordSearchQueryMode(mode) {
+        switch (mode) {
+            case "auto":
+                this.searchQueryModeAutoCount += 1;
+                break;
+            case "token":
+                this.searchQueryModeTokenCount += 1;
+                break;
+            case "literal":
+                this.searchQueryModeLiteralCount += 1;
+                this.searchLiteralExplicitCount += 1;
+                break;
+        }
+    }
     recordSearchIntentDuration(intent, durationMs) {
         const metricName = intent === "symbol"
             ? "search_intent_symbol_duration_ms"
@@ -106,12 +137,8 @@ export class RuntimeMetrics {
     setCacheTotalContentBytes(totalBytes) {
         this.cacheTotalContentBytes = Math.max(0, Math.trunc(totalBytes));
     }
-    setCacheArtifactByteAccounting(entries) {
-        this.cacheArtifactBytesLru = entries.map((entry) => ({
-            artifact_id: entry.artifact_id,
-            content_bytes: Math.max(0, Math.trunc(entry.content_bytes)),
-            updated_at: entry.updated_at
-        }));
+    setCacheArtifactByteAccountingRef(entries) {
+        this.cacheArtifactBytesLruRef = entries;
     }
     snapshot() {
         return {
@@ -123,6 +150,10 @@ export class RuntimeMetrics {
             search_intent_symbol_duration_ms: this.toSnapshot("search_intent_symbol_duration_ms"),
             search_intent_text_duration_ms: this.toSnapshot("search_intent_text_duration_ms"),
             search_intent_path_duration_ms: this.toSnapshot("search_intent_path_duration_ms"),
+            search_query_mode_auto_count: this.searchQueryModeAutoCount,
+            search_query_mode_token_count: this.searchQueryModeTokenCount,
+            search_query_mode_literal_count: this.searchQueryModeLiteralCount,
+            search_literal_explicit_count: this.searchLiteralExplicitCount,
             search_regex_fallback_count: this.searchRegexFallbackCount,
             search_token_bytes_returned: this.searchTokenBytesReturned,
             onehop_expand_count: this.oneHopExpandCount,
@@ -138,7 +169,11 @@ export class RuntimeMetrics {
             cache_evictions: this.cacheEvictions,
             cache_entries: this.cacheEntries,
             cache_total_content_bytes: this.cacheTotalContentBytes,
-            cache_artifact_bytes_lru: this.cacheArtifactBytesLru,
+            cache_artifact_bytes_lru: this.cacheArtifactBytesLruRef.map((entry) => ({
+                artifact_id: entry.artifactId,
+                content_bytes: Math.max(0, Math.trunc(entry.totalContentBytes)),
+                updated_at: entry.updatedAt
+            })),
             cache_hit_rate: this.resolveCacheHitRate(),
             repo_failover_count: this.repoFailoverCount
         };
@@ -151,7 +186,9 @@ export class RuntimeMetrics {
             count,
             totalMs,
             avgMs: count > 0 ? totalMs / count : 0,
-            lastMs: timing?.lastMs ?? 0
+            lastMs: timing?.lastMs ?? 0,
+            p95Ms: percentile(timing?.samples ?? [], 95),
+            p99Ms: percentile(timing?.samples ?? [], 99)
         };
     }
     resolveCacheHitRate() {

package/dist/source-service.d.ts

@@ -488,7 +488,6 @@ export declare class SourceService {
     private searchTextIntent;
     private searchPathIntent;
     private findSymbolHits;
-    private loadScopedFilePaths;
     private indexedCandidateLimit;
     private indexedCandidateLimitForMatch;
     private extractClassMetadata;