@malloy-publisher/server 0.0.226 → 0.0.228

package/src/ducklake_version.spec.ts

@@ -1,43 +0,0 @@
-import { describe, expect, it } from "bun:test";
-import {
-   isCatalogVersionSupported,
-   SUPPORTED_CATALOG_VERSIONS,
-} from "./ducklake_version";
-
-describe("ducklake_version", () => {
-   describe("SUPPORTED_CATALOG_VERSIONS", () => {
-      it("matches the 0.3-line DuckLake extension's internal list", () => {
-         expect([...SUPPORTED_CATALOG_VERSIONS]).toEqual([
-            "0.1",
-            "0.2",
-            "0.3-dev1",
-            "0.3",
-         ]);
-      });
-   });
-
-   describe("isCatalogVersionSupported", () => {
-      it("accepts each documented 0.3-line version", () => {
-         for (const v of SUPPORTED_CATALOG_VERSIONS) {
-            expect(isCatalogVersionSupported(v)).toBe(true);
-         }
-      });
-
-      it("rejects 1.0-line versions", () => {
-         expect(isCatalogVersionSupported("1.0")).toBe(false);
-         expect(isCatalogVersionSupported("1.0.0")).toBe(false);
-         expect(isCatalogVersionSupported("1.1.0")).toBe(false);
-      });
-
-      it("rejects newer pre-1.0 versions not in the supported list", () => {
-         expect(isCatalogVersionSupported("0.4")).toBe(false);
-         expect(isCatalogVersionSupported("0.3-dev2")).toBe(false);
-      });
-
-      it("rejects empty and malformed input without throwing", () => {
-         expect(isCatalogVersionSupported("")).toBe(false);
-         expect(isCatalogVersionSupported("not a version")).toBe(false);
-         expect(isCatalogVersionSupported("0.3 ")).toBe(false);
-      });
-   });
-});

package/src/ducklake_version.ts

@@ -1,26 +0,0 @@
-// DuckLake catalog format compatibility check. Lives at `src/` root so
-// both `service/` (user-facing connections) and `storage/` (materialization
-// catalog) can pre-flight a catalog's recorded version without bringing in
-// the other layer's helpers. See CLAUDE.md's "Two parallel DuckLake/PG
-// attach paths" note.
-//
-// The Publisher Docker image bakes a specific DuckLake extension version at
-// build time (see Dockerfile). If a catalog's on-disk format version is
-// newer than what the baked extension supports, ATTACH fails deep inside
-// DuckDB with a generic 500. The preflight catches that case and surfaces
-// it as a non-retryable 422 instead.
-
-// Versions the currently-baked DuckLake extension (0.3 line, paired with
-// duckdb@1.4.4) can read. When the Publisher upgrades to the DuckLake 1.0
-// line (separate PR, requires duckdb@1.5+), extend this list to include
-// "1.0" and later format versions.
-export const SUPPORTED_CATALOG_VERSIONS: readonly string[] = [
-   "0.1",
-   "0.2",
-   "0.3-dev1",
-   "0.3",
-];
-
-export function isCatalogVersionSupported(version: string): boolean {
-   return SUPPORTED_CATALOG_VERSIONS.includes(version);
-}

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

