@adhisang/minecraft-modding-mcp 2.1.0 → 3.0.0

package/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project aims to follow [Semantic Versioning](https://semver.org/spec/v2
 
 ## [Unreleased]
 
+## [3.0.0] - 2026-03-09
+
+### Added
+- v3 entry tools: `inspect-minecraft`, `analyze-symbol`, `compare-minecraft`, `analyze-mod`, `validate-project`, and `manage-cache` now provide summary-first starting points for the main Minecraft, symbol, mod, validation, and cache workflows while keeping expert tools available for follow-up work.
+- The new v3 entry tools share `detail` / `include` response shaping and always return `result.summary` inside the standard `{ result?, error?, meta }` envelope, reducing default payload size and making next actions explicit.
+- `analyze-mod` now exposes `executionMode="preview" | "apply"` for safe remap planning and execution, and `manage-cache` now exposes the same preview/apply model for cache deletion, pruning, and rebuild workflows.
+
+### Documentation
+- Added v3 entry-tool usage guidance, shared response-shaping notes, and entry-tool-first migration guidance to both READMEs.
+
+### Fixed
+- `inspect-minecraft` now routes `subject.kind="workspace"` requests with `focus.kind="class" | "file" | "search"` through the matching task for `task=auto`, while preserving workspace-aware artifact resolution for focused file and search follow-up flows.
+- `inspect-minecraft task=class-overview | class-source | class-members` now accepts `subject.kind="workspace"` with `focus.kind="class"` even when the focus omits an explicit artifact reference, reusing workspace version detection to resolve artifact context first.
+- `validate-project task=project-summary` now keeps per-config Mixin validation failures inside the summary result as warnings and invalid counts instead of aborting the whole workspace run on the first bad config.
+- `compare-minecraft` now accepts `sourcePriority` for class-diff requests, and `registry-diff` degrades to `summary.status="partial"` with recovery actions when only one side of detailed registry data can be loaded.
+- `compare-minecraft task=versions` now sets `meta.truncated` with recovery actions when summary-mode class or registry samples are clipped, including mixed `include=["classes"]` / `["registry"]` requests where the other summary-side group was truncated.
+- `manage-cache` now applies `selector.olderThan`, `mapping`, `scope`, `projectPath`, and normalized `jarPath` matching, exposes real cache health states (`stale`, `orphaned`, `corrupt`, `in_use`), and advances `list` pagination through `meta.pagination.nextCursor`.
+
 ## [2.1.0] - 2026-03-08
 
 ### Added

package/README.md

@@ -13,7 +13,7 @@
 
 It lets you explore decompiled Minecraft source, convert symbol names across four naming namespaces (`obfuscated`, `mojang`, `intermediary`, `yarn`), analyze and decompile Fabric/Forge/NeoForge mod JARs, validate Mixin and Access Widener files, read and patch NBT data, and query generated registry snapshots — all through a structured tool and resource interface designed for Claude Desktop, VS Code, and other MCP-capable clients.
 
-**29 tools** | **7 resources** | **4 namespace mappings** | **SQLite-backed cache**
+**35 tools** (6 entry + 29 expert) | **7 resources** | **4 namespace mappings** | **SQLite-backed cache**
 
 ## Features
 
@@ -172,6 +172,29 @@ Pass environment variables to override defaults:
 
 ## Tool Surface
 
+### v3 Entry Tools
+
+These are the default starting points for v3 workflows. They keep the public `{ result?, error?, meta }` envelope, always return `result.summary`, and share `detail: "summary" | "standard" | "full"` plus opt-in `include[]` groups. Mutating entry tools use `executionMode: "preview" | "apply"` so preview is explicit in the public contract.
+
+| Tool | Purpose | Key Inputs | Key Outputs |
+| --- | --- | --- | --- |
+| `inspect-minecraft` | Start from a version, artifact, class, file, search query, or workspace and route to the most relevant Minecraft inspection flow | `task?`, `subject?`, `detail?`, `include?`, `limit?`, `cursor?`, `includeSnapshots?` | `result.summary`, `subject`, `artifact?`, `class?`, `search?`, `file?`, `files?` |
+| `analyze-symbol` | One entry point for symbol existence checks, namespace mapping, lifecycle tracing, workspace symbol analysis, and API overview | `task`, `subject`, `version?`, `sourceMapping?`, `targetMapping?`, `projectPath?`, `classNameMapping?`, `signatureMode?`, `nameMode?`, `includeKinds?`, `maxRows?`, `maxCandidates?`, `detail?`, `include?` | `result.summary`, `match?`, `candidates?`, `ambiguity?`, `matrix?`, `workspace?` |
+| `compare-minecraft` | Compare version pairs, class signatures, registries, or produce a migration-oriented overview | `task?`, `subject`, `detail?`, `include?`, `sourcePriority?`, `maxClassResults?`, `maxEntriesPerRegistry?`, `includeFullDiff?`, `limit?` | `result.summary`, `comparison`, `classes?`, `classDiff?`, `registry?`, `migration?` |
+| `analyze-mod` | Metadata-first entry point for mod summary, decompile/search flows, class source, and safe remap previews/applies | `task`, `subject`, `query?`, `searchType?`, `targetMapping?`, `outputJar?`, `executionMode?`, `includeFiles?`, `maxFiles?`, `maxLines?`, `maxChars?`, `limit?`, `detail?`, `include?` | `result.summary`, `metadata?`, `decompile?`, `hits?`, `source?`, `operation?` |
+| `validate-project` | Project-level validation entry for workspace summaries plus direct Mixin and Access Widener validation | `task`, `subject`, `version?`, `mapping?`, `sourcePriority?`, `scope?`, `preferProjectVersion?`, `preferProjectMapping?`, `sourceRoots?`, `configPaths?`, `minSeverity?`, `hideUncertain?`, `explain?`, `warningMode?`, `warningCategoryFilter?`, `treatInfoAsWarning?`, `includeIssues?`, `detail?`, `include?` | `result.summary`, `project`, `workspace?`, `issues?`, `recovery?` |
+| `manage-cache` | User-facing cache summary, listing, verification, previewed deletion/pruning/rebuild, and explicit apply operations | `action`, `cacheKinds?`, `selector?`, `executionMode?`, `detail?`, `include?`, `limit?`, `cursor?` | `result.summary`, `stats?`, `cacheEntries?`, `operation?`, `meta.pagination.nextCursor?` |
+
+`compare-minecraft` forwards `sourcePriority` for class-diff flows, matching `diff-class-signatures`.
+`inspect-minecraft` also accepts `subject.kind="workspace"` with `focus.kind="class"` for `task="class-overview" | "class-source" | "class-members"` without requiring an explicit `artifact`; it resolves the artifact from the workspace version first.
+`compare-minecraft` summary-mode version comparisons now expose clipped class and registry samples through `meta.truncated`, including mixed `include=["classes"]` / `["registry"]` requests where the other summary-side group was clipped.
+When `registry-diff` can only load one side of detailed registry data, it returns `summary.status="partial"` plus recovery-oriented `nextActions` instead of failing the whole call.
+
+`manage-cache` list pagination returns `meta.pagination.nextCursor`.
+`selector.olderThan` accepts ISO-8601 durations such as `P30D`, `selector.status` uses the shared `healthy | partial | stale | orphaned | corrupt | in_use` vocabulary, and `jarPath` / `projectPath` matching normalizes WSL and Windows path forms before filtering.
+
+If you already know the exact low-level operation you want, the retained expert tools below are still available and remain the fastest way to do narrow follow-up work.
+
 ### Source Exploration
 
 Tools for browsing Minecraft versions, resolving source artifacts, and reading/searching decompiled source code.
@@ -181,8 +204,8 @@ Tools for browsing Minecraft versions, resolving source artifacts, and reading/s
 | `list-versions` | List available Minecraft versions from Mojang manifest + local cache | `includeSnapshots?`, `limit?` | `result.latest`, `result.releases[]`, `meta.warnings[]` |
 | `resolve-artifact` | Resolve source artifact from `version` / `jar` / `coordinate` | `target`, `mapping?`, `sourcePriority?`, `allowDecompile?`, `projectPath?`, `scope?`, `preferProjectVersion?`, `strictVersion?` | `artifactId`, `origin`, `mappingApplied`, `qualityFlags[]`, `artifactContents`, `adjacentSourceCandidates?`, `sampleEntries?`, `warnings[]` |
 | `find-class` | Resolve simple or fully-qualified class names inside an artifact | `className`, `artifactId`, `limit?` | `matches[]`, `total`, `warnings[]` |
-| `get-class-source` | Get class source by artifact target or resolve target on demand (`mode=metadata` by default) | `className`, `target`, `mode?`, `projectPath?`, `scope?`, `preferProjectVersion?`, `strictVersion?`, `startLine?`, `endLine?`, `maxLines?`, `maxChars?`, `outputFile?` | `mode`, `sourceText`, `returnedRange`, `truncated`, `charsTruncated?`, `outputFile?`, `artifactId`, `returnedNamespace`, `artifactContents`, mapping/provenance metadata |
-| `get-class-members` | Get class fields/methods/constructors from bytecode | `className`, `target`, `mapping?`, `access?`, `includeInherited?`, `maxMembers?`, `strictVersion?` | `members.{constructors,fields,methods}`, `counts`, `truncated`, `context`, `returnedNamespace`, `artifactContents`, `warnings[]` |
+| `get-class-source` | Get class source by artifact target or resolve target on demand (`mode=metadata` by default) | `className`, `target`, `mode?`, `mapping?`, `sourcePriority?`, `allowDecompile?`, `projectPath?`, `scope?`, `preferProjectVersion?`, `strictVersion?`, `startLine?`, `endLine?`, `maxLines?`, `maxChars?`, `outputFile?` | `mode`, `sourceText`, `returnedRange`, `truncated`, `charsTruncated?`, `outputFile?`, `artifactId`, `returnedNamespace`, `artifactContents`, mapping/provenance metadata |
+| `get-class-members` | Get class fields/methods/constructors from bytecode | `className`, `target`, `mapping?`, `sourcePriority?`, `allowDecompile?`, `access?`, `includeSynthetic?`, `includeInherited?`, `memberPattern?`, `maxMembers?`, `projectPath?`, `scope?`, `preferProjectVersion?`, `strictVersion?` | `members.{constructors,fields,methods}`, `counts`, `truncated`, `context`, `returnedNamespace`, `artifactContents`, `warnings[]` |
 | `search-class-source` | Search indexed class source for symbols/text/path | `artifactId`, `query`, `intent?`, `match?`, `packagePrefix?`, `fileGlob?`, `symbolKind?`, `queryMode?`, `limit?`, `cursor?` | `hits[]`, `nextCursor?`, `mappingApplied`, `returnedNamespace`, `artifactContents` |
 | `get-artifact-file` | Read full source file with byte guard | `artifactId`, `filePath`, `maxBytes?` | `content`, `contentBytes`, `truncated`, `mappingApplied`, `returnedNamespace`, `artifactContents` |
 | `list-artifact-files` | List indexed source file paths with cursor pagination | `artifactId`, `prefix?`, `limit?`, `cursor?` | `items[]`, `nextCursor?`, `mappingApplied`, `artifactContents`, `warnings[]` |
@@ -194,7 +217,7 @@ Tools for comparing class/registry changes across Minecraft versions and tracing
 
 | Tool | Purpose | Key Inputs | Key Outputs |
 | --- | --- | --- | --- |
-| `trace-symbol-lifecycle` | Trace when `Class.method` exists across Minecraft versions (`descriptor` omitted = name-only lookup) | `symbol`, `descriptor?`, `fromVersion?`, `toVersion?`, `mapping?`, `sourcePriority?`, `maxVersions?`, `includeTimeline?` | `presence.firstSeen`, `presence.lastSeen`, `presence.missingBetween[]`, `presence.existsNow`, `timeline?`, `warnings[]` |
+| `trace-symbol-lifecycle` | Trace when `Class.method` exists across Minecraft versions (`descriptor` omitted = name-only lookup) | `symbol`, `descriptor?`, `fromVersion?`, `toVersion?`, `mapping?`, `sourcePriority?`, `includeSnapshots?`, `maxVersions?`, `includeTimeline?` | `presence.firstSeen`, `presence.lastSeen`, `presence.missingBetween[]`, `presence.existsNow`, `timeline?`, `warnings[]` |
 | `diff-class-signatures` | Compare one class between two versions and return member deltas | `className`, `fromVersion`, `toVersion`, `mapping?`, `sourcePriority?`, `includeFullDiff?` | `classChange`, `constructors/methods/fields.{added,removed,modified}`, `modified`, `modified[].{key,changed,from?,to?}`, `summary`, `warnings[]` |
 | `compare-versions` | Compare class/registry changes between two versions | `fromVersion`, `toVersion`, `category?`, `packageFilter?`, `maxClassResults?` | `classes`, `registry`, `summary`, `warnings[]` |
 
@@ -332,6 +355,12 @@ Mod tool `jarPath` inputs are normalized to a canonical local `.jar` file path b
 `get-registry-data` now discards corrupt cached `registries.json` files, regenerates them when possible, and returns `ERR_REGISTRY_GENERATION_FAILED` if the regenerated snapshot is still unreadable.
 `get-registry-data` supports `includeData=false` to return registry names and counts without full entry bodies. `maxEntriesPerRegistry` caps returned entries per registry while preserving full `entryCount` and `registryEntryCounts`.
 Migration notes:
+- Start with `inspect-minecraft` for version/artifact/class/file/search workflows before dropping to `list-versions`, `resolve-artifact`, `get-class-source`, `get-class-members`, `search-class-source`, `get-artifact-file`, or `list-artifact-files`.
+- Start with `analyze-symbol` for symbol mapping/existence/lifecycle/workspace questions before using `find-mapping`, `resolve-method-mapping-exact`, `check-symbol-exists`, `trace-symbol-lifecycle`, `resolve-workspace-symbol`, or `get-class-api-matrix` directly.
+- Start with `compare-minecraft` for version-pair, class diff, registry diff, and migration-summary flows before using `compare-versions`, `diff-class-signatures`, or `get-registry-data` directly.
+- Start with `analyze-mod` for metadata-first mod inspection and safe remap previews/applies before using `analyze-mod-jar`, `decompile-mod-jar`, `get-mod-class-source`, `search-mod-source`, or `remap-mod-jar` directly.
+- Start with `validate-project` for workspace summaries and direct Mixin / Access Widener validation before using `validate-mixin` or `validate-access-widener` directly.
+- Start with `manage-cache` for cache inventory and safe cleanup; use `executionMode="preview"` to inspect deletion/prune/rebuild impact before `executionMode="apply"`.
 - Replace `resolve-artifact` `targetKind` + `targetValue` with `target: { kind, value }`.
 - Replace `get-class-source` / `get-class-members` top-level `artifactId` / `targetKind` / `targetValue` with `target: { type: "artifact", artifactId }` or `target: { type: "resolve", kind, value }`.
 - `resolve-method-mapping-exact` is method-only and no longer accepts `kind`.

package/dist/cache-registry.d.ts

@@ -0,0 +1,95 @@
+import { type PathRuntimeInfo } from "./path-converter.js";
+export declare const PUBLIC_CACHE_KINDS: readonly ["artifact-index", "downloads", "mapping", "registry", "decompiled-source", "mod-remap"];
+export type PublicCacheKind = (typeof PUBLIC_CACHE_KINDS)[number];
+export declare const CACHE_HEALTH_STATES: readonly ["healthy", "partial", "stale", "orphaned", "corrupt", "in_use"];
+export type CacheHealthState = (typeof CACHE_HEALTH_STATES)[number];
+export type CacheSelector = {
+    artifactId?: string;
+    version?: string;
+    jarPath?: string;
+    entryId?: string;
+    status?: CacheHealthState;
+    olderThan?: string;
+    mapping?: string;
+    scope?: string;
+    projectPath?: string;
+};
+export type CacheKindSummary = {
+    cacheKind: PublicCacheKind;
+    entryCount: number;
+    totalBytes: number;
+    status: CacheHealthState;
+};
+export type CacheEntry = {
+    cacheKind: PublicCacheKind;
+    entryId: string;
+    path: string;
+    sizeBytes: number;
+    status: CacheHealthState;
+    owner?: string;
+    meta?: Record<string, unknown>;
+};
+type CacheEntryPage = {
+    entries: CacheEntry[];
+    nextCursor?: string;
+};
+export type CacheRegistryConfig = {
+    cacheDir: string;
+    sqlitePath: string;
+    pathRuntimeInfo?: PathRuntimeInfo;
+};
+export interface CacheRegistry {
+    summarize(input: {
+        cacheKinds?: PublicCacheKind[];
+        selector?: CacheSelector;
+    }): Promise<{
+        kinds: Partial<Record<PublicCacheKind, CacheKindSummary>>;
+    }>;
+    listEntries(input: {
+        cacheKinds?: PublicCacheKind[];
+        selector?: CacheSelector;
+        limit?: number;
+        cursor?: string;
+    }): Promise<CacheEntryPage>;
+    inspectEntries(input: {
+        cacheKinds?: PublicCacheKind[];
+        selector?: CacheSelector;
+        limit?: number;
+    }): Promise<CacheEntry[]>;
+    verifyEntries(input: {
+        cacheKinds?: PublicCacheKind[];
+        selector?: CacheSelector;
+    }): Promise<{
+        checkedEntries: number;
+        unhealthyEntries: number;
+        warnings: string[];
+    }>;
+    deleteEntries(input: {
+        cacheKinds?: PublicCacheKind[];
+        selector?: CacheSelector;
+        executionMode: "preview" | "apply";
+    }): Promise<{
+        deletedEntries: number;
+        deletedBytes: number;
+        warnings: string[];
+    }>;
+    pruneEntries(input: {
+        cacheKinds?: PublicCacheKind[];
+        selector?: CacheSelector;
+        executionMode: "preview" | "apply";
+    }): Promise<{
+        deletedEntries: number;
+        deletedBytes: number;
+        warnings: string[];
+    }>;
+    rebuildEntries(input: {
+        cacheKinds?: PublicCacheKind[];
+        selector?: CacheSelector;
+        executionMode: "preview" | "apply";
+    }): Promise<{
+        rebuiltEntries: number;
+        warnings: string[];
+    }>;
+}
+export declare function createCacheRegistry(config: CacheRegistryConfig): CacheRegistry;
+export {};