@creeperhost/modlens-mcp 1.6.18 → 1.6.19

package/scripts/gradle/modlens.init.gradle

@@ -0,0 +1,154 @@
+// Apply without modifying a project: ./gradlew -I /path/to/modlens.init.gradle :modlensExport
+// ModDevGradle 2.x adapter plus a generic Java source-set compile-classpath exporter.
+import groovy.json.JsonOutput
+import java.security.MessageDigest
+import java.security.SecureRandom
+import java.nio.file.Files
+import java.nio.file.StandardCopyOption
+import java.nio.file.StandardOpenOption
+import java.nio.file.FileAlreadyExistsException
+import java.util.zip.ZipEntry
+import java.util.zip.ZipOutputStream
+import org.gradle.api.GradleException
+import org.gradle.api.plugins.JavaPluginExtension
+import org.gradle.api.provider.Provider
+
+def sha256 = { File file ->
+    def md = MessageDigest.getInstance('SHA-256')
+    file.withInputStream { input ->
+        byte[] buffer = new byte[65536]
+        int count
+        while ((count = input.read(buffer)) != -1) md.update(buffer, 0, count)
+    }
+    md.digest().encodeHex().toString()
+}
+
+gradle.projectsEvaluated {
+    allprojects { p ->
+        def javaExtension = p.extensions.findByType(JavaPluginExtension)
+        if (javaExtension == null) return
+        String selected = p.findProperty('modlensSourceSet')?.toString() ?: 'main'
+        def sourceSet = javaExtension.sourceSets.findByName(selected)
+        if (sourceSet == null) {
+            // A sibling module may not have the source set selected for the requested module.
+            p.tasks.register('modlensExport') {
+                doLast { throw new GradleException("Unknown ModLens source set '${selected}' in ${p.path}") }
+            }
+            return
+        }
+        boolean moddev = p.plugins.hasPlugin('net.neoforged.moddev') || p.plugins.hasPlugin('net.neoforged.moddev.legacyforge')
+        def artifactsTask = moddev ? p.tasks.findByName('createMinecraftArtifacts') : null
+        if (moddev && artifactsTask == null) throw new GradleException('ModLens requires a ModDevGradle version with createMinecraftArtifacts (2.x).')
+
+        p.tasks.register('modlensExport') { task ->
+            group = 'modlens'
+            description = 'Export the resolved compile environment for local or remote ModLens.'
+            // Gradle resolves/builds the actual compilation inputs, including AT processing.
+            dependsOn(sourceSet.compileClasspath)
+            if (artifactsTask != null) dependsOn(artifactsTask)
+            // This task accesses the evaluated model and is intentionally not configuration-cache compatible.
+            notCompatibleWithConfigurationCache('ModLens exports the evaluated compile classpath and modding task outputs.')
+            doLast {
+                File output = p.layout.buildDirectory.dir("modlens/${selected}").get().asFile
+                output.mkdirs()
+                def artifacts = []
+                def files = []
+                def byFile = [:]
+                def addArtifact = { File file, String kind, String sourceFor ->
+                    if (!file.isFile()) throw new GradleException("Missing ModLens artifact: ${file.name}")
+                    String path = "artifacts/${artifacts.size()}.jar"
+                    def info = [path: path, name: file.name, sha256: sha256(file), size: file.length(), kind: kind]
+                    if (sourceFor != null) info.sourceFor = sourceFor
+                    artifacts.add(info)
+                    files.add(file)
+                    if (kind == 'classpath') byFile[file.canonicalPath] = path
+                    path
+                }
+                sourceSet.compileClasspath.files.eachWithIndex { File file, int index ->
+                    if (!file.exists()) throw new GradleException("Compile classpath entry does not exist: ${file.name}")
+                    if (file.isDirectory()) {
+                        // Project dependencies often expose class directories instead of JARs.
+                        File jar = new File(output, "directory-${index}.jar")
+                        def entries = p.fileTree(file).matching { include '**/*.class'; include '**/*.java' }.files.sort { a, b ->
+                            file.toPath().relativize(a.toPath()).toString() <=> file.toPath().relativize(b.toPath()).toString()
+                        }
+                        jar.withOutputStream { stream ->
+                            def zip = new ZipOutputStream(stream)
+                            entries.each { entry ->
+                                def name = file.toPath().relativize(entry.toPath()).toString().replace('\\', '/')
+                                def ze = new ZipEntry(name); ze.time = 0
+                                zip.putNextEntry(ze); entry.withInputStream { zip << it }; zip.closeEntry()
+                            }
+                            zip.finish()
+                        }
+                        addArtifact(jar, 'classpath', null)
+                    } else if (file.name.endsWith('.jar')) {
+                        addArtifact(file, 'classpath', null)
+                    } else {
+                        throw new GradleException("Unsupported compile classpath entry: ${file.name}")
+                    }
+                }
+                if (artifacts.empty) throw new GradleException('Compile classpath is empty; there is no dependency environment to export.')
+
+                def transforms = []
+                if (artifactsTask != null) {
+                    // Bind sources to the binary actually selected by the compile classpath, not a guessed cache path.
+                    def binaryPaths = ['gameJarArtifact', 'gameJarWithSourcesArtifact'].collect { property ->
+                        artifactsTask.hasProperty(property) ? artifactsTask.property(property).orNull?.asFile?.canonicalPath : null
+                    }.findAll { it != null && byFile.containsKey(it) }
+                    if (binaryPaths.empty) throw new GradleException('ModLens cannot locate ModDevGradle Minecraft output on this source set compile classpath. Select a mod-enabled source set.')
+                    def sourceFile = artifactsTask.hasProperty('gameSourcesArtifact') ? artifactsTask.gameSourcesArtifact.orNull?.asFile : null
+                    if (sourceFile?.isFile()) binaryPaths.each { path -> addArtifact(sourceFile, 'sources', byFile[path]) }
+                    if (artifactsTask.hasProperty('accessTransformers')) {
+                        artifactsTask.accessTransformers.files.each { File file -> transforms.add([name: file.name, sha256: sha256(file)]) }
+                    }
+                }
+                def neo = p.extensions.findByName('neoForge') ?: p.extensions.findByName('legacyForge')
+                def propertyText = { String name -> p.findProperty(name)?.toString() ?: '' }
+                String loaderVersion = propertyText('neo_version') ?: propertyText('forge_version')
+                if (neo != null && neo.hasProperty('version')) {
+                    def version = neo.version
+                    loaderVersion = (version instanceof Provider ? version.orNull : version)?.toString() ?: loaderVersion
+                }
+                String mappings = propertyText('modlensMappings')
+                if (!mappings && neo != null && neo.hasProperty('parchment') && neo.parchment.enabled.getOrElse(false)) {
+                    mappings = "parchment:${neo.parchment.minecraftVersion.orNull ?: ''}:${neo.parchment.mappingsVersion.orNull ?: ''}"
+                }
+                if (!mappings) mappings = moddev ? 'toolchain-prepared (official names where applicable)' : 'compile-classpath'
+                def manifest = [format: 'modlens-project-v1', project: "${p.rootProject.name}${p.path}", sourceSet: selected,
+                    toolchain: moddev ? 'moddevgradle' : 'gradle-compile-classpath',
+                    minecraftVersion: propertyText('minecraft_version') ?: propertyText('modlensMinecraftVersion'),
+                    loaderVersion: loaderVersion, mappings: mappings,
+                    javaVersion: p.tasks.named(sourceSet.compileJavaTaskName).get().options.release.orNull ?: javaExtension.toolchain.languageVersion.orNull?.asInt() ?: Integer.parseInt(org.gradle.api.JavaVersion.current().majorVersion),
+                    transformations: transforms, artifacts: artifacts]
+                File temporary = new File(output, 'environment.zip.tmp')
+                temporary.withOutputStream { stream ->
+                    def zip = new ZipOutputStream(stream)
+                    def metadata = new ZipEntry('manifest.json'); metadata.time = 0
+                    zip.putNextEntry(metadata); zip.write(JsonOutput.toJson(manifest).getBytes('UTF-8')); zip.closeEntry()
+                    artifacts.eachWithIndex { artifact, index ->
+                        def entry = new ZipEntry(artifact.path); entry.time = 0
+                        zip.putNextEntry(entry); files[index].withInputStream { zip << it }; zip.closeEntry()
+                    }
+                    zip.finish()
+                }
+                File destination = new File(output, 'environment.zip')
+                Files.move(temporary.toPath(), destination.toPath(), StandardCopyOption.REPLACE_EXISTING)
+                File keyFile = new File(p.projectDir, '.gradle/modlens/project-key.txt')
+                keyFile.parentFile.mkdirs()
+                if (!keyFile.exists()) {
+                    byte[] key = new byte[32]; new SecureRandom().nextBytes(key)
+                    // CREATE_NEW prevents concurrent exports from silently replacing a project key.
+                    try { Files.write(keyFile.toPath(), (key.encodeHex().toString() + '\n').getBytes('UTF-8'), StandardOpenOption.CREATE_NEW) }
+                    catch (FileAlreadyExistsException ignored) { }
+                    keyFile.setReadable(false, false); keyFile.setWritable(false, false)
+                    keyFile.setReadable(true, true); keyFile.setWritable(true, true)
+                }
+                if (!(keyFile.text.trim() ==~ /[a-f0-9]{64}/)) throw new GradleException('Invalid existing ModLens project key; expected 64 lowercase hex characters.')
+                logger.lifecycle("ModLens bundle: ${destination}")
+                logger.lifecycle("ModLens private key file: ${keyFile}")
+                logger.lifecycle('Re-export and import after changing dependencies, mappings or access transformers.')
+            }
+        }
+    }
+}

