fix: add unobfuscated version awareness to MappingService (#5)

MappingService.getMappings() and lookupMapping() now detect unobfuscated
Minecraft versions (26.1+) and throw clear, actionable errors instead of
failing with cryptic "Intermediary mappings not available" messages.

The RemapService already handled this correctly, but tools like
find_mapping and the mappings resource endpoint called MappingService
directly, bypassing the check.

Bumps version to 1.1.0 for npm publish — v1.0.0 on npm predates the
unobfuscated version support added in PR #4.

Author: GhostTypes

__tests__/core/mapping-service.test.ts

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { describe, expect, it } from 'vitest';
 import { getMappingService } from '../../src/services/mapping-service.js';
-import { TEST_MAPPING, TEST_VERSION } from '../test-constants.js';
+import { TEST_MAPPING, TEST_VERSION, UNOBFUSCATED_TEST_VERSION } from '../test-constants.js';
 
 /**
  * Mapping Service Tests
@@ -434,3 +434,79 @@ describe('Mojmap Tiny v2 Structure Verification', () => {
     expect(firstLine).toContain('named');
   }, 180000);
 });
+
+/**
+ * Unobfuscated version handling (26.1+)
+ *
+ * Unobfuscated Minecraft versions ship JARs without obfuscation.
+ * No intermediary, yarn, or mojmap mapping files exist for these versions.
+ * MappingService.getMappings() and lookupMapping() must fail with clear,
+ * actionable error messages instead of cryptic download failures.
+ *
+ * Reproduces: https://github.com/MCDxAI/minecraft-dev-mcp/issues/5
+ */
+describe('Unobfuscated version handling', () => {
+  it('should throw actionable error for getMappings(intermediary) on unobfuscated version', async () => {
+    const mappingService = getMappingService();
+    await expect(
+      mappingService.getMappings(UNOBFUSCATED_TEST_VERSION, 'intermediary'),
+    ).rejects.toThrow(/unobfuscated/i);
+    await expect(
+      mappingService.getMappings(UNOBFUSCATED_TEST_VERSION, 'intermediary'),
+    ).rejects.toThrow(/mojmap/i);
+  }, 30000);
+
+  it('should throw actionable error for getMappings(yarn) on unobfuscated version', async () => {
+    const mappingService = getMappingService();
+    await expect(
+      mappingService.getMappings(UNOBFUSCATED_TEST_VERSION, 'yarn'),
+    ).rejects.toThrow(/unobfuscated/i);
+    await expect(
+      mappingService.getMappings(UNOBFUSCATED_TEST_VERSION, 'yarn'),
+    ).rejects.toThrow(/mojmap/i);
+  }, 30000);
+
+  it('should throw actionable error for getMappings(mojmap) on unobfuscated version', async () => {
+    const mappingService = getMappingService();
+    await expect(
+      mappingService.getMappings(UNOBFUSCATED_TEST_VERSION, 'mojmap'),
+    ).rejects.toThrow(/unobfuscated/i);
+    await expect(
+      mappingService.getMappings(UNOBFUSCATED_TEST_VERSION, 'mojmap'),
+    ).rejects.toThrow(/already in Mojang/i);
+  }, 30000);
+
+  it('should throw actionable error for lookupMapping on unobfuscated version', async () => {
+    const mappingService = getMappingService();
+    await expect(
+      mappingService.lookupMapping(
+        UNOBFUSCATED_TEST_VERSION,
+        'Entity',
+        'mojmap',
+        'yarn',
+      ),
+    ).rejects.toThrow(/unobfuscated/i);
+    await expect(
+      mappingService.lookupMapping(
+        UNOBFUSCATED_TEST_VERSION,
+        'Entity',
+        'mojmap',
+        'yarn',
+      ),
+    ).rejects.toThrow(/no mapping translation is needed/i);
+  }, 30000);
+
+  it('should allow same-type lookupMapping on unobfuscated version (identity)', async () => {
+    const mappingService = getMappingService();
+    // Same source and target mapping should still return identity (no mapping file needed)
+    const result = await mappingService.lookupMapping(
+      UNOBFUSCATED_TEST_VERSION,
+      'net/minecraft/world/entity/Entity',
+      'mojmap',
+      'mojmap',
+    );
+    expect(result.found).toBe(true);
+    expect(result.source).toBe('net/minecraft/world/entity/Entity');
+    expect(result.target).toBe('net/minecraft/world/entity/Entity');
+  }, 10000);
+});

__tests__/core/version-manager.test.ts

@@ -70,5 +70,24 @@ describe('Version Management', () => {
       const result = await versionManager.isVersionUnobfuscated('26.1-snapshot-9');
       expect(result).toBe(true);
     }, 30000);
+
+    // Regression tests for https://github.com/MCDxAI/minecraft-dev-mcp/issues/5
+    it('should return true for 26.1-snapshot-10 (issue #5)', async () => {
+      const versionManager = getVersionManager();
+      const result = await versionManager.isVersionUnobfuscated('26.1-snapshot-10');
+      expect(result).toBe(true);
+    }, 30000);
+
+    it('should return true for 26.1-snapshot-11 (issue #5)', async () => {
+      const versionManager = getVersionManager();
+      const result = await versionManager.isVersionUnobfuscated('26.1-snapshot-11');
+      expect(result).toBe(true);
+    }, 30000);
+
+    it('should return true for 26.1-rc-3 (issue #5)', async () => {
+      const versionManager = getVersionManager();
+      const result = await versionManager.isVersionUnobfuscated('26.1-rc-3');
+      expect(result).toBe(true);
+    }, 30000);
   });
 });

