Vinculum

Vinculum is a Fabric mod that helps players keep their Minecraft mod list aligned with the servers they join.

This mod must be present on both the client and the server/lan.

How It Works

When a server or game with LAN open is running Vinculum, it advertises its Minecraft version, loader version, and installed mods through the server list. The client compares that information with the local mods folder before joining, then shows a clear status screen for anything that is missing or using a different version.

Features

• Detects missing server-required mods before joining.
• Highlights version mismatches between the client and server.
• Marks client-only mods separately so players know which entries do not block joining.
• Downloads missing Fabric mods from Modrinth when a matching file is available.
• Falls back to server-provided transfers when Modrinth cannot resolve a required mod and server transfers are enabled.
• Requires explicit confirmation before downloading any JAR directly from a server, with a security warning and the advertised file metadata.
• Offers Necessary Sync for join-blocking mods and Full Sync for the complete server mod set.
• Backs up mismatched or extra local mods before replacing them.
• Shows sync progress directly in the Minecraft UI.

Configuration

Vinculum creates a modsync.json config file in the Fabric config directory.

{
  "transferPort": 9123,
  "allowServerTransfers": true,
  "filterMode": "none",
  "filterRules": []
}

• transferPort: port used for server-hosted mod transfers.
• allowServerTransfers: enables or disables direct downloads from the server.
• filterMode: controls which JARs Vinculum manages. Use none, blacklist, or whitelist.
• filterRules: JAR names or gitignore-like patterns. Blacklisted JARs and JARs outside a whitelist are not advertised, transferred, compared, or moved to backups.

Rules without a slash match a JAR filename in any directory. Rules containing a slash are relative to the mods directory. Matching is case-insensitive, * matches any characters except /, ? matches one character except /, ** can cross directories, and a trailing / matches a directory and everything below it. Blank rules and rules beginning with # are ignored.

For example:

{
  "transferPort": 9123,
  "allowServerTransfers": true,
  "filterMode": "blacklist",
  "filterRules": [
    "client-only/",
    "mod-proprietario-*",
    "optional/**/*.jar"
  ]
}

Both values can also be overridden with the modsync.transferPort and modsync.allowServerTransfers system properties, or the MODSYNC_TRANSFER_PORT and MODSYNC_ALLOW_SERVER_TRANSFERS environment variables.

Requirements

• Minecraft 26.1.2
• Fabric Loader 0.19.3 or newer
• Fabric API
• Java 25 or newer

License

This project is licensed under the MIT License. You may reuse, modify, and distribute it, provided that the original copyright notice and license are preserved.