@malloy-publisher/server 0.0.232 → 0.0.234

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

@@ -18,6 +18,7 @@ import {
 } from "./get_context_tool";
 import { embeddingText } from "./embedding_index";
 import type { EnvironmentStore } from "../../service/environment_store";
+import { PackageNotFoundError } from "../../errors";
 import { DuckDBConnection } from "../../storage/duckdb/DuckDBConnection";
 import { createEntityEmbeddingsTable } from "../../storage/duckdb/schema";
 import {
@@ -132,9 +133,15 @@ describe("get_context sanitize", () => {
 
 // Capture the tool handler that registerGetContextTool passes to McpServer.tool,
 // so each discovery tier can be exercised against a mocked EnvironmentStore.
+type Content = Array<{
+   type?: string;
+   text?: string;
+   resource?: { text: string };
+}>;
+
 type Handler = (params: Record<string, unknown>) => Promise<{
    isError?: boolean;
-   content: Array<{ resource: { text: string } }>;
+   content: Content;
 }>;
 
 function captureHandler(store: Partial<EnvironmentStore>): Handler {
@@ -149,8 +156,12 @@ function captureHandler(store: Partial<EnvironmentStore>): Handler {
    return handler;
 }
 
-function parse(result: { content: Array<{ resource: { text: string } }> }) {
-   return JSON.parse(result.content[0].resource.text);
+function parse(result: { content: Content }) {
+   return JSON.parse(result.content[0].resource!.text);
+}
+
+function textBlock(result: { content: Content }) {
+   return result.content.find((b) => b.type === "text")?.text;
 }
 
 // A model with one source (order_items) carrying one dimension (state).
@@ -242,6 +253,53 @@ describe("get_context discovery tiers", () => {
       const parsed = parse(result);
       expect(parsed.results).toEqual([]);
       expect(parsed.error).toContain("could not be resolved");
+      // Suggestions and a text block, same as this tool's three siblings. Both
+      // were absent before: the payload carried a bare message, and a
+      // text-only client saw nothing at all.
+      expect(parsed.suggestions.length).toBeGreaterThan(0);
+      expect(textBlock(result)).toContain("could not be resolved");
+   });
+
+   it("reports an unknown package as not-found, not as an internal fault", async () => {
+      // Pins the classification, not just that an error came back. Before this
+      // routed through classifyToolError every failure arrived as the raw
+      // message with no remediation, so a typo'd package name gave the agent
+      // nothing to act on.
+      const handler = captureHandler({
+         getEnvironment: async () =>
+            ({
+               getPackage: async () => {
+                  throw new PackageNotFoundError("Package 'nope' not found");
+               },
+            }) as never,
+      });
+      const result = await handler({
+         environmentName: "malloy-samples",
+         packageName: "nope",
+         query: "state",
+      });
+      expect(result.isError).toBe(true);
+      const parsed = parse(result);
+      expect(parsed.results).toEqual([]);
+      expect(parsed.error).toContain("Resource not found");
+      expect(parsed.error).toContain("nope");
+      expect(textBlock(result)).toContain("Resource not found");
+   });
+
+   it("reports a non-Error throwable without inventing 'Unknown error'", async () => {
+      // The old per-site `error instanceof Error ? error.message : "Unknown
+      // error"` turned a thrown string into exactly the unhelpful text this
+      // tool's callers reported. classifyToolError stringifies it instead.
+      const handler = captureHandler({
+         listEnvironments: async () => {
+            throw "the store exploded";
+         },
+      });
+      const result = await handler({});
+      const parsed = parse(result);
+      expect(parsed.error).toContain("the store exploded");
+      expect(parsed.error).not.toContain("Unknown error");
+      expect(textBlock(result)).toContain("the store exploded");
    });
 
    it("tier 3: package without a query lists only its sources", async () => {
@@ -299,6 +357,8 @@ describe("get_context discovery tiers", () => {
       const parsed = parse(result);
       expect(parsed.results).toEqual([]);
       expect(parsed.error).toContain("not initialized");
+      expect(parsed.suggestions.length).toBeGreaterThan(0);
+      expect(textBlock(result)).toContain("not initialized");
    });
 
    it("tier 3: lists every source, not just the first 10", async () => {

package/src/mcp/tools/get_context_tool.ts

@@ -8,7 +8,8 @@ import {
    embeddingConfigured,
    getEmbeddingProvider,
 } from "../../service/embedding_provider";
-import { buildMalloyUri } from "../handler_utils";
+import { buildMalloyUri, classifyToolError } from "../handler_utils";
+import { jsonResource, jsonToolError } from "../tool_response";
 import { logger } from "../../logger";
 import { entityRowKey, trySemanticSearch } from "./embedding_index";
 
@@ -261,46 +262,45 @@ async function getPackageIndex(
 
 const GET_CONTEXT_DESCRIPTION = `Discover what a Publisher deployment exposes and retrieve the model entities most relevant to a plain-English question, so you can ground a query in what the model actually defines instead of guessing. This is the starting point when you do not yet know the environment, package, or model names.
 
-## Progressive discovery
-Call it with as much as you know and omit the rest; it answers at the appropriate level:
-- No arguments: lists the available environments, each with its package names.
-- environmentName only: lists the packages in that environment, with descriptions.
-- environmentName + packageName: lists that package's sources.
-- environmentName + packageName + query: returns the sources, views, named queries, and dimension/measure fields most relevant to the question.
+## Contract rules
+- Use the names it returns verbatim; never invent an environment, package, or entity that is not in the results.
+- Start broad and narrow down: environments, then packages, then sources, then a query.
 
 ## Parameters
-- environmentName (optional): omit to list environments.
-- packageName (optional): omit, with environmentName set, to list packages.
-- query (optional): a plain-English description of what you need; omit, with environmentName and packageName set, to list the package's sources.
-- sourceName (optional): narrow retrieval to entities within one source (the drill-down phase).
-- limit (optional): cap the number of results (max 50). Retrieval defaults to 10; the listing tiers return all unless set.
+All optional. Supply what you know and omit the rest; each combination answers at its own level.
+- none: lists the environments, each with its package names.
+- environmentName: lists that environment's packages, with descriptions.
+- + packageName: lists that package's sources.
+- + query: a plain-English description of what you need, returning the sources, views, named queries, and dimension/measure fields most relevant to it.
+- sourceName: narrows retrieval to one source (the drill-down phase).
+- limit: caps results (max 50). Retrieval defaults to 10; the listing levels return all unless set.
 
 ## Response
 A JSON object with a results array whose items carry a kind field. For retrieval, each entity has kind (source / view / query / dimension / measure), name, source, modelPath, and doc; environmentName, packageName, modelPath, and source map directly onto malloy_executeQuery parameters, and for a view or named query you pass its name as queryName with sourceName. When the server is configured with an embedding provider, retrieval is ranked by semantic similarity: the payload then carries a retrieval field ("semantic", or "lexical" when the provider is unavailable) and each semantic entity a score.
 
-## Contract rules
-- Use the names verbatim; do not invent environments, packages, or entities not in the results.
-- Start broad and narrow down: list environments, then packages, then sources, then query.
-
 ## Worked example
 { "environmentName": "examples", "packageName": "storefront", "query": "revenue by product category" }`;
 
 /**
- * Wrap a JSON payload in the MCP resource-content shape every tier of this tool
- * returns. isError marks a tool-level error (e.g. an unknown environment/package).
+ * Every tier of this tool answers with `results`, so an error keeps that key
+ * (empty) alongside `error`. Callers can read `results` unconditionally without
+ * branching on success first.
+ *
+ * Routed through classifyToolError for the same reason its three sibling tools
+ * are: it homes each error class to real remediation, so an unknown package
+ * says so instead of arriving as a bare message with no suggestions. It also
+ * replaces a per-site `error instanceof Error ? error.message : "Unknown
+ * error"`, which was the one path in this file that could produce exactly the
+ * unhelpful string this tool's callers reported.
  */
-function jsonResource(uri: string, payload: unknown, isError = false) {
-   const content = [
+function contextError(uri: string, identifier: string, error: unknown) {
+   return jsonToolError(
+      uri,
+      classifyToolError("getContext", identifier, error),
       {
-         type: "resource" as const,
-         resource: {
-            type: "application/json",
-            uri,
-            text: JSON.stringify(payload),
-         },
+         results: [],
       },
-   ];
-   return isError ? { isError: true, content } : { content };
+   );
 }
 
 /**
@@ -348,16 +348,17 @@ export function registerGetContextTool(
                   results,
                });
             } catch (error) {
-               const message =
-                  error instanceof Error ? error.message : "Unknown error";
                logger.warn(
                   "[MCP Tool getContext] listing environments failed",
-                  { error: message },
+                  {
+                     error:
+                        error instanceof Error ? error.message : String(error),
+                  },
                );
-               return jsonResource(
+               return contextError(
                   buildMalloyUri({}, "get-context"),
-                  { error: message, results: [] },
-                  true,
+                  "environments",
+                  error,
                );
             }
          }
@@ -384,19 +385,17 @@ export function registerGetContextTool(
                   { results },
                );
             } catch (error) {
-               const message =
-                  error instanceof Error ? error.message : "Unknown error";
                logger.warn("[MCP Tool getContext] listing packages failed", {
                   environmentName,
-                  error: message,
+                  error: error instanceof Error ? error.message : String(error),
                });
-               return jsonResource(
+               return contextError(
                   buildMalloyUri(
                      { environment: environmentName },
                      "get-context",
                   ),
-                  { error: message, results: [] },
-                  true,
+                  environmentName,
+                  error,
                );
             }
          }
@@ -410,21 +409,19 @@ export function registerGetContextTool(
                packageName,
             );
          } catch (error) {
-            const message =
-               error instanceof Error ? error.message : "Unknown error";
             logger.warn("[MCP Tool getContext] index build failed", {
                environmentName,
                packageName,
                sourceName,
-               error: message,
+               error: error instanceof Error ? error.message : String(error),
             });
-            return jsonResource(
+            return contextError(
                buildMalloyUri(
                   { environment: environmentName, package: packageName },
                   "get-context",
                ),
-               { error: message, results: [] },
-               true,
+               `${environmentName}/${packageName}`,
+               error,
             );
          }
 

package/src/mcp/tools/reload_package_tool.ts

@@ -5,6 +5,7 @@ import { EnvironmentStore } from "../../service/environment_store";
 import { PackageController } from "../../controller/package.controller";
 import { type ErrorDetails } from "../error_messages";
 import { buildMalloyUri, classifyToolError } from "../handler_utils";
+import { jsonResource, jsonToolError } from "../tool_response";
 
 // Zod shape for malloy_reloadPackage. environmentName/packageName mirror the
 // other tools and point the agent at malloy_getContext for name discovery.
@@ -109,19 +110,7 @@ export function registerReloadPackageTool(
                   }),
             };
 
-            return {
-               isError: false,
-               content: [
-                  {
-                     type: "resource" as const,
-                     resource: {
-                        type: "application/json",
-                        uri,
-                        text: JSON.stringify(payload),
-                     },
-                  },
-               ],
-            };
+            return jsonResource(uri, payload);
          } catch (error) {
             // Unknown environment/package, or a compile error in the reloaded
             // package: surface as a clean isError payload rather than a
@@ -136,22 +125,7 @@ export function registerReloadPackageTool(
                `${environmentName}/${packageName}`,
                error,
             );
-            return {
-               isError: true,
-               content: [
-                  {
-                     type: "resource" as const,
-                     resource: {
-                        type: "application/json",
-                        uri,
-                        text: JSON.stringify({
-                           error: errorDetails.message,
-                           suggestions: errorDetails.suggestions,
-                        }),
-                     },
-                  },
-               ],
-            };
+            return jsonToolError(uri, errorDetails);
          }
       },
    );