@malloy-publisher/server 0.0.225 → 0.0.227

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

package/src/mcp/prompts/utils.ts

@@ -1,62 +0,0 @@
-import { EnvironmentStore } from "../../service/environment_store";
-import { McpError, ErrorCode } from "@modelcontextprotocol/sdk/types.js";
-
-// Type alias for compiled model pulled from OpenAPI-generated types.
-// Using `any` fallback in case the exact type path changes.
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type ApiCompiledModel = any;
-
-export interface ParsedMalloyUri {
-   environmentName: string;
-   packageName: string;
-   modelPath: string;
-}
-
-/**
- * Parse a canonical Malloy model URI of the form:
- *   malloy://environment/{environment}/package/{package}/models/{modelPath}
- *
- * Throws an McpError(InvalidParams) if the URI is malformed.
- */
-export function parseMalloyUri(uri: string): ParsedMalloyUri {
-   const match = uri.match(
-      /^malloy:\/\/environment\/([^/]+)\/package\/([^/]+)\/models\/(.+)$/,
-   );
-
-   if (!match) {
-      throw new McpError(ErrorCode.InvalidParams, `Invalid Malloy URI: ${uri}`);
-   }
-
-   return {
-      environmentName: match[1],
-      packageName: match[2],
-      modelPath: match[3],
-   };
-}
-
-/**
- * Retrieve the compiled model for the given Malloy URI, using the provided
- * EnvironmentStore. Results are memoised in `compiledModelCache`.
- */
-export async function getCompiledModel(
-   uri: string,
-   environmentStore: EnvironmentStore,
-): Promise<ApiCompiledModel> {
-   const { environmentName, packageName, modelPath } = parseMalloyUri(uri);
-
-   // Look up the model via the EnvironmentStore hierarchy.
-   const model = await environmentStore
-      .getEnvironment(environmentName, false)
-      .then((e) => e.getPackage(packageName, false))
-      .then((pkg) => pkg.getModel(modelPath));
-
-   if (!model || model.getModelType() === "notebook") {
-      throw new McpError(
-         ErrorCode.InvalidParams,
-         `Model ${uri} not found or refers to a notebook`,
-      );
-   }
-
-   const compiled = await model.getModel();
-   return compiled;
-}

package/src/mcp/resource_metadata.ts

@@ -1,47 +0,0 @@
-import type { ResourceMetadata as SdkResourceMetadata } from "@modelcontextprotocol/sdk/server/mcp";
-
-// Define the specific resource types expected as keys
-type McpResourceType = "model" | "source" | "view" | "query" | "notebook";
-
-// Descriptions and usage guidance for different Malloy resource types.
-// Sourced from documentation and adapted for MCP client context.
-// Type assertion ensures compatibility with the SDK's ResourceMetadata,
-// which might include optional fields or an index signature.
-export const RESOURCE_METADATA: Record<
-   McpResourceType | "package" | "environment",
-   SdkResourceMetadata // Use the imported SDK type here
-> = {
-   model: {
-      description:
-         "A blueprint organizing your data tables, their connections, and reusable calculations (like 'revenue'). Models contain Sources, Views, and saved Queries.",
-      usage: "This is your main map. Use its `definition` to see the available Sources, Views, and Queries inside (identified by their names or URIs). You can then fetch details for those specific items using `GetResource`. Use the `malloy_executeQuery` tool with queries defined here to get results, typically as structured data tables (JSON). The results might also include styling information suggesting visualizations.",
-   },
-   source: {
-      description:
-         "Represents a table or dataset (like 'orders'), including its columns and any attached calculations (dimensions/measures) or Views.",
-      usage: "Examine the `definition` to understand the structure of this data and see available Views. Use `GetResource` on a View's URI to inspect it, or use the `malloy_executeQuery` tool (referencing the source and potentially a view) to get data results (JSON).",
-   },
-   view: {
-      description:
-         "A saved recipe within a Source for a specific analysis (like 'Top 10 Products').",
-      usage: "Run this predefined analysis using the `malloy_executeQuery` tool (referencing the parent source/model and this view's name) to get results, typically structured data tables (JSON), sometimes with visualization hints.",
-   },
-   query: {
-      description:
-         "Similar to a View, a saved recipe for an analysis, usually stored directly in a Model.",
-      usage: "Run this standard report using the `malloy_executeQuery` tool (referencing the parent model and this query's name) to get results, typically structured data tables (JSON), sometimes with visualization hints.",
-   },
-   notebook: {
-      description:
-         "An interactive document combining notes (Markdown text), Malloy code, and potentially saved queries or results.",
-      usage: "Read the `definition` to explore the analysis steps, notes (Markdown), and code. Identify queries within the notebook cells that you can run using the `malloy_executeQuery` tool to get results (JSON data, visualization hints).",
-   },
-   package: {
-      description: "A folder grouping related Models and Notebooks.",
-      usage: "Use `ListResources` on this Package's URI to discover the Models and Notebooks it contains. You can then use `GetResource` on those items' URIs to explore them further.",
-   },
-   environment: {
-      description: "The main workspace folder holding Packages, Models, etc.",
-      usage: "Use `ListResources` on this environment's URI to see the Packages inside and begin navigating your data assets.",
-   },
-};