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

package/dist/index.d.ts

@@ -2,6 +2,7 @@ import { McpServer, McpServerFactory, JsonSchemaType, StandardSchemaWithJSON } f
 import { FormatAdapter, FormatName } from '@json-to-office/jto-ops';
 export { FormatAdapter, FormatName } from '@json-to-office/jto-ops';
 import { ValidationError } from '@json-to-office/shared';
+import { QualityCategory, QualityCertainty, QualityEvidence, JsonPatchOperation as JsonPatchOperation$1 } from '@json-to-office/quality';
 
 /**
  * Structured results, not protocol errors.
@@ -32,6 +33,14 @@ interface Diagnostic {
     suggestion?: string;
     /** Free-form extras (offending value, component name, renderer id, …). */
     context?: Record<string, unknown>;
+    source?: 'schema' | 'semantic' | 'renderer' | 'quality';
+    ruleId?: string;
+    category?: QualityCategory;
+    certainty?: QualityCertainty;
+    relatedPaths?: readonly string[];
+    evidence?: QualityEvidence;
+    fixes?: readonly JsonPatchOperation$1[];
+    blocking?: boolean;
 }
 /**
  * The envelope every tool's `structuredContent` starts from.
@@ -100,6 +109,8 @@ declare const ERROR_CODES: {
     readonly HOST_NOTE: "W_HOST_NOTE";
     /** A generation warning the core raised without a code of its own. */
     readonly GENERATION: "W_GENERATION";
+    /** A design-quality rule threw, so its whole class of findings is missing. */
+    readonly QUALITY_RULE_ERROR: "W_QUALITY_RULE_ERROR";
     /** A required host binary (LibreOffice, poppler) is absent. */
     readonly DEPENDENCY_MISSING: "E_DEPENDENCY_MISSING";
     /** The client cancelled the request. */
@@ -177,6 +188,10 @@ declare const OPTION_ERROR_CODES: {
     readonly INVALID_THEME_PATH: "E_INVALID_THEME_PATH";
     /** The tool does not support the requested format. */
     readonly UNSUPPORTED_FORMAT: "E_UNSUPPORTED_FORMAT";
+    /** `quality.profile` does not cover the format or renderer of this run. */
+    readonly INVALID_QUALITY_PROFILE: "E_INVALID_QUALITY_PROFILE";
+    /** `quality.policy` sets a gate, severity or budget that is not a legal value. */
+    readonly INVALID_QUALITY_POLICY: "E_INVALID_QUALITY_POLICY";
 };
 /**
  * Normalize a validator path to an RFC 6901 JSON Pointer.
@@ -492,7 +507,7 @@ declare function createToolDeps(options?: CreateToolDepsOptions): ToolDeps;
  * lose more than they fix, and that looking at a rendered page is cheaper than
  * reasoning about whether a layout worked (#271).
  */
-declare const SERVER_INSTRUCTIONS = "Author Microsoft Word (.docx) and PowerPoint (.pptx) documents as JSON.\n\nThe JSON is authoritative. A generated file is a build product of the document JSON plus a renderer, a theme, fonts, assets and options \u2014 edit the JSON and regenerate; never treat the binary as the source.\n\nWorking rules:\n- 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.\n- 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.\n- 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.\n- 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.\n- Snapshot before risky changes. jto_workspace_snapshot pins the current revision so a restructuring you cannot cleanly undo is still recoverable.\n\nDocument defects come back as structured diagnostics with ok: false, not as errors \u2014 read them and repair. Generated files are written under the server's output root and returned as paths; ask for base64 only for small artifacts.";
+declare const SERVER_INSTRUCTIONS = "Author Microsoft Word (.docx) and PowerPoint (.pptx) documents as JSON.\n\nThe JSON is authoritative. A generated file is a build product of the document JSON plus a renderer, a theme, fonts, assets and options \u2014 edit the JSON and regenerate; never treat the binary as the source.\n\nWorking rules:\n- 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.\n- 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.\n- 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.\n- 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.\n- 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.\n- Snapshot before risky changes. jto_workspace_snapshot pins the current revision so a restructuring you cannot cleanly undo is still recoverable.\n\nDocument defects come back as structured diagnostics with ok: false, not as errors \u2014 read them and repair. Generated files are written under the server's output root and returned as paths; ask for base64 only for small artifacts.";
 /** Build a server with every tool and resource registered. */
 declare function createServer(deps: ToolDeps): McpServer;
 /**

package/dist/index.js

@@ -2,7 +2,7 @@
 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";
 
@@ -216,6 +216,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. */
@@ -312,6 +314,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";
@@ -362,7 +383,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: {
@@ -381,7 +402,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
@@ -421,6 +446,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"
@@ -1117,10 +1170,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",
@@ -1994,17 +2047,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",
@@ -2020,6 +2082,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"],
@@ -2050,7 +2135,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."
           }
         })
       )
@@ -2070,24 +2159,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
+          }
         };
       })
     )
@@ -5717,6 +5834,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`
@@ -5768,7 +5886,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) => {
@@ -5781,6 +5899,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,
@@ -5829,6 +5974,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.