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

package/README.md

@@ -164,12 +164,14 @@ Nested components collapse to their names on purpose — describe those separate
 
 ### `jto_validate`
 
-**In** — `format` (required); document source; `renderer` (validate against this profile instead of the document's own, for this check only); `maxDiagnostics` (1–1000, default 100 — errors are kept ahead of warnings when the cap bites).
+**In** — `format` (required); document source; `renderer` (validate against this profile instead of the document's own, for this check only); `quality` `{profile?, policy?}`; `maxDiagnostics` (1–1000, default 100 — errors are kept ahead of warnings when the cap bites).
 
 **Out** — `valid`, `format`, `renderer` (when one was requested), `source` `{origin, handle?, revision?}`, `counts` `{error, warning, info}` (before any cap), `truncated`.
 
 `ok` mirrors the gate generation applies: schema and semantic errors block it, renderer-profile findings (`W_UNSUPPORTED_RENDERER_FEATURE`) come back as warnings, because the renderer has the last word on those.
 
+Design-quality findings ride the same envelope as `W_QUALITY_*` warnings and infos: an undeclared slide canvas, estimated text overflow, overcrowding, unreadable type, table overflow, or a skipped heading. They carry category, certainty, evidence, suggestion, and optional fixes. They are advisory by default; `quality.policy.gate: "warning"` makes warning-or-higher findings set `ok: false` without turning the tool call into a protocol error.
+
 The gate, not `jto://schema/{format}/document`. The two agree except on component nodes whose props are all optional, where the generated schema asks for a `props: {}` the validator and both renderers treat as omissible; validate follows the renderer, because that is what `jto_generate` runs.
 
 ### `jto_generate`
@@ -229,6 +231,7 @@ The same catalogues, for clients that read resources. URIs are stable.
 | `jto://catalog`              | The resource form of `jto_discover`: every format, in full.               |
 | `jto://renderers`            | Renderer ids per format, which is default, what each profile can draw.    |
 | `jto://themes`               | Built-in theme names per format.                                          |
+| `jto://themes/values`        | What each built-in theme actually is: palette, fonts, style tables.       |
 | `jto://templates`            | Every starter document.                                                   |
 | `jto://schema/docx/document` | Generated JSON Schema for a complete `.docx` document, by renderer.       |
 | `jto://schema/pptx/document` | The same for `.pptx`.                                                     |

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.4.0" : "dev-mode";
+var SERVER_VERSION = true ? "1.5.0" : "dev-mode";
 var SERVER_NAME = "json-to-office";
 var PACKAGE_NAME = "@json-to-office/mcp-server";
 
@@ -221,6 +221,8 @@ var ERROR_CODES = {
   HOST_NOTE: "W_HOST_NOTE",
   /** A generation warning the core raised without a code of its own. */
   GENERATION: "W_GENERATION",
+  /** A design-quality rule threw, so its whole class of findings is missing. */
+  QUALITY_RULE_ERROR: "W_QUALITY_RULE_ERROR",
   /** A required host binary (LibreOffice, poppler) is absent. */
   DEPENDENCY_MISSING: "E_DEPENDENCY_MISSING",
   /** The client cancelled the request. */
@@ -317,6 +319,25 @@ function toolResult(payload) {
   };
 }
 var HOST_DEPENDENCY_ERRORS = /* @__PURE__ */ new Set([RENDERER_DEPENDENCY_MISSING]);
+function qualityOptionDiagnostic(error) {
+  const code = qualityCallerCode(error);
+  if (code === void 0 || code === ERROR_CODES.INVALID_DOCUMENT) {
+    return void 0;
+  }
+  return diagnostic(
+    code,
+    error instanceof Error ? error.message : String(error)
+  );
+}
+function qualityCallerCode(error) {
+  const code = error?.code;
+  if (code === "QUALITY_PROFILE_INCOMPATIBLE")
+    return OPTION_ERROR_CODES.INVALID_QUALITY_PROFILE;
+  if (code === "QUALITY_POLICY_INVALID")
+    return OPTION_ERROR_CODES.INVALID_QUALITY_POLICY;
+  if (code === "QUALITY_GATE_FAILED") return ERROR_CODES.INVALID_DOCUMENT;
+  return void 0;
+}
 function stackAllowed() {
   const flag = process.env.JTO_MCP_DEBUG_STACKS;
   return flag === "1" || flag === "true";
@@ -367,7 +388,7 @@ async function guarded(body) {
     return withHostNotes(result, notes);
   } catch (error) {
     const message2 = error instanceof Error ? error.message : String(error);
-    const code = error instanceof Error && HOST_DEPENDENCY_ERRORS.has(error.name) ? ERROR_CODES.DEPENDENCY_MISSING : ERROR_CODES.INTERNAL;
+    const code = qualityCallerCode(error) ?? (error instanceof Error && HOST_DEPENDENCY_ERRORS.has(error.name) ? ERROR_CODES.DEPENDENCY_MISSING : ERROR_CODES.INTERNAL);
     return withHostNotes(
       failure(code, message2, {
         context: {
@@ -386,7 +407,11 @@ var OPTION_ERROR_CODES = {
   /** `themePath` is not a data-only JSON theme path. */
   INVALID_THEME_PATH: "E_INVALID_THEME_PATH",
   /** The tool does not support the requested format. */
-  UNSUPPORTED_FORMAT: "E_UNSUPPORTED_FORMAT"
+  UNSUPPORTED_FORMAT: "E_UNSUPPORTED_FORMAT",
+  /** `quality.profile` does not cover the format or renderer of this run. */
+  INVALID_QUALITY_PROFILE: "E_INVALID_QUALITY_PROFILE",
+  /** `quality.policy` sets a gate, severity or budget that is not a legal value. */
+  INVALID_QUALITY_POLICY: "E_INVALID_QUALITY_POLICY"
 };
 var DEFERRED_TO_COMPILER = /* @__PURE__ */ new Set([
   ERROR_CODES.UNSUPPORTED_RENDERER_FEATURE
@@ -426,6 +451,34 @@ function validationDiagnostics(errors) {
     })
   );
 }
+function qualityAnalysisDiagnostics(analysis) {
+  return analysis.diagnostics.map((diagnostic2) => ({
+    source: diagnostic2.source,
+    ruleId: diagnostic2.ruleId,
+    category: diagnostic2.category,
+    certainty: diagnostic2.certainty,
+    severity: diagnostic2.severity,
+    code: diagnostic2.code,
+    message: diagnostic2.message,
+    path: diagnostic2.path,
+    blocking: diagnostic2.blocking,
+    ...diagnostic2.suggestion !== void 0 && {
+      suggestion: diagnostic2.suggestion
+    },
+    ...diagnostic2.context !== void 0 && {
+      context: { ...diagnostic2.context }
+    },
+    ...diagnostic2.relatedPaths !== void 0 && {
+      relatedPaths: diagnostic2.relatedPaths
+    },
+    ...diagnostic2.evidence !== void 0 && {
+      evidence: { ...diagnostic2.evidence }
+    },
+    ...diagnostic2.fixes !== void 0 && {
+      fixes: diagnostic2.fixes
+    }
+  }));
+}
 function looksLikeValidationErrors(value) {
   return Array.isArray(value) && value.length > 0 && value.every(
     (entry) => typeof entry === "object" && entry !== null && typeof entry.message === "string"
@@ -1122,10 +1175,10 @@ var STARTERS = [
     id: "pptx-minimal",
     format: "pptx",
     title: "Minimal presentation",
-    description: "The smallest valid .pptx: root, one slide, one title text.",
+    description: "The smallest well-formed .pptx: root with a declared 16:9 canvas, one slide, one title text. The canvas stays: without it the renderer silently falls back to 4:3.",
     document: {
       name: "pptx",
-      props: { title: "Untitled deck" },
+      props: { title: "Untitled deck", slideWidth: 13.333, slideHeight: 7.5 },
       children: [
         {
           name: "slide",
@@ -1982,17 +2035,26 @@ function capDiagnostics(diagnostics, limit) {
   if (diagnostics.length <= limit)
     return { kept: diagnostics, truncated: false };
   const ordered = [...diagnostics].sort(
-    (a, b) => SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity]
+    (a, b) => SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity] || Number(b.blocking === true) - Number(a.blocking === true)
   );
   return { kept: ordered.slice(0, limit), truncated: true };
 }
+function ruleErrorDiagnostics(analysis) {
+  return analysis.ruleErrors.map(
+    (entry) => diagnostic(
+      ERROR_CODES.QUALITY_RULE_ERROR,
+      `Quality rule "${entry.ruleId}" failed: ${entry.message}`,
+      { severity: "warning", source: "quality", ruleId: entry.ruleId }
+    )
+  );
+}
 var DEFAULT_MAX_DIAGNOSTICS = 100;
 function register4(server, deps) {
   server.registerTool(
     "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. 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.",
+      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. `ok` mirrors generation: schema and semantic errors block; design-quality `W_QUALITY_*` findings advise by default and block only when `quality.policy.gate` requests it. A broken document is a normal result with `ok: false`, never a protocol error.",
       annotations: { readOnlyHint: true, openWorldHint: false },
       inputSchema: S({
         type: "object",
@@ -2008,6 +2070,29 @@ function register4(server, deps) {
             minimum: 1,
             maximum: 1e3,
             description: `Cap on returned diagnostics (default ${DEFAULT_MAX_DIAGNOSTICS}). Errors are kept ahead of warnings when the cap bites.`
+          },
+          quality: {
+            type: "object",
+            description: "Optional design profile plus per-run enforcement policy.",
+            properties: {
+              profile: {
+                type: "object",
+                properties: { id: { type: "string", minLength: 1 } },
+                required: ["id"],
+                additionalProperties: true
+              },
+              policy: {
+                type: "object",
+                properties: {
+                  gate: {
+                    type: "string",
+                    enum: ["none", "error", "warning", "info"]
+                  }
+                },
+                additionalProperties: true
+              }
+            },
+            additionalProperties: false
           }
         },
         required: ["format"],
@@ -2038,7 +2123,11 @@ function register4(server, deps) {
           },
           truncated: {
             type: "boolean",
-            description: "`diagnostics` was capped by `maxDiagnostics`."
+            description: "`diagnostics` was capped, by `maxDiagnostics` or by the budget the quality policy set."
+          },
+          profileId: {
+            type: "string",
+            description: "The quality profile the design analysis ran under, when one applied."
           }
         })
       )
@@ -2058,24 +2147,52 @@ function register4(server, deps) {
           resolved.document,
           args.renderer
         );
-        const all = [
+        let analysis;
+        let qualityOption;
+        if (adapter.analyzeQuality) {
+          try {
+            analysis = await adapter.analyzeQuality(resolved.document, {
+              renderer: args.renderer,
+              quality: args.quality
+            });
+          } catch (error) {
+            const option = result.valid ? void 0 : qualityOptionDiagnostic(error);
+            if (!option) throw error;
+            qualityOption = option;
+          }
+        }
+        const structural = [
           ...validationDiagnostics(result.errors),
-          ...unavailable2 ? [unavailable2] : []
+          ...unavailable2 ? [unavailable2] : [],
+          ...qualityOption ? [qualityOption] : []
+        ];
+        const all = [
+          ...structural,
+          ...analysis ? [
+            ...qualityAnalysisDiagnostics(analysis),
+            ...ruleErrorDiagnostics(analysis)
+          ] : []
         ];
         const counts = countDiagnostics(all);
+        const blocked = countDiagnostics(structural).error > 0 || analysis?.blocked === true;
         const { kept, truncated } = capDiagnostics(
           all,
           args.maxDiagnostics ?? DEFAULT_MAX_DIAGNOSTICS
         );
         return {
-          ok: counts.error === 0,
+          ok: !blocked,
           diagnostics: kept,
-          valid: counts.error === 0,
+          valid: !blocked,
           format: args.format,
           ...args.renderer !== void 0 && { renderer: args.renderer },
           source: sourceSummary(resolved),
           counts,
-          truncated
+          // The engine caps its own list under a policy budget, so a report
+          // shortened there would otherwise come back reading complete.
+          truncated: truncated || analysis?.truncated === true,
+          ...analysis?.profileId !== void 0 && {
+            profileId: analysis.profileId
+          }
         };
       })
     )
@@ -5705,6 +5822,7 @@ var RESOURCE_URIS = {
   catalog: "jto://catalog",
   renderers: "jto://renderers",
   themes: "jto://themes",
+  themeValues: "jto://themes/values",
   templates: "jto://templates",
   documentSchema: (format) => `jto://schema/${format}/document`,
   themeSchema: (format) => `jto://schema/${format}/theme`
@@ -5756,7 +5874,7 @@ function register9(server, deps) {
     RESOURCE_URIS.themes,
     {
       title: "Built-in themes",
-      description: "Theme names shipped with each format, usable as a document\u2019s props.theme or as the tools\u2019 theme option.",
+      description: "Theme names shipped with each format, usable as a document\u2019s props.theme or as the tools\u2019 theme option. jto://themes/values carries what each name actually looks like.",
       mimeType: JSON_MIME
     },
     async (uri) => {
@@ -5769,6 +5887,33 @@ function register9(server, deps) {
       });
     }
   );
+  server.registerResource(
+    "theme-values",
+    RESOURCE_URIS.themeValues,
+    {
+      title: "Built-in theme values",
+      description: "The palette, fonts, style tables and component defaults behind every built-in theme name \u2014 what a document actually opts into with props.theme. A name alone cannot tell you whether a theme fits the brief; this can.",
+      mimeType: JSON_MIME
+    },
+    async (uri) => {
+      const formats = await Promise.all(
+        FORMAT_NAMES.map(async (format) => {
+          const adapter = deps.getAdapter(format);
+          let themes;
+          try {
+            themes = adapter.getBuiltinThemeValues ? await adapter.getBuiltinThemeValues() : adapter.getBuiltinThemes();
+          } catch {
+            themes = adapter.getBuiltinThemes();
+          }
+          return {
+            format,
+            themes
+          };
+        })
+      );
+      return jsonContents(uri, { formats });
+    }
+  );
   server.registerResource(
     "templates",
     RESOURCE_URIS.templates,
@@ -5817,6 +5962,7 @@ Working rules:
 - Discover before authoring. Call jto_info first, then jto_discover and jto_describe_component (or read the jto:// resources) for the components and renderer ids a format actually supports.
 - Make small edits. With a workspace handle, patch precisely (RFC 6902 over RFC 6901 paths) instead of resending the whole document; without one, change one region at a time.
 - Validate often. Run jto_validate after each edit rather than once at the end; diagnostics are path-addressed, so they map straight back onto the JSON you just changed.
+- Treat design findings as defects. Schema-valid is not well-designed: jto_validate also lints layout and legibility (W_QUALITY_* \u2014 undeclared slide canvas, text overflowing its box, overcrowded slides, table widths exceeding their section). These never block generation, but they almost always show in the rendered result \u2014 repair them like errors.
 - Preview when the answer is visual. jto_preview renders pages to PNG; use it whenever layout, overflow or fit is in question, not only before finishing.
 - Snapshot before risky changes. jto_workspace_snapshot pins the current revision so a restructuring you cannot cleanly undo is still recoverable.