@malloy-publisher/server 0.0.232 → 0.0.233

package/src/mcp/tools/docs_search_tool.ts

@@ -3,6 +3,7 @@ import { z } from "zod";
 import lunr from "lunr";
 import { EnvironmentStore } from "../../service/environment_store";
 import { buildMalloyUri } from "../handler_utils";
+import { jsonResource } from "../tool_response";
 import { logger } from "../../logger";
 import rawIndex from "./docs_search/malloy_docs_index.json";
 
@@ -88,6 +89,10 @@ const SEARCH_DOCS_DESCRIPTION = `Search the Malloy documentation by keyword and
 - Before writing unfamiliar Malloy syntax (window functions, autobin, dialect-specific functions, rendering tags) or when a query fails with a syntax error you do not recognize.
 - Do NOT use it to look up field or source names in a model; use malloy_getContext for that.
 
+## Contract rules
+- These are documentation pages, not model entities. Do not treat a doc title as a field or source name.
+- The excerpt is only a hint; open the url for the full detail.
+
 ## Parameters
 - query (required): keywords describing what you need.
 - limit (optional): maximum results to return; default 8.
@@ -95,10 +100,6 @@ const SEARCH_DOCS_DESCRIPTION = `Search the Malloy documentation by keyword and
 ## Response
 A JSON array of matches, each with title, url (a docs.malloydata.dev link), and a short excerpt, ordered by relevance. Empty array if nothing matches; broaden the keywords and retry.
 
