@malloy-publisher/server 0.0.226 → 0.0.228

package/src/mcp/handler_utils.ts

@@ -1,13 +1,15 @@
-import { URL } from "url";
-import type { ResourceMetadata } from "@modelcontextprotocol/sdk/server/mcp";
-import type { ReadResourceResult } from "@modelcontextprotocol/sdk/types.js";
+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 {
@@ -19,103 +21,96 @@ import {
 import type { Model } from "../service/model";
 import { logger } from "../logger";
 
-// Custom error to wrap specific GetResource application errors
-export class McpGetResourceError extends Error {
-   details: ErrorDetails;
-
-   constructor(details: ErrorDetails) {
-      super(details.message); // Pass message to the base Error constructor
-      this.name = "McpGetResourceError"; // Custom error name
-      this.details = details; // Store the structured details
-
-      // Maintain stack trace (important for V8)
-      if (Error.captureStackTrace) {
-         Error.captureStackTrace(this, McpGetResourceError);
-      }
-   }
-}
-
-// Helper type for the data fetching logic within a resource handler
-type GetDataLogic<TParams, TDefinition> = (
-   params: TParams,
-   uri: URL,
-) => Promise<TDefinition>;
-
 /**
- * Handles the common logic for GetResource handlers, fetching data and formatting the response or error.
+ * 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 async function handleResourceGet<
-   TParams extends Record<string, unknown>,
-   TDefinition,
->(
-   uri: URL,
-   params: TParams,
-   resourceType: string, // e.g., 'environment', 'package' for logging/errors
-   getData: GetDataLogic<TParams, TDefinition>,
-   resourceMetadata: ResourceMetadata | undefined,
-): Promise<ReadResourceResult> {
-   try {
-      const definition = await getData(params, uri);
-
-      // Combine definition and metadata
-      const responsePayload = JSON.stringify(
-         { definition: definition, metadata: resourceMetadata },
-         null,
-         2,
-      );
+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 {
-         contents: [
-            {
-               type: "application/json",
-               uri: uri.href,
-               text: responsePayload,
-            },
-         ],
-      };
-   } catch (error) {
-      logger.error(
-         `[MCP Server Error] Error reading ${resourceType} ${uri.href}:`,
-         { error },
-      );
-
-      let errorDetails: ErrorDetails;
-
-      // Determine the correct error details based on the error type
-      if (error instanceof McpGetResourceError) {
-         // The getData function already caught, formatted, and wrapped the error
-         errorDetails = error.details;
-      } else {
-         // Catch-all for truly unexpected errors not handled by the specific getData logic
-         logger.error(
-            "[MCP Server Error] Unexpected error type caught in handleResourceGet:",
-            { error },
-         );
-         errorDetails = getInternalError(
-            `GetResource (${resourceType})`,
-            error,
-         );
-      }
-
-      // Format the error response consistently
+         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 {
-         isError: true,
-         contents: [
-            {
-               type: "application/json", // Keep JSON for structured error
-               uri: uri.href,
-               text: JSON.stringify(
-                  {
-                     error: errorDetails.message,
-                     suggestions: errorDetails.suggestions,
-                  },
-                  null,
-                  2,
-               ),
-            },
+         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);
 }
 
 /**
@@ -184,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
@@ -202,28 +194,20 @@ export async function getModelForQuery(
 }
 
 /**
- * Constructs a valid malloy:// URI string from its components.
- * Handles encoding of path segments.
+ * Constructs a malloy:// URI string identifying the model a tool response came
+ * from. Attached as `uri` metadata on tool results (get-context, execute-query,
+ * docs-search); it is not a fetchable MCP resource.
  *
- * @param components An object containing the URI parts (environment, package, model, etc.)
- * @param fragment Optional fragment identifier (e.g., #queryResult)
- * @returns A valid malloy:// URI string.
+ * @param components The URI parts (environment, package, and optionally the model).
+ * @param fragment Optional fragment identifier (e.g., "result", "get-context").
+ * @returns A malloy:// URI string.
  */
 export function buildMalloyUri(
    components: {
       environment?: string;
       package?: string;
-      model?: string;
-      resourceType?:
-         | "models"
-         | "packages"
-         | "notebooks"
-         | "sources"
-         | "queries"
-         | "views"; // Type of resource list or specific resource
-      resourceName?: string; // Specific name for model, query, etc.
-      subResourceType?: "views"; // For views within sources
-      subResourceName?: string; // Name of the view
+      resourceType?: "models";
+      resourceName?: string;
    },
    fragment?: string,
 ): string {
@@ -244,20 +228,11 @@ export function buildMalloyUri(
       path += "/" + components.resourceType;
       if (components.resourceName) {
          path += "/" + encodeURIComponent(components.resourceName);
-
-         if (components.subResourceType && components.subResourceName) {
-            path +=
-               "/" +
-               components.subResourceType +
-               "/" +
-               encodeURIComponent(components.subResourceName);
-         }
       }
    }
 
-   // The URL constructor seems to normalize malloy://path to malloy:///path
-   // which breaks the tests expecting malloy://environment/...
-   // We manually construct the string instead.
+   // The URL constructor normalizes malloy://path to malloy:///path, so we
+   // build the string manually to keep the malloy://environment/... shape.
    let uriString = "malloy:/" + path; // Start with one slash after scheme
 
    if (fragment) {

package/src/mcp/mcp_constants.ts

@@ -3,20 +3,4 @@ export const MCP_ERROR_MESSAGES = {
    MISSING_REQUIRED_PARAMS:
       "Either 'query' or both 'sourceName' and 'queryName' must be provided",
    MUTUALLY_EXCLUSIVE_PARAMS: "Cannot provide both 'query' and 'queryName'",
-   INVALID_ARGUMENTS: (toolName: string, errors: string[]) =>
-      `Invalid arguments for tool ${toolName}: ${errors.join(", ")}`,
-
-   // Application-level errors (runtime)
-   PROJECT_NOT_FOUND: (projectName: string) =>
-      `Environment '${projectName}' is not available or does not exist.`,
-   PACKAGE_NOT_FOUND: (packageName: string) =>
-      `Package manifest for ${packageName} does not exist.`,
-   MODEL_NOT_FOUND: (packageName: string, modelPath: string) =>
-      `Model '${modelPath}' not found in package '${packageName}'`,
-   QUERY_NOT_FOUND: (queryName: string) => `'${queryName}' is not defined`,
-   COMPILATION_ERROR: (error: string) => `Error(s) compiling model:\n${error}`,
-
-   // Error message prefixes
-   ERROR_EXECUTING_QUERY: (packagePath: string) =>
-      `Error executing query on '${packagePath}':`,
 } as const;

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

@@ -0,0 +1,138 @@
+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";
+
+/**
+ * End-to-end coverage of the unified MCP server over the real MCP protocol,
+ * using the SDK's in-memory transport (no HTTP, no network, no DuckDB).
+ * Exercises tool registration (including the agent retrieval tools that now
+ * live on the same server), the dual-channel skill prompts, a real tool call
+ * (searchDocs over the bundled index), and the getContext error path.
+ */
+describe("MCP server over the MCP protocol (in-memory)", () => {
+   let client: Client;
+
+   beforeAll(async () => {
+      // searchDocs does not touch the store; getContext's error path only needs
+      // getEnvironment to reject, so a throwing stub is sufficient here.
+      const stubStore = {
+         getEnvironment: async (name: string): Promise<never> => {
+            throw new Error(`Environment not found: ${name}`);
+         },
+      } as unknown as EnvironmentStore;
+
+      const server = initializeMcpServer(stubStore);
+      const [clientTransport, serverTransport] =
+         InMemoryTransport.createLinkedPair();
+      await server.connect(serverTransport);
+      client = new Client({ name: "mcp-protocol-test", version: "0.0.0" });
+      await client.connect(clientTransport);
+   });
+
+   it("exposes the agent retrieval tools alongside the core tools", async () => {
+      const { tools } = await client.listTools();
+      const names = new Set(tools.map((t) => t.name));
+      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 () => {
+      const { prompts } = await client.listPrompts();
+      expect(prompts.length).toBeGreaterThanOrEqual(24);
+      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",
+         arguments: { query: "window functions" },
+      });
+      const content = res.content as Array<{ resource?: { text?: string } }>;
+      const results = JSON.parse(
+         content?.[0]?.resource?.text ?? "[]",
+      ) as Array<{
+         url: string;
+      }>;
+      expect(results.length).toBeGreaterThan(0);
+      expect(results[0].url.length).toBeGreaterThan(0);
+   });
+
+   it("malloy_getContext fails gracefully (isError) for an unknown environment", async () => {
+      const res = await client.callTool({
+         name: "malloy_getContext",
+         arguments: {
+            environmentName: "nope",
+            packageName: "nope",
+            query: "x",
+         },
+      });
+      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 };
+      expect((content.text ?? "").length).toBeGreaterThan(200);
+   });
+});

package/src/mcp/server.ts

@@ -2,16 +2,15 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { EnvironmentStore } from "../service/environment_store";
 
 import { formatDuration, logger } from "../logger";
-import { registerPromptCapability } from "./prompts/prompt_service.js";
-import { registerEnvironmentResource } from "./resources/environment_resource";
-import { registerModelResource } from "./resources/model_resource";
-import { registerNotebookResource } from "./resources/notebook_resource";
-import { registerPackageResource } from "./resources/package_resource";
-import { registerQueryResource } from "./resources/query_resource";
-import { registerSourceResource } from "./resources/source_resource";
-import { registerViewResource } from "./resources/view_resource";
-import { registerTools } from "./tools/discovery_tools";
+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 = {
    name: "malloy-publisher-mcp-server",
@@ -20,43 +19,64 @@ export const testServerInfo = {
    description: "Provides access to Malloy models and query execution via MCP.",
 };
 
+// Build-time bundle of the agent skills (see skills/build_skills_bundle.ts),
+// exposed as MCP prompts for the dual-channel delivery below.
+const AGENT_SKILLS = (
+   skillsBundle as {
+      skills: { name: string; description: string; body: string }[];
+   }
+).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);
-
-   logger.info("[MCP Init] Registering environment resource...");
-   registerEnvironmentResource(mcpServer, environmentStore);
-   logger.info("[MCP Init] Registering package resource...");
-   registerPackageResource(mcpServer, environmentStore);
-
-   // Register more specific templates first
-   logger.info("[MCP Init] Registering notebook resource...");
-   registerNotebookResource(mcpServer, environmentStore);
-   logger.info("[MCP Init] Registering source resource...");
-   registerSourceResource(mcpServer, environmentStore);
-   logger.info("[MCP Init] Registering query resource...");
-   registerQueryResource(mcpServer, environmentStore);
-   logger.info("[MCP Init] Registering view resource...");
-   registerViewResource(mcpServer, environmentStore);
-
-   // Register the general model template last among resource types
-   logger.info("[MCP Init] Registering model resource...");
-   registerModelResource(mcpServer, environmentStore);
+   const mcpServer = new McpServer(testServerInfo, {
+      instructions: MCP_INSTRUCTIONS,
+   });
 
-   logger.info("[MCP Init] Registering executeQuery tool...");
    registerExecuteQueryTool(mcpServer, environmentStore);
+   registerGetContextTool(mcpServer, environmentStore);
+   registerDocsSearchTool(mcpServer, environmentStore);
+   registerCompileTool(mcpServer, environmentStore);
+   registerReloadPackageTool(mcpServer, environmentStore);
 
-   registerTools(mcpServer, environmentStore);
-
-   // Note: malloy_getContext and malloy_searchDocs are intentionally NOT registered
-   // here. They run on a separate, isolated agent MCP server (see mcp/agent_server.ts).
-
-   logger.info("[MCP Init] Registering prompt capability...");
-   registerPromptCapability(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
+   // same guidance. Skill-aware hosts (Claude Code/Desktop) use the native skill
+   // files. Note: MCP prompts are on-demand, so always-on "prevention" skills
+   // become on-demand here; see docs/agent-skills/design-principles.md.
+   for (const skill of AGENT_SKILLS) {
+      mcpServer.prompt(skill.name, skill.description, () => ({
+         messages: [
+            {
+               role: "user" as const,
+               content: { type: "text" as const, text: skill.body },
+            },
+         ],
+      }));
+   }
 
    const endTime = performance.now();
    logger.info(`[MCP Init] Finished initializeMcpServer`, {

package/src/mcp/skills/build_skills_bundle.ts

@@ -1,5 +1,5 @@
 /**
- * Build a bundled JSON of the agent skills so the agent MCP server can expose them as
+ * Build a bundled JSON of the agent skills so the MCP server can expose them as
  * MCP prompts (dual-channel): skill-aware hosts read the skill files directly, while
  * hosts that only ingest MCP get the same guidance through these prompts.
  *