@malloy-publisher/server 0.0.225 → 0.0.227

package/src/mcp/tools/docs_search_tool.ts

@@ -86,7 +86,7 @@ const SEARCH_DOCS_DESCRIPTION = `Search the Malloy documentation by keyword and
 
 ## When to use
 - 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 or malloy_modelGetText for that.
+- Do NOT use it to look up field or source names in a model; use malloy_getContext for that.
 
 ## Parameters
 - query (required): keywords describing what you need.

package/src/mcp/tools/execute_query_tool.ts

@@ -20,12 +20,12 @@ const executeQueryShape = {
    environmentName: z
       .string()
       .describe(
-         "Environment name. Names are listed in the malloy resource list.",
+         "Environment name. Call malloy_getContext with no arguments to list the available environments.",
       ),
    packageName: z
       .string()
       .describe(
-         "Package containing the model. Package names are listed in the malloy resource list.",
+         "Package containing the model. Call malloy_getContext with just environmentName to list its packages.",
       ),
    modelPath: z.string().describe("Path to the .malloy model file"),
    query: z.string().optional().describe("Ad-hoc Malloy query code"),

package/src/mcp/tools/get_context_eval.ts

@@ -1,7 +1,7 @@
 /**
  * Lexical-baseline eval for malloy_getContext.
  *
- * Runs a labeled set of plain-English queries against the live agent MCP endpoint
+ * Runs a labeled set of plain-English queries against the live MCP endpoint
  * and reports recall@K: whether the expected entity appears in the top-K results.
  * This establishes the lexical (lunr/BM25) baseline so retrieval quality is
  * measurable; an embeddings comparison is deferred to if/when an embedding
@@ -9,7 +9,7 @@
  *
  *   bun run packages/server/src/mcp/tools/get_context_eval.ts [K]
  *
- * Targets AGENT_MCP_URL (default http://localhost:4041/mcp) over the demo
+ * Targets MCP_URL (default http://localhost:4040/mcp) over the demo
  * environment (EVAL_ENV, default "samples"); start the server first.
  */
 
@@ -44,7 +44,7 @@ const CASES: EvalCase[] = [
    { pkg: "faa", query: "departure delay", expect: "delay" },
 ];
 
-const ENDPOINT = process.env.AGENT_MCP_URL || "http://localhost:4041/mcp";
+const ENDPOINT = process.env.MCP_URL || "http://localhost:4040/mcp";
 const EVAL_ENV = process.env.EVAL_ENV || "samples";
 const K = Number(process.argv[2] || 5);
 

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

@@ -1,5 +1,6 @@
 import { describe, expect, it } from "bun:test";
-import { docText, sanitize } from "./get_context_tool";
+import { docText, sanitize, registerGetContextTool } from "./get_context_tool";
+import type { EnvironmentStore } from "../../service/environment_store";
 
 describe("get_context docText", () => {
    it("extracts #(doc) text from annotation lines", () => {
@@ -42,3 +43,197 @@ 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 Handler = (params: Record<string, unknown>) => Promise<{
+   isError?: boolean;
+   content: Array<{ resource: { text: string } }>;
+}>;
+
+function captureHandler(store: Partial<EnvironmentStore>): Handler {
+   let handler: Handler | undefined;
+   const fakeServer = {
+      tool: (_name: string, _desc: string, _shape: unknown, h: Handler) => {
+         handler = h;
+      },
+   };
+   registerGetContextTool(fakeServer as never, store as EnvironmentStore);
+   if (!handler) throw new Error("handler was not registered");
+   return handler;
+}
+
+function parse(result: { content: Array<{ resource: { text: string } }> }) {
+   return JSON.parse(result.content[0].resource.text);
+}
+
+// A model with one source (order_items) carrying one dimension (state).
+const mockModel = {
+   getSourceInfos: () => [
+      {
+         name: "order_items",
+         annotations: [],
+         schema: {
+            fields: [{ kind: "dimension", name: "state", annotations: [] }],
+         },
+      },
+   ],
+   getQueries: () => [],
+};
+const mockPackage = {
+   listModels: async () => [{ path: "ecommerce.malloy" }],
+   getModel: () => mockModel,
+};
+
+// A package with more than 10 sources, to prove the enumeration tier is not
+// silently capped the way ranked retrieval is.
+const manySourceNames = Array.from({ length: 12 }, (_, i) => `s${i}`);
+const mockManySourceModel = {
+   getSourceInfos: () =>
+      manySourceNames.map((name) => ({
+         name,
+         annotations: [],
+         schema: { fields: [] },
+      })),
+   getQueries: () => [],
+};
+const mockManySourcePackage = {
+   listModels: async () => [{ path: "many.malloy" }],
+   getModel: () => mockManySourceModel,
+};
+
+describe("get_context discovery tiers", () => {
+   it("tier 1: no environment lists environments with their package names", async () => {
+      const handler = captureHandler({
+         listEnvironments: async () =>
+            [
+               {
+                  name: "malloy-samples",
+                  packages: [{ name: "ecommerce" }, { name: "imdb" }],
+               },
+            ] as never,
+      });
+      const { results } = parse(await handler({}));
+      expect(results).toEqual([
+         {
+            kind: "environment",
+            name: "malloy-samples",
+            packages: ["ecommerce", "imdb"],
+         },
+      ]);
+   });
+
+   it("tier 2: environment without a package lists the packages", async () => {
+      const handler = captureHandler({
+         getEnvironment: async () =>
+            ({
+               listPackages: async () => [
+                  { name: "ecommerce", description: "Ecommerce demo" },
+               ],
+            }) as never,
+      });
+      const { results } = parse(
+         await handler({ environmentName: "malloy-samples" }),
+      );
+      expect(results).toEqual([
+         {
+            kind: "package",
+            name: "ecommerce",
+            description: "Ecommerce demo",
+            environmentName: "malloy-samples",
+         },
+      ]);
+   });
+
+   it("tier 2: surfaces an unresolved environment as a tool error", async () => {
+      const handler = captureHandler({
+         getEnvironment: async () => {
+            throw new Error("Environment 'nope' could not be resolved");
+         },
+      });
+      const result = await handler({ environmentName: "nope" });
+      expect(result.isError).toBe(true);
+      const parsed = parse(result);
+      expect(parsed.results).toEqual([]);
+      expect(parsed.error).toContain("could not be resolved");
+   });
+
+   it("tier 3: package without a query lists only its sources", async () => {
+      const handler = captureHandler({
+         getEnvironment: async () =>
+            ({ getPackage: async () => mockPackage }) as never,
+      });
+      const { results } = parse(
+         await handler({
+            environmentName: "malloy-samples",
+            packageName: "ecommerce",
+         }),
+      );
+      expect(results).toEqual([
+         {
+            kind: "source",
+            name: "order_items",
+            source: "order_items",
+            environmentName: "malloy-samples",
+            packageName: "ecommerce",
+            modelPath: "ecommerce.malloy",
+            doc: "",
+         },
+      ]);
+   });
+
+   it("tier 4: a query retrieves the matching entity", async () => {
+      const handler = captureHandler({
+         getEnvironment: async () =>
+            ({ getPackage: async () => mockPackage }) as never,
+      });
+      const { results } = parse(
+         await handler({
+            environmentName: "malloy-samples",
+            packageName: "ecommerce",
+            query: "state",
+         }),
+      );
+      expect(
+         results.some(
+            (r: { name: string; kind: string }) =>
+               r.name === "state" && r.kind === "dimension",
+         ),
+      ).toBe(true);
+   });
+
+   it("tier 1: surfaces a listEnvironments failure as a tool error", async () => {
+      const handler = captureHandler({
+         listEnvironments: async () => {
+            throw new Error("environment store not initialized");
+         },
+      });
+      const result = await handler({});
+      expect(result.isError).toBe(true);
+      const parsed = parse(result);
+      expect(parsed.results).toEqual([]);
+      expect(parsed.error).toContain("not initialized");
+   });
+
+   it("tier 3: lists every source, not just the first 10", async () => {
+      const handler = captureHandler({
+         getEnvironment: async () =>
+            ({ getPackage: async () => mockManySourcePackage }) as never,
+      });
+      const { results } = parse(
+         await handler({ environmentName: "e", packageName: "p" }),
+      );
+      expect(results).toHaveLength(12);
+   });
+
+   it("tier 3: honors an explicit limit when given", async () => {
+      const handler = captureHandler({
+         getEnvironment: async () =>
+            ({ getPackage: async () => mockManySourcePackage }) as never,
+      });
+      const { results } = parse(
+         await handler({ environmentName: "e", packageName: "p", limit: 5 }),
+      );
+      expect(results).toHaveLength(5);
+   });
+});

package/src/mcp/tools/get_context_tool.ts

@@ -24,19 +24,20 @@ interface Entity {
 const getContextShape = {
    environmentName: z
       .string()
-      .describe(
-         "Environment name. Names are listed in the malloy_environmentList tool.",
-      ),
+      .optional()
+      .describe("Environment name. Omit to list the available environments."),
    packageName: z
       .string()
+      .optional()
       .describe(
-         "Package name. Package names are listed in malloy_packageList.",
+         "Package name. Omit, with environmentName set, to list the packages in that environment.",
       ),
    query: z
       .string()
       .max(500)
+      .optional()
       .describe(
-         'Plain-English description of what you need, e.g. "revenue by product category" or "customer churn".',
+         'Plain-English description of what you need, e.g. "revenue by product category". Omit, with environmentName and packageName set, to list the package\'s sources.',
       ),
    sourceName: z
       .string()
@@ -50,7 +51,9 @@ const getContextShape = {
       .positive()
       .max(50)
       .optional()
-      .describe("Maximum number of entities to return. Default 10, max 50."),
+      .describe(
+         "Maximum results to return (max 50). Ranked retrieval defaults to 10; the listing tiers return everything unless you set this.",
+      ),
 };
 type GetContextParams = z.infer<z.ZodObject<typeof getContextShape>>;
 
@@ -203,33 +206,58 @@ async function getPackageIndex(
    return built;
 }
 
-const GET_CONTEXT_DESCRIPTION = `Retrieve the model entities (sources, views, named queries, and dimension/measure fields) most relevant to a plain-English question, so you can ground a query in what the model actually defines instead of guessing.
+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.
 