-## Contract rules
-- These are documentation pages, not model entities. Do not treat a doc title as a field or source name.
-- The excerpt is only a hint; open the url for the full detail.
-
 ## Worked example
 { "query": "window functions lag" }`;
 
@@ -121,18 +122,7 @@ export function registerDocsSearchTool(
 
          const results = searchDocsIndex(query, max);
 
-         return {
-            content: [
-               {
-                  type: "resource" as const,
-                  resource: {
-                     type: "application/json",
-                     uri: buildMalloyUri({}, "docs-search"),
-                     text: JSON.stringify(results),
-                  },
-               },
-            ],
-         };
+         return jsonResource(buildMalloyUri({}, "docs-search"), results);
       },
    );
 }

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

@@ -13,7 +13,11 @@ import {
 // compile_tool.spec.ts and reload_package_tool.spec.ts.
 type Handler = (params: Record<string, unknown>) => Promise<{
    isError?: boolean;
-   content: Array<{ resource: { text: string } }>;
+   content: Array<{
+      type?: string;
+      text?: string;
+      resource?: { text: string };
+   }>;
 }>;
 
 function captureHandler(store: Partial<EnvironmentStore>): Handler {
@@ -28,8 +32,8 @@ 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: Array<{ resource?: { text: string } }> }) {
+   return JSON.parse(result.content[0].resource!.text);
 }
 
 /**
@@ -140,4 +144,20 @@ describe("malloy_executeQuery error classification", () => {
       // one; echoing the name back would undo that.
       expect(parsed.error).not.toContain("salaries");
    });
+
+   it("also states the error in a text block", async () => {
+      // The structured payload rides in an embedded resource block. A client
+      // that renders only text blocks on an isError result shows nothing at
+      // all for it, which is how a real diagnostic surfaces to the agent as a
+      // bare "Unknown error". Every error must say it in plain text too.
+      const handler = captureHandler(
+         storeWhoseQueryThrows(new MalloyError("unexpected '@'", [])),
+      );
+      const result = await handler(args);
+      const parsed = parse(result);
+
+      const textBlock = result.content.find((b) => b.type === "text");
+      expect(textBlock).toBeDefined();
+      expect(textBlock!.text).toContain(parsed.error);
+   });
 });

package/src/mcp/tools/execute_query_tool.ts

@@ -16,6 +16,9 @@ import {
    classifyToolError,
    getModelForQuery,
 } from "../handler_utils";
+import { jsonResource, jsonToolError } from "../tool_response";
+import { buildQueryEnvelope } from "../query_envelope";
+import { bigIntReplacer } from "../../json_utils";
 import { MCP_ERROR_MESSAGES } from "../mcp_constants";
 
 /**
@@ -61,6 +64,26 @@ const executeQueryShape = {
       ),
 };
 
+const EXECUTE_QUERY_DESCRIPTION = `Run a Malloy query against a model and return the rows. Takes either ad-hoc Malloy in query, or a named view/query via queryName (with sourceName for a view).
+
+## Contract rules
+- Check _limit_hit before reporting any total, count, or "top N". True means the server's default row cap cut the result off and more rows exist, so the numbers in front of you are a partial set, not the answer. A query that set its own limit: or top: does not set it, and returning exactly that many rows is a complete answer to what was asked.
+- Never sum or count the returned rows to state a total when _limit_hit or _rows_truncated is set. Aggregate in the query instead.
+- _returned_rows: 0 with _rows_truncated set means one row was too large to send, NOT that nothing matched. Do not report it as an empty result.
+- Use source, view, and field names exactly as malloy_getContext returned them.
+
+## Response
+A JSON object, the same shape Credible's execute_query returns, so a data app behaves the same authored locally and served in production:
+- rows: flat objects keyed by column name, the shape an in-package data app receives.
+- _meta: the Malloy metadata flat rows drop (schema with field types and render tags, annotations, connection_name, query_timezone).
+- _query_row_limit: the cap pushed into the SQL, from the query's own limit: or the server default.
+- _limit_source: "query" when the cap came from the query's own limit:/top:, "server_default" otherwise.
+- _limit_hit: the row count equals that cap AND the cap was the server default.
+- _rows_truncated / _total_rows / _returned_rows: present only when the payload cap dropped rows.
+- warning, renderLogErrors: present only when they apply.
+
+A query with no limit: of its own gets the server default, so a result landing exactly on _query_row_limit is almost never the whole table. Values above 2^53 are returned as JSON strings so their digits survive.`;
+
 // Type inference is handled automatically by the MCP server based on the executeQueryShape
 
 /**
@@ -72,7 +95,7 @@ export function registerExecuteQueryTool(
 ): void {
    mcpServer.tool(
       "malloy_executeQuery",
-      "Executes a Malloy query (either ad-hoc or a named query/view defined in a model) against the specified model and returns the results as JSON.",
+      EXECUTE_QUERY_DESCRIPTION,
       executeQueryShape,
       /** Handles requests for the malloy_executeQuery tool */
       async (params) => {
@@ -120,29 +143,10 @@ export function registerExecuteQueryTool(
 
          // Handle errors during package/model access (e.g., not found, initial compilation)
          if ("error" in modelResult) {
-            // Format error details as structured JSON
-            const errorJson = JSON.stringify(
-               {
-                  error: modelResult.error.message,
-                  suggestions: modelResult.error.suggestions,
-               },
-               null,
-               2,
+            return jsonToolError(
+               "error://executeQuery/modelAccess",
+               modelResult.error,
             );
-            return {
-               isError: true,
-               // Return as application/json nested inside a 'resource' type
-               content: [
-                  {
-                     type: "resource", // Use 'resource' type
-                     resource: {
-                        type: "application/json", // Actual content type
-                        uri: "error://executeQuery/modelAccess", // Placeholder URI
-                        text: errorJson,
-                     },
-                  },
-               ],
-            };
          }
 
          // --- Execute Query ---
@@ -160,123 +164,77 @@ export function registerExecuteQueryTool(
          let querySlot: QuerySlotHandle | null = null;
          try {
             querySlot = tryAcquireQuerySlot("mcp:executeQuery");
-            // If ad-hoc query is provided, use it directly in the 3rd arg
-            if (query) {
-               const { result } = await runWithQueryTimeout(
+            // The two call modes differ only in which arguments carry the
+            // query; everything after the run is identical, so they share one
+            // path rather than two copies that can drift.
+            const { result, compactResult, rowLimit, rowLimitSource } =
+               await runWithQueryTimeout(
                   (abortSignal) =>
-                     model.getQueryResults(
-                        undefined,
-                        undefined,
-                        query,
-                        filterParams,
-                        undefined,
-                        givens as Record<string, GivenValue> | undefined,
-                        abortSignal,
-                     ),
+                     query
+                        ? model.getQueryResults(
+                             undefined,
+                             undefined,
+                             query,
+                             filterParams,
+                             undefined,
+                             givens as Record<string, GivenValue> | undefined,
+                             abortSignal,
+                          )
+                        : model.getQueryResults(
+                             sourceName,
+                             queryName,
+                             undefined,
+                             filterParams,
+                             undefined,
+                             givens as Record<string, GivenValue> | undefined,
+                             abortSignal,
+                          ),
                   getQueryTimeoutMs(),
                );
-               const { validateRenderTags } = await import(
-                  "@malloydata/render-validator"
-               );
-               const renderLogs = validateRenderTags(result);
 
-               const baseUriComponents = {
-                  environment: environmentName,
-                  package: packageName,
-                  resourceType: "models" as const,
-                  resourceName: modelPath,
-               };
-               const resultUri = buildMalloyUri(baseUriComponents, "result");
-               const resultString = JSON.stringify(result, null, 2);
-
-               const content = [
-                  {
-                     type: "resource" as const,
-                     resource: {
-                        type: "application/json",
-                        uri: resultUri,
-                        text: resultString,
-                     },
-                  },
-               ];
-
-               if (renderLogs.length > 0) {
-                  return {
-                     isError: false,
-                     content: [
-                        ...content,
-                        {
-                           type: "text" as const,
-                           text: `Render tag warnings:\n${JSON.stringify(renderLogs, null, 2)}`,
-                        },
-                     ],
-                  };
-               }
-
-               return { isError: false, content };
-            } else if (queryName) {
-               const { result } = await runWithQueryTimeout(
-                  (abortSignal) =>
-                     model.getQueryResults(
-                        sourceName,
-                        queryName,
-                        undefined,
-                        filterParams,
-                        undefined,
-                        givens as Record<string, GivenValue> | undefined,
-                        abortSignal,
-                     ),
-                  getQueryTimeoutMs(),
-               );
-               const { validateRenderTags } = await import(
-                  "@malloydata/render-validator"
-               );
-               const renderLogs = validateRenderTags(result);
+            // Render-tag validation reads the FULL Malloy result: the tags live
+            // in its schema annotations, which the flat rows do not carry. It
+            // runs regardless of which shape is returned.
+            const { validateRenderTags } = await import(
+               "@malloydata/render-validator"
+            );
+            const renderLogs = validateRenderTags(result);
 
-               const baseUriComponents = {
+            const resultUri = buildMalloyUri(
+               {
                   environment: environmentName,
                   package: packageName,
                   resourceType: "models" as const,
                   resourceName: modelPath,
-               };
-               const resultUri = buildMalloyUri(baseUriComponents, "result");
-               const resultString = JSON.stringify(result, null, 2);
-
-               const content = [
-                  {
-                     type: "resource" as const,
-                     resource: {
-                        type: "application/json",
-                        uri: resultUri,
-                        text: resultString,
-                     },
-                  },
-               ];
+               },
+               "result",
+            );
 
-               if (renderLogs.length > 0) {
-                  return {
-                     isError: false,
-                     content: [
-                        ...content,
-                        {
-                           type: "text" as const,
-                           text: `Render tag warnings:\n${JSON.stringify(renderLogs, null, 2)}`,
-                        },
-                     ],
-                  };
-               }
+            const envelope = buildQueryEnvelope(
+               compactResult,
+               rowLimit,
+               result,
+               renderLogs.map((log) => log.message),
+               undefined,
+               rowLimitSource,
+            );
 
-               return { isError: false, content };
-            }
+            // A capped or truncated result, and a broken render tag, are the
+            // things an agent most needs to notice, so they are stated in text
+            // rather than left for a client that parses the payload.
+            const notes = [
+               envelope.warning,
+               envelope.renderLogErrors &&
+                  `Render tag problems: ${envelope.renderLogErrors.join("; ")}`,
+            ].filter(Boolean);
 
-            // If execution reaches this point, something has gone wrong with
-            // the earlier parameter validation logic. Throw an explicit error
-            // so the return type is never 'undefined' from the compiler's
-            // perspective.
-            throw new McpError(
-               ErrorCode.InternalError,
-               "Unreachable executeQuery code path – parameters were not validated correctly.",
-            );
+            return jsonResource(resultUri, envelope, {
+               space: 2,
+               // BigInt reaches here: compactResult is raw driver output and
+               // DuckDB returns count() as one.
+               replacer: bigIntReplacer,
+               text: notes.length > 0 ? notes.join("\n\n") : undefined,
+            });
          } catch (queryError) {
             // Handle query execution errors (syntax errors, invalid queries, etc.)
             logger.error(
@@ -306,29 +264,10 @@ export function registerExecuteQueryTool(
                );
             }
 
-            // Format error details as structured JSON
-            const errorJson = JSON.stringify(
-               {
-                  error: errorDetails.message,
-                  suggestions,
-               },
-               null,
-               2,
-            );
-            return {
-               isError: true,
-               // Return as application/json nested inside a 'resource' type
-               content: [
-                  {
-                     type: "resource", // Use 'resource' type
-                     resource: {
-                        type: "application/json", // Actual content type
-                        uri: "error://executeQuery/queryExecution", // Placeholder URI
-                        text: errorJson,
-                     },
-                  },
-               ],
-            };
+            return jsonToolError("error://executeQuery/queryExecution", {
+               message: errorDetails.message,
+               suggestions,
+            });
          } finally {
             // Release on every exit path — success, error, or
             // unreachable code-path throw. `release()` is idempotent

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,
             );
          }