@@ -1,78 +0,0 @@
-import { beforeAll, describe, expect, it } from "bun:test";
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
-import { initializeAgentMcpServer } from "./agent_server";
-import type { EnvironmentStore } from "../service/environment_store";
-
-/**
- * End-to-end coverage of the agent MCP server over the real MCP protocol, using
- * the SDK's in-memory transport (no HTTP, no network, no DuckDB). Exercises tool
- * registration, the dual-channel prompts, a real tool call (searchDocs over the
- * bundled index), and the getContext error path.
- */
-describe("agent MCP server over the MCP protocol (in-memory)", () => {
-   let client: Client;
-
-   beforeAll(async () => {
-      // searchDocs does not touch the store; getContext's error path only needs
-      // getEnvironment to reject, so a throwing stub is sufficient here.
-      const stubStore = {
-         getEnvironment: async (name: string): Promise<never> => {
-            throw new Error(`Environment not found: ${name}`);
-         },
-      } as unknown as EnvironmentStore;
-
-      const server = initializeAgentMcpServer(stubStore);
-      const [clientTransport, serverTransport] =
-         InMemoryTransport.createLinkedPair();
-      await server.connect(serverTransport);
-      client = new Client({ name: "agent-protocol-test", version: "0.0.0" });
-      await client.connect(clientTransport);
-   });
-
-   it("exposes exactly the two agent tools", async () => {
-      const { tools } = await client.listTools();
-      expect(new Set(tools.map((t) => t.name))).toEqual(
-         new Set(["malloy_getContext", "malloy_searchDocs"]),
-      );
-   });
-
-   it("exposes the skill set as dual-channel prompts", async () => {
-      const { prompts } = await client.listPrompts();
-      expect(prompts.length).toBeGreaterThanOrEqual(24);
-      expect(prompts.some((p) => p.name === "malloy-analysis")).toBe(true);
-   });
-
-   it("malloy_searchDocs returns relevant docs over the protocol", async () => {
-      const res = await client.callTool({
-         name: "malloy_searchDocs",
-         arguments: { query: "window functions" },
-      });
-      const content = res.content as Array<{ resource?: { text?: string } }>;
-      const results = JSON.parse(
-         content?.[0]?.resource?.text ?? "[]",
-      ) as Array<{
-         url: string;
-      }>;
-      expect(results.length).toBeGreaterThan(0);
-      expect(results[0].url.length).toBeGreaterThan(0);
-   });
-
-   it("malloy_getContext fails gracefully (isError) for an unknown environment", async () => {
-      const res = await client.callTool({
-         name: "malloy_getContext",
-         arguments: {
-            environmentName: "nope",
-            packageName: "nope",
-            query: "x",
-         },
-      });
-      expect(res.isError).toBe(true);
-   });
-
-   it("a skill prompt returns its body", async () => {
-      const res = await client.getPrompt({ name: "malloy-analysis" });
-      const content = res.messages[0].content as { text?: string };
-      expect((content.text ?? "").length).toBeGreaterThan(200);
-   });
-});

package/src/mcp/agent_server.spec.ts

@@ -1,18 +0,0 @@
-import { describe, expect, it } from "bun:test";
-import { agentServerInfo, initializeAgentMcpServer } from "./agent_server";
-import type { EnvironmentStore } from "../service/environment_store";
-
-describe("agent MCP server", () => {
-   it("advertises a distinct server name from the core MCP server", () => {
-      expect(agentServerInfo.name).toBe("malloy-publisher-agent-mcp-server");
-   });
-
-   it("initializes and registers its tools and skill prompts without throwing", () => {
-      // The store is captured for later handler calls, not used during
-      // registration, so a placeholder is sufficient for this smoke test.
-      const server = initializeAgentMcpServer(
-         {} as unknown as EnvironmentStore,
-      );
-      expect(server).toBeTruthy();
-   });
-});

package/src/mcp/agent_server.ts

