@creeperhost/modlens-mcp 1.6.19 → 1.6.21

package/dist/runtime/requests.js

@@ -0,0 +1,57 @@
+import { z } from "zod";
+import { RUNTIME_HELP } from "./hub.js";
+import { runtimeCommand, runtimeMode } from "./protocol.js";
+export const runtimeToolSchema = {
+    action: z.enum(["help", "setup", "status", "sessions", "launch", "events", "command", "artifact"]),
+    projectDir: z
+        .string()
+        .optional()
+        .describe("Absolute local mod project directory for setup; requires an existing Gradle dev run."),
+    projectId: z.string().uuid().optional(),
+    sessionId: z.string().uuid().optional(),
+    mcVersion: z.literal("26.3").optional(),
+    mode: runtimeMode
+        .optional()
+        .describe("interactive=human input, observe=visible/MCP input only, hidden=invisible/MCP input only"),
+    gradleTask: z
+        .string()
+        .optional()
+        .describe("Existing client JavaExec task, defaults to runClient; e.g. :fabric:runClient"),
+    minecraftHooks: z
+        .boolean()
+        .optional()
+        .describe("Enable optional 26.3 screenshot/state/crash hooks (default true). SDL input and JVM monitoring are independent."),
+    javaHome: z.string().optional().describe("JDK home for the Gradle launch; use JDK 25 for 26.3"),
+    afterCursor: z.number().int().min(0).optional(),
+    waitMs: z.number().int().min(0).max(30_000).optional(),
+    command: runtimeCommand.optional(),
+    artifactName: z.string().optional(),
+};
+export const runtimeRequest = z.object(runtimeToolSchema);
+function need(v, name) {
+    if (v === undefined)
+        throw new Error(`${name} is required for this action`);
+    return v;
+}
+export async function executeRuntime(hub, raw) {
+    const a = runtimeRequest.parse(raw);
+    if (a.action === "help")
+        return RUNTIME_HELP;
+    switch (a.action) {
+        case "setup":
+            return hub.setup(need(a.projectDir, "projectDir"), a.mode, a.gradleTask, a.minecraftHooks);
+        case "status":
+            return hub.status(a.sessionId);
+        case "sessions":
+            return hub.list();
+        case "launch":
+            return hub.launch(need(a.projectId, "projectId"), a.javaHome);
+        case "events":
+            return hub.events(a.afterCursor, a.waitMs, a.sessionId);
+        case "command":
+            return hub.command(need(a.sessionId, "sessionId"), need(a.command, "command"));
+        case "artifact":
+            return hub.artifact(need(a.sessionId, "sessionId"), need(a.artifactName, "artifactName"));
+    }
+}
+//# sourceMappingURL=requests.js.map

package/dist/runtime/requests.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"requests.js","sourceRoot":"","sources":["../../src/runtime/requests.ts"],"names":[],"mappings":"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"}

package/dist/server.js

@@ -39,6 +39,10 @@ import { mcPaths } from "./minecraft.js";
 import { findModById, resolveModRefSlim } from "./repositories/mod.js";
 import { CACHE_ROOT } from "./cache.js";
 import { projectAction, projectToolSchema } from "./tools/project.js";
+import { runtimeAction, runtimeToolSchema, runtimeHub } from "./tools/runtime.js";
+import { reportIssue, reportIssueSchema } from "./tools/report-issue.js";
+import { HOSTED_ACTIONS, HostedBudget, HostedPolicyError, hostedLimits, hostedPrincipal, runHostedTool } from "./hosted-policy.js";
+import { reviewHostedMod, localModPlan } from "./hosted-mod-license.js";
 // Load .env — try ~/.modlens/.env first (npx/installed users), then local .env (git-clone users)
 import { readFileSync, existsSync } from "fs";
 import { join, dirname } from "path";
@@ -158,10 +162,74 @@ class JsonBodyParseError extends Error {
 }
 class HttpBodyTooLargeError extends Error {
 }
-function createMcpServer() {
-    const server = new McpServer({ name: "modlens", version: pkg.version });
+const hostedBudget = new HostedBudget();
+function createMcpServer(principal) {
+    const server = new McpServer({ name: "modlens", version: pkg.version }, {
+        instructions: "ModLens supports optional Minecraft 26.3 runtime control. Call runtime help/setup. On remote MCP, runtime returns executed:false and a local execution plan: use your local terminal/file tools to run the --runtime helper on the Minecraft PC. No second MCP connection or tunnel is needed. Local stdio executes directly. Inspect sessions/capabilities after launch; use events/command/artifact for input, screenshots, crashes and allocation reports. Never describe a returned plan as an executed action. Idle AI wake-up is not provided. To report a ModLens bug, use report_issue help/prepare for a GitHub draft and submission instructions; the caller files it using existing GitHub access when requested by the user.",
+    });
+    const limits = principal === undefined ? undefined : hostedLimits();
+    function registerTool(name, description, schema, handler) {
+        if (!limits || principal === undefined) {
+            server.tool(name, description, schema, handler);
+            return;
+        }
+        const actions = HOSTED_ACTIONS[name];
+        if (!actions)
+            return;
+        const actionSchema = schema.action;
+        let publicSchema = actionSchema instanceof z.ZodEnum
+            ? { ...schema, action: z.enum(actions.filter(a => actionSchema.options.includes(a))) }
+            : schema;
+        if (name === "mod_bytecode")
+            publicSchema = { ...publicSchema,
+                startLine: z.number().int().positive().optional().describe("First bytecode line, 1-based"),
+                maxLines: z.number().int().positive().optional().describe("Bytecode lines to return (hosted cap applies)"),
+            };
+        // Do not advertise host paths, cache jobs, registry exports or unavailable operations.
+        const publicDescription = `${description.split(". ")[0]}. Hosted access: ${actions.filter(Boolean).join(", ") || "analysis"}. Responses and cumulative usage are bounded; use focused queries and source ranges.`;
+        server.tool(name, publicDescription, publicSchema, (async (args, extra) => runHostedTool(name, args, principal, limits, hostedBudget, async (bounded) => handler(bounded, extra))));
+    }
+    registerTool("report_issue", "Prepare a ModLens GitHub issue and direct the coding agent to submit it using its own GitHub tools or gh CLI; this tool does not publish anything. " +
+        "Use help for guidance or prepare with title/summary and sanitized reproduction details. Available locally and remotely; always returns executed:false. The caller separately reports the GitHub URL after submission.", reportIssueSchema, safe(async (args) => out(reportIssue(args, pkg.version))));
+    registerTool("mod_license", "Inspect a mod's license evidence before hosted source access, or request consent for local decompilation. " +
+        "Precedence: applicable GitHub version, mod JAR, CurseForge. action=check|local_plan. " +
+        "Provide modId/dbId or projectKey+environmentId+className. Local plans must run on the user's computer; never claim a plan has executed.", {
+        action: z.enum(["check", "local_plan"]),
+        modId: z.union([z.string(), z.number()]).optional(), dbId: z.number().int().positive().optional(),
+        projectKey: z.string().optional(), environmentId: z.string().optional(), className: z.string().optional(),
+        operation: z.enum(["source", "bytecode"]).optional(),
+        startLine: z.number().int().positive().optional(), maxLines: z.number().int().positive().max(10000).optional(),
+    }, safe(async (args) => {
+        const decision = await reviewHostedMod(args);
+        if (args.action === "check")
+            return out(decision);
+        let accepted = false;
+        if (server.server.getClientCapabilities()?.elicitation?.form !== undefined) {
+            const consent = await server.server.elicitInput({
+                mode: "form",
+                message: `Allow local decompilation of ${args.className ?? "this mod"} from JAR SHA-256 ${decision.sha256}? ${decision.reason} This does not grant redistribution rights; source stays on your computer.`,
+                requestedSchema: { type: "object", properties: {
+                        acceptLocal: { type: "boolean", title: "I accept local decompilation of this artifact", default: false },
+                    }, required: ["acceptLocal"] },
+            });
+            if (consent.action !== "accept" || consent.content?.acceptLocal !== true)
+                return out({ executed: false, declined: true });
+            accepted = true;
+        }
+        return out({ licenseReview: decision, local: localModPlan(decision, { ...args, action: args.operation ?? "source" }, accepted) });
+    }));
+    registerTool("runtime", "Optional Minecraft 26.3 live dev runtime: help/setup/status/sessions/launch/events/command/artifact. " +
+        "The AI can set up the Java agent and IntelliJ Gradle launch itself with setup(projectDir), then launch or detect a user launch. Remote MCP returns a local execution plan for the --runtime CLI helper; execute it using local terminal/file tools. " +
+        "Monitor JVM metrics/crashes and allocation hotspots filtered by mod package, control keyboard/mouse internally, capture screenshots, and switch visible watch-only/hidden/human modes. " +
+        "No desktop control or extra local MCP connection required. Plans have executed:false; verify local results. Call help for setup. Poll events with a cursor to actively monitor.", runtimeToolSchema, safe(async (args) => {
+        const result = await runtimeAction(args);
+        if (args.action === "artifact" && result && typeof result === "object" && "mimeType" in result && "data" in result) {
+            return { content: [{ type: "image", mimeType: "image/png", data: result.data }] };
+        }
+        return out(result);
+    }));
     // ── 1. mod ────────────────────────────────────────────────────────────────────
-    server.tool("mod", "Mod database, decompile, and source browser. action=ingest|list|get|search|stats|dependencies|dep_graph|version_conflicts|source_urls|decompile|decompile_status|decompile_class|source|search_source|reindex|batch_ingest|batch_decompile|refresh_metadata|index_fts|search_indexed|index_semantic|search_semantic|get_paths|delete|graph_build|graph_status|graph_query|graph_report|graph_enrich_next|graph_enrich_submit|graph_download|graph_export|graph_submit|embed_export|embed_download|embed_download_all|embed_status|embed_submit. index_fts/search_indexed: BM25-ranked FTS over source code. index_semantic/search_semantic: vector search (requires Ollama). refresh_metadata: re-parse all mods with degraded metadata (filename/@Mod annotation) and upgrade if a higher-quality manifest is found. graph_enrich_next: get next un-enriched chunk for chat enrichment. graph_enrich_submit: submit enriched nodes/edges (chunkIndex, nodes, edges). graph_download: download pre-built graph from registry (targetType=mod|vanilla|modloader with targetId/targetVersion). graph_export: export a mod's local graph as a shareable gzipped bundle. graph_submit: validate an exported bundle and open a draft GitHub registry PR (bundlePath required). embed_export/embed_download/embed_status: targetType-aware embeddings actions for mod/vanilla/modloader. embed_download: downloads registry embeddings; protects local embeddings by default (use force=true to overwrite). embed_download_all: download embeddings for all mods. embed_submit: validate an exported bundle and open a draft GitHub registry PR (bundlePath required). Auto-behaviors: decompile_status auto-queues embedding (MODLENS_AUTO_EMBED) and graph build (MODLENS_AUTO_GRAPH). Pass autoEmbed/autoGraph to override per-call.", {
+    registerTool("mod", "Mod database, decompile, and source browser. action=ingest|list|get|search|stats|dependencies|dep_graph|version_conflicts|source_urls|decompile|decompile_status|decompile_class|source|search_source|reindex|batch_ingest|batch_decompile|refresh_metadata|index_fts|search_indexed|index_semantic|search_semantic|get_paths|delete|graph_build|graph_status|graph_query|graph_report|graph_enrich_next|graph_enrich_submit|graph_download|graph_export|graph_submit|embed_export|embed_download|embed_download_all|embed_status|embed_submit. index_fts/search_indexed: BM25-ranked FTS over source code. index_semantic/search_semantic: vector search (requires Ollama). refresh_metadata: re-parse all mods with degraded metadata (filename/@Mod annotation) and upgrade if a higher-quality manifest is found. graph_enrich_next: get next un-enriched chunk for chat enrichment. graph_enrich_submit: submit enriched nodes/edges (chunkIndex, nodes, edges). graph_download: download pre-built graph from registry (targetType=mod|vanilla|modloader with targetId/targetVersion). graph_export: export a mod's local graph as a shareable gzipped bundle. graph_submit: validate an exported bundle and open a draft GitHub registry PR (bundlePath required). embed_export/embed_download/embed_status: targetType-aware embeddings actions for mod/vanilla/modloader. embed_download: downloads registry embeddings; protects local embeddings by default (use force=true to overwrite). embed_download_all: download embeddings for all mods. embed_submit: validate an exported bundle and open a draft GitHub registry PR (bundlePath required). Auto-behaviors: decompile_status auto-queues embedding (MODLENS_AUTO_EMBED) and graph build (MODLENS_AUTO_GRAPH). Pass autoEmbed/autoGraph to override per-call.", {
         action: z.enum([
             "ingest", "list", "get", "search", "stats", "dependencies", "dep_graph",
             "version_conflicts", "source_urls", "decompile", "decompile_status",
@@ -176,6 +244,8 @@ function createMcpServer() {
         dbId: z.number().optional().describe("DB id"),
         query: z.string().optional(),
         path: z.string().optional(),
+        startLine: z.number().int().positive().optional().describe("First source line, 1-based"),
+        maxLines: z.number().int().positive().optional().describe("Source lines to return"),
         className: z.string().optional(),
         loader: z.string().optional().describe("fabric|neoforge|forge|quilt"),
         mcVersion: z.string().optional(),
@@ -208,7 +278,7 @@ function createMcpServer() {
         autoEmbed: z.boolean().optional().describe("Override auto-embed on decompile completion (default: env MODLENS_AUTO_EMBED, true)"),
         autoGraph: z.boolean().optional().describe("Override auto-graph-build on decompile/source-download (default: env MODLENS_AUTO_GRAPH, true)"),
         provenance: z.enum(["local", "registry", "community"]).optional().describe("Filter search_semantic results by embedding source (default: all sources)"),
-    }, safe(async ({ action, jarPath, modId, dbId: rawDbId, query, path, className, loader, mcVersion, hasMixins, decompiled, recursive, skipSource, isRegex, force, limit, directory, indexClasses, replace, budget, backend, chunkIndex, nodes, edges, outputDir, modVersion, targetType, targetId, targetVersion, targetLoader, targetMcVersion, model, autoEmbed, autoGraph, provenance, bundlePath, contributor, note }) => {
+    }, safe(async ({ action, jarPath, modId, dbId: rawDbId, query, path, startLine, maxLines, className, loader, mcVersion, hasMixins, decompiled, recursive, skipSource, isRegex, force, limit, directory, indexClasses, replace, budget, backend, chunkIndex, nodes, edges, outputDir, modVersion, targetType, targetId, targetVersion, targetLoader, targetMcVersion, model, autoEmbed, autoGraph, provenance, bundlePath, contributor, note }) => {
         const dbId = await resolveDbIdAsync(rawDbId, modId);
         const resolvedTargetType = targetType ?? "mod";
         const resolvedTargetId = targetId ?? (typeof modId === "string" ? modId : undefined) ?? (resolvedTargetType === "vanilla" ? "minecraft" : undefined);
@@ -260,7 +330,7 @@ function createMcpServer() {
             case "source":
                 if (dbId == null)
                     throw new Error(`Mod not found: ${String(modId ?? rawDbId ?? "")}`);
-                result = await getModSource(dbId, path);
+                result = await getModSource(dbId, path, startLine, maxLines);
                 break;
             case "search_source":
                 result = await searchSource(query, dbId, isRegex ?? false, limit ?? 50);
@@ -381,7 +451,7 @@ function createMcpServer() {
         return out(result);
     }));
     // ── 2. mod_bytecode ───────────────────────────────────────────────────────────
-    server.tool("mod_bytecode", "Mod JAR bytecode and class analysis — for INGESTED MODS only (requires dbId or modId of an ingested mod). For vanilla Minecraft classes use mc_source instead. action=search_class|class_members|bytecode|find_refs|cross_refs|inheritance|diff|diff_detailed|cache_diff|find_implementors|scan_registrations|annotated_by|event_listeners|optional_integrations|network_payloads|config_schema. Most actions require dbId or modId. cross_refs/find_implementors/annotated_by/event_listeners can omit modId to search all mods. diff/diff_detailed/cache_diff require dbIdA+dbIdB. diff_detailed gives AST-level method/field changes with breaking-change flags (add semantic=true for cosine similarity, requires mod index_semantic). cache_diff forces a (re)compute and writes to DB. Set env AUTO_CACHE_MOD_DIFFS=1 to auto-cache all diff_detailed calls.", {
+    registerTool("mod_bytecode", "Mod JAR bytecode and class analysis — for INGESTED MODS only (requires dbId or modId of an ingested mod). For vanilla Minecraft classes use mc_source instead. action=search_class|class_members|bytecode|find_refs|cross_refs|inheritance|diff|diff_detailed|cache_diff|find_implementors|scan_registrations|annotated_by|event_listeners|optional_integrations|network_payloads|config_schema. Most actions require dbId or modId. cross_refs/find_implementors/annotated_by/event_listeners can omit modId to search all mods. diff/diff_detailed/cache_diff require dbIdA+dbIdB. diff_detailed gives AST-level method/field changes with breaking-change flags (add semantic=true for cosine similarity, requires mod index_semantic). cache_diff forces a (re)compute and writes to DB. Set env AUTO_CACHE_MOD_DIFFS=1 to auto-cache all diff_detailed calls.", {
         action: z.enum(["search_class", "class_members", "bytecode", "find_refs", "cross_refs", "inheritance", "diff", "diff_detailed", "cache_diff", "find_implementors", "scan_registrations", "annotated_by", "event_listeners", "optional_integrations", "network_payloads", "config_schema"]),
         dbId: z.number().optional().describe("DB id"),
         dbIdA: z.number().optional().describe("older DB id"),
@@ -457,7 +527,7 @@ function createMcpServer() {
         return out(result);
     }));
     // ── 3. mod_mixins ─────────────────────────────────────────────────────────────
-    server.tool("mod_mixins", "Mod mixin and access transformer analysis. action=targets|resolve|conflicts|targets_in_package|at_conflicts|at_entries|aw_entries.", {
+    registerTool("mod_mixins", "Mod mixin and access transformer analysis. action=targets|resolve|conflicts|targets_in_package|at_conflicts|at_entries|aw_entries.", {
         action: z.enum(["targets", "resolve", "conflicts", "targets_in_package", "at_conflicts", "at_entries", "aw_entries"]),
         modId: z.union([z.string(), z.number()]).optional().describe("mod ID or DB id"),
         dbId: z.number().optional().describe("DB id"),
@@ -494,7 +564,7 @@ function createMcpServer() {
         return out(result);
     }));
     // ── 4. platform ───────────────────────────────────────────────────────────────
-    server.tool("platform", "Modrinth/CurseForge platform sync and source download. action=sync_modrinth|sync_curseforge|check_updates|batch_sync|download_source|search|batch_check_updates. " +
+    registerTool("platform", "Modrinth/CurseForge platform sync and source download. action=sync_modrinth|sync_curseforge|check_updates|batch_sync|download_source|search|batch_check_updates. " +
         "action=search: unified mod search across both Modrinth and CurseForge — deduplicated, sorted by downloads (query required, loader, mcVersion, limit). Missing modpacks.ch loader labels are recovered by inspecting cached/downloaded JARs. " +
         "action=batch_check_updates: check ALL linked mods for newer versions on Modrinth/CurseForge in one pass (mcVersion, loader, modIdFilter, limit). " +
         "download_source downloads GitHub source without decompilation — auto-queues graph build (override with autoGraph). Env: MODLENS_AUTO_GRAPH (default: 1).", {
@@ -540,7 +610,7 @@ function createMcpServer() {
         return out(result);
     }));
     // ── 5. modpacks_ch ───────────────────────────────────────────────────────────
-    server.tool("modpacks_ch", "Search, resolve, list versions for, and ingest arbitrary modpacks so other ModLens tools can analyze the exact pack contents. General workflow: when the user names a modpack and possibly a fuzzy version like 7.1, call action=list_versions with packRef/versionRef, choose the best matching version, then call action=ingest_pack before using analyze_crash_log, reports, pack_tools, dependency checks, mixin scans, source search, or other pack-aware analysis. Crash triage is one common use, not the only use. " +
+    registerTool("modpacks_ch", "Search, resolve, list versions for, and ingest arbitrary modpacks so other ModLens tools can analyze the exact pack contents. General workflow: when the user names a modpack and possibly a fuzzy version like 7.1, call action=list_versions with packRef/versionRef, choose the best matching version, then call action=ingest_pack before using analyze_crash_log, reports, pack_tools, dependency checks, mixin scans, source search, or other pack-aware analysis. Crash triage is one common use, not the only use. " +
         "Metadata comes from modpacks.ch for all providers; downloads use the supplied URLs and Modrinth .mrpack archives. Loader-filtered mod queries automatically download and inspect unlabeled JARs; recovered labels report loaderSource=jar. No CurseForge API key is required. Modrinth packRef may be a slug/project ID, a modrinth.com modpack/version URL, an api.modrinth.com project/version URL, a cdn.modrinth.com .mrpack URL, or any direct HTTPS .mrpack URL. " +
         "action=search|featured|info|manifest|resolve_pack|list_versions|ingest_pack|sync_pack_mods|search_mods|mod_info|download_mod|download_overrides|list_pack_versions|list_pack_files|find_mod_in_packs. mod_info returns up to limit versions (default 20). search_ftb_mods and ftb_mod_info remain compatibility aliases. " +
         "namespace=ftb|curseforge|modrinth|feedthebeast (default: ftb). feedthebeast uses the modpacks.ch /ftb catalog; ftb uses /modpack. resolve_pack/list_versions/ingest_pack accept packRef=name/slug/id and versionRef=version id/name/number/partial text. list_versions returns matches for fuzzy refs; list_pack_versions is DB-backed synced-pack history. " +
@@ -648,7 +718,7 @@ function createMcpServer() {
         return out(result);
     }));
     // ── 6. mc_versions ────────────────────────────────────────────────────────────
-    server.tool("mc_versions", "Minecraft and mod loader version management. action=list_mc|list_neoforge|list_forge|list_fabric|ingest_neoforge|ingest_forge|ingest_fabric.", {
+    registerTool("mc_versions", "Minecraft and mod loader version management. action=list_mc|list_neoforge|list_forge|list_fabric|ingest_neoforge|ingest_forge|ingest_fabric.", {
         action: z.enum(["list_mc", "list_neoforge", "list_forge", "list_fabric", "ingest_neoforge", "ingest_forge", "ingest_fabric"]),
         type: z.enum(["release", "snapshot", "all"]).optional(),
         mcVersion: z.string().optional(),
@@ -712,7 +782,7 @@ function createMcpServer() {
         return out(result);
     }));
     // ── 6. mc_source ─────────────────────────────────────────────────────────────
-    server.tool("mc_source", "Vanilla Minecraft source code, decompilation, and validation — use this for vanilla MC classes (net/minecraft/...), NOT mod_bytecode. Requires version param. action=search_class|get_source|bytecode|class_members|find_refs|inheritance|diff|diff_detailed|decompile|decompile_status|search_code|index|search_indexed|search_events|validate_aw|analyze_mixin|index_semantic|search_semantic|get_paths. get_paths returns the on-disk jar, decompiled source directory, and index paths so the agent can grep/search files natively. diff_detailed gives AST-level method/field changes with breaking-change flags per class; add semantic=true for cosine similarity scoring (requires Ollama + index_semantic run first). index_semantic/search_semantic require Ollama running.", {
+    registerTool("mc_source", "Vanilla Minecraft source code, decompilation, and validation — use this for vanilla MC classes (net/minecraft/...), NOT mod_bytecode. Requires version param. action=search_class|get_source|bytecode|class_members|find_refs|inheritance|diff|diff_detailed|decompile|decompile_status|search_code|index|search_indexed|search_events|validate_aw|analyze_mixin|index_semantic|search_semantic|get_paths. get_paths returns the on-disk jar, decompiled source directory, and index paths so the agent can grep/search files natively. diff_detailed gives AST-level method/field changes with breaking-change flags per class; add semantic=true for cosine similarity scoring (requires Ollama + index_semantic run first). index_semantic/search_semantic require Ollama running.", {
         action: z.enum(["search_class", "get_source", "bytecode", "class_members", "find_refs", "inheritance", "diff", "diff_detailed", "decompile", "decompile_status", "search_code", "index", "search_indexed", "search_events", "validate_aw", "analyze_mixin", "index_semantic", "search_semantic", "get_paths"]),
         version: z.string().optional(),
         versionA: z.string().optional(),
@@ -808,7 +878,7 @@ function createMcpServer() {
         return out(result);
     }));
     // ── 7. mappings ───────────────────────────────────────────────────────────────
-    server.tool("mappings", "Minecraft name mappings and Parchment parameter docs. action=find translates one symbol between namespaces; action=remap rewrites a mod JAR and requires inputJar/outputJar/toMapping; action=parchment|list_parchment|parchment_summary reads Parchment docs.", {
+    registerTool("mappings", "Minecraft name mappings and Parchment parameter docs. action=find translates one symbol between namespaces; action=remap rewrites a mod JAR and requires inputJar/outputJar/toMapping; action=parchment|list_parchment|parchment_summary reads Parchment docs.", {
         action: z.enum(["find", "remap", "parchment", "list_parchment", "parchment_summary"]),
         symbol: z.string().optional().describe("Symbol to translate; use with action=find, not action=remap"),
         version: z.string().optional(),
@@ -854,7 +924,7 @@ function createMcpServer() {
         return out(result);
     }));
     // ── 8. docs ───────────────────────────────────────────────────────────────────
-    server.tool("docs", "Minecraft modding documentation database. action=ingest|seed|get|search|list|delete|semantic_search|backfill_embeddings. semantic_search requires Ollama running.", {
+    registerTool("docs", "Minecraft modding documentation database. action=ingest|seed|get|search|list|delete|semantic_search|backfill_embeddings. semantic_search requires Ollama running.", {
         action: z.enum(["ingest", "seed", "get", "search", "list", "delete", "semantic_search", "backfill_embeddings"]),
         entries: z.array(z.object({
             className: z.string().optional(),
@@ -903,7 +973,7 @@ function createMcpServer() {
         return out(result);
     }));
     // ── 9. primers ────────────────────────────────────────────────────────────────
-    server.tool("primers", "Minecraft version migration primers and porting guides. action=ingest|seed|get|by_version|search|list|delete|semantic_search|backfill_embeddings. semantic_search requires Ollama running.", {
+    registerTool("primers", "Minecraft migration primers. by_version finds each migration step, including vanilla changes for the selected loader; includeContent=true bundles the Markdown with a shared maxChars budget. Continue with nextCursor until null, keeping the same range and loader. get reads one guide (follow nextStartLine). Missing content is fetched and cached unless fetchContent=false. seed populates the catalogue. Bundles report per-guide failures; retry failed IDs with get. Published guides may leave coverage gaps. semantic_search requires Ollama.", {
         action: z.enum(["ingest", "seed", "get", "by_version", "search", "list", "delete", "semantic_search", "backfill_embeddings"]),
         entries: z.array(z.object({
             fromVersion: z.string(),
@@ -916,27 +986,34 @@ function createMcpServer() {
             tags: z.array(z.string()).optional(),
             source: z.string().optional(),
             fetchContent: z.boolean().optional(),
-        })).optional().describe("Primer entries to ingest (ingest)"),
-        id: z.number().optional(),
+        })).min(1).optional().describe("Primer entries to ingest; set entries[].fetchContent=true to fetch before saving"),
+        id: z.number().int().positive().optional(),
         fromVersion: z.string().optional(),
         toVersion: z.string().optional(),
-        modloader: z.string().optional().describe("neoforge|forge|fabric|quilt"),
+        modloader: z.string().optional().describe("neoforge|forge|fabric|quilt|vanilla; discovery includes vanilla guides"),
         query: z.string().optional(),
-        limit: z.number().optional(),
-    }, safe(async ({ action, entries, id, fromVersion, toVersion, modloader, query, limit }) => {
+        limit: z.number().int().min(1).max(200).optional(),
+        fetchContent: z.boolean().optional().describe("get/seed/by_version: fetch missing content (default true); false permits cached/offline reads"),
+        includeContent: z.boolean().optional().describe("by_version: bundle guide bodies (default false); includes vanilla guides for the selected loader"),
+        maxChars: z.number().int().min(1000).max(200000).optional().describe("by_version with includeContent: combined text budget (default 60000); up to 20 guides per page"),
+        cursor: z.string().min(1).max(2048).optional().describe("by_version with includeContent: nextCursor from the previous page; retain the same range and loader"),
+        refresh: z.boolean().optional().describe("get: re-fetch even if cached; failed refresh preserves the cached guide"),
+        startLine: z.number().int().positive().optional().describe("get: first line, 1-based (default 1)"),
+        maxLines: z.number().int().min(1).max(2000).optional().describe("get: page size (default 400); follow nextStartLine until null"),
+    }, safe(async ({ action, entries, id, fromVersion, toVersion, modloader, query, limit, fetchContent, includeContent, maxChars, cursor, refresh, startLine, maxLines }) => {
         let result;
         switch (action) {
             case "ingest":
                 result = await ingestPrimer(entries);
                 break;
             case "seed":
-                result = await seedDefaultPrimers();
+                result = await seedDefaultPrimers(fetchContent);
                 break;
             case "get":
-                result = await getPrimer(id);
+                result = await getPrimer(id, { fetchContent, refresh, startLine, maxLines });
                 break;
             case "by_version":
-                result = await getPrimersByVersionRange(fromVersion, toVersion, modloader);
+                result = await getPrimersByVersionRange(fromVersion, toVersion, modloader, { includeContent, fetchContent, maxChars, cursor });
                 break;
             case "search":
                 result = await searchPrimers(query, modloader, fromVersion, toVersion, limit);
@@ -954,10 +1031,10 @@ function createMcpServer() {
                 result = await backfillPrimerEmbeddings();
                 break;
         }
-        return out(result);
+        return { ...out(result), ...(result && typeof result === "object" && "failed" in result && Number(result.failed) > 0 ? { isError: true } : {}) };
     }));
     // ── 10. mc_registry ───────────────────────────────────────────────────────────
-    server.tool("mc_registry", "Vanilla MC registry and meta data (blocks, commands, registries, sounds, item components). action=blocks|commands|registries|sounds|item_components|registry_entries|mcmeta_versions.", {
+    registerTool("mc_registry", "Vanilla MC registry and meta data (blocks, commands, registries, sounds, item components). action=blocks|commands|registries|sounds|item_components|registry_entries|mcmeta_versions.", {
         action: z.enum(["blocks", "commands", "registries", "sounds", "item_components", "registry_entries", "mcmeta_versions"]),
         version: z.string().optional(),
         registry: z.string().optional().describe("registry key e.g. 'block','item','entity_type'"),
@@ -990,7 +1067,7 @@ function createMcpServer() {
         return out(result);
     }));
     // ── 11. mc_data ───────────────────────────────────────────────────────────────
-    server.tool("mc_data", "Vanilla MC data browser — tags, recipes, loot tables, lang, blockstates, models, biomes, enchantments, advancements, structures, particles, entity attributes. action=tags|find_tags_for|recipes|get_recipe|find_recipes_for|loot_tables|get_loot_table|lang|blockstate|model|model_tree|biomes|get_biome|damage_types|enchantments|get_enchantment|advancements|get_advancement|structures|get_structure|particles|get_particle|entity_attributes.", {
+    registerTool("mc_data", "Vanilla MC data browser — tags, recipes, loot tables, lang, blockstates, models, biomes, enchantments, advancements, structures, particles, entity attributes. action=tags|find_tags_for|recipes|get_recipe|find_recipes_for|loot_tables|get_loot_table|lang|blockstate|model|model_tree|biomes|get_biome|damage_types|enchantments|get_enchantment|advancements|get_advancement|structures|get_structure|particles|get_particle|entity_attributes.", {
         action: z.enum([
             "tags", "find_tags_for", "recipes", "get_recipe", "find_recipes_for",
             "loot_tables", "get_loot_table", "lang", "blockstate", "model", "model_tree",
@@ -1094,7 +1171,7 @@ function createMcpServer() {
         return out(result);
     }));
     // ── 12. mc_files ─────────────────────────────────────────────────────────────
-    server.tool("mc_files", "Vanilla MC file access via misode/mcmeta (data packs, assets, atlases, diffs, changelogs). action=get_data|get_asset|list_files|diff|atlas|raw|compare|changelog. list_files requires dirPath+version+branch. diff requires filePath+versionA+versionB. get_data/get_asset require filePath.", {
+    registerTool("mc_files", "Vanilla MC file access via misode/mcmeta (data packs, assets, atlases, diffs, changelogs). action=get_data|get_asset|list_files|diff|atlas|raw|compare|changelog. list_files requires dirPath+version+branch. diff requires filePath+versionA+versionB. get_data/get_asset require filePath.", {
         action: z.enum(["get_data", "get_asset", "list_files", "diff", "atlas", "raw", "compare", "changelog"]),
         filePath: z.string().optional().describe("relative path in branch"),
         version: z.string().optional(),
@@ -1136,7 +1213,7 @@ function createMcpServer() {
         return out(result);
     }));
     // ── 13. mod_jar ───────────────────────────────────────────────────────────────
-    server.tool("mod_jar", "Mod JAR file access and registry discovery (lang, sounds, atlases, configs, manifests). action=list_files|get_file|lang|sounds|atlas|registry_entries|manifest|list_configs|get_config.", {
+    registerTool("mod_jar", "Mod JAR file access and registry discovery (lang, sounds, atlases, configs, manifests). action=list_files|get_file|lang|sounds|atlas|registry_entries|manifest|list_configs|get_config.", {
         action: z.enum(["list_files", "get_file", "lang", "sounds", "atlas", "registry_entries", "manifest", "list_configs", "get_config"]),
         modId: z.union([z.string(), z.number()]).describe("mod ID or DB id"),
         prefix: z.string().optional(),
@@ -1180,7 +1257,7 @@ function createMcpServer() {
         return out(result);
     }));
     // ── 14. mod_data ─────────────────────────────────────────────────────────────
-    server.tool("mod_data", "Mod JAR structured data — list/get/diff JSON (recipes, loot tables, advancements, blockstates, models, biomes, tags, etc.) or trace a crafting dependency tree. action=list|get|diff|trace_item.", {
+    registerTool("mod_data", "Mod JAR structured data — list/get/diff JSON (recipes, loot tables, advancements, blockstates, models, biomes, tags, etc.) or trace a crafting dependency tree. action=list|get|diff|trace_item.", {
         action: z.enum(["list", "get", "diff", "trace_item"]).describe("list/get: JAR data operations; diff: compare two mod versions; trace_item: recipe chain"),
         type: z.enum(["recipe", "loot_table", "advancement", "blockstate", "model", "biome", "structure", "data_tag", "particle", "damage_type", "enchantment", "configured_feature", "placed_feature", "structure_set", "noise", "density_function", "processor_list", "template_pool", "dimension_type", "dimension", "trim_material", "trim_pattern", "painting_variant", "wolf_variant", "cat_variant", "chat_type"]).describe("Data type to query"),
         modId: z.union([z.string(), z.number()]).optional().describe("mod ID or DB id"),
@@ -1228,7 +1305,7 @@ function createMcpServer() {
         return out(result);
     }));
     // ── 15. mod_tags ──────────────────────────────────────────────────────────────
-    server.tool("mod_tags", "Cross-mod data-pack tag indexing — index, browse, expand, find contributors, and detect replace:true conflicts. action=index|index_all|namespaces|contributors|expand|mod_list|find_conflicts|search.", {
+    registerTool("mod_tags", "Cross-mod data-pack tag indexing — index, browse, expand, find contributors, and detect replace:true conflicts. action=index|index_all|namespaces|contributors|expand|mod_list|find_conflicts|search.", {
         action: z.enum(["index", "index_all", "namespaces", "contributors", "expand", "mod_list", "find_conflicts", "search"]),
         modId: z.union([z.string(), z.number()]).optional().describe("Mod ID string or DB id (index, mod_list)"),
         tagPath: z.string().optional().describe("Tag path to look up contributors or expand (contributors, expand), e.g. 'c:ores/iron', '#forge:storage_blocks'"),
@@ -1267,7 +1344,7 @@ function createMcpServer() {
         return out(result);
     }));
     // ── 16. mixin_scan ────────────────────────────────────────────────────────────
-    server.tool("mixin_scan", "Cross-mod mixin conflict analysis. action=list_mods|conflict_matrix|class_detail|hotspots|batch_resolve.", {
+    registerTool("mixin_scan", "Cross-mod mixin conflict analysis. action=list_mods|conflict_matrix|class_detail|hotspots|batch_resolve.", {
         action: z.enum(["list_mods", "conflict_matrix", "class_detail", "hotspots", "batch_resolve"]),
         loader: z.string().optional().describe("fabric|neoforge|forge|quilt"),
         mcVersion: z.string().optional(),
@@ -1296,7 +1373,7 @@ function createMcpServer() {
         return out(result);
     }));
     // ── 17. gradle ────────────────────────────────────────────────────────────────
-    server.tool("gradle", "Gradle build file analysis — extract deps/plugins, search across mods, compare dependency versions. action=get_files|search|compare_deps.", {
+    registerTool("gradle", "Gradle build file analysis — extract deps/plugins, search across mods, compare dependency versions. action=get_files|search|compare_deps.", {
         action: z.enum(["get_files", "search", "compare_deps"]),
         modId: z.union([z.string(), z.number()]).optional().describe("Mod ID string or DB id (get_files)"),
         query: z.string().optional(),
@@ -1319,13 +1396,13 @@ function createMcpServer() {
         return out(result);
     }));
     // ── 18. reports ───────────────────────────────────────────────────────────────
-    server.tool("project", "Import and query a private Gradle compile environment, including prepared ATs, mappings and loader patches. " +
+    registerTool("project", "Import and query a private Gradle compile environment, including prepared ATs, mappings and loader patches. " +
         "Use this instead of mc_source/mod source or member tools when answering about an imported project. " +
         "Every query requires projectKey and immutable environmentId; no shared vanilla caches are modified. " +
         "Export with scripts/gradle/modlens.init.gradle; use scripts/project-upload.mjs for remote imports. " +
         "action=import_local|upload_begin|upload_chunk|upload_finish|upload_abort|list|info|classes|source|search|members|bytecode. " +
-        "list is restricted to the supplied private key. Search covers provided sources and cached decompiles, not all runtime transformations.", projectToolSchema, safe(async (params) => out(await projectAction(params))));
-    server.tool("reports", "Generate Markdown reports. report=mixin_conflicts|tag_conflicts|version_conflicts|mod_overview|gradle_deps|pack_compat|dep_graph|sidedness|mod_complexity|pack_changelog. savePath to write to disk.", {
+        "list is restricted to the supplied private key. Search covers provided sources and cached decompiles, not all runtime transformations.", projectToolSchema, safe(async (params) => out(await projectAction(params, undefined, principal !== undefined))));
+    registerTool("reports", "Generate Markdown reports. report=mixin_conflicts|tag_conflicts|version_conflicts|mod_overview|gradle_deps|pack_compat|dep_graph|sidedness|mod_complexity|pack_changelog. savePath to write to disk.", {
         report: z.enum(["mixin_conflicts", "tag_conflicts", "version_conflicts", "mod_overview", "gradle_deps", "pack_compat", "dep_graph", "sidedness", "mod_complexity", "pack_changelog"]),
         savePath: z.string().optional().describe("Absolute path to save the .md file, e.g. 'C:/reports/mixin_conflicts.md'"),
         modId: z.union([z.string(), z.number()]).optional(),
@@ -1343,7 +1420,7 @@ function createMcpServer() {
         return out(result.savedTo ? `Saved to: ${result.savedTo}\n\n${result.markdown}` : result.markdown);
     }));
     // ── 20. pack_tools ────────────────────────────────────────────────────────────
-    server.tool("pack_tools", "Modpack-specific analysis tools. " +
+    registerTool("pack_tools", "Modpack-specific analysis tools. " +
         "action=asset_conflicts: find assets/ paths shipped by 2+ mods \u2014 last-loaded mod silently wins, causing visual/audio corruption (assetType, mcVersion, loader, limit). " +
         "action=vanilla_overrides: find mods overriding data/minecraft/ or assets/minecraft/ \u2014 affects vanilla recipes, loot tables, textures (overrideType, dataSubtype, mcVersion, loader). " +
         "action=sidedness: determine whether a single mod is client_only / client_optional / common / server_only (modId). " +
@@ -1404,7 +1481,7 @@ function createMcpServer() {
         return out(result);
     }));
     // ── 21. kubejs ────────────────────────────────────────────────────────────────
-    server.tool("kubejs", "KubeJS script analysis \u2014 index a kubejs/ directory or text-search scripts. action=index|search|semantic_search. semantic_search requires Ollama running.", {
+    registerTool("kubejs", "KubeJS script analysis \u2014 index a kubejs/ directory or text-search scripts. action=index|search|semantic_search. semantic_search requires Ollama running.", {
         action: z.enum(["index", "search", "semantic_search"]),
         scriptsDir: z.string().describe("Absolute path to the kubejs/ folder or a subfolder like kubejs/server_scripts/"),
         query: z.string().optional(),
@@ -1425,14 +1502,14 @@ function createMcpServer() {
         return out(result);
     }));
     // ── 22. analyze_crash_log ────────────────────────────────────────────────────
-    server.tool("analyze_crash_log", "Parse a NeoForge/Forge/Fabric crash log and return suspect mods ranked by stack-frame hits against the indexed class DB.", {
+    registerTool("analyze_crash_log", "Parse a NeoForge/Forge/Fabric crash log and return suspect mods ranked by stack-frame hits against the indexed class DB.", {
         logText: z.string().describe("full crash log text"),
     }, safe(async ({ logText }) => {
         const result = await analyzeCrashLog(logText);
         return out(result);
     }));
     // ── 23. find_missing_deps ────────────────────────────────────────────────────
-    server.tool("find_missing_deps", "Find declared mod dependencies not satisfied by any ingested mod in the DB. Skips loader pseudo-deps (minecraft, neoforge, java, etc.).", {
+    registerTool("find_missing_deps", "Find declared mod dependencies not satisfied by any ingested mod in the DB. Skips loader pseudo-deps (minecraft, neoforge, java, etc.).", {
         mcVersion: z.string().optional(),
         loader: z.string().optional().describe("neoforge|forge|fabric|quilt"),
     }, safe(async ({ mcVersion, loader }) => {
@@ -1440,7 +1517,7 @@ function createMcpServer() {
         return out(result);
     }));
     // ── 24. check_mod_compat ──────────────────────────────────────────────────────
-    server.tool("check_mod_compat", "Pre-flight check a candidate JAR against the DB — mixin conflicts, AT/AW overlaps, asset conflicts, missing deps, sidedness. Does not require prior ingestion.", {
+    registerTool("check_mod_compat", "Pre-flight check a candidate JAR against the DB — mixin conflicts, AT/AW overlaps, asset conflicts, missing deps, sidedness. Does not require prior ingestion.", {
         jarPath: z.string().describe("Absolute path to the candidate mod JAR"),
         mcVersion: z.string().optional(),
         loader: z.string().optional().describe("neoforge|forge|fabric|quilt"),
@@ -1451,8 +1528,11 @@ function createMcpServer() {
     return server;
 }
 // ── Start ─────────────────────────────────────────────────────────────────────
-process.on("SIGINT", async () => { await disconnect(); process.exit(0); });
-process.on("SIGTERM", async () => { await disconnect(); process.exit(0); });
+process.on("SIGINT", async () => { await runtimeHub.close(); await disconnect(); process.exit(0); });
+process.on("SIGTERM", async () => { await runtimeHub.close(); await disconnect(); process.exit(0); });
+// No listener or JVM is started until a project has opted in through setup.
+if (!process.env.MCP_PORT)
+    await runtimeHub.initialize().catch(e => console.error("[modlens] runtime:", String(e)));
 // Transport selection:
 //   • MCP_PORT set  → Streamable HTTP transport (for k8s / remote deployments).
 //   • otherwise     → stdio transport (default, local CLI use).
@@ -1485,8 +1565,15 @@ if (process.env.MODLENS_AUTO_EMBED !== "0") {
 async function startHttpServer(port) {
     const mcpPath = process.env.MCP_PATH ?? "/mcp";
     const host = process.env.MCP_HOST ?? "0.0.0.0";
+    const restricted = process.env.MODLENS_HOSTED_LIMITS !== "0";
+    if (restricted)
+        hostedLimits(); // Reject invalid operator configuration at startup.
+    const proxySecret = process.env.MODLENS_HOSTED_PROXY_SECRET;
+    if (proxySecret && proxySecret.length < 32)
+        throw new Error("MODLENS_HOSTED_PROXY_SECRET must have at least 32 characters");
     // Active sessions keyed by Mcp-Session-Id header.
     const transports = new Map();
+    const sessionOwners = new Map();
     const readBody = (req) => new Promise((resolve, reject) => {
         const chunks = [];
         let size = 0;
@@ -1542,10 +1629,11 @@ async function startHttpServer(port) {
         }
         const sessionId = getHeader(req, "mcp-session-id");
         try {
+            const principal = restricted ? hostedPrincipal(req.headers, proxySecret) : undefined;
             // Existing session — route to its transport.
             if (sessionId) {
                 const transport = transports.get(sessionId);
-                if (!transport) {
+                if (!transport || (restricted && sessionOwners.get(sessionId) !== principal)) {
                     return sendJson(res, 404, {
                         jsonrpc: "2.0",
                         error: { code: -32001, message: "Session not found" },
@@ -1568,13 +1656,19 @@ async function startHttpServer(port) {
                 }
                 const transport = new StreamableHTTPServerTransport({
                     sessionIdGenerator: () => randomUUID(),
-                    onsessioninitialized: (id) => { transports.set(id, transport); },
+                    onsessioninitialized: (id) => {
+                        transports.set(id, transport);
+                        if (principal !== undefined)
+                            sessionOwners.set(id, principal);
+                    },
                 });
                 transport.onclose = () => {
-                    if (transport.sessionId)
+                    if (transport.sessionId) {
                         transports.delete(transport.sessionId);
+                        sessionOwners.delete(transport.sessionId);
+                    }
                 };
-                const server = createMcpServer();
+                const server = createMcpServer(principal);
                 await server.connect(transport);
                 await transport.handleRequest(req, res, body);
                 return;
@@ -1587,6 +1681,8 @@ async function startHttpServer(port) {
         }
         catch (err) {
             if (!res.headersSent) {
+                if (err instanceof HostedPolicyError)
+                    return sendJson(res, 401, { error: err.message });
                 if (err instanceof HttpBodyTooLargeError)
                     return sendJson(res, 413, { error: err.message });
                 if (err instanceof JsonBodyParseError) {