__tests__/tools/core-tools.test.ts

@@ -560,6 +560,21 @@ describe('Decompile and Remap Tools', () => {
     expect(text).toMatch(/use ['"]mojmap['"] mapping/i);
   }, 120000);
 
+  it('should return actionable error for find_mapping on unobfuscated version', async () => {
+    const result = await handleFindMapping({
+      symbol: 'Entity',
+      version: UNOBFUSCATED_TEST_VERSION,
+      sourceMapping: 'mojmap',
+      targetMapping: 'yarn',
+    });
+
+    expect(result).toBeDefined();
+    expect(result.isError).toBe(true);
+    const text = result.content[0].text;
+    expect(text).toMatch(/unobfuscated/i);
+    expect(text).toMatch(/no mapping translation is needed/i);
+  }, 60000);
+
   it('should handle remap_mod_jar with Fabric mod', async () => {
     // Skip if fixture doesn't exist
     if (!existsSync(METEOR_JAR_PATH)) {

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcdxai/minecraft-dev-mcp",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "MCP server for Minecraft mod development - decompile, remap, and explore Minecraft source code",
   "type": "module",
   "main": "./dist/index.js",

package.json

@@ -11,6 +11,7 @@ import { MappingNotFoundError } from '../utils/errors.js';
 import { ensureDir } from '../utils/file-utils.js';
 import { logger } from '../utils/logger.js';
 import { getMojmapTinyPath } from '../utils/paths.js';
+import { getVersionManager } from './version-manager.js';
 
 /**
  * Manages mapping downloads and caching
@@ -19,6 +20,7 @@ export class MappingService {
   private mojangDownloader = getMojangDownloader();
   private fabricMaven = getFabricMaven();
   private cache = getCacheManager();
+  private versionManager = getVersionManager();
 
   // Lock to prevent concurrent downloads of the same mappings
   private downloadLocks = new Map<string, Promise<string>>();
@@ -28,6 +30,25 @@ export class MappingService {
    * Uses locking to prevent concurrent downloads of the same mapping
    */
   async getMappings(version: string, mappingType: MappingType): Promise<string> {
+    // Unobfuscated versions (26.1+) ship without obfuscation — no mapping files exist.
+    const isUnobfuscated = await this.versionManager.isVersionUnobfuscated(version);
+    if (isUnobfuscated) {
+      if (mappingType === 'mojmap') {
+        throw new MappingNotFoundError(
+          version,
+          mappingType,
+          `Mojmap mapping files are not available for unobfuscated version ${version}. ` +
+            `The JAR is already in Mojang's human-readable names — decompile it directly with mapping 'mojmap'.`,
+        );
+      }
+      throw new MappingNotFoundError(
+        version,
+        mappingType,
+        `${mappingType} mappings are not available for unobfuscated version ${version}. ` +
+          `Use 'mojmap' mapping instead — the JAR ships without obfuscation.`,
+      );
+    }
+
     const lockKey = `${version}-${mappingType}`;
 
     // For Mojmap, check for converted Tiny file first (not raw ProGuard)
@@ -267,6 +288,17 @@ export class MappingService {
       return this.createLookupResult(true, symbol, symbol);
     }
 
+    // Unobfuscated versions (26.1+) have no mapping files — lookups are not possible.
+    const isUnobfuscated = await this.versionManager.isVersionUnobfuscated(version);
+    if (isUnobfuscated) {
+      throw new MappingNotFoundError(
+        version,
+        `${sourceMapping}->${targetMapping}`,
+        `Mapping lookup is not available for unobfuscated version ${version}. ` +
+          `The source code is already in Mojang's human-readable names — no mapping translation is needed.`,
+      );
+    }
+
     // Determine routing strategy
     const singleFile = this.getSingleFileLookup(sourceMapping, targetMapping);