@json-to-office/mcp-server 1.2.0 → 1.4.0

package/dist/cli.js

@@ -7,7 +7,7 @@ import { serveStdio } from "@modelcontextprotocol/server/stdio";
 import { McpServer } from "@modelcontextprotocol/server";
 
 // src/lib/version.ts
-var SERVER_VERSION = true ? "1.2.0" : "dev-mode";
+var SERVER_VERSION = true ? "1.4.0" : "dev-mode";
 var SERVER_NAME = "json-to-office";
 var PACKAGE_NAME = "@json-to-office/mcp-server";
 
@@ -170,6 +170,9 @@ function outputSchema(properties, required = []) {
 import {
   runWithDiagnosticSink
 } from "@json-to-office/jto-ops";
+import {
+  RENDERER_DEPENDENCY_MISSING
+} from "@json-to-office/shared";
 import { ValueErrorType } from "@sinclair/typebox/errors";
 var ERROR_CODES = {
   /** An exception escaped a tool handler. Always a bug here, never the caller's. */
@@ -313,7 +316,11 @@ function toolResult(payload) {
     structuredContent: payload
   };
 }
-var HOST_DEPENDENCY_ERRORS = /* @__PURE__ */ new Set(["RendererDependencyMissingError"]);
+var HOST_DEPENDENCY_ERRORS = /* @__PURE__ */ new Set([RENDERER_DEPENDENCY_MISSING]);
+function stackAllowed() {
+  const flag = process.env.JTO_MCP_DEBUG_STACKS;
+  return flag === "1" || flag === "true";
+}
 function hostNote(text, tone = "muted") {
   return {
     // Never `error`. The body has already decided `ok` by the time a note
@@ -364,7 +371,7 @@ async function guarded(body) {
     return withHostNotes(
       failure(code, message2, {
         context: {
-          ...error instanceof Error && error.stack !== void 0 && { stack: error.stack }
+          ...stackAllowed() && error instanceof Error && error.stack !== void 0 && { stack: error.stack }
         }
       }),
       notes
@@ -607,7 +614,7 @@ function register(server, deps) {
     "jto_info",
     {
       title: "Server info",
-      description: "Versions, supported formats and renderer ids, workspace availability, output-root and size limits, and whether the optional host dependencies (LibreOffice and poppler for jto_preview, a Highcharts export server for the DOCX `highcharts` component) are present on this host. Call this first.",
+      description: "Versions, supported formats with each renderer and whether its backend loads here, workspace availability, output-root and size limits, and whether the optional host dependencies (LibreOffice and poppler for jto_preview, a Highcharts export server for the DOCX `highcharts` component) are present on this host. Call this first.",
       annotations: { readOnlyHint: true, openWorldHint: false },
       inputSchema: S({
         type: "object",
@@ -659,10 +666,32 @@ function register(server, deps) {
                   rendererIds: {
                     type: "array",
                     items: { type: "string" },
-                    description: "Defaults first."
+                    description: "Defaults first. Registered, which is not the same as usable \u2014 read `renderers` before picking one."
+                  },
+                  renderers: {
+                    type: "array",
+                    description: "Every registered renderer with whether its backend loads on this host. A renderer with `available: false` will fail every render until `installHint` is run.",
+                    items: {
+                      type: "object",
+                      properties: {
+                        id: { type: "string" },
+                        default: { type: "boolean" },
+                        available: { type: "boolean" },
+                        reason: { type: "string" },
+                        installHint: { type: "string" }
+                      },
+                      required: ["id", "default", "available"],
+                      additionalProperties: false
+                    }
                   }
                 },
-                required: ["name", "extension", "label", "rendererIds"],
+                required: [
+                  "name",
+                  "extension",
+                  "label",
+                  "rendererIds",
+                  "renderers"
+                ],
                 additionalProperties: false
               }
             },
@@ -718,9 +747,21 @@ function register(server, deps) {
         const formats = await Promise.all(
           FORMAT_NAMES.map(async (name) => {
             const adapter = deps.getAdapter(name);
-            let rendererIds = [];
+            let renderers = [];
             try {
-              rendererIds = [...await adapter.rendererIds()];
+              renderers = (await adapter.rendererStatuses()).map(
+                (status) => ({
+                  id: status.id,
+                  default: status.default,
+                  available: status.available,
+                  ...status.reason !== void 0 && {
+                    reason: status.reason
+                  },
+                  ...status.installHint !== void 0 && {
+                    installHint: status.installHint
+                  }
+                })
+              );
             } catch (error) {
               diagnostics.push(
                 diagnostic(
@@ -730,11 +771,32 @@ function register(server, deps) {
                 )
               );
             }
+            for (const renderer of renderers) {
+              if (renderer.available) continue;
+              diagnostics.push(
+                diagnostic(
+                  ERROR_CODES.DEPENDENCY_MISSING,
+                  `The "${renderer.id}" ${name} renderer is registered but cannot load on this host, so every render through it will fail.`,
+                  {
+                    severity: "warning",
+                    ...renderer.installHint && {
+                      suggestion: `Install its backend: ${renderer.installHint}. Until then use one of: ${renderers.filter((entry) => entry.available).map((entry) => `"${entry.id}"`).join(", ")}.`
+                    },
+                    context: {
+                      format: name,
+                      renderer: renderer.id,
+                      ...renderer.reason && { reason: renderer.reason }
+                    }
+                  }
+                )
+              );
+            }
             return {
               name: adapter.name,
               extension: adapter.extension,
               label: adapter.label,
-              rendererIds
+              rendererIds: renderers.map((renderer) => renderer.id),
+              renderers
             };
           })
         );
@@ -1122,8 +1184,16 @@ async function catalogFormat(format, deps, diagnostics) {
   const schemas = formatSchemas(format);
   const adapter = deps.getAdapter(format);
   let rendererIds = [];
+  const availability = /* @__PURE__ */ new Map();
+  const installHints = /* @__PURE__ */ new Map();
+  let probed = false;
   try {
-    rendererIds = [...await adapter.rendererIds()];
+    for (const status of await adapter.rendererStatuses()) {
+      rendererIds.push(status.id);
+      availability.set(status.id, status.available);
+      if (status.installHint) installHints.set(status.id, status.installHint);
+    }
+    probed = true;
   } catch (error) {
     diagnostics.push(
       diagnostic(
@@ -1239,6 +1309,14 @@ async function catalogFormat(format, deps, diagnostics) {
     renderers: orderedIds.map((id, index) => ({
       id,
       default: index === 0,
+      // Three cases, and they are not the same. A probed renderer answers for
+      // itself. A profile the cores never registered has no status but is
+      // already reported as drift above, so calling it unavailable would be a
+      // second, worse description of that. And a probe that threw knows
+      // nothing about any of them — reporting those as usable would contradict
+      // the diagnostic pushed beside them.
+      available: availability.get(id) ?? probed,
+      ...installHints.has(id) && { installHint: installHints.get(id) },
       components: [...byRenderer.get(id)?.components.keys() ?? []].sort(),
       unsupported: allNames.filter((name) => !byRenderer.get(id)?.components.has(name)).sort()
     })),
@@ -1308,6 +1386,14 @@ function register2(server, deps) {
                       properties: {
                         id: { type: "string" },
                         default: { type: "boolean" },
+                        available: {
+                          type: "boolean",
+                          description: "Whether this renderer's backend loads on this host. A renderer that is registered but unavailable accepts the components below and then fails every render."
+                        },
+                        installHint: {
+                          type: "string",
+                          description: "The command that would make an unavailable renderer available."
+                        },
                         components: {
                           type: "array",
                           items: { type: "string" }
@@ -1318,7 +1404,13 @@ function register2(server, deps) {
                           description: "Components another renderer of this format accepts and this one does not."
                         }
                       },
-                      required: ["id", "default", "components", "unsupported"],
+                      required: [
+                        "id",
+                        "default",
+                        "available",
+                        "components",
+                        "unsupported"
+                      ],
                       additionalProperties: false
                     }
                   },
@@ -1758,6 +1850,39 @@ function withRenderer(document, renderer) {
   }
   return { ...document, renderer };
 }
+function effectiveRenderer(document, override2) {
+  if (override2 !== void 0) return override2;
+  if (typeof document === "object" && document !== null) {
+    const declared = document.renderer;
+    if (typeof declared === "string") return declared;
+  }
+  return void 0;
+}
+async function rendererAvailability(adapter, document, override2) {
+  const wanted = effectiveRenderer(document, override2);
+  let statuses;
+  try {
+    statuses = await adapter.rendererStatuses();
+  } catch {
+    return void 0;
+  }
+  const status = wanted ? statuses.find((entry) => entry.id === wanted) : statuses.find((entry) => entry.default);
+  if (!status || status.available) return void 0;
+  const usable = statuses.filter((entry) => entry.available).map((entry) => `"${entry.id}"`);
+  return diagnostic(
+    ERROR_CODES.DEPENDENCY_MISSING,
+    `This document validates against the "${status.id}" ${adapter.name} renderer, but that renderer cannot load on this host \u2014 generating with it will fail.`,
+    {
+      severity: "warning",
+      suggestion: status.installHint ? `Install its backend: ${status.installHint}.${usable.length > 0 ? ` Or render with ${usable.join(" or ")}.` : ""}` : `Render with ${usable.join(" or ")} instead.`,
+      context: {
+        format: adapter.name,
+        renderer: status.id,
+        ...status.reason && { reason: status.reason }
+      }
+    }
+  );
+}
 
 // src/lib/workspace-store.ts
 var unavailable = () => failure(
@@ -1867,7 +1992,7 @@ function register4(server, deps) {
     "jto_validate",
     {
       title: "Validate a document",
-      description: "Check a document against its format schema and report every defect as a path-addressed diagnostic. Paths are RFC 6901 JSON Pointers into the document you passed, so they can be used directly as patch targets; codes are the stable `E_`/`W_` vocabulary, e.g. `E_REQUIRED_PROPERTY`, `E_UNEXPECTED_PROPERTY`, `E_TYPE_MISMATCH`, `E_UNKNOWN_COMPONENT`. `ok` mirrors the gate generation applies: schema and semantic errors block it \u2014 the semantic rules the published JSON Schema cannot state, such as a text component needing one of `text`/`runs`, are checked here and only here \u2014 while renderer-profile findings (code `W_UNSUPPORTED_RENDERER_FEATURE`) come back as warnings because the renderer, not the schema, has the last word on those. A broken document is a normal result with `ok: false`, never an error.",
+      description: "Check a document against its format schema and report every defect as a path-addressed diagnostic. Paths are RFC 6901 JSON Pointers into the document you passed, so they can be used directly as patch targets; codes are the stable `E_`/`W_` vocabulary, e.g. `E_REQUIRED_PROPERTY`, `E_UNEXPECTED_PROPERTY`, `E_TYPE_MISMATCH`, `E_UNKNOWN_COMPONENT`. `ok` mirrors the gate generation applies: schema and semantic errors block it \u2014 the semantic rules the published JSON Schema cannot state, such as a text component needing one of `text`/`runs`, are checked here and only here \u2014 while renderer-profile findings (code `W_UNSUPPORTED_RENDERER_FEATURE`) come back as warnings because the renderer, not the schema, has the last word on those. A broken document is a normal result with `ok: false`, never an error. A renderer whose backend is not installed on this host is reported here too, as a `E_DEPENDENCY_MISSING` warning \u2014 the document may be fine and the host merely incomplete.",
       annotations: { readOnlyHint: true, openWorldHint: false },
       inputSchema: S({
         type: "object",
@@ -1928,7 +2053,15 @@ function register4(server, deps) {
         const result = adapter.validateDocument(
           withRenderer(resolved.document, args.renderer)
         );
-        const all = validationDiagnostics(result.errors);
+        const unavailable2 = await rendererAvailability(
+          adapter,
+          resolved.document,
+          args.renderer
+        );
+        const all = [
+          ...validationDiagnostics(result.errors),
+          ...unavailable2 ? [unavailable2] : []
+        ];
         const counts = countDiagnostics(all);
         const { kept, truncated } = capDiagnostics(
           all,
@@ -2818,6 +2951,9 @@ import crypto2 from "crypto";
 import { promises as fs6 } from "fs";
 import os2 from "os";
 import path5 from "path";
+import {
+  RENDERER_DEPENDENCY_MISSING as RENDERER_DEPENDENCY_MISSING2
+} from "@json-to-office/shared";
 import { getFontStager } from "@json-to-office/jto-ops";
 
 // src/preview/cache-key.ts
@@ -3149,6 +3285,15 @@ function renderFailure(stage, detail, context = {}) {
     { suggestion, context: { stage, ...context } }
   );
 }
+function buildFailure(error) {
+  if (error instanceof Error && error.name === RENDERER_DEPENDENCY_MISSING2) {
+    return failure(ERROR_CODES.DEPENDENCY_MISSING, message(error), {
+      suggestion: "Install the renderer's backend, or re-run with a renderer jto_info reports as available. The document is not at fault.",
+      context: { stage: "build" }
+    });
+  }
+  return renderFailure("build", message(error));
+}
 var PNG_SIGNATURE = Buffer.from([
   137,
   80,
@@ -3355,9 +3500,10 @@ async function renderPreview(options) {
     converters = versions;
   } catch (error) {
     if (signal?.aborted) return cancelled2();
+    const build = buildFailure(error);
     return failureFrom([
-      ...validationDiagnostics2(options.getAdapter(format), document),
-      ...renderFailure("build", message(error)).diagnostics
+      ...build.diagnostics[0]?.code === ERROR_CODES.DEPENDENCY_MISSING ? [] : validationDiagnostics2(options.getAdapter(format), document),
+      ...build.diagnostics
     ]);
   }
   const generateMs = elapsed(generateStarted);