@adhisang/minecraft-modding-mcp 2.1.0 → 3.0.0

package/dist/entry-tools/validate-project-service.js

@@ -0,0 +1,381 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import fastGlob from "fast-glob";
+import { z } from "zod";
+import { createError, ERROR_CODES } from "../errors.js";
+import { buildIncludeSchema, detailSchema } from "./entry-tool-schema.js";
+import { buildEntryToolResult } from "./response-contract.js";
+import { resolveDetail, resolveInclude } from "./request-normalizers.js";
+const nonEmptyString = z.string().trim().min(1);
+const INCLUDE_GROUPS = ["warnings", "issues", "workspace", "recovery"];
+const mixinInputSchema = z.discriminatedUnion("mode", [
+    z.object({ mode: z.literal("inline"), source: nonEmptyString }),
+    z.object({ mode: z.literal("path"), path: nonEmptyString }),
+    z.object({ mode: z.literal("paths"), paths: z.array(nonEmptyString).min(1) }),
+    z.object({ mode: z.literal("config"), configPaths: z.array(nonEmptyString).min(1) }),
+    z.object({ mode: z.literal("project"), path: nonEmptyString })
+]);
+const accessWidenerInputSchema = z.discriminatedUnion("mode", [
+    z.object({ mode: z.literal("inline"), content: nonEmptyString }),
+    z.object({ mode: z.literal("path"), path: nonEmptyString })
+]);
+const subjectSchema = z.discriminatedUnion("kind", [
+    z.object({
+        kind: z.literal("workspace"),
+        projectPath: nonEmptyString,
+        discover: z.array(z.enum(["mixins", "access-wideners"])).optional()
+    }),
+    z.object({
+        kind: z.literal("mixin"),
+        input: mixinInputSchema
+    }),
+    z.object({
+        kind: z.literal("access-widener"),
+        input: accessWidenerInputSchema
+    })
+]);
+export const validateProjectShape = {
+    task: z.enum(["project-summary", "mixin", "access-widener"]),
+    subject: subjectSchema,
+    version: nonEmptyString.optional(),
+    mapping: z.enum(["obfuscated", "mojang", "intermediary", "yarn"]).optional(),
+    sourcePriority: z.enum(["loom-first", "maven-first"]).optional(),
+    scope: z.enum(["vanilla", "merged", "loader"]).optional(),
+    preferProjectVersion: z.boolean().optional(),
+    preferProjectMapping: z.boolean().optional(),
+    detail: detailSchema.optional(),
+    include: buildIncludeSchema(INCLUDE_GROUPS),
+    sourceRoots: z.array(nonEmptyString).optional(),
+    configPaths: z.array(nonEmptyString).optional(),
+    minSeverity: z.enum(["error", "warning", "all"]).optional(),
+    hideUncertain: z.boolean().optional(),
+    explain: z.boolean().optional(),
+    warningMode: z.enum(["full", "aggregated"]).optional(),
+    warningCategoryFilter: z.array(z.enum(["mapping", "configuration", "validation", "resolution", "parse"])).optional(),
+    treatInfoAsWarning: z.boolean().optional(),
+    includeIssues: z.boolean().optional()
+};
+export const validateProjectSchema = z.object(validateProjectShape).superRefine((value, ctx) => {
+    if (value.task === "project-summary" && value.subject.kind !== "workspace") {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["subject", "kind"],
+            message: "task=project-summary requires subject.kind=workspace."
+        });
+    }
+    if (value.task === "mixin" && value.subject.kind !== "mixin") {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["subject", "kind"],
+            message: "task=mixin requires subject.kind=mixin."
+        });
+    }
+    if (value.task === "access-widener" && value.subject.kind !== "access-widener") {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["subject", "kind"],
+            message: "task=access-widener requires subject.kind=access-widener."
+        });
+    }
+    if (value.configPaths?.length && value.task !== "project-summary") {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["configPaths"],
+            message: "configPaths is only supported for task=project-summary workspace discovery."
+        });
+    }
+});
+export async function discoverWorkspaceMixins(projectPath, configPaths) {
+    if (configPaths?.length) {
+        return [...configPaths];
+    }
+    return fastGlob.sync(["**/*.mixins.json"], {
+        cwd: projectPath,
+        absolute: true,
+        onlyFiles: true,
+        ignore: ["**/.git/**", "**/build/**", "**/out/**", "**/node_modules/**"]
+    });
+}
+export async function discoverWorkspaceAccessWideners(projectPath) {
+    const descriptorFiles = fastGlob.sync(["fabric.mod.json", "quilt.mod.json", "**/fabric.mod.json", "**/quilt.mod.json"], {
+        cwd: projectPath,
+        absolute: true,
+        onlyFiles: true,
+        ignore: ["**/.git/**", "**/build/**", "**/out/**", "**/node_modules/**"]
+    });
+    const discovered = new Set();
+    for (const descriptorPath of descriptorFiles) {
+        try {
+            const parsed = JSON.parse(await readFile(descriptorPath, "utf8"));
+            const relative = parsed.accessWidener ?? parsed.access_widener;
+            if (relative) {
+                discovered.add(resolve(descriptorPath, "..", relative));
+            }
+        }
+        catch {
+            // ignore malformed descriptors in discovery mode
+        }
+    }
+    return [...discovered].sort((left, right) => left.localeCompare(right));
+}
+export class ValidateProjectService {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async execute(input) {
+        const detail = resolveDetail(input.detail);
+        const include = resolveInclude(input.include);
+        switch (input.task) {
+            case "mixin": {
+                if (input.subject.kind !== "mixin") {
+                    throw createError({
+                        code: ERROR_CODES.INVALID_INPUT,
+                        message: "task=mixin requires subject.kind=mixin."
+                    });
+                }
+                const output = await this.deps.validateMixin({
+                    input: input.subject.input,
+                    version: input.version,
+                    mapping: input.mapping,
+                    sourcePriority: input.sourcePriority,
+                    scope: input.scope,
+                    preferProjectVersion: input.preferProjectVersion,
+                    preferProjectMapping: input.preferProjectMapping,
+                    sourceRoots: input.sourceRoots,
+                    minSeverity: input.minSeverity,
+                    hideUncertain: input.hideUncertain,
+                    explain: input.explain,
+                    warningMode: input.warningMode,
+                    warningCategoryFilter: input.warningCategoryFilter,
+                    treatInfoAsWarning: input.treatInfoAsWarning,
+                    includeIssues: input.includeIssues
+                });
+                const summary = output.summary;
+                const invalidCount = summary?.invalid ?? 0;
+                const partialCount = summary?.partial ?? 0;
+                return {
+                    ...buildEntryToolResult({
+                        task: "mixin",
+                        detail,
+                        include,
+                        summary: {
+                            status: invalidCount > 0 ? "invalid" : partialCount > 0 ? "partial" : "ok",
+                            headline: `Validated ${summary?.total ?? 0} mixin input(s).`,
+                            counts: {
+                                valid: summary?.valid ?? 0,
+                                partial: partialCount,
+                                invalid: invalidCount
+                            }
+                        },
+                        blocks: {
+                            project: {
+                                summary
+                            },
+                            issues: include.includes("issues") || detail !== "summary" ? output.results : undefined
+                        },
+                        alwaysBlocks: ["project"]
+                    }),
+                    warnings: Array.isArray(output.warnings) ? output.warnings : []
+                };
+            }
+            case "access-widener": {
+                if (input.subject.kind !== "access-widener") {
+                    throw createError({
+                        code: ERROR_CODES.INVALID_INPUT,
+                        message: "task=access-widener requires subject.kind=access-widener."
+                    });
+                }
+                const content = input.subject.input.mode === "inline"
+                    ? input.subject.input.content
+                    : await readFile(input.subject.input.path, "utf8");
+                const output = await this.deps.validateAccessWidener({
+                    content,
+                    version: input.version,
+                    mapping: input.mapping,
+                    sourcePriority: input.sourcePriority
+                });
+                return {
+                    ...buildEntryToolResult({
+                        task: "access-widener",
+                        detail,
+                        include,
+                        summary: {
+                            status: output.valid ? "ok" : "invalid",
+                            headline: output.valid
+                                ? "Access Widener is valid."
+                                : "Access Widener contains validation issues.",
+                            counts: {
+                                valid: output.valid ? 1 : 0,
+                                invalid: output.valid ? 0 : 1
+                            }
+                        },
+                        blocks: {
+                            project: {
+                                summary: {
+                                    total: 1,
+                                    valid: output.valid ? 1 : 0,
+                                    invalid: output.valid ? 0 : 1
+                                }
+                            },
+                            issues: include.includes("issues") || detail !== "summary" ? output.issues : undefined
+                        },
+                        alwaysBlocks: ["project"]
+                    }),
+                    warnings: Array.isArray(output.warnings) ? output.warnings : []
+                };
+            }
+            case "project-summary": {
+                if (input.subject.kind !== "workspace") {
+                    throw createError({
+                        code: ERROR_CODES.INVALID_INPUT,
+                        message: "task=project-summary requires subject.kind=workspace."
+                    });
+                }
+                if (!input.version && !input.preferProjectVersion) {
+                    return {
+                        ...buildEntryToolResult({
+                            task: "project-summary",
+                            detail,
+                            include,
+                            summary: {
+                                status: "blocked",
+                                headline: "project-summary requires version or preferProjectVersion=true.",
+                                nextActions: [
+                                    {
+                                        tool: "validate-project",
+                                        params: {
+                                            task: "project-summary",
+                                            version: "1.21.10",
+                                            subject: input.subject
+                                        }
+                                    }
+                                ]
+                            },
+                            blocks: {
+                                workspace: {
+                                    projectPath: input.subject.projectPath
+                                }
+                            }
+                        }),
+                        warnings: []
+                    };
+                }
+                const projectPath = input.subject.projectPath;
+                const discover = input.subject.discover ?? ["mixins", "access-wideners"];
+                const [mixinConfigs, accessWideners] = await Promise.all([
+                    discover.includes("mixins")
+                        ? this.deps.discoverMixins(projectPath, input.configPaths)
+                        : Promise.resolve([]),
+                    discover.includes("access-wideners")
+                        ? this.deps.discoverAccessWideners(projectPath)
+                        : Promise.resolve([])
+                ]);
+                const warnings = [];
+                let validMixins = 0;
+                let partialMixins = 0;
+                let invalidMixins = 0;
+                for (const configPath of mixinConfigs) {
+                    try {
+                        const mixinResult = await this.deps.validateMixin({
+                            input: {
+                                mode: "config",
+                                configPaths: [configPath]
+                            },
+                            version: input.version,
+                            mapping: input.mapping,
+                            sourcePriority: input.sourcePriority,
+                            scope: input.scope,
+                            preferProjectVersion: input.preferProjectVersion,
+                            preferProjectMapping: input.preferProjectMapping,
+                            sourceRoots: input.sourceRoots,
+                            minSeverity: input.minSeverity,
+                            hideUncertain: input.hideUncertain,
+                            explain: input.explain,
+                            warningMode: input.warningMode,
+                            warningCategoryFilter: input.warningCategoryFilter,
+                            treatInfoAsWarning: input.treatInfoAsWarning,
+                            includeIssues: input.includeIssues
+                        });
+                        const summary = mixinResult.summary;
+                        validMixins += summary?.valid ?? 0;
+                        partialMixins += summary?.partial ?? 0;
+                        invalidMixins += summary?.invalid ?? 0;
+                        if (Array.isArray(mixinResult.warnings)) {
+                            warnings.push(...mixinResult.warnings);
+                        }
+                    }
+                    catch (error) {
+                        invalidMixins += 1;
+                        if (error instanceof Error) {
+                            warnings.push(`${configPath}: ${error.message}`);
+                        }
+                    }
+                }
+                let validAw = 0;
+                let invalidAw = 0;
+                for (const awPath of accessWideners) {
+                    try {
+                        const output = await this.deps.validateAccessWidener({
+                            content: await readFile(awPath, "utf8"),
+                            version: input.version,
+                            mapping: input.mapping,
+                            sourcePriority: input.sourcePriority
+                        });
+                        if (output.valid) {
+                            validAw += 1;
+                        }
+                        else {
+                            invalidAw += 1;
+                        }
+                        if (Array.isArray(output.warnings)) {
+                            warnings.push(...output.warnings);
+                        }
+                    }
+                    catch (error) {
+                        invalidAw += 1;
+                        if (error instanceof Error) {
+                            warnings.push(error.message);
+                        }
+                    }
+                }
+                const invalidCount = invalidMixins + invalidAw;
+                const partialCount = partialMixins;
+                const status = invalidCount > 0 ? "invalid" : partialCount > 0 ? "partial" : "ok";
+                return {
+                    ...buildEntryToolResult({
+                        task: "project-summary",
+                        detail,
+                        include,
+                        summary: {
+                            status,
+                            headline: `Validated ${mixinConfigs.length} mixin config(s) and ${accessWideners.length} access widener(s).`,
+                            counts: {
+                                valid: validMixins + validAw,
+                                partial: partialCount,
+                                invalid: invalidCount
+                            }
+                        },
+                        blocks: {
+                            project: {
+                                summary: {
+                                    valid: validMixins + validAw,
+                                    partial: partialCount,
+                                    invalid: invalidCount
+                                }
+                            },
+                            workspace: {
+                                projectPath,
+                                mixinConfigs,
+                                accessWideners
+                            }
+                        },
+                        alwaysBlocks: ["project"]
+                    }),
+                    warnings
+                };
+            }
+        }
+    }
+}
+//# sourceMappingURL=validate-project-service.js.map

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();
@@ -639,6 +656,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;
@@ -1146,18 +1207,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 +1262,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 +1341,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhisang/minecraft-modding-mcp",
-  "version": "2.1.0",
+  "version": "3.0.0",
   "description": "MCP server with utilities for Minecraft modding workflows",
   "type": "module",
   "main": "dist/index.js",