@malloy-publisher/server 0.0.382-dev → 0.2.0

package/src/mcp/handler_utils.ts

@@ -1,239 +0,0 @@
-import { URL } from "url";
-import type { ResourceMetadata } from "@modelcontextprotocol/sdk/server/mcp";
-import type { ReadResourceResult } from "@modelcontextprotocol/sdk/types.js";
-import { ProjectStore } from "../service/project_store";
-import {
-   PackageNotFoundError,
-   ModelNotFoundError,
-   ModelCompilationError,
-   ProjectNotFoundError,
-} from "../errors";
-import {
-   getNotFoundError,
-   getInternalError,
-   getMalloyErrorDetails,
-   type ErrorDetails,
-} from "./error_messages";
-import type { Model } from "../service/model";
-import { logger } from "../logger";
-
-// Custom error to wrap specific GetResource application errors
-export class McpGetResourceError extends Error {
-   details: ErrorDetails;
-
-   constructor(details: ErrorDetails) {
-      super(details.message); // Pass message to the base Error constructor
-      this.name = "McpGetResourceError"; // Custom error name
-      this.details = details; // Store the structured details
-
-      // Maintain stack trace (important for V8)
-      if (Error.captureStackTrace) {
-         Error.captureStackTrace(this, McpGetResourceError);
-      }
-   }
-}
-
-// Helper type for the data fetching logic within a resource handler
-type GetDataLogic<TParams, TDefinition> = (
-   params: TParams,
-   uri: URL,
-) => Promise<TDefinition>;
-
-/**
- * Handles the common logic for GetResource handlers, fetching data and formatting the response or error.
- */
-export async function handleResourceGet<
-   TParams extends Record<string, unknown>,
-   TDefinition,
->(
-   uri: URL,
-   params: TParams,
-   resourceType: string, // e.g., 'project', 'package' for logging/errors
-   getData: GetDataLogic<TParams, TDefinition>,
-   resourceMetadata: ResourceMetadata | undefined,
-): Promise<ReadResourceResult> {
-   try {
-      const definition = await getData(params, uri);
-
-      // Combine definition and metadata
-      const responsePayload = JSON.stringify(
-         { definition: definition, metadata: resourceMetadata },
-         null,
-         2,
-      );
-
-      return {
-         contents: [
-            {
-               type: "application/json",
-               uri: uri.href,
-               text: responsePayload,
-            },
-         ],
-      };
-   } catch (error) {
-      logger.error(
-         `[MCP Server Error] Error reading ${resourceType} ${uri.href}:`,
-         { error },
-      );
-
-      let errorDetails: ErrorDetails;
-
-      // Determine the correct error details based on the error type
-      if (error instanceof McpGetResourceError) {
-         // The getData function already caught, formatted, and wrapped the error
-         errorDetails = error.details;
-      } else {
-         // Catch-all for truly unexpected errors not handled by the specific getData logic
-         logger.error(
-            "[MCP Server Error] Unexpected error type caught in handleResourceGet:",
-            { error },
-         );
-         errorDetails = getInternalError(
-            `GetResource (${resourceType})`,
-            error,
-         );
-      }
-
-      // Format the error response consistently
-      return {
-         isError: true,
-         contents: [
-            {
-               type: "application/json", // Keep JSON for structured error
-               uri: uri.href,
-               text: JSON.stringify(
-                  {
-                     error: errorDetails.message,
-                     suggestions: errorDetails.suggestions,
-                  },
-                  null,
-                  2,
-               ),
-            },
-         ],
-      };
-   }
-}
-
-/**
- * Fetches and validates the Package and Model instances needed for query execution.
- * Handles errors related to package/model access and initial compilation.
- * @returns An object containing the Model instance or a pre-formatted ErrorDetails object.
- */
-export async function getModelForQuery(
-   projectStore: ProjectStore,
-   projectName: string,
-   packageName: string,
-   modelPath: string,
-): Promise<{ model: Model } | { error: ErrorDetails }> {
-   try {
-      const project = await projectStore.getProject(projectName, false);
-      const pkg = await project.getPackage(packageName, false);
-      const model = pkg.getModel(modelPath);
-      if (!model || model.getModelType() === "notebook") {
-         // Ensure it's actually a model
-         const details = getNotFoundError(
-            `model '${modelPath}' in package '${packageName}' for project '${projectName}'`,
-         );
-         return { error: details };
-      }
-      // Attempt to get the model definition early to catch initial compilation errors
-      await model.getModel(); // This might throw ModelCompilationError
-      return { model };
-   } catch (error) {
-      // Handle errors during package/model access or initial compilation
-      let errorDetails: ErrorDetails;
-      if (error instanceof ProjectNotFoundError) {
-         errorDetails = getNotFoundError(`project '${projectName}'`);
-      } else if (error instanceof PackageNotFoundError) {
-         errorDetails = getNotFoundError(
-            `package '${packageName}' in project '${projectName}'`,
-         );
-      } else if (error instanceof ModelNotFoundError) {
-         errorDetails = getNotFoundError(
-            `model '${modelPath}' in package '${packageName}' for project '${projectName}'`,
-         );
-      } else if (error instanceof ModelCompilationError) {
-         errorDetails = getMalloyErrorDetails(
-            "executeQuery (load model)",
-            `${projectName}/${packageName}/${modelPath}`,
-            error,
-         );
-      } else {
-         // Unexpected error during setup
-         errorDetails = getInternalError("executeQuery (Setup)", error);
-      }
-      logger.error(
-         `[MCP Server Error] Error accessing package/model for query: ${projectName}/${packageName}/${modelPath}`,
-         { error },
-      );
-      return { error: errorDetails };
-   }
-}
-
-/**
- * Constructs a valid malloy:// URI string from its components.
- * Handles encoding of path segments.
- *
- * @param components An object containing the URI parts (project, package, model, etc.)
- * @param fragment Optional fragment identifier (e.g., #queryResult)
- * @returns A valid malloy:// URI string.
- */
-export function buildMalloyUri(
-   components: {
-      project?: string;
-      package?: string;
-      model?: string;
-      resourceType?:
-         | "models"
-         | "packages"
-         | "notebooks"
-         | "sources"
-         | "queries"
-         | "views"; // Type of resource list or specific resource
-      resourceName?: string; // Specific name for model, query, etc.
-      subResourceType?: "views"; // For views within sources
-      subResourceName?: string; // Name of the view
-   },
-   fragment?: string,
-): string {
-   let path = "/project/";
-
-   if (components.project) {
-      path += encodeURIComponent(components.project);
-   } else {
-      // Default to 'home' if not provided, consistent with current behavior
-      path += "home";
-   }
-
-   if (components.package) {
-      path += "/package/" + encodeURIComponent(components.package);
-   }
-
-   if (components.resourceType) {
-      path += "/" + components.resourceType;
-      if (components.resourceName) {
-         path += "/" + encodeURIComponent(components.resourceName);
-
-         if (components.subResourceType && components.subResourceName) {
-            path +=
-               "/" +
-               components.subResourceType +
-               "/" +
-               encodeURIComponent(components.subResourceName);
-         }
-      }
-   }
-
-   // The URL constructor seems to normalize malloy://path to malloy:///path
-   // which breaks the tests expecting malloy://project/...
-   // We manually construct the string instead.
-   let uriString = "malloy:/" + path; // Start with one slash after scheme
-
-   if (fragment) {
-      uriString += "#" + fragment;
-   }
-
-   return uriString;
-}