@@ -1,144 +0,0 @@
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import cors from "cors";
-import express from "express";
-import * as http from "http";
-import { registerHealthEndpoints } from "../health";
-import { logger } from "../logger";
-import { EnvironmentStore } from "../service/environment_store";
-import { registerDocsSearchTool } from "./tools/docs_search_tool";
-import { registerGetContextTool } from "./tools/get_context_tool";
-import skillsBundle from "./skills/skills_bundle.json";
-
-const AGENT_MCP_ENDPOINT = "/mcp";
-
-// Build-time bundle of the agent skills (see skills/build_skills_bundle.ts), exposed
-// as MCP prompts for the dual-channel delivery below.
-const AGENT_SKILLS = (
-   skillsBundle as {
-      skills: { name: string; description: string; body: string }[];
-   }
-).skills;
-
-export const agentServerInfo = {
-   name: "malloy-publisher-agent-mcp-server",
-   version: "0.0.1",
-   displayName: "Malloy Publisher Agent MCP Server",
-   description:
-      "Agent retrieval tools (semantic model context and docs search) for Malloy, served on a separate MCP endpoint from the core Publisher MCP tools.",
-};
-
-/**
- * Builds an MCP server exposing ONLY the agent retrieval tools (malloy_getContext,
- * malloy_searchDocs). Kept deliberately separate from the core initializeMcpServer so
- * these tools and their tests stay isolated from the existing MCP tool surface.
- */
-export function initializeAgentMcpServer(
-   environmentStore: EnvironmentStore,
-): McpServer {
-   const mcpServer = new McpServer(agentServerInfo);
-   registerGetContextTool(mcpServer, environmentStore);
-   registerDocsSearchTool(mcpServer, environmentStore);
-
-   // Dual-channel: also expose each skill as an MCP prompt, so hosts that ingest MCP
-   // but do not load skill files (e.g. Codex, ChatGPT, Cursor) can pull the same
-   // guidance. Skill-aware hosts (Claude Code/Desktop) use the native skill files.
-   // Note: MCP prompts are on-demand, so always-on "prevention" skills become
-   // on-demand here; see docs/agent-skills/design-principles.md.
-   for (const skill of AGENT_SKILLS) {
-      mcpServer.prompt(skill.name, skill.description, () => ({
-         messages: [
-            {
-               role: "user" as const,
-               content: { type: "text" as const, text: skill.body },
-            },
-         ],
-      }));
-   }
-
-   return mcpServer;
-}
-
-/**
- * Starts the agent MCP server on its own HTTP listener (a third Publisher listener),
- * using the same stateless StreamableHTTP transport pattern as the core MCP server.
- * Returns the http.Server so the caller can manage shutdown.
- */
-export function startAgentMcpServer(
-   environmentStore: EnvironmentStore,
-   host: string,
-   port: number,
-): http.Server {
-   const agentMcpApp = express();
-   registerHealthEndpoints(agentMcpApp);
-   agentMcpApp.use(AGENT_MCP_ENDPOINT, express.json());
-   agentMcpApp.use(AGENT_MCP_ENDPOINT, cors());
-
-   agentMcpApp.all(AGENT_MCP_ENDPOINT, async (req, res) => {
-      if (req.method !== "POST") {
-         res.setHeader("Allow", "POST");
-         res.status(405).json({
-            jsonrpc: "2.0",
-            error: {
-               code: -32601,
-               message: "Method Not Allowed in Stateless Mode",
-            },
-            id: null,
-         });
-         return;
-      }
-
-      try {
-         const transport = new StreamableHTTPServerTransport({
-            sessionIdGenerator: undefined,
-         });
-         transport.onerror = (err: Error) => {
-            logger.error("[Agent MCP Transport Error]", {
-               error: err instanceof Error ? err.message : String(err),
-            });
-         };
-         const requestMcpServer = initializeAgentMcpServer(environmentStore);
-         await requestMcpServer.connect(transport);
-         res.on("close", () => {
-            transport.close().catch((err) => {
-               logger.error("[Agent MCP Transport Error] close failed", {
-                  error: err instanceof Error ? err.message : String(err),
-               });
-            });
-         });
-         await transport.handleRequest(req, res, req.body);
-      } catch (err) {
-         logger.error("[Agent MCP] request handler error", {
-            error: err instanceof Error ? err.message : String(err),
-         });
-         if (!res.headersSent) {
-            res.status(500).json({
-               jsonrpc: "2.0",
-               error: { code: -32603, message: "Internal server error" },
-               id: null,
-            });
-         }
-      }
-   });
-
-   const agentMcpServer = agentMcpApp.listen(port, host, () => {
-      logger.info(
-         `Agent MCP server listening at http://${host}:${port}${AGENT_MCP_ENDPOINT}`,
-      );
-   });
-
-   // The agent MCP server is auxiliary: a bind failure here (e.g. EADDRINUSE)
-   // must not take down the main API or the core MCP server. Without this
-   // handler the listener's 'error' event would surface as an uncaught
-   // exception and crash the whole process at boot. Log and degrade instead.
-   agentMcpServer.on("error", (err: NodeJS.ErrnoException) => {
-      logger.error("Agent MCP server failed to start; continuing without it", {
-         host,
-         port,
-         code: err.code,
-         error: err.message,
-      });
-   });
-
-   return agentMcpServer;
-}

