@malloy-publisher/server 0.0.227 → 0.0.229

package/src/mcp/handler_utils.spec.ts

@@ -0,0 +1,108 @@
+import { describe, expect, it } from "bun:test";
+import { MalloyError } from "@malloydata/malloy";
+import { classifyToolError } from "./handler_utils";
+import {
+   AccessDeniedError,
+   BadRequestError,
+   ModelCompilationError,
+   PackageNotFoundError,
+   ServiceUnavailableError,
+} from "../errors";
+
+/**
+ * classifyToolError decides what an agent is told to do about a failure, so
+ * every branch is pinned by the advice it produces, not just by "an error came
+ * back". Asserting only that an error exists is what let every class funnel
+ * through the Malloy helper unnoticed.
+ *
+ * The routing is by error CLASS on purpose. getMalloyErrorDetails refines on
+ * message patterns the shipped engine does not emit, so "did it refine?" would
+ * send real compile errors to the internal branch.
+ */
+describe("classifyToolError", () => {
+   const advice = (e: unknown) =>
+      JSON.stringify(classifyToolError("op", "env/pkg", e).suggestions);
+
+   it("homes a missing package as not-found, not as Malloy", () => {
+      const details = classifyToolError(
+         "op",
+         "env/pkg",
+         new PackageNotFoundError("Package 'nope' not found"),
+      );
+      expect(details.message).toContain("Resource not found");
+      expect(JSON.stringify(details.suggestions)).not.toContain("Malloy file");
+   });
+
+   it("homes back-pressure as retryable, not as Malloy", () => {
+      const details = classifyToolError(
+         "op",
+         "env/pkg",
+         new ServiceUnavailableError("Memory limit reached"),
+      );
+      expect(details.message).toContain("Memory limit reached");
+      expect(JSON.stringify(details.suggestions)).toContain("Retry");
+      expect(JSON.stringify(details.suggestions)).not.toContain("Malloy file");
+   });
+
+   it("keeps Malloy advice for a raw engine error", () => {
+      // The regression guard for executeQuery. A bad query throws MalloyError,
+      // NOT ModelCompilationError: the engine's error reaches the tool's catch
+      // unwrapped. Route it by the internal branch and a syntax error tells the
+      // agent an "unexpected internal error occurred", which is worse than the
+      // bug this classifier was written to fix.
+      const details = classifyToolError(
+         "executeQuery",
+         "env/pkg/m.malloy",
+         new MalloyError("unexpected '@'", []),
+      );
+      expect(details.message).not.toContain("unexpected internal error");
+      expect(advice(new MalloyError("unexpected '@'", []))).toContain("Malloy");
+   });
+
+   it("keeps Malloy advice for a wrapped compile error", () => {
+      // What a failed reload throws. #890's promise is that a failed reload
+      // returns the compile errors, so this must not read as an internal fault.
+      const details = classifyToolError(
+         "reloadPackage",
+         "env/pkg",
+         new ModelCompilationError({
+            message: "Error(s) compiling model: unexpected '@'",
+         }),
+      );
+      expect(details.message).not.toContain("unexpected internal error");
+   });
+
+   it("keeps Malloy advice for an authorize denial and a malformed request", () => {
+      expect(
+         classifyToolError(
+            "op",
+            "env/pkg",
+            new AccessDeniedError('Access denied for source "orders"'),
+         ).message,
+      ).not.toContain("unexpected internal error");
+      expect(
+         classifyToolError(
+            "op",
+            "env/pkg",
+            new BadRequestError("Invalid query request."),
+         ).message,
+      ).not.toContain("unexpected internal error");
+   });
+
+   it("reports anything else as internal rather than blaming the Malloy", () => {
+      // A bug in our own code, a filesystem failure, or a worker crash. Telling
+      // the agent to check its syntax sends it to edit a model that is fine.
+      for (const error of [
+         new TypeError("cannot read properties of undefined"),
+         Object.assign(new Error("EACCES: permission denied"), {
+            code: "EACCES",
+         }),
+      ]) {
+         const details = classifyToolError("op", "env/pkg", error);
+         expect(details.message).toContain("unexpected internal error");
+         expect(JSON.stringify(details.suggestions)).not.toContain(
+            "Malloy file",
+         );
+      }
+   });
+});

package/src/mcp/handler_utils.ts