-## When to use
-- Before writing a query, to find which source and which prebuilt views fit the question.
-- Two-phase: call once with just a query to discover the most relevant sources and views (discovery), then optionally call again with sourceName set to focus on one source (drill-down).
+## 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.
 
 ## Parameters
-- environmentName, packageName (required): where to look.
-- query (required): a plain-English description of what you need.
-- sourceName (optional): narrow to entities within one source.
-- limit (optional): maximum entities to return; default 10.
+- 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.
 
 ## Response
-A JSON object with results: a ranked list of entities, each with kind (source / view / query / dimension / measure), name, source, modelPath, and doc. The environmentName, packageName, modelPath, and source map directly onto malloy_executeQuery parameters; for a view or named query, pass its name as queryName with sourceName.
+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.
 
 ## Contract rules
-- Use the names verbatim; do not invent entities not in the results.
-- Results include field-level dimensions and measures. If you need the full field list of a source or want to confirm exact spelling, read the model with malloy_modelGetText on the modelPath this returns.
+- 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": "samples", "packageName": "ecommerce", "query": "revenue by product category" }`;
+{ "environmentName": "malloy-samples", "packageName": "ecommerce", "query": "revenue by product category" }`;
 
 /**
- * Registers the malloy_getContext MCP tool: lexical (lunr/BM25) retrieval over a
- * package's model entities (sources, views, dimension/measure fields, named
- * queries). The entity index is built once per Package and cached (see
- * getPackageIndex), rebuilding automatically when the package reloads.
+ * 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).
+ */
+function jsonResource(uri: string, payload: unknown, isError = false) {
+   const content = [
+      {
+         type: "resource" as const,
+         resource: {
+            type: "application/json",
+            uri,
+            text: JSON.stringify(payload),
+         },
+      },
+   ];
+   return isError ? { isError: true, content } : { content };
+}
+
+/**
+ * Registers the malloy_getContext MCP tool. It is a progressive-discovery tool:
+ * with no environment it lists environments, with an environment but no package
+ * it lists packages, with a package but no query it lists the package's sources,
+ * and with a query it runs lexical (lunr/BM25) retrieval over the package's model
+ * entities (sources, views, dimension/measure fields, named queries). The entity
+ * index is built once per Package and cached (see getPackageIndex), rebuilding
+ * automatically when the package reloads.
  */
 export function registerGetContextTool(
    mcpServer: McpServer,
@@ -251,6 +279,76 @@ export function registerGetContextTool(
             limit,
          });
 
+         // Tier 1: no environment -> enumerate the available environments, each
+         // with its package names, so an agent with no prior knowledge can start.
+         if (!environmentName) {
+            try {
+               const environments = await environmentStore.listEnvironments();
+               const results = environments.map((env) => ({
+                  kind: "environment" as const,
+                  name: env.name,
+                  packages: (env.packages ?? [])
+                     .map((p) => p.name)
+                     .filter((n): n is string => Boolean(n)),
+               }));
+               return jsonResource(buildMalloyUri({}, "get-context"), {
+                  results,
+               });
+            } catch (error) {
+               const message =
+                  error instanceof Error ? error.message : "Unknown error";
+               logger.warn(
+                  "[MCP Tool getContext] listing environments failed",
+                  { error: message },
+               );
+               return jsonResource(
+                  buildMalloyUri({}, "get-context"),
+                  { error: message, results: [] },
+                  true,
+               );
+            }
+         }
+
+         // Tier 2: environment but no package -> enumerate its packages.
+         if (!packageName) {
+            try {
+               const environment = await environmentStore.getEnvironment(
+                  environmentName,
+                  false,
+               );
+               const packages = await environment.listPackages();
+               const results = packages.map((pkg) => ({
+                  kind: "package" as const,
+                  name: pkg.name,
+                  description: pkg.description,
+                  environmentName,
+               }));
+               return jsonResource(
+                  buildMalloyUri(
+                     { environment: environmentName },
+                     "get-context",
+                  ),
+                  { results },
+               );
+            } catch (error) {
+               const message =
+                  error instanceof Error ? error.message : "Unknown error";
+               logger.warn("[MCP Tool getContext] listing packages failed", {
+                  environmentName,
+                  error: message,
+               });
+               return jsonResource(
+                  buildMalloyUri(
+                     { environment: environmentName },
+                     "get-context",
+                  ),
+                  { error: message, results: [] },
+                  true,
+               );
+            }
+         }
+
+         // Tiers 3 and 4 need the package's entity index.
          let pkgIndex: PackageIndex;
          try {
             pkgIndex = await getPackageIndex(
@@ -267,41 +365,55 @@ export function registerGetContextTool(
                sourceName,
                error: message,
             });
-            return {
-               isError: true,
-               content: [
-                  {
-                     type: "resource" as const,
-                     resource: {
-                        type: "application/json",
-                        uri: buildMalloyUri(
-                           {
-                              environment: environmentName,
-                              package: packageName,
-                           },
-                           "get-context",
-                        ),
-                        text: JSON.stringify({ error: message, results: [] }),
-                     },
-                  },
-               ],
-            };
+            return jsonResource(
+               buildMalloyUri(
+                  { environment: environmentName, package: packageName },
+                  "get-context",
+               ),
+               { error: message, results: [] },
+               true,
+            );
          }
 
          const { byId, index } = pkgIndex;
+         const uri = buildMalloyUri(
+            { environment: environmentName, package: packageName },
+            "get-context",
+         );
 
-         const sanitized = sanitize(query);
+         // Tier 3: package but no query -> list the package's sources as an
+         // overview the agent can then query or drill into.
+         const sanitized = query ? sanitize(query) : "";
+         if (!sanitized) {
+            // Enumeration: return every source unless the caller sets an explicit
+            // limit. slice(0, undefined) keeps the whole list, so discovery is
+            // not silently capped the way ranked retrieval (tier 4) is.
+            const results = Array.from(byId.values())
+               .filter((e) => e.kind === "source")
+               .filter((e) => !sourceName || e.source === sourceName)
+               .slice(0, limit)
+               .map((e) => ({
+                  kind: e.kind,
+                  name: e.name,
+                  source: e.source,
+                  environmentName,
+                  packageName,
+                  modelPath: e.modelPath,
+                  doc: e.doc,
+               }));
+            return jsonResource(uri, { results });
+         }
+
+         // Tier 4: retrieval over the package's entities.
          let hits: lunr.Index.Result[] = [];
-         if (sanitized) {
-            try {
-               hits = index.search(sanitized);
-            } catch (error) {
-               logger.warn("[MCP Tool getContext] lunr search failed", {
-                  query,
-                  error: error instanceof Error ? error.message : String(error),
-               });
-               hits = [];
-            }
+         try {
+            hits = index.search(sanitized);
+         } catch (error) {
+            logger.warn("[MCP Tool getContext] lunr search failed", {
+               query,
+               error: error instanceof Error ? error.message : String(error),
+            });
+            hits = [];
          }
 
          // Defensive: skip any hit whose ref is missing from the entity map.
@@ -321,21 +433,7 @@ export function registerGetContextTool(
                doc: e.doc,
             }));
 
-         return {
-            content: [
-               {
-                  type: "resource" as const,
-                  resource: {
-                     type: "application/json",
-                     uri: buildMalloyUri(
-                        { environment: environmentName, package: packageName },
-                        "get-context",
-                     ),
-                     text: JSON.stringify({ results }),
-                  },
-               },
-            ],
-         };
+         return jsonResource(uri, { results });
       },
    );
 }

package/src/package_load/package_load_pool.ts

@@ -81,7 +81,10 @@ import { fileURLToPath, pathToFileURL } from "url";
 
 import { ModelCompilationError } from "../errors";
 import { logger } from "../logger";
-import type { PackageMaterializationConfig } from "../service/package_manifest";
+import type {
+   PackageMaterializationConfig,
+   PackageScope,
+} from "../service/package_manifest";
 import type {
    ConnectionMetadataRequest,
    ConnectionMetadataResponse,
@@ -235,6 +238,7 @@ export interface LoadPackageOutcome {
       queryableSources?: "declared" | "all";
       manifestLocation?: string | null;
       materialization?: PackageMaterializationConfig | null;
+      scope?: PackageScope;
    };
    models: Array<
       Omit<SerializedModel, "modelDef" | "sourceInfos"> & {
@@ -243,6 +247,8 @@ export interface LoadPackageOutcome {
       }
    >;
    loadDurationMs: number;
+   /** Per-load phase timing breakdown (see {@link LoadPackageResult.timings}). */
+   timings: LoadPackageResult["timings"];
 }
 
 // ──────────────────────────────────────────────────────────────────────
@@ -840,6 +846,7 @@ function adaptResult(result: LoadPackageResult): LoadPackageOutcome {
          sourceInfos: m.sourceInfos as Malloy.SourceInfo[] | undefined,
       })),
       loadDurationMs: result.loadDurationMs,
+      timings: result.timings,
    };
 }