@malloy-publisher/server 0.0.232 → 0.0.234

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

@@ -2,6 +2,7 @@ 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 type { ModelQueryMetadataInput } from "../../service/model";
 import {
    NotQueryableError,
    QueryTimeoutError,
@@ -13,7 +14,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 +33,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);
 }
 
 /**
@@ -60,6 +65,64 @@ function storeWhoseQueryThrows(error: unknown): Partial<EnvironmentStore> {
    };
 }
 
+/**
+ * A store whose query SUCCEEDS, capturing the per-query metadata input the tool
+ * built. `connections` becomes the environment's connection config, so a test
+ * can pin what the connection layers resolved to.
+ */
+function storeCapturingMetadata(
+   connections: Record<
+      string,
+      {
+         queryMetadata?: Record<string, string>;
+         queryMetadataEnforced?: Record<string, string>;
+      }
+   > = {},
+): {
+   store: Partial<EnvironmentStore>;
+   captured: () => ModelQueryMetadataInput | undefined;
+} {
+   let captured: ModelQueryMetadataInput | undefined;
+   const store: Partial<EnvironmentStore> = {
+      getEnvironment: async () =>
+         ({
+            assertCanAdmitQuery: () => undefined,
+            getApiConnection: (name: string) => {
+               const connection = connections[name];
+               if (!connection) throw new Error(`no connection ${name}`);
+               return connection;
+            },
+            getPackage: async () => ({
+               getModel: () => ({
+                  getModelType: () => "model",
+                  getModel: async () => ({}),
+                  getQueryResults: async (
+                     ..._args: [
+                        ...unknown[],
+                        ModelQueryMetadataInput | undefined,
+                     ]
+                  ) => {
+                     // The 8th argument: sourceName, queryName, query,
+                     // filterParams, bypassFilters, givens, abortSignal, input.
+                     captured = _args[7] as ModelQueryMetadataInput | undefined;
+                     return {
+                        result: {
+                           schema: { fields: [] },
+                           connection_name: "warehouse",
+                        },
+                        compactResult: [{ c: 1 }],
+                        rowLimit: 1000,
+                        rowLimitSource: "server_default",
+                        queryCorrelationId: "corr-1",
+                     };
+                  },
+               }),
+            }),
+         }) as never,
+   };
+   return { store, captured: () => captured };
+}
+
 const args = {
    environmentName: "env",
    packageName: "pkg",
@@ -140,4 +203,92 @@ 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);
+   });
+});
+
+describe("malloy_executeQuery per-query metadata", () => {
+   it("resolves the connection's enforced layer, which an agent must not be able to shed", async () => {
+      // The reason this path matters: `queryMetadataEnforced` is the property a
+      // host is billed or audited by, and MCP is this server's primary agent
+      // interface. A tool that omits the metadata input issues every one of its
+      // statements without the tenant label, on a connection whose config says
+      // it is applied to everything the connection sends.
+      const { store, captured } = storeCapturingMetadata({
+         warehouse: {
+            queryMetadata: { team: "finance" },
+            queryMetadataEnforced: { tenant: "acme" },
+         },
+      });
+      const handler = captureHandler(store);
+      await handler(args);
+
+      const layers = captured()?.connectionMetadata?.("warehouse");
+      expect(layers).toEqual({
+         default: { team: "finance" },
+         enforced: { tenant: "acme" },
+      });
+   });
+
+   it("passes the environment and mints a correlation id", async () => {
+      // Both arrive through the input object; neither is derivable inside Model.
+      const { store, captured } = storeCapturingMetadata();
+      const handler = captureHandler(store);
+      await handler(args);
+
+      expect(captured()?.environment).toBe("env");
+      expect(captured()?.correlationId).toMatch(/^[0-9a-f-]{36}$/);
+   });
+
+   it("returns the id the statements carried, so an agent can find its query", async () => {
+      const { store } = storeCapturingMetadata();
+      const handler = captureHandler(store);
+      const parsed = parse(await handler(args));
+      expect(parsed._query_id).toBe("corr-1");
+   });
+
+   it("fails open when the connection config cannot be read", async () => {
+      // A tag must never be the reason a query fails, so an unresolvable
+      // connection costs the layers rather than the statement.
+      const { store, captured } = storeCapturingMetadata();
+      const handler = captureHandler(store);
+      await handler(args);
+      expect(captured()?.connectionMetadata?.("missing")).toBeNull();
+   });
+
+   it("builds the same input for a named view as for ad-hoc Malloy", async () => {
+      // Two call sites, one input: the enforced layer cannot depend on which
+      // shape of query the agent happened to send.
+      const { store, captured } = storeCapturingMetadata({
+         warehouse: { queryMetadataEnforced: { tenant: "acme" } },
+      });
+      const handler = captureHandler(store);
+      await handler({
+         environmentName: "env",
+         packageName: "pkg",
+         modelPath: "m.malloy",
+         sourceName: "orders",
+         queryName: "by_month",
+      });
+
+      expect(captured()?.environment).toBe("env");
+      expect(captured()?.connectionMetadata?.("warehouse")).toEqual({
+         default: undefined,
+         enforced: { tenant: "acme" },
+      });
+   });
 });