package/scripts/project-upload.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+// Transfer a Gradle export over MCP without exposing a local filesystem path to the server.
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { readFile, open, stat } from 'node:fs/promises';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+
+const [endpoint, bundlePath, keyFile] = process.argv.slice(2);
+if (!endpoint || !bundlePath || !keyFile || process.argv.length !== 5) {
+    console.error('Usage: node scripts/project-upload.mjs <https://host/mcp> <environment.zip> <project-key.txt>');
+    process.exit(1);
+}
+const url = new URL(endpoint);
+if (url.protocol !== 'https:' && !(url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname))) {
+    throw new Error('Use HTTPS for remote project uploads (HTTP is allowed only on loopback).');
+}
+if (url.username || url.password || url.search || url.hash) throw new Error('Endpoint must not contain credentials, query parameters or a fragment. Use MODLENS_AUTH_TOKEN for proxy authentication.');
+const projectKey = (await readFile(keyFile, 'utf8')).trim();
+if (!/^[a-f0-9]{64}$/.test(projectKey)) throw new Error('Invalid project key file');
+const size = (await stat(bundlePath)).size;
+if (!size || size > 512 * 1024 * 1024) throw new Error('Bundle must contain 1 byte to 512 MiB');
+const hash = createHash('sha256');
+for await (const chunk of createReadStream(bundlePath)) hash.update(chunk);
+const client = new Client({ name: 'modlens-project-upload', version: '1.0.0' });
+const transport = new StreamableHTTPClientTransport(url, { requestInit: {
+    // Never follow redirects carrying the private project capability in the request body.
+    redirect: 'error',
+    headers: process.env.MODLENS_AUTH_TOKEN ? { Authorization: `Bearer ${process.env.MODLENS_AUTH_TOKEN}` } : {},
+} });
+let uploadId;
+try {
+    await client.connect(transport);
+    const call = async (args) => {
+        const response = await client.callTool({ name: 'project', arguments: { ...args, projectKey } }, undefined, { timeout: 300_000 });
+        const text = response.content?.filter(c => c.type === 'text').map(c => c.text).join('\n');
+        if (response.isError) throw new Error(text || 'Project upload failed');
+        return JSON.parse(text);
+    };
+    const begin = await call({ action: 'upload_begin', size, sha256: hash.digest('hex') });
+    uploadId = begin.uploadId;
+    const file = await open(bundlePath, 'r');
+    try {
+        let offset = 0;
+        while (offset < size) {
+            const bytes = Buffer.alloc(Math.min(begin.chunkBytes, size - offset));
+            const { bytesRead } = await file.read(bytes, 0, bytes.length, offset);
+            if (bytesRead !== bytes.length) throw new Error('Bundle changed during upload; re-export it.');
+            // Retrying an acknowledged range is checked byte-for-byte by the server.
+            let result;
+            for (let attempt = 0; attempt < 3; attempt++) {
+                try { result = await call({ action: 'upload_chunk', uploadId, offset, data: bytes.toString('base64') }); break; }
+                catch (error) { if (attempt === 2) throw error; }
+            }
+            if (result.offset !== offset + bytes.length) throw new Error('Unexpected upload offset');
+            offset = result.offset;
+        }
+    } finally { await file.close(); }
+    let result;
+    for (let attempt = 0; attempt < 3; attempt++) {
+        try { result = await call({ action: 'upload_finish', uploadId }); break; }
+        catch (error) { if (attempt === 2) throw error; }
+    }
+    console.log(JSON.stringify(result, null, 2));
+    await call({ action: 'upload_abort', uploadId }); // receipt no longer needed
+    uploadId = undefined;
+} catch (error) {
+    if (uploadId) {
+        try { await client.callTool({ name: 'project', arguments: { action: 'upload_abort', projectKey, uploadId } }); } catch { }
+    }
+    // Do not print transport objects or request bodies, which contain the project capability.
+    console.error(`Project upload failed: ${String(error.message).split(projectKey).join('[redacted]')}`);
+    process.exitCode = 1;
+} finally { await client.close(); }

package/scripts/test-minecraft-eras.mjs

@@ -0,0 +1,202 @@
+/** Live MCP compatibility checks. Uses public downloads and an isolated database/cache. */
+import assert from "node:assert/strict";
+import { appendFile, copyFile, cp, mkdir, mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+const repository = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const arguments_ = process.argv.slice(2);
+const runMods = !arguments_.length || arguments_.includes("--mods");
+const selectedVersions = arguments_.filter(arg => arg !== "--mods");
+const versions = selectedVersions.length ? selectedVersions : runMods && arguments_.length ? [] : [
+    "b1.7.3", "1.2.5", "1.5.2", "1.6.4", "1.7.10", "1.8.9", "1.12.2",
+    "1.13.2", "1.16.5", "1.18.2", "1.20.1", "1.20.6", "1.21.1", "26.1.2",
+];
+const root = await mkdtemp(join(tmpdir(), "modlens-minecraft-eras-"));
+const cache = join(root, "cache");
+await mkdir(cache, { recursive: true });
+if (process.env.MODLENS_TEST_ARTIFACT_CACHE) {
+    for (const directory of ["mc-jars", "mappings", "tools", "jdk"]) {
+        await cp(join(process.env.MODLENS_TEST_ARTIFACT_CACHE, directory), join(cache, directory), { recursive: true }).catch(error => {
+            if (error.code !== "ENOENT") throw error;
+        });
+    }
+}
+await copyFile(join(repository, "prisma/backends/template.db"), join(root, "database.db"));
+
+// An explicit read-only seed can avoid re-downloading the analysis tools.
+if (process.env.MODLENS_TEST_TOOL_CACHE) {
+    await mkdir(join(cache, "tools"), { recursive: true });
+    for (const name of ["mcsrc-indexer.jar", "vineflower.jar", "tiny-remapper.jar", "SpecialSource.jar"]) {
+        await copyFile(join(process.env.MODLENS_TEST_TOOL_CACHE, name), join(cache, "tools", name)).catch(error => {
+            if (error.code !== "ENOENT") throw error;
+        });
+    }
+}
+const environment = Object.fromEntries(Object.entries(process.env).filter(([key, value]) =>
+    typeof value === "string" && !/TOKEN|API_KEY|SECRET|^(MCP_|DATABASE_URL$|MODLENS_|OLLAMA_|AUTO_)/i.test(key),
+));
+Object.assign(environment, {
+    DATABASE_URL: `file:${join(root, "database.db").replaceAll("\\", "/")}`,
+    MODLENS_HOME: join(root, "home"), MODLENS_CACHE_ROOT: cache,
+    MODLENS_AUTO_EMBED: "0", MODLENS_AUTO_GRAPH: "0", OLLAMA_URL: "http://127.0.0.1:1",
+});
+const client = new Client({ name: "minecraft-era-validation", version: "1.0" });
+const transport = new StdioClientTransport({
+    command: process.execPath, args: [join(repository, "dist/server.js")],
+    cwd: root, env: environment, stderr: "pipe",
+});
+const errors = [];
+const results = [];
+let serverLog = "";
+transport.stderr?.on("data", data => { serverLog += data; });
+console.log(`Evidence: ${root}`);
+
+async function call(name, args, validate, expectError = false) {
+    const start = Date.now();
+    const result = { name, args };
+    try {
+        const response = await client.callTool({ name, arguments: args }, undefined, { timeout: 300_000 });
+        const text = response.content.filter(item => item.type === "text").map(item => item.text).join("\n");
+        let data;
+        try { data = JSON.parse(text); } catch { data = text; }
+        if (args.action === "search_class" && typeof data === "string") data = data.split("\n").filter(Boolean);
+        assert.equal(response.isError === true, expectError, text);
+        validate?.(data);
+        result.passed = true;
+        return data;
+    } catch (error) {
+        result.passed = false;
+        result.error = error.message;
+        throw error;
+    } finally {
+        result.elapsedMs = Date.now() - start;
+        results.push(result);
+        await appendFile(join(root, "results.jsonl"), JSON.stringify(result) + "\n");
+        console.log(`${result.passed ? "PASS" : "FAIL"} ${args.version ?? ""} ${name}.${args.action} (${result.elapsedMs}ms)${result.error ? `: ${result.error.slice(0, 220)}` : ""}`);
+    }
+}
+
+try {
+    await client.connect(transport);
+    await call("mc_versions", { action: "list_mc", type: "all" }, rows => {
+        for (const version of versions) assert.ok(rows.some(row => row.id === version), `Version list omits ${version}`);
+    }).catch(error => errors.push({ version: "catalog", error: error.message }));
+    for (const version of versions) {
+        try {
+            const classes = await call("mc_source", { action: "search_class", version, query: "Minecraft" }, rows => {
+                assert.ok(rows.some(name => /(?:^|\/)Minecraft$/.test(name)), "No named Minecraft class found");
+            });
+            const className = classes.find(name => /(?:^|\/)Minecraft$/.test(name));
+            await call("mc_source", { action: "get_source", version, className, maxLines: 20 }, text => {
+                assert.equal(typeof text, "string");
+                assert.match(text, /(?:package|import) net\.minecraft\./);
+            });
+            await call("mc_source", { action: "class_members", version, className }, data => {
+                assert.ok(data.methods.length > 5, "Missing class methods");
+                assert.ok(data.fields.length > 5, "Missing class fields");
+            });
+            await call("mc_source", { action: "bytecode", version, className }, text => {
+                assert.equal(typeof text, "string");
+                assert.match(text, /Minecraft/);
+                assert.match(text, /descriptor:/);
+            });
+            await call("mc_source", { action: "inheritance", version, className }, data => {
+                assert.equal(data.className, className);
+                assert.ok(data.superClass);
+            });
+            if (version === "1.5.2") {
+                for (const [className, method] of [
+                    ["net/minecraft/server/MinecraftServer", "tick"],
+                    ["net/minecraft/src/IntegratedServer", "tickIntegrated"],
+                ]) await call("mc_source", { action: "class_members", version, className }, data => {
+                    assert.ok(data.methods.some(entry => entry.name === method), `Lost explicit mapping for ${className}.${method}`);
+                });
+            }
+        } catch (error) {
+            errors.push({ version, error: error.message });
+        }
+    }
+    if (runMods) {
+        await call("mod", { action: "get" }, text => assert.match(text, /modId or dbId is required/), true);
+        const mods = [
+            { project: 73488, version: "1.6.4", loader: "forge", name: "Waila" },
+            { project: 73488, version: "1.7.10", loader: "forge", name: "Waila" },
+            { project: 238222, version: "1.8.9", loader: "forge", name: "JEI" },
+            { project: 238222, version: "1.12.2", loader: "forge", name: "JEI" },
+            { project: 238222, version: "1.16.5", loader: "forge", name: "JEI" },
+            { project: "AANobbMI", version: "1.16.5", loader: "fabric", name: "Sodium" },
+            { project: 238222, version: "1.20.1", loader: "forge", name: "JEI" },
+            { project: 238222, version: "1.21.1", loader: "neoforge", name: "JEI" },
+        ];
+        for (const mod of mods) {
+            try {
+                const infoArgs = { modId: mod.project, mcVersionFilter: mod.version, loader: mod.loader };
+                const before = await call("mod", { action: "stats" });
+                const info = await call("modpacks_ch", { action: "mod_info", ...infoArgs }, data => {
+                    assert.ok(data.versions.length, `No ${mod.name} versions for ${mod.version}/${mod.loader}`);
+                    assert.equal(data.versionLimit, 20);
+                    assert.ok(data.versions.length <= data.versionLimit);
+                    assert.ok(data.versions.every(version => version.loaders.includes(mod.loader)), "Accepted an unverified loader");
+                });
+                const compatibilityAlias = await call("modpacks_ch", { action: "ftb_mod_info", ...infoArgs });
+                assert.deepEqual(compatibilityAlias, info);
+                if (mod.name === "Waila" && mod.version === "1.7.10") {
+                    await call("platform", { action: "search", query: "Waila", mcVersion: mod.version, loader: "forge", limit: 5 }, data => {
+                        assert.ok(data.results.some(hit => String(hit.projectId) === String(mod.project)), "Loader-filtered search omitted Waila");
+                        assert.ok(data.results.every(hit => hit.loaders.includes("forge")), "Search returned an unverified loader");
+                    });
+                    await call("modpacks_ch", { action: "mod_info", ...infoArgs, loader: "fabric", limit: 1 }, data => {
+                        assert.deepEqual(data.versions, [], "Accepted a Forge-only release for Fabric");
+                    });
+                }
+                await call("mod", { action: "stats" }, data => assert.equal(data.total, before.total, "Metadata inspection ingested candidate files"));
+                const downloaded = await call("modpacks_ch", { action: "download_mod", ...infoArgs }, data => {
+                    assert.ok(data.modId > 0, "Download did not produce an ingested mod");
+                });
+                const dbId = downloaded.modId;
+                await call("mod", { action: "get", dbId }, data => {
+                    assert.equal(data.id, dbId, "Returned the wrong database record");
+                    assert.equal(data.loader, mod.loader);
+                    assert.ok(data.modId && data.modId !== "unknown");
+                    assert.ok(data.version && !data.version.includes("${"), "Unresolved version placeholder");
+                });
+                const files = await call("mod_jar", { action: "list_files", modId: dbId });
+                const englishPath = files.entries.find(path => /(?:^|\/)lang\/en_us\.(json|lang)$/i.test(path));
+                const languageFile = englishPath ? await call("mod_jar", { action: "get_file", modId: dbId, path: englishPath }) : undefined;
+                const emptyLanguage = languageFile && (languageFile.data
+                    ? Object.keys(languageFile.data).length === 0 : !languageFile.raw?.trim());
+                await call("mod_jar", { action: "lang", modId: dbId }, data => {
+                    if (emptyLanguage) assert.equal(data.total, 0, "Invented translations for an empty language file");
+                    else if (englishPath) assert.ok(data.total > 0, "Existing language file was not read");
+                    else assert.equal(data.found, false, "Reported language entries for a JAR without English translations");
+                });
+                await call("mod", { action: "reindex", dbId });
+                const query = mod.name === "JEI" ? "JustEnoughItems" : mod.name;
+                const classes = await call("mod_bytecode", { action: "search_class", dbId, query });
+                const className = classes.find(name => !name.includes("$"));
+                assert.ok(className, "No matching mod class found");
+                await call("mod_bytecode", { action: "class_members", dbId, className }, data => {
+                    assert.equal(data.className, className);
+                    assert.ok(data.methods.length, "No methods returned for mod class");
+                });
+                await call("mod_bytecode", { action: "bytecode", dbId, className }, text => assert.match(text, /descriptor:/));
+                await call("mod", { action: "decompile_class", dbId, className }, text => {
+                    assert.match(text, /package /);
+                    assert.ok(text.includes(className.split("/").at(-1)), "Decompiled the wrong class");
+                });
+            } catch (error) {
+                errors.push({ version: `${mod.name} ${mod.version}/${mod.loader}`, error: error.message });
+            }
+        }
+    }
+} finally {
+    await client.close();
+    await writeFile(join(root, "server.log"), serverLog);
+    await writeFile(join(root, "summary.json"), JSON.stringify({ versions, results, errors }, null, 2));
+}
+console.log(`${results.filter(row => row.passed).length}/${results.length} checks passed; ${errors.length} failing versions/catalogs. Evidence: ${root}`);
+if (errors.length) process.exitCode = 1;

package/scripts/test-package.mjs

@@ -109,6 +109,13 @@ try {
         .filter(dir => existsSync(join(dir, "package.json")));
     assert.equal(installs.length, 1);
     const installed = installs[0];
+    const initScript = execFileSync(process.execPath, [join(installed, "dist/launcher.js"), "--gradle-init-script"], { env, encoding: "utf8" }).trim();
+    assert.equal(initScript, join(installed, "scripts/gradle/modlens.init.gradle"));
+    assert.ok(statSync(initScript).size > 0, "Gradle exporter must ship in the npm package");
+    assert.ok(statSync(join(installed, "scripts/project-upload.mjs")).size > 0, "Remote uploader must ship in the npm package");
+    const keyFile = join(root, "project-key.txt");
+    writeFileSync(keyFile, "a".repeat(64));
+    assert.deepEqual(JSON.parse(execFileSync(process.execPath, [join(installed, "dist/launcher.js"), "--project", "list", `--key-file=${keyFile}`], { env, encoding: "utf8" })), []);
     const require = createRequire(join(installed, "package.json"));
     const adapterRequire = createRequire(require.resolve("@prisma/adapter-better-sqlite3"));
     assert.equal(require.resolve("better-sqlite3"), adapterRequire.resolve("better-sqlite3"), "Prisma must share the v12 driver");
@@ -155,6 +162,7 @@ try {
             send({ method: "notifications/initialized" });
             const list = await request("tools/list", {});
             assert.ok(list.tools.some(tool => tool.name === "mod"));
+            assert.ok(list.tools.some(tool => tool.name === "project"));
             const stats = await request("tools/call", { name: "mod", arguments: { action: "stats" } });
             assert.ok(!stats.isError, JSON.stringify(stats));
             assert.equal(JSON.parse(stats.content.find(item => item.type === "text").text).total, 0);

package/scripts/test-project-gradle.mjs

@@ -0,0 +1,76 @@
+// Real Gradle -> export -> ModLens source/member/search assertions. No game launch.
+// Set MODLENS_TEST_GRADLE_HOME and JAVA_HOME. Optional argument: moddev (NeoForge 1.21.1).
+// Uses a disposable fixture; retained on failure for diagnosis.
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { mkdtemp, mkdir, writeFile, readFile, readdir, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ProjectStore } from '../dist/tools/project.js';
+
+const moddev = process.argv[2] === 'moddev';
+const root = await mkdtemp(join(tmpdir(), 'modlens-gradle-smoke-'));
+const repo = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const gradleHome = process.env.MODLENS_TEST_GRADLE_HOME;
+if (!gradleHome || !process.env.JAVA_HOME) throw new Error('Set MODLENS_TEST_GRADLE_HOME and JAVA_HOME');
+const launcher = (await readdir(join(gradleHome, 'lib'))).find(n => /^gradle-launcher-.*\.jar$/.test(n));
+if (!launcher) throw new Error('Gradle launcher JAR missing');
+const java = join(process.env.JAVA_HOME, 'bin', process.platform === 'win32' ? 'java.exe' : 'java');
+const write = async (path, text) => { await mkdir(dirname(join(root, path)), { recursive: true }); await writeFile(join(root, path), text); };
+const run = (sourceSet = 'main') => execFileSync(java, ['-classpath', join(gradleHome, 'lib', launcher), 'org.gradle.launcher.GradleMain',
+    '--no-daemon', '--console=plain', '--no-configuration-cache', '-I', join(repo, 'scripts/gradle/modlens.init.gradle'), `-PmodlensSourceSet=${sourceSet}`, ':modlensExport'],
+    { cwd: root, env: process.env, stdio: 'inherit', timeout: 1200_000 });
+let passed = false;
+try {
+    if (moddev) {
+        await write('settings.gradle', "pluginManagement { repositories { gradlePluginPortal(); maven { url = 'https://maven.neoforged.net/releases' } } }\nrootProject.name = 'modlens-at-smoke'\n");
+        await write('build.gradle', "plugins { id 'java'; id 'net.neoforged.moddev' version '2.0.141' }\njava { toolchain { languageVersion = JavaLanguageVersion.of(21) } }\nneoForge { version = '21.1.209' }\n");
+        await write('gradle.properties', 'minecraft_version=1.21.1\norg.gradle.jvmargs=-Xmx3G\n');
+        await write('src/main/resources/META-INF/accesstransformer.cfg', '# baseline\n');
+    } else {
+        await write('settings.gradle', "rootProject.name = 'modlens-classpath-smoke'\ninclude 'library'\n");
+        await write('build.gradle', "plugins { id 'java' }\ndependencies { implementation project(':library') }\nsourceSets { client { compileClasspath = sourceSets.main.compileClasspath } }\n");
+        await write('library/build.gradle', "plugins { id 'java' }\n");
+        await write('library/src/main/java/example/Target.java', 'package example; public class Target { private final int counter = 7; public int read() { return counter; } }\n');
+    }
+    run();
+    const key = (await readFile(join(root, '.gradle/modlens/project-key.txt'), 'utf8')).trim();
+    const store = new ProjectStore(join(root, 'server-projects'));
+    const first = await store.importBuffer(key, await readFile(join(root, 'build/modlens/main/environment.zip')));
+    const target = moddev ? 'net.minecraft.world.level.Level' : 'example.Target';
+    const fieldName = moddev ? 'isDebug' : 'counter';
+    const field = async id => (await store.members(key, id, target)).result.fields.find(f => f.name === fieldName);
+    const before = await field(first.environmentId);
+    assert.ok(before, `Missing ${fieldName}`);
+    assert.ok(before.access & 0x10, 'baseline field must be final');
+    if (moddev) await write('src/main/resources/META-INF/accesstransformer.cfg', 'public-f net.minecraft.world.level.Level isDebug\n');
+    else await write('library/src/main/java/example/Target.java', 'package example; public class Target { public int counter = 7; public int read() { return counter; } }\n');
+    run();
+    assert.equal((await readFile(join(root, '.gradle/modlens/project-key.txt'), 'utf8')).trim(), key, 'export must preserve private key');
+    const second = await store.importBuffer(key, await readFile(join(root, 'build/modlens/main/environment.zip')));
+    assert.notEqual(first.environmentId, second.environmentId);
+    const after = await field(second.environmentId);
+    assert.ok(after.access & 1, 'transformed field must be public');
+    assert.equal(after.access & 0x10, 0, 'transformed field must not be final');
+    assert.ok((await field(first.environmentId)).access & 0x10, 'baseline must stay final');
+    const source = await store.source(key, second.environmentId, target, 1, 1000);
+    assert.match(source.source, new RegExp(`public (?!final)\\w+ ${fieldName}`));
+    if (moddev) assert.equal(source.origin, 'gradle-sources', 'adapter must supply actual transformed sources');
+    const search = await store.search(key, second.environmentId, `public ${moddev ? 'boolean' : 'int'} ${fieldName}`, 200);
+    assert.ok(search.results.some(r => r.className === target.replaceAll('.', '/')));
+    assert.equal((await store.list('f'.repeat(64))).length, 0);
+    if (!moddev) {
+        run('client'); // sibling :library has no client source set and must not break this export
+        const client = await store.importBuffer(key, await readFile(join(root, 'build/modlens/client/environment.zip')));
+        assert.equal(client.sourceSet, 'client');
+        assert.equal((await field(client.environmentId)).access, 1);
+    }
+    console.log(JSON.stringify({ passed: true, toolchain: second.toolchain, beforeAccess: before.access, afterAccess: after.access,
+        classCount: second.classCount, sourceCount: second.sourceCount, first: first.environmentId, second: second.environmentId }, null, 2));
+    // Keep a bundle for the optional HTTP smoke, without copying any project key into the repository.
+    if (process.env.MODLENS_KEEP_FIXTURE !== '1') passed = true;
+} finally {
+    if (passed) await rm(root, { recursive: true, force: true });
+    else console.log(`Fixture retained: ${root}`);
+}

package/scripts/test-project-http.mjs

@@ -0,0 +1,98 @@
+// Real HTTP MCP transport and shipped uploader smoke. Uses a disposable server/cache on loopback.
+import assert from 'node:assert/strict';
+import { spawn } from 'node:child_process';
+import { createHash, randomBytes } from 'node:crypto';
+import { mkdtemp, writeFile, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createServer } from 'node:net';
+import { once } from 'node:events';
+import AdmZip from 'adm-zip';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+
+const repo = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const root = await mkdtemp(join(tmpdir(), 'modlens-http-smoke-'));
+const listener = createServer();
+listener.listen(0, '127.0.0.1'); await once(listener, 'listening');
+const port = listener.address().port;
+await new Promise(resolveClose => listener.close(resolveClose));
+const endpoint = `http://127.0.0.1:${port}/mcp`;
+const keyFile = process.argv[3] ?? join(root, 'key.txt');
+const bundlePath = process.argv[2] ?? join(root, 'environment.zip');
+const target = process.argv[4] ?? 'example.Target';
+const key = process.argv[3] ? (await readFile(keyFile, 'utf8')).trim() : randomBytes(32).toString('hex');
+if (!process.argv[2]) {
+    await writeFile(keyFile, `${key}\n`);
+    const jar = new AdmZip();
+    jar.addFile('example/Target.class', Buffer.from('test class entry'));
+    jar.addFile('example/Target.java', Buffer.from('package example; public class Target { public int counter; }'));
+    // An incompressible payload exercises multiple full upload chunks.
+    jar.addFile('payload.bin', randomBytes(2 * 1024 * 1024));
+    const bytes = jar.toBuffer();
+    const bundle = new AdmZip();
+    bundle.addFile('artifacts/0.jar', bytes);
+    bundle.addFile('manifest.json', Buffer.from(JSON.stringify({ format: 'modlens-project-v1', project: 'http-smoke:', sourceSet: 'main',
+        toolchain: 'gradle-compile-classpath', minecraftVersion: '', loaderVersion: '', mappings: 'compile-classpath', javaVersion: 21, transformations: [],
+        artifacts: [{ path: 'artifacts/0.jar', name: 'prepared.jar', size: bytes.length, sha256: createHash('sha256').update(bytes).digest('hex'), kind: 'classpath' }] })));
+    await writeFile(bundlePath, bundle.toBuffer());
+}
+const env = { ...process.env, MCP_PORT: String(port), MCP_HOST: '127.0.0.1', MODLENS_AUTO_EMBED: '0',
+    MODLENS_CACHE_ROOT: join(root, 'cache'), MODLENS_HOME: root, DATABASE_URL: `file:${join(root, 'unused.db')}`, MODLENS_VERBOSE: '1' };
+const server = spawn(process.execPath, [join(repo, 'dist/server.js')], { cwd: root, env, stdio: ['ignore', 'ignore', 'pipe'] });
+let logs = '';
+server.stderr.on('data', b => { logs += b; });
+const stopped = once(server, 'exit');
+const client = new Client({ name: 'project-http-test', version: '1.0.0' });
+let passed = false;
+try {
+    await new Promise((resolveReady, reject) => {
+        const timer = setTimeout(() => reject(new Error('HTTP server startup timed out')), 30_000);
+        const ready = () => { if (logs.includes('listening on')) { clearTimeout(timer); server.stderr.off('data', ready); resolveReady(); } };
+        server.stderr.on('data', ready);
+        server.once('error', reject);
+        server.once('exit', () => { clearTimeout(timer); reject(new Error(`Server exited before startup: ${logs}`)); });
+        ready();
+    });
+    const uploader = spawn(process.execPath, [join(repo, 'scripts/project-upload.mjs'), endpoint, bundlePath, keyFile], { cwd: root, env, stdio: ['ignore', 'pipe', 'pipe'] });
+    let output = ''; let error = '';
+    uploader.stdout.on('data', b => { output += b; }); uploader.stderr.on('data', b => { error += b; });
+    const [code] = await once(uploader, 'exit');
+    assert.equal(code, 0, error);
+    assert.ok(!output.includes(key), 'uploader must not print project key');
+    const imported = JSON.parse(output);
+    await client.connect(new StreamableHTTPClientTransport(new URL(endpoint)));
+    const call = (action, args = {}) => client.callTool({ name: 'project', arguments: { action, projectKey: key, environmentId: imported.environmentId, ...args } }, undefined, { timeout: 300_000 });
+    const tools = await client.listTools();
+    assert.ok(tools.tools.some(t => t.name === 'project'));
+    const source = await call('source', { className: target });
+    assert.ok(!source.isError, JSON.stringify(source));
+    assert.ok(JSON.parse(source.content[0].text).source.length > 0);
+    if (process.argv[5]) {
+        const members = await call('members', { className: target });
+        assert.ok(!members.isError, JSON.stringify(members));
+        const field = JSON.parse(members.content[0].text).result.fields.find(f => f.name === process.argv[5]);
+        assert.equal(field?.access, 1, 'remote member view must preserve the public, non-final AT result');
+        const searched = await call('search', { query: `public boolean ${process.argv[5]}`, limit: 200 });
+        assert.ok(!searched.isError, JSON.stringify(searched));
+        assert.ok(JSON.parse(searched.content[0].text).results.some(r => r.className === target.replaceAll('.', '/')));
+    }
+    const wrongKey = await call('info', { projectKey: randomBytes(32).toString('hex') });
+    assert.ok(wrongKey.isError);
+    const local = await call('import_local', { bundlePath });
+    assert.ok(local.isError, 'HTTP must reject host-local import');
+    const failedChunk = await call('upload_chunk', { uploadId: 'f'.repeat(64), offset: 0, data: 'SENSITIVE_PAYLOAD' });
+    assert.ok(failedChunk.isError);
+    const large = await fetch(endpoint, { method: 'POST', body: 'x'.repeat(9 * 1024 * 1024) });
+    assert.equal(large.status, 413);
+    assert.ok(!logs.includes(key), 'server logs must redact project key');
+    assert.ok(!logs.includes('SENSITIVE_PAYLOAD'), 'server logs must redact upload bytes');
+    console.log(`PASS: HTTP upload, ${imported.classCount} classes, source query, project isolation, host-path rejection, body limits and log redaction`);
+    passed = true;
+} finally {
+    await client.close();
+    server.kill(); await stopped;
+    if (passed) await rm(root, { recursive: true, force: true });
+    else console.log(`HTTP fixture retained: ${root}`);
+}