package/src/mcp/mcp_constants.ts

@@ -1,22 +0,0 @@
-export const MCP_ERROR_MESSAGES = {
-   // Protocol-level errors (validation)
-   MISSING_REQUIRED_PARAMS:
-      "Either 'query' or both 'sourceName' and 'queryName' must be provided",
-   MUTUALLY_EXCLUSIVE_PARAMS: "Cannot provide both 'query' and 'queryName'",
-   INVALID_ARGUMENTS: (toolName: string, errors: string[]) =>
-      `Invalid arguments for tool ${toolName}: ${errors.join(", ")}`,
-
-   // Application-level errors (runtime)
-   PROJECT_NOT_FOUND: (projectName: string) =>
-      `Project '${projectName}' is not available or does not exist.`,
-   PACKAGE_NOT_FOUND: (packageName: string) =>
-      `Package manifest for ${packageName} does not exist.`,
-   MODEL_NOT_FOUND: (packageName: string, modelPath: string) =>
-      `Model '${modelPath}' not found in package '${packageName}'`,
-   QUERY_NOT_FOUND: (queryName: string) => `'${queryName}' is not defined`,
-   COMPILATION_ERROR: (error: string) => `Error(s) compiling model:\n${error}`,
-
-   // Error message prefixes
-   ERROR_EXECUTING_QUERY: (packagePath: string) =>
-      `Error executing query on '${packagePath}':`,
-} as const;

package/src/mcp/prompts/handlers.ts

@@ -1,84 +0,0 @@
-import * as 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 { ProjectStore } from "../../service/project_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: ProjectStore) => {
-      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: ProjectStore,
-   ) => 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 { ProjectStore } from "../../service/project_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 projectStore The ProjectStore instance for handlers to access project data.
- */
-export function registerPromptCapability(
-   mcpServer: McpServer,
-   projectStore: ProjectStore,
-): 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 projectStore
-         const preparedHandler = (
-            args: z.infer<typeof promptDefinition.argsSchema>,
-         ) => handler(args, projectStore);
-
-         // 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 { ProjectStore } from "../../service/project_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 {
-   projectName: string;
-   packageName: string;
-   modelPath: string;
-}
-
-/**
- * Parse a canonical Malloy model URI of the form:
- *   malloy://project/{project}/package/{package}/models/{modelPath}
- *
- * Throws an McpError(InvalidParams) if the URI is malformed.
- */
-export function parseMalloyUri(uri: string): ParsedMalloyUri {
-   const match = uri.match(
-      /^malloy:\/\/project\/([^/]+)\/package\/([^/]+)\/models\/(.+)$/,
-   );
-
-   if (!match) {
-      throw new McpError(ErrorCode.InvalidParams, `Invalid Malloy URI: ${uri}`);
-   }
-
-   return {
-      projectName: match[1],
-      packageName: match[2],
-      modelPath: match[3],
-   };
-}
-
-/**
- * Retrieve the compiled model for the given Malloy URI, using the provided
- * ProjectStore. Results are memoised in `compiledModelCache`.
- */
-export async function getCompiledModel(
-   uri: string,
-   projectStore: ProjectStore,
-): Promise<ApiCompiledModel> {
-   const { projectName, packageName, modelPath } = parseMalloyUri(uri);
-
-   // Look up the model via the ProjectStore hierarchy.
-   const model = await projectStore
-      .getProject(projectName, false)
-      .then((p) => p.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;
-}