package/src/mcp/tools/execute_query_tool.ts

@@ -16,6 +16,10 @@ import {
    classifyToolError,
    getModelForQuery,
 } from "../handler_utils";
+import { jsonResource, jsonToolError } from "../tool_response";
+import { buildQueryEnvelope } from "../query_envelope";
+import { mintCorrelationId } from "../../service/query_metadata";
+import { bigIntReplacer } from "../../json_utils";
 import { MCP_ERROR_MESSAGES } from "../mcp_constants";
 
 /**
@@ -61,6 +65,27 @@ 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.
+- _query_id: this query's id in the warehouse's own query history. Present only where enabled.
+- 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 +97,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,33 +145,14 @@ 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 ---
-         const { model } = modelResult;
+         const { model, environment } = modelResult;
          logger.info(
             `[MCP Tool executeQuery] Model found. Proceeding to execute query.`,
          );
@@ -160,123 +166,112 @@ 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(
-                  (abortSignal) =>
-                     model.getQueryResults(
-                        undefined,
-                        undefined,
-                        query,
-                        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)}`,
-                        },
-                     ],
-                  };
-               }
+            // Per-query metadata, built the same way the HTTP query controller
+            // builds it: MCP is a query boundary like any other, and a
+            // connection's enforced properties describe the deployment rather
+            // than the protocol a query arrived over.
+            const queryMetadataInput = {
+               environment: environmentName,
+               // Minted here because the envelope below returns it.
+               correlationId: mintCorrelationId(),
+               // The environment owns the connection configs, so the default
+               // and enforced layers are read here rather than from the model.
+               connectionMetadata: (connectionName: string) => {
+                  try {
+                     const connection =
+                        environment.getApiConnection(connectionName);
+                     return {
+                        default: connection.queryMetadata,
+                        enforced: connection.queryMetadataEnforced,
+                     };
+                  } catch (error) {
+                     logger.debug(
+                        "[MCP Tool executeQuery] No query-metadata layers for connection",
+                        { connectionName, error },
+                     );
+                     return null;
+                  }
+               },
+            };
+            // 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,
+               queryCorrelationId,
+            } = await runWithQueryTimeout(
+               (abortSignal) =>
+                  query
+                     ? model.getQueryResults(
+                          undefined,
+                          undefined,
+                          query,
+                          filterParams,
+                          undefined,
+                          givens as Record<string, GivenValue> | undefined,
+                          abortSignal,
+                          queryMetadataInput,
+                       )
+                     : model.getQueryResults(
+                          sourceName,
+                          queryName,
+                          undefined,
+                          filterParams,
+                          undefined,
+                          givens as Record<string, GivenValue> | undefined,
+                          abortSignal,
+                          queryMetadataInput,
+                       ),
+               getQueryTimeoutMs(),
+            );
 
-               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,
+               queryCorrelationId,
+            );
 
-               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 +301,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