package/src/mcp/prompts/handlers.ts

@@ -1,84 +0,0 @@
-import Handlebars from "handlebars";
-import { z } from "zod";
-import {
-   PromptMessageSchema,
-   GetPromptResultSchema,
-} from "@modelcontextprotocol/sdk/types.js";
-import { PROMPTS } from "./prompt_definitions";
-import { getCompiledModel } from "./utils";
-import { EnvironmentStore } from "../../service/environment_store";
-
-/* eslint-disable @typescript-eslint/no-explicit-any */
-
-/* --------------------------------------------------------------------------
- * Helper – create a simple text prompt message
- * ----------------------------------------------------------------------- */
-
-const textMsg = (text: string): z.infer<typeof PromptMessageSchema> => ({
-   role: "user",
-   content: { type: "text", text },
-});
-
-/* --------------------------------------------------------------------------
- * makePromptHandler – higher-order factory
- * ----------------------------------------------------------------------- */
-
-export function makePromptHandler(id: string) {
-   const def = PROMPTS[id];
-   if (!def) throw new Error(`Unknown prompt id: ${id}`);
-
-   // pre-compile Handlebars template
-   const templateFn = Handlebars.compile(def.template, { noEscape: true });
-
-   // eslint-disable-next-line @typescript-eslint/no-explicit-any
-   return async (params: any, ps: EnvironmentStore) => {
-      const data: Record<string, unknown> = { ...params };
-
-      // Dynamically add model content / schema context if the args include URIs
-      if (ps) {
-         if (typeof params?.model_uri === "string") {
-            const compiled = await getCompiledModel(params.model_uri, ps);
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            (data as any).model_def_content = (compiled as any).modelDef;
-         }
-         if (typeof params?.target_model_uri === "string") {
-            const compiled = await getCompiledModel(
-               params.target_model_uri,
-               ps,
-            );
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            (data as any).schema_context = (compiled as any).modelInfo;
-         }
-         if (typeof params?.model_context_uri === "string") {
-            const compiled = await getCompiledModel(
-               params.model_context_uri,
-               ps,
-            );
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            (data as any).schema_context = (compiled as any).modelInfo;
-         }
-      }
-
-      const rendered = templateFn(data);
-
-      return {
-         messages: [textMsg(rendered)],
-         // Ensure shape matches SDK schema
-      } as z.infer<typeof GetPromptResultSchema>;
-   };
-}
-
-/* --------------------------------------------------------------------------
- * Registry – id -> handler
- * ----------------------------------------------------------------------- */
-
-export const promptHandlerMap = Object.fromEntries(
-   Object.keys(PROMPTS).map((id) => [id, makePromptHandler(id)]),
-) as Record<
-   string,
-   // eslint-disable-next-line @typescript-eslint/no-explicit-any
-   (
-      params: any,
-      ps: EnvironmentStore,
-   ) => Promise<z.infer<typeof GetPromptResultSchema>>
->;

package/src/mcp/prompts/index.ts

@@ -1,11 +0,0 @@
-export {
-   withVersion,
-   PROMPTS,
-   MALLOY_PROMPTS,
-   ExplainArgsSchema,
-   GenerateQueryArgsSchema,
-   TranslateSqlArgsSchema,
-   SummarizeModelArgsSchema,
-} from "./prompt_definitions";
-export { promptHandlerMap, makePromptHandler } from "./handlers";
-export { registerPromptCapability } from "./prompt_service";

package/src/mcp/prompts/prompt_definitions.ts

@@ -1,160 +0,0 @@
-import { z } from "zod";
-
-/**
- * Helper to build fully-qualified prompt IDs combining name + semver.
- */
-export const withVersion = (name: string, v: string) => `${name}@${v}`;
-
-/* --------------------------------------------------------------------------
- * Argument Schemas (Zod) – one per prompt
- * ----------------------------------------------------------------------- */
-
-export const ExplainArgsSchema = z
-   .object({
-      query_code: z.string(),
-      model_context_uri: z.string().url().optional(),
-   })
-   .describe(
-      "Explain a Malloy query: purpose, transformations, output structure.",
-   );
-
-export const GenerateQueryArgsSchema = z
-   .object({
-      natural_language_goal: z.string(),
-      target_model_uri: z.string().url(),
-      data_source_hints: z.string().optional(),
-   })
-   .describe(
-      "Generate a Malloy query from a natural-language goal and model context.",
-   );
-
-export const TranslateSqlArgsSchema = z
-   .object({
-      sql_query: z.string(),
-      target_model_uri: z.string().url(),
-      sql_dialect: z.string().default("standard_sql"),
-   })
-   .describe("Translate a SQL query to Malloy using model schema context.");
-
-export const SummarizeModelArgsSchema = z
-   .object({
-      model_uri: z.string().url(),
-   })
-   .describe("Summarize a Malloy model's purpose, sources, and joins.");
-
-/* --------------------------------------------------------------------------
- * PromptDefinition
- * ----------------------------------------------------------------------- */
-
-export interface PromptDefinition {
-   id: string;
-   argsSchema: z.ZodTypeAny;
-   template: string; // Handlebars syntax
-}
-
-/* --------------------------------------------------------------------------
- * Prompt Templates  (Handlebars strings)
- * ----------------------------------------------------------------------- */
-
-const explainTemplate = `
-<instructions>
-You are an expert Malloy data analyst.
-Explain the following Malloy query. Provide details on:
-• Purpose and intended insight
-• Key sources involved
-• Main transformations / calculations
-• Expected result structure (dimensions/measures)
-</instructions>
-
-<malloy_query>
-{{query_code}}
-</malloy_query>
-
-{{#if schema_context}}
-<model_schema_context uri="{{model_context_uri}}">
-{{schema_context}}
-</model_schema_context>
-{{/if}}
-`;
-
-const generateTemplate = `
-<instructions>
-You are an expert Malloy modeler and query writer.
-Generate a Malloy query that satisfies the goal below using the model at {{target_model_uri}}.
-
-Goal: {{natural_language_goal}}
-
-{{#if data_source_hints}}
-Hints to consider: {{data_source_hints}}
-{{/if}}
-
-Return ONLY the Malloy query code.
-</instructions>
-
-<malloy_model_context uri="{{target_model_uri}}" />
-{{#if schema_context}}
-<fetched_model_schema_context>
-{{schema_context}}
-</fetched_model_schema_context>
-{{/if}}
-`;
-
-const translateTemplate = `
-<instructions>
-You are fluent in both {{sql_dialect}} SQL and Malloy.
-Translate the SQL below into Malloy using the model at {{target_model_uri}} for schema context. Return ONLY Malloy code.
-</instructions>
-
-<sql_query dialect="{{sql_dialect}}">{{sql_query}}</sql_query>
-
-<malloy_model_context uri="{{target_model_uri}}" />
-{{#if schema_context}}
-<fetched_model_schema_context>
-{{schema_context}}
-</fetched_model_schema_context>
-{{/if}}
-`;
-
-const summarizeTemplate = `
-<instructions>
-You are an expert Malloy modeler.
-Provide a concise summary of the model at {{model_uri}} covering purpose, key sources, dimensions, measures & joins.
-</instructions>
-
-<malloy_model_content uri="{{model_uri}}" />
-{{#if model_def_content}}
-<fetched_model_definition>
-{{model_def_content}}
-</fetched_model_definition>
-{{/if}}
-`;
-
-/* --------------------------------------------------------------------------
- * PROMPTS registry
- * ----------------------------------------------------------------------- */
-
-export const PROMPTS: Record<string, PromptDefinition> = {
-   [withVersion("explain-malloy-query", "1.0.0")]: {
-      id: withVersion("explain-malloy-query", "1.0.0"),
-      argsSchema: ExplainArgsSchema,
-      template: explainTemplate,
-   },
-   [withVersion("generate-malloy-query-from-description", "1.0.0")]: {
-      id: withVersion("generate-malloy-query-from-description", "1.0.0"),
-      argsSchema: GenerateQueryArgsSchema,
-      template: generateTemplate,
-   },
-   [withVersion("translate-sql-to-malloy", "1.0.0")]: {
-      id: withVersion("translate-sql-to-malloy", "1.0.0"),
-      argsSchema: TranslateSqlArgsSchema,
-      template: translateTemplate,
-   },
-   [withVersion("summarize-malloy-model", "1.0.0")]: {
-      id: withVersion("summarize-malloy-model", "1.0.0"),
-      argsSchema: SummarizeModelArgsSchema,
-      template: summarizeTemplate,
-   },
-};
-
-// Backwards-compat alias until the old handlers are removed (step 4).
-export const MALLOY_PROMPTS = PROMPTS;