@@ -1,10 +1,15 @@
+import { MalloyError } from "@malloydata/malloy";
 import { EnvironmentStore } from "../service/environment_store";
 import {
    AccessDeniedError,
+   BadRequestError,
    PackageNotFoundError,
    ModelNotFoundError,
    ModelCompilationError,
    EnvironmentNotFoundError,
+   NotQueryableError,
+   PayloadTooLargeError,
+   QueryTimeoutError,
    ServiceUnavailableError,
 } from "../errors";
 import {
@@ -16,6 +21,98 @@ import {
 import type { Model } from "../service/model";
 import { logger } from "../logger";
 
+/**
+ * Remediation for a ServiceUnavailableError, shared by every caller that homes
+ * one. The error covers both the memory governor and the concurrency slots, so
+ * the wording names both rather than only memory.
+ */
+export const BACK_PRESSURE_SUGGESTIONS: readonly string[] = [
+   "Retry once the publisher is below its configured memory or concurrency limit.",
+   "If this persists, raise the limit or scale up the pod.",
+];
+
+/**
+ * Turns a thrown error into agent-facing ErrorDetails, homed by error class.
+ *
+ * Without this, a tool that funnels every failure through getMalloyErrorDetails
+ * dresses each one up as a Malloy language problem: a missing package tells the
+ * agent to check its Malloy syntax, and a back-pressure rejection sends it
+ * hunting for a typo instead of retrying.
+ *
+ * Only the classes that really are about the caller's Malloy or request reach
+ * the Malloy advice; anything else is reported as internal rather than blamed
+ * on the model. Routing by class and not by message is deliberate:
+ * getMalloyErrorDetails refines on message patterns that the shipped engine
+ * does not emit (its syntax pattern wants "no viable alternative at input"
+ * where a real error says "unexpected '@'"), so "did it refine?" would send
+ * genuine compile errors to the internal branch.
+ *
+ * @param operation The operation that failed (e.g. 'compile', 'reloadPackage').
+ * @param identifier The resource it failed on (e.g. 'env/package').
+ */
+export function classifyToolError(
+   operation: string,
+   identifier: string,
+   error: unknown,
+): ErrorDetails {
+   if (
+      error instanceof EnvironmentNotFoundError ||
+      error instanceof PackageNotFoundError ||
+      error instanceof ModelNotFoundError ||
+      // A query-boundary denial is a deliberate 404, and reporting it as a
+      // server fault would tell the caller to contact support about a boundary
+      // that is working. getNotFoundError also drops the source name this class
+      // is careful not to confirm.
+      error instanceof NotQueryableError
+   ) {
+      return getNotFoundError(identifier);
+   }
+   if (error instanceof ServiceUnavailableError) {
+      // Back-pressure: surface the server's own message so the caller knows to
+      // retry rather than to go edit its Malloy.
+      return {
+         message: error.message,
+         suggestions: [...BACK_PRESSURE_SUGGESTIONS],
+      } satisfies ErrorDetails;
+   }
+   if (
+      error instanceof QueryTimeoutError ||
+      error instanceof PayloadTooLargeError
+   ) {
+      // The query was too slow or too big. Both classes already carry their own
+      // "refine the query" remediation in the message, so the suggestions say
+      // the part the message leaves out and the internal branch got backwards:
+      // this is not transient, and retrying it unchanged fails identically.
+      // That distinction is the whole reason these are 504/413 and not the
+      // retryable 503 (see the QueryTimeoutError docstring in errors.ts).
+      return {
+         message: error.message,
+         suggestions: [
+            "This is not transient. The same query will fail the same way, so change the query rather than retrying it.",
+            "If it is already minimal, raise the configured cap named in the message.",
+         ],
+      } satisfies ErrorDetails;
+   }
+   if (
+      // A raw engine error: what a bad query throws (syntax, undefined name,
+      // field not found). executeQuery's catch sees these, so they must keep
+      // the Malloy advice.
+      error instanceof MalloyError ||
+      // The same thing wrapped: what a failed compile or reload throws.
+      error instanceof ModelCompilationError ||
+      // An #(authorize) denial, whose message getMalloyErrorDetails recognizes.
+      error instanceof AccessDeniedError ||
+      // A malformed request is the caller's to fix, not ours to retry.
+      error instanceof BadRequestError
+   ) {
+      return getMalloyErrorDetails(operation, identifier, error);
+   }
+   // Everything else (a filesystem EACCES, a TypeError, a worker crash, a
+   // timeout) is not the caller's Malloy. Telling them to check their syntax
+   // sends them to edit a model that is fine.
+   return getInternalError(operation, error);
+}
+
 /**
  * Fetches and validates the Package and Model instances needed for query execution.
  * Handles errors related to package/model access and initial compilation.
@@ -82,10 +179,7 @@ export async function getModelForQuery(
          // server's own message so the MCP caller knows to retry.
          errorDetails = {
             message: error.message,
-            suggestions: [
-               "Retry after the publisher's memory usage drops below the configured low-water mark.",
-               "If this happens repeatedly, raise PUBLISHER_MAX_MEMORY_BYTES or scale up the pod.",
-            ],
+            suggestions: [...BACK_PRESSURE_SUGGESTIONS],
          } satisfies ErrorDetails;
       } else {
          // Unexpected error during setup

package/src/mcp/server.protocol.spec.ts

@@ -2,6 +2,7 @@ import { beforeAll, describe, expect, it } from "bun:test";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
 import { initializeMcpServer } from "./server";
+import { RELOAD_FAILURE_IS_SAFE } from "./tools/reload_package_tool";
 import type { EnvironmentStore } from "../service/environment_store";
 
 /**
@@ -37,6 +38,8 @@ describe("MCP server over the MCP protocol (in-memory)", () => {
       expect(names.has("malloy_getContext")).toBe(true);
       expect(names.has("malloy_searchDocs")).toBe(true);
       expect(names.has("malloy_executeQuery")).toBe(true);
+      expect(names.has("malloy_compile")).toBe(true);
+      expect(names.has("malloy_reloadPackage")).toBe(true);
    });
 
    it("exposes the skill set as dual-channel prompts", async () => {
@@ -45,6 +48,17 @@ describe("MCP server over the MCP protocol (in-memory)", () => {
       expect(prompts.some((p) => p.name === "malloy-analysis")).toBe(true);
    });
 
+   it("delivers orientation instructions to the connecting client", () => {
+      const instructions = client.getInstructions();
+      expect(instructions).toBeDefined();
+      expect(instructions).toContain("malloy_getContext");
+      // Pin the shared fragment, not just that instructions exist. The whole
+      // point of exporting it is that this surface and the tool description
+      // cannot drift, and they have drifted twice. Without this, deleting the
+      // interpolation leaves the suite green and the drift comes back.
+      expect(instructions).toContain(RELOAD_FAILURE_IS_SAFE);
+   });
+
    it("malloy_searchDocs returns relevant docs over the protocol", async () => {
       const res = await client.callTool({
          name: "malloy_searchDocs",
@@ -72,6 +86,50 @@ describe("MCP server over the MCP protocol (in-memory)", () => {
       expect(res.isError).toBe(true);
    });
 
+   /**
+    * Assert the tool's OWN error payload, not just isError. The SDK sets
+    * isError for any uncaught throw, so `expect(res.isError).toBe(true)` passes
+    * even with the tool's catch deleted entirely. Only these tools emit a
+    * resource block carrying structured JSON; a raw throw yields the SDK's text
+    * content instead, so this shape is what actually pins the catch.
+    */
+   function expectToolErrorPayload(result: unknown): {
+      error: string;
+      suggestions: string[];
+   } {
+      const res = result as {
+         isError?: boolean;
+         content?: Array<{ type?: string; resource?: { text?: string } }>;
+      };
+      expect(res.isError).toBe(true);
+      expect(res.content?.[0]?.type).toBe("resource");
+      const payload = JSON.parse(res.content?.[0]?.resource?.text ?? "{}");
+      expect(typeof payload.error).toBe("string");
+      expect(Array.isArray(payload.suggestions)).toBe(true);
+      return payload;
+   }
+
+   it("malloy_compile returns its own error payload over the protocol", async () => {
+      const res = await client.callTool({
+         name: "malloy_compile",
+         arguments: {
+            environmentName: "nope",
+            packageName: "nope",
+            modelPath: "x.malloy",
+            source: "run: x -> { aggregate: c is count() }",
+         },
+      });
+      expect(expectToolErrorPayload(res).error).toContain("nope");
+   });
+
+   it("malloy_reloadPackage returns its own error payload over the protocol", async () => {
+      const res = await client.callTool({
+         name: "malloy_reloadPackage",
+         arguments: { environmentName: "nope", packageName: "nope" },
+      });
+      expect(expectToolErrorPayload(res).error).toContain("nope");
+   });
+
    it("a skill prompt returns its body", async () => {
       const res = await client.getPrompt({ name: "malloy-analysis" });
       const content = res.messages[0].content as { text?: string };

package/src/mcp/server.ts

@@ -2,9 +2,14 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { EnvironmentStore } from "../service/environment_store";
 
 import { formatDuration, logger } from "../logger";
+import { registerCompileTool } from "./tools/compile_tool";
 import { registerDocsSearchTool } from "./tools/docs_search_tool";
 import { registerExecuteQueryTool } from "./tools/execute_query_tool";
 import { registerGetContextTool } from "./tools/get_context_tool";
+import {
+   registerReloadPackageTool,
+   RELOAD_FAILURE_IS_SAFE,
+} from "./tools/reload_package_tool";
 import skillsBundle from "./skills/skills_bundle.json";
 
 export const testServerInfo = {
@@ -22,17 +27,40 @@ const AGENT_SKILLS = (
    }
 ).skills;
 
+// Orientation delivered to any connecting MCP client via the initialize
+// response (the on-the-wire analog of AGENTS.md), so an agent that reached the
+// server over npx without cloning the repo still knows how to work. Kept
+// workflow-focused rather than a tool catalog, which the client already gets
+// from listTools, so it does not drift as the tool set changes.
+// SECURITY: this is delivered pre-authorization to any connecting client, so it
+// must stay STATIC. It may interpolate module-scope string LITERALS (see
+// RELOAD_FAILURE_IS_SAFE, shared with the tool description so the two cannot
+// drift). Not "constants": `const x = process.env.FOO` is a module-scope
+// constant and would put deployment config into an unauthenticated string. It
+// must never interpolate environment, package, connection, or request data.
+const MCP_INSTRUCTIONS = `Malloy Publisher serves one or more Malloy semantic-model packages, so you can discover what data exists and answer questions against it, grounded in the names the model actually defines.
+
+Start with malloy_getContext. Call it with no arguments to list the environments (each with its packages), with an environment to list its packages, with a package to list its sources, and with a package plus a plain-English question to get the sources, views, and fields most relevant to it. Use the names it returns verbatim and do not guess. Then run a query with malloy_executeQuery. To change a model: validate the edit with malloy_compile, save it, then call malloy_reloadPackage so the new sources and views become queryable by name without restarting the server. ${RELOAD_FAILURE_IS_SAFE}
+
+Task-specific guidance is served as prompts you can fetch by name: malloy-getting-started to begin, malloy-modeling to build or change a model, malloy-analysis to explore and answer questions, and malloy-review to check correctness.
+
+Results and any charts render in the Publisher web UI on the REST port (4000 by default).`;
+
 export function initializeMcpServer(
    environmentStore: EnvironmentStore,
 ): McpServer {
    logger.info("[MCP Init] Starting initializeMcpServer...");
    const startTime = performance.now();
 
-   const mcpServer = new McpServer(testServerInfo);
+   const mcpServer = new McpServer(testServerInfo, {
+      instructions: MCP_INSTRUCTIONS,
+   });
 
    registerExecuteQueryTool(mcpServer, environmentStore);
    registerGetContextTool(mcpServer, environmentStore);
    registerDocsSearchTool(mcpServer, environmentStore);
+   registerCompileTool(mcpServer, environmentStore);
+   registerReloadPackageTool(mcpServer, environmentStore);
 
    // Dual-channel: also expose each skill as an MCP prompt, so hosts that ingest
    // MCP but do not load skill files (e.g. Codex, ChatGPT, Cursor) can pull the

package/src/mcp/skills/build_skills_bundle.ts

@@ -13,7 +13,7 @@
 import * as fs from "fs";
 import * as path from "path";
 
-interface SkillEntry {
+export interface SkillEntry {
    name: string;
    description: string;
    body: string;
@@ -36,6 +36,33 @@ export function parseSkill(md: string, dirName: string): SkillEntry {
    return { name, description, body };
 }
 
+/**
+ * `credible-*` skills are Credible-platform-specific and never ship (see
+ * skills/README.md). They can legitimately sit in skills/ uncommitted: the
+ * directory is a gitignored local install target (`skills/credible-*` in
+ * .gitignore), so the bundle must skip them or a regeneration on a machine
+ * with Credible installed would bake them into the committed bundle, and the
+ * regenerate-and-compare spec would fail on a clean checkout.
+ *
+ * The canonical predicate lives in packages/skills/scripts/exclusions.ts;
+ * duplicated here because the server does not depend on that package.
+ */
+export function isCredible(dirName: string): boolean {
+   return dirName.toLowerCase().startsWith("credible-");
+}
+
+/** Read every skill under a skills directory, in the bundle's own order. */
+export function buildSkills(skillsDir: string): SkillEntry[] {
+   const skills: SkillEntry[] = [];
+   for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
+      if (!entry.isDirectory() || isCredible(entry.name)) continue;
+      const skillFile = path.join(skillsDir, entry.name, "SKILL.md");
+      if (!fs.existsSync(skillFile)) continue;
+      skills.push(parseSkill(fs.readFileSync(skillFile, "utf8"), entry.name));
+   }
+   return skills.sort((a, b) => a.name.localeCompare(b.name));
+}
+
 function main(): void {
    const skillsDir = process.argv[2];
    const outFile =
@@ -47,14 +74,7 @@ function main(): void {
       process.exit(1);
    }
 
-   const skills: SkillEntry[] = [];
-   for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
-      if (!entry.isDirectory()) continue;
-      const skillFile = path.join(skillsDir, entry.name, "SKILL.md");
-      if (!fs.existsSync(skillFile)) continue;
-      skills.push(parseSkill(fs.readFileSync(skillFile, "utf8"), entry.name));
-   }
-   skills.sort((a, b) => a.name.localeCompare(b.name));
+   const skills = buildSkills(skillsDir);
 
    fs.writeFileSync(outFile, JSON.stringify({ skills }));
    console.log(`Wrote ${skills.length} skills to ${outFile}`);