@malloy-publisher/server 0.0.227 → 0.0.229

package/src/mcp/skills/skills_bundle.spec.ts

@@ -1,4 +1,6 @@
 import { describe, expect, it } from "bun:test";
+import * as path from "node:path";
+import { buildSkills, type SkillEntry } from "./build_skills_bundle";
 import bundle from "./skills_bundle.json";
 
 const skills = (
@@ -7,9 +9,36 @@ const skills = (
    }
 ).skills;
 
+/** The repo's top-level skills/, which this bundle is generated from. */
+const sourceDir = path.join(
+   import.meta.dir,
+   "..",
+   "..",
+   "..",
+   "..",
+   "..",
+   "skills",
+);
+
+/**
+ * Codepoint order. The committed bundle is sorted with localeCompare, which
+ * depends on the runtime's locale, and this suite runs on three platforms.
+ * Membership and content are what matter here; file order is cosmetic.
+ */
+const byName = (a: SkillEntry, b: SkillEntry) =>
+   a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
+
 describe("skills_bundle.json (generated dual-channel asset)", () => {
-   it("contains the full ported skill set", () => {
-      expect(skills.length).toBeGreaterThanOrEqual(24);
+   it("is in sync with skills/", () => {
+      // Regenerate with:
+      //   bun run src/mcp/skills/build_skills_bundle.ts ../../skills
+      expect([...skills].sort(byName)).toEqual(
+         [...buildSkills(sourceDir)].sort(byName),
+      );
+   });
+
+   it("is not empty", () => {
+      expect(skills.length).toBeGreaterThan(0);
    });
 
    it("every skill has a nonempty name, description, and body", () => {

package/src/mcp/tools/compile_tool.spec.ts

@@ -0,0 +1,207 @@
+import { describe, expect, it } from "bun:test";
+import { registerCompileTool } from "./compile_tool";
+import type { EnvironmentStore } from "../../service/environment_store";
+import { PackageNotFoundError, ServiceUnavailableError } from "../../errors";
+
+// Capture the handler registerCompileTool passes to McpServer.tool, so it can
+// be exercised against a mocked EnvironmentStore. The tool builds a
+// CompileController internally, which calls environment.compileSource, so the
+// mock only needs getEnvironment -> { compileSource }.
+type Handler = (params: Record<string, unknown>) => Promise<{
+   isError?: boolean;
+   content: Array<{ resource: { text: string } }>;
+}>;
+
+function captureHandler(store: Partial<EnvironmentStore>): Handler {
+   let handler: Handler | undefined;
+   const fakeServer = {
+      tool: (_name: string, _desc: string, _shape: unknown, h: Handler) => {
+         handler = h;
+      },
+   };
+   registerCompileTool(fakeServer as never, store as EnvironmentStore);
+   if (!handler) throw new Error("handler was not registered");
+   return handler;
+}
+
+function parse(result: { content: Array<{ resource: { text: string } }> }) {
+   return JSON.parse(result.content[0].resource.text);
+}
+
+function storeReturning(
+   problems: Array<Record<string, unknown>>,
+   sql?: string,
+): Partial<EnvironmentStore> {
+   return {
+      getEnvironment: async () =>
+         ({
+            compileSource: async () => ({ problems, sql }),
+         }) as never,
+   };
+}
+
+const args = {
+   environmentName: "malloy-samples",
+   packageName: "ecommerce",
+   modelPath: "ecommerce.malloy",
+   source: "run: order_items -> { aggregate: c is count() }",
+};
+
+describe("malloy_compile tool", () => {
+   it("returns status success and empty diagnostics for a clean compile", async () => {
+      const handler = captureHandler(storeReturning([]));
+      const result = await handler(args);
+      expect(result.isError).toBe(false);
+      expect(parse(result)).toEqual({ status: "success", diagnostics: [] });
+   });
+
+   it("flattens an error diagnostic and sets isError", async () => {
+      const handler = captureHandler(
+         storeReturning([
+            {
+               severity: "error",
+               message: "'nope' is not defined",
+               code: "field-not-found",
+               at: {
+                  range: {
+                     start: { line: 2, character: 3 },
+                     end: { line: 2, character: 7 },
+                  },
+               },
+               replacement: undefined,
+            },
+         ]),
+      );
+      const result = await handler(args);
+      expect(result.isError).toBe(true);
+      const parsed = parse(result);
+      expect(parsed.status).toBe("error");
+      expect(parsed.diagnostics).toEqual([
+         {
+            severity: "error",
+            message: "'nope' is not defined",
+            code: "field-not-found",
+            line: 2,
+            character: 3,
+            endLine: 2,
+            endCharacter: 7,
+         },
+      ]);
+   });
+
+   it("treats a warning as a clean compile (status success, isError false)", async () => {
+      const handler = captureHandler(
+         storeReturning([
+            {
+               severity: "warn",
+               message: "deprecated syntax",
+               code: "deprecated",
+               at: {
+                  range: {
+                     start: { line: 0, character: 0 },
+                     end: { line: 0, character: 4 },
+                  },
+               },
+            },
+         ]),
+      );
+      const result = await handler(args);
+      expect(result.isError).toBe(false);
+      const parsed = parse(result);
+      expect(parsed.status).toBe("success");
+      expect(parsed.diagnostics[0].severity).toBe("warn");
+   });
+
+   it("includes sql when the controller returns it", async () => {
+      const handler = captureHandler(storeReturning([], "SELECT 1"));
+      const parsed = parse(await handler({ ...args, includeSql: true }));
+      expect(parsed.sql).toBe("SELECT 1");
+   });
+
+   it("surfaces a thrown error as a tool error, not a transport fault", async () => {
+      const handler = captureHandler({
+         getEnvironment: async () => {
+            throw new Error("Environment 'nope' could not be resolved");
+         },
+      });
+      const result = await handler({ ...args, environmentName: "nope" });
+      expect(result.isError).toBe(true);
+      const parsed = parse(result);
+      expect(parsed.error).toBeDefined();
+   });
+
+   it("reports a missing package as not-found, not as a Malloy syntax problem", async () => {
+      // Pin the remediation text, not just that an error came back. Asserting
+      // only that `error` is defined passes even when every class funnels
+      // through the Malloy helper, which is the bug classifyToolError exists to
+      // fix: a typo'd package name told the caller to check its Malloy syntax.
+      const handler = captureHandler({
+         getEnvironment: async () => {
+            throw new PackageNotFoundError("Package 'nope' not found");
+         },
+      });
+      const parsed = parse(await handler({ ...args, packageName: "nope" }));
+      expect(parsed.error).toContain("Resource not found");
+      expect(JSON.stringify(parsed.suggestions)).not.toContain("Malloy file");
+   });
+
+   it("reports back-pressure as retryable, not as a Malloy syntax problem", async () => {
+      const handler = captureHandler({
+         getEnvironment: async () => {
+            throw new ServiceUnavailableError("Memory limit reached");
+         },
+      });
+      const parsed = parse(await handler(args));
+      expect(parsed.error).toContain("Memory limit reached");
+      expect(JSON.stringify(parsed.suggestions)).toContain("Retry");
+      expect(JSON.stringify(parsed.suggestions)).not.toContain("Malloy file");
+   });
+
+   it("reports an unexpected internal error without blaming the Malloy", async () => {
+      // The catch-all used to hand a TypeError to the Malloy helper, so a bug
+      // in our own code told the agent to go edit a model that was fine.
+      const handler = captureHandler({
+         getEnvironment: async () => {
+            throw new TypeError("cannot read properties of undefined");
+         },
+      });
+      const parsed = parse(await handler(args));
+      expect(parsed.error).toContain("unexpected internal error");
+      expect(JSON.stringify(parsed.suggestions)).not.toContain("Malloy file");
+   });
+
+   it("omits position fields when a diagnostic has no location", async () => {
+      const handler = captureHandler(
+         storeReturning([
+            { severity: "error", message: "no location", code: "syntax" },
+         ]),
+      );
+      const parsed = parse(await handler(args));
+      expect(parsed.diagnostics[0]).toEqual({
+         severity: "error",
+         message: "no location",
+         code: "syntax",
+      });
+   });
+
+   it("forwards givens to compileSource", async () => {
+      let captured: unknown;
+      const handler = captureHandler({
+         getEnvironment: async () =>
+            ({
+               compileSource: async (
+                  _pkg: string,
+                  _model: string,
+                  _source: string,
+                  _includeSql: boolean,
+                  givens: unknown,
+               ) => {
+                  captured = givens;
+                  return { problems: [] };
+               },
+            }) as never,
+      });
+      await handler({ ...args, givens: { region: "west" } });
+      expect(captured).toEqual({ region: "west" });
+   });
+});

package/src/mcp/tools/compile_tool.ts

@@ -0,0 +1,177 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { GivenValue } from "@malloydata/malloy";
+import { logger } from "../../logger";
+import { EnvironmentStore } from "../../service/environment_store";
+import { CompileController } from "../../controller/compile.controller";
+import { type ErrorDetails } from "../error_messages";
+import { buildMalloyUri, classifyToolError } from "../handler_utils";
+
+// Zod shape for malloy_compile. environmentName/packageName mirror the other
+// tools and point the agent at malloy_getContext for name discovery.
+const compileShape = {
+   environmentName: z
+      .string()
+      .describe(
+         "Environment name. Call malloy_getContext with no arguments to list the available environments.",
+      ),
+   packageName: z
+      .string()
+      .describe(
+         "Package containing the model. Call malloy_getContext with just environmentName to list its packages.",
+      ),
+   modelPath: z
+      .string()
+      .describe(
+         "Path to the .malloy model whose namespace the source compiles against. The source is appended to this model, so its imports, sources, and queries are in scope.",
+      ),
+   source: z
+      .string()
+      .describe(
+         "The Malloy source to validate. Compiled in the context of modelPath and not executed.",
+      ),
+   includeSql: z
+      .boolean()
+      .optional()
+      .describe(
+         "When true and the source ends in a runnable query, also return the generated SQL for inspection. The query is still not run.",
+      ),
+   givens: z
+      .record(z.unknown())
+      .optional()
+      .describe(
+         "Given values for the model's given: block. Also required to satisfy any #(authorize) gate on the target model, whether or not includeSql is set.",
+      ),
+};
+
+const COMPILE_DESCRIPTION = `Compile-check Malloy source against a model and return structured diagnostics WITHOUT running a query. Use this to validate a model or a change while authoring, instead of firing a throwaway malloy_executeQuery just to see whether it parses.
+
+## Parameters
+- environmentName, packageName, modelPath (required): the model whose namespace the source compiles against. The source is appended to that model, so its imports, sources, and queries are in scope, and modelPath is real context, not a label.
+- source (required): the Malloy text to validate.
+- includeSql (optional): also return the generated SQL when the source ends in a runnable query. The query is still not executed and no data is scanned.
+
+## Response
+A JSON object with status ("success" or "error") and diagnostics: an array of { severity ("error" / "warn" / "debug"), message, code, line, character, endLine, endCharacter, replacement }. Positions are 0-based (line and character start at 0) and relative to the model file with your source appended to it, so a diagnostic in your submitted source lands after the model's own line count, and a diagnostic may point at pre-existing content in the model rather than at your source. A clean compile can still return warnings; status is "error" only when at least one diagnostic has error severity.`;
+
+/**
+ * Registers the malloy_compile MCP tool: validates Malloy source against a model
+ * and returns structured diagnostics without executing a query. Wraps the same
+ * in-process compile path the REST /compile endpoint uses (CompileController).
+ */
+export function registerCompileTool(
+   mcpServer: McpServer,
+   environmentStore: EnvironmentStore,
+): void {
+   const compileController = new CompileController(environmentStore);
+
+   mcpServer.tool(
+      "malloy_compile",
+      COMPILE_DESCRIPTION,
+      compileShape,
+      async (params) => {
+         const {
+            environmentName,
+            packageName,
+            modelPath,
+            source,
+            includeSql,
+            givens,
+         } = params;
+
+         logger.info("[MCP Tool compile] Compiling source", {
+            environmentName,
+            packageName,
+            modelPath,
+            includeSql: !!includeSql,
+         });
+
+         const uri = buildMalloyUri(
+            {
+               environment: environmentName,
+               package: packageName,
+               resourceType: "models",
+               resourceName: modelPath,
+            },
+            "compile",
+         );
+
+         try {
+            const result = await compileController.compile(
+               environmentName,
+               packageName,
+               modelPath,
+               source,
+               includeSql ?? false,
+               givens as Record<string, GivenValue> | undefined,
+            );
+
+            // Flatten each LogMessage's nested at.range into line/character so
+            // agents do not have to walk it. Positions are 0-based (LSP-style).
+            const diagnostics = result.problems.map((p) => ({
+               severity: p.severity,
+               message: p.message,
+               code: p.code,
+               line: p.at?.range.start.line,
+               character: p.at?.range.start.character,
+               endLine: p.at?.range.end.line,
+               endCharacter: p.at?.range.end.character,
+               replacement: p.replacement,
+            }));
+
+            const payload = {
+               status: result.status,
+               diagnostics,
+               ...(result.sql !== undefined && { sql: result.sql }),
+            };
+
+            return {
+               isError: result.status === "error",
+               content: [
+                  {
+                     type: "resource" as const,
+                     resource: {
+                        type: "application/json",
+                        uri,
+                        text: JSON.stringify(payload),
+                     },
+                  },
+               ],
+            };
+         } catch (error) {
+            // Unknown environment/package, a notebook (.malloynb) rejected up
+            // front, an authorize denial, or a system error: surface as a clean
+            // isError payload rather than a transport fault. A missing modelPath
+            // does NOT error here; compileSource compiles the source against an
+            // empty namespace, so a typo in modelPath yields a normal result.
+            logger.warn("[MCP Tool compile] compile failed", {
+               environmentName,
+               packageName,
+               modelPath,
+               error: error instanceof Error ? error.message : String(error),
+            });
+            const errorDetails: ErrorDetails = classifyToolError(
+               "compile",
+               `${environmentName}/${packageName}/${modelPath}`,
+               error,
+            );
+            return {
+               isError: true,
+               content: [
+                  {
+                     type: "resource" as const,
+                     resource: {
+                        type: "application/json",
+                        uri,
+                        text: JSON.stringify({
+                           error: errorDetails.message,
+                           suggestions: errorDetails.suggestions,
+                        }),
+                     },
+                  },
+               ],
+            };
+         }
+      },
+   );
+}

package/src/mcp/tools/execute_query_tool.spec.ts

@@ -0,0 +1,143 @@
+import { describe, expect, it } from "bun:test";
+import { MalloyError } from "@malloydata/malloy";
+import { registerExecuteQueryTool } from "./execute_query_tool";
+import type { EnvironmentStore } from "../../service/environment_store";
+import {
+   NotQueryableError,
+   QueryTimeoutError,
+   ServiceUnavailableError,
+} from "../../errors";
+
+// Capture the handler registerExecuteQueryTool passes to McpServer.tool, so it
+// can be exercised against a mocked EnvironmentStore. Mirrors the pattern in
+// compile_tool.spec.ts and reload_package_tool.spec.ts.
+type Handler = (params: Record<string, unknown>) => Promise<{
+   isError?: boolean;
+   content: Array<{ resource: { text: string } }>;
+}>;
+
+function captureHandler(store: Partial<EnvironmentStore>): Handler {
+   let handler: Handler | undefined;
+   const fakeServer = {
+      tool: (_name: string, _desc: string, _shape: unknown, h: Handler) => {
+         handler = h;
+      },
+   };
+   registerExecuteQueryTool(fakeServer as never, store as EnvironmentStore);
+   if (!handler) throw new Error("handler was not registered");
+   return handler;
+}
+
+function parse(result: { content: Array<{ resource: { text: string } }> }) {
+   return JSON.parse(result.content[0].resource.text);
+}
+
+/**
+ * A store whose model loads cleanly and whose QUERY throws.
+ *
+ * The throw has to originate inside the tool's own try block to pin anything.
+ * getModelForQuery already homes a back-pressure error from
+ * `environment.assertCanAdmitQuery()`, which runs outside it, so a test that
+ * trips that path passes even with the catch's classifyToolError call reverted.
+ * Failing at getQueryResults puts the error where tryAcquireQuerySlot's
+ * ServiceUnavailableError lands, which is the case that was reported.
+ */
+function storeWhoseQueryThrows(error: unknown): Partial<EnvironmentStore> {
+   return {
+      getEnvironment: async () =>
+         ({
+            assertCanAdmitQuery: () => undefined,
+            getPackage: async () => ({
+               getModel: () => ({
+                  getModelType: () => "model",
+                  getModel: async () => ({}),
+                  getQueryResults: async () => {
+                     throw error;
+                  },
+               }),
+            }),
+         }) as never,
+   };
+}
+
+const args = {
+   environmentName: "env",
+   packageName: "pkg",
+   modelPath: "m.malloy",
+   query: "run: a -> { aggregate: c is count() }",
+};
+
+describe("malloy_executeQuery error classification", () => {
+   it("tells an at-capacity caller to retry, not to check its Malloy", async () => {
+      // The reported bug. tryAcquireQuerySlot runs inside the tool's try, so at
+      // the concurrency cap its ServiceUnavailableError landed in a catch that
+      // funnelled everything through the Malloy helper: a 503 told the agent to
+      // go verify its syntax. This is the assertion that fails if the catch
+      // stops routing through classifyToolError.
+      const handler = captureHandler(
+         storeWhoseQueryThrows(
+            new ServiceUnavailableError("Memory limit reached"),
+         ),
+      );
+      const parsed = parse(await handler(args));
+      expect(parsed.error).toContain("Memory limit reached");
+      expect(JSON.stringify(parsed.suggestions)).toContain("Retry");
+      expect(JSON.stringify(parsed.suggestions)).not.toContain("Malloy file");
+   });
+
+   it("keeps Malloy advice for a real query error", async () => {
+      // The other half: a bad query throws a raw MalloyError, so homing by
+      // class must not send it to the internal branch.
+      const handler = captureHandler(
+         storeWhoseQueryThrows(new MalloyError("unexpected '@'", [])),
+      );
+      const parsed = parse(await handler(args));
+      expect(parsed.error).not.toContain("unexpected internal error");
+      expect(JSON.stringify(parsed.suggestions)).toContain("Malloy");
+   });
+
+   it("keeps the reload hint on an undefined name", async () => {
+      const handler = captureHandler(
+         storeWhoseQueryThrows(
+            new MalloyError("Reference to undefined object 'orders'", []),
+         ),
+      );
+      const parsed = parse(await handler(args));
+      expect(JSON.stringify(parsed.suggestions)).toContain(
+         "malloy_reloadPackage",
+      );
+   });
+
+   it("does not tell a timed-out query to try again later", async () => {
+      // Retrying an identical too-slow query fails the same way. The class
+      // exists to be distinguishable from the retryable 503, so the one thing
+      // it must not say is the internal branch's "try the request again later".
+      const handler = captureHandler(
+         storeWhoseQueryThrows(
+            new QueryTimeoutError("Query exceeded PUBLISHER_QUERY_TIMEOUT_MS"),
+         ),
+      );
+      const parsed = parse(await handler(args));
+      expect(JSON.stringify(parsed.suggestions)).toContain("not transient");
+      expect(JSON.stringify(parsed.suggestions)).not.toContain(
+         "Try the request again later",
+      );
+   });
+
+   it("reports a query-boundary denial as not-found, not as a server fault", async () => {
+      // NotQueryableError is a deliberate 404: a hidden source should look like
+      // a missing one. Reporting it as an internal error tells the caller to
+      // contact support about a boundary that is working correctly.
+      const handler = captureHandler(
+         storeWhoseQueryThrows(
+            new NotQueryableError('No queryable source "salaries".'),
+         ),
+      );
+      const parsed = parse(await handler(args));
+      expect(parsed.error).toContain("Resource not found");
+      expect(parsed.error).not.toContain("unexpected internal error");
+      // The class exists so a hidden target is indistinguishable from a missing
+      // one; echoing the name back would undo that.
+      expect(parsed.error).not.toContain("salaries");
+   });
+});

package/src/mcp/tools/execute_query_tool.ts

@@ -10,10 +10,26 @@ import {
 } from "../../query_concurrency";
 import { runWithQueryTimeout } from "../../query_timeout";
 import { EnvironmentStore } from "../../service/environment_store";
-import { getMalloyErrorDetails, type ErrorDetails } from "../error_messages";
-import { buildMalloyUri, getModelForQuery } from "../handler_utils";
+import { type ErrorDetails } from "../error_messages";
+import {
+   buildMalloyUri,
+   classifyToolError,
+   getModelForQuery,
+} from "../handler_utils";
 import { MCP_ERROR_MESSAGES } from "../mcp_constants";
 
+/**
+ * Malloy's two ways of saying a name is not in the model's namespace: a bare
+ * reference ("Reference to undefined object 'x'") and a name used where the
+ * compiler expected a definition ("'x' is not defined").
+ */
+function isUndefinedNameError(message: string): boolean {
+   return (
+      message.includes("is not defined") ||
+      message.includes("Reference to undefined object")
+   );
+}
+
 // Zod shape defining required/optional params for executeQuery
 const executeQueryShape = {
    // environmentName is required; other fields mirror SDK expectations
@@ -267,17 +283,34 @@ export function registerExecuteQueryTool(
                `[MCP Server Error] Error executing query in ${environmentName}/${packageName}/${modelPath}:`,
                { error: queryError },
             );
-            const errorDetails: ErrorDetails = getMalloyErrorDetails(
+            // Home the error by class first. tryAcquireQuerySlot runs inside
+            // this try, so at the concurrency cap a ServiceUnavailableError
+            // lands here; funnelling that through the Malloy helper told the
+            // agent to check its syntax when the answer was to retry.
+            const errorDetails: ErrorDetails = classifyToolError(
                "executeQuery",
                `${environmentName}/${packageName}/${modelPath}`, // Include environment
                queryError,
             );
 
+            // A name the model does not define reads as a typo, and the
+            // suggestions say so. But the same error is what an author gets
+            // after saving a new source or view: the served model is the one
+            // compiled at boot, so the name exists on disk and not in memory.
+            // Point at the reload rather than let them hunt for a typo that
+            // isn't there.
+            const suggestions = [...errorDetails.suggestions];
+            if (isUndefinedNameError(errorDetails.message)) {
+               suggestions.push(
+                  "If you added or renamed this source or view on disk after the server loaded the package, the running model is still the one compiled at boot. Call malloy_reloadPackage for this package, then retry.",
+               );
+            }
+
             // Format error details as structured JSON
             const errorJson = JSON.stringify(
                {
                   error: errorDetails.message,
-                  suggestions: errorDetails.suggestions,
+                  suggestions,
                },
                null,
                2,

package/src/mcp/tools/get_context_tool.ts

@@ -230,7 +230,7 @@ A JSON object with a results array whose items carry a kind field. For retrieval
 - Start broad and narrow down: list environments, then packages, then sources, then query.
 
 ## Worked example
-{ "environmentName": "malloy-samples", "packageName": "ecommerce", "query": "revenue by product category" }`;
+{ "environmentName": "examples", "packageName": "storefront", "query": "revenue by product category" }`;
 
 /**
  * Wrap a JSON payload in the MCP resource-content shape every tier of this tool