package/src/mcp/prompts/prompt_service.ts

@@ -1,67 +0,0 @@
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z } from "zod";
-import { logger } from "../../logger";
-import { EnvironmentStore } from "../../service/environment_store";
-import { promptHandlerMap } from "./handlers";
-import { MALLOY_PROMPTS } from "./prompt_definitions";
-
-/**
- * Registers all defined Malloy prompts with the MCP server.
- *
- * @param mcpServer The McpServer instance.
- * @param environmentStore The EnvironmentStore instance for handlers to access environment data.
- */
-export function registerPromptCapability(
-   mcpServer: McpServer,
-   environmentStore: EnvironmentStore,
-): void {
-   logger.info("[MCP Init] Registering prompt capability...");
-   const startTime = performance.now();
-   let registeredCount = 0;
-
-   for (const promptKey in MALLOY_PROMPTS) {
-      const promptDefinition = MALLOY_PROMPTS[promptKey];
-      const handler = promptHandlerMap[promptDefinition.id];
-
-      if (handler && promptDefinition.argsSchema instanceof z.ZodObject) {
-         // Prepare a handler that injects the environmentStore
-         const preparedHandler = (
-            args: z.infer<typeof promptDefinition.argsSchema>,
-         ) => handler(args, environmentStore);
-
-         // Register using prompt ID, the Zod schema shape, and the prepared handler.
-         mcpServer.prompt(
-            promptDefinition.id,
-            (
-               promptDefinition.argsSchema as z.ZodObject<
-                  z.ZodRawShape,
-                  z.UnknownKeysParam,
-                  z.ZodTypeAny,
-                  object,
-                  object
-               >
-            ).shape,
-            preparedHandler,
-         );
-
-         registeredCount++;
-         logger.info(
-            `[MCP Prompt Reg] Registered prompt: ${promptDefinition.id}`,
-         );
-      } else if (!handler) {
-         logger.warn(
-            `Handler not found for prompt: ${promptDefinition.id}. It will not be registered.`,
-         );
-      } else if (!(promptDefinition.argsSchema instanceof z.ZodObject)) {
-         logger.warn(
-            `Prompt definition for ${promptDefinition.id} does not have a ZodObject schema. It will not be registered.`,
-         );
-      }
-   }
-
-   const endTime = performance.now();
-   logger.info(
-      `[MCP Init] Finished registering prompts. Registered: ${registeredCount}`,
-      { duration: endTime - startTime },
-   );
-}