Fabric MCP Server

Model Context Protocol (MCP) server dla Minecraft Fabric modding — asystent AI z pełną wiedzą o Yarn mappings, Fabric API i Mixinach.

Funkcje

• 🔍 Analiza kodu — wykrywa błędy w kodzie Fabric (named mappings w reflection, brakujący @Environment, deprecated API)
• 🗺️ Yarn mappings — konwersja między official ↔ intermediary ↔ named namespace'ami
• 🔧 Walidacja Mixinów — sprawdza poprawność @Inject, @At selectors, CallbackInfo
• 📚 Javadoc — dostęp do dokumentacji Yarn i Fabric API
• 📖 Fabric docs — oficjalne tutoriale jako MCP resources
• 💡 Prompty — gotowe system prompts dla AI

Instalacja

Lokalna (development)

# Clone repository
git clone https://github.com/rafalohaki/fabric-mcp.git
cd fabric-mcp

# Instaluj dependencies
npm install

# Build
npm run build

# Test
npm test

NPM (po publikacji)

npm i fabric-mcp -g

Konfiguracja

Claude Desktop

Edytuj config: %APPDATA%/Claude/claude_desktop_config.json (Windows) lub ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

{
  "mcpServers": {
    "fabric-mcp": {
      "command": "node",
      "args": [
        "C:/sciezka/do/fabric-mcp/dist/index.js"
      ]
    }
  }
}

Lub po publikacji na NPM:

{
  "mcpServers": {
    "fabric-mcp": {
      "command": "npx",
      "args": ["-y", "fabric-mcp"]
    }
  }
}

Cursor / VSCode z Copilot

Dodaj do .vscode/settings.json:

{
  "github.copilot.chat.mcp.servers": {
    "fabric-mcp": {
      "command": "node",
      "args": ["path/to/fabric-mcp/dist/index.js"]
    }
  }
}

Użycie

1. Analiza kodu Fabric

Prompt dla AI:

Sprawdź ten kod Fabric dla MC 1.21.10:

public class PlayerMixin {
  public void badCode() {
    Field f = PlayerEntity.class.getDeclaredField("inventory");
    MinecraftClient.getInstance().player.sendMessage(Text.of("test"));
  }
}

Odpowiedź AI (używa tool analyze_fabric_code):

• ❌ Błędy: Reflection z Named mapping "inventory" — nie zadziała w produkcji!
  • 💡 Fix: Użyj intermediary: "field_7514" lub MappingResolver
• ⚠️ Ostrzeżenia: Używasz MinecraftClient bez @Environment(EnvType.CLIENT)
  • 💡 Fix: Dodaj @Environment(EnvType.CLIENT) do klasy/metody

2. Wyszukiwanie mappings

Prompt:

Znajdź Yarn mapping dla PlayerEntity.inventory w MC 1.21.10

AI używa get_yarn_mapping:

| Namespace | Name | |-----------|------| | Named (Yarn) | inventory | | Intermediary | field_7514 | | Official (obf) | h |

Descriptor: Lnet/minecraft/inventory/Inventory;
Parent: net/minecraft/entity/player/PlayerEntity

3. Walidacja Mixinów

Prompt:

Sprawdź czy ten Mixin jest poprawny:

@Mixin(PlayerEntity.class)
public class PlayerMixin {
  @Inject(method = "tick", at = @At("INVOKE"))
  private void onTick() {
    System.out.println("Tick!");
  }
}

AI używa validate_mixin:

• ❌ @At("INVOKE") wymaga target = "..."
• ❌ @Inject handler musi mieć parametr CallbackInfo/CallbackInfoReturnable

4. Dostęp do Javadoc

Prompt:

Pokaż dokumentację dla net.minecraft.entity.player.PlayerEntity

AI używa get_javadoc:

• Zwraca opis z Javadoc lub komunikat o braku dokumentacji

Dostępne Tools

| Tool | Opis | Parametry | |------|------|-----------| | analyze_fabric_code | Analizuje kod Java pod kątem błędów Fabric | code, mcVersion, checkMixins | | get_yarn_mapping | Wyszukuje i konwertuje mappings | query, mcVersion, searchType | | validate_mixin | Waliduje kod Mixin | code, mcVersion | | get_javadoc | Pobiera dokumentację klasy | className, mcVersion |

Resources

| URI | Opis | |-----|------| | fabric://docs/tutorial/items | Tutorial: Custom Items | | fabric://docs/mixin/introduction | Wprowadzenie do Mixinów | | fabric://docs/tutorial/blocks | Tutorial: Custom Blocks |

Prompts

| Prompt | Opis | Argumenty | |--------|------|-----------| | fabric_developer | System prompt dla AI asystenta Fabric | mcVersion (optional) |

Development

# Watch (jeśli dodasz w przyszłości)
# npm run dev

# Testy
npm test
npm run test:watch
npm run test:coverage

# Lint / type-check
npm run lint
npm run type-check

# Build
npm run build

Troubleshooting

• Tool not found — sprawdź ścieżkę w config, zrestartuj klienta.
• Cannot find module — uruchom npm run build ponownie.
• Mappings not found for MC X.X — sprawdź, czy wersja istnieje na Maven (yarn).
• Server nie startuje — npm run type-check i npm test po kolei.

Roadmap (v1.1+)

• check_deprecated — detekcja deprecated API
• get_migration_guide — diff mappings między wersjami
• Resources dla ASM
• Pattern templates (snippety kodu)
• SQLite cache dla mappings
• Multi-version comparison (1.20 → 1.21)

Technologie

• MCP SDK 0.5+
• TypeScript 5.3+
• Vitest 1.0+
• Fabric API (Yarn mappings)

Licencja

MIT License — patrz LICENSE

Contributing

Pull requests mile widziane! Sprawdź CONTRIBUTING.md przed wysłaniem PR.

Credits

• Fabric — Yarn mappings i dokumentacja
• Anthropic — Model Context Protocol
• SpongePowered — Mixin framework

Contact

• Issues: https://github.com/rafalohaki/fabric-mcp/issues
• Discord: (link do serwera)
• Email: [email protected]

⭐ Star this repo jeśli pomaga w Fabric moddingu!