@malloy-publisher/server 0.0.226 → 0.0.227

package/package.json

@@ -1,7 +1,7 @@
 {
    "name": "@malloy-publisher/server",
    "description": "Malloy Publisher Server",
-   "version": "0.0.226",
+   "version": "0.0.227",
    "main": "dist/server.mjs",
    "bin": {
       "malloy-publisher": "dist/server.mjs"
@@ -58,8 +58,6 @@
       "aws-sdk": "^2.1692.0",
       "body-parser": "^1.20.2",
       "chokidar": "^4.0.3",
-      "class-transformer": "^0.5.1",
-      "class-validator": "^0.14.1",
       "cors": "^2.8.5",
       "express": "^4.21.0",
       "extract-zip": "^2.0.1",
@@ -74,7 +72,6 @@
       "uuid": "^11.0.3"
    },
    "devDependencies": {
-      "@anthropic-ai/dxt": "^0.1.0",
       "@eslint/compat": "^1.2.7",
       "@eslint/eslintrc": "^3.3.1",
       "@eslint/js": "^9.23.0",

package/src/health.ts

@@ -74,10 +74,10 @@ export function registerSignalHandlers(
    mcpServer: Server,
    shutdownDrainDurationSeconds: number = 0,
    shutdownGracefulCloseTimeoutSeconds: number = 0,
-   agentMcpServer?: Server,
 ): void {
-   // Keep the process alive on SIGTERM — do not close the server.
-   // K8s will SIGKILL after terminationGracePeriodSeconds (which cannot be caught).
+   // On SIGTERM, drain in-flight requests before closing the servers (see the
+   // shutdown sequence above). K8s will SIGKILL after terminationGracePeriodSeconds
+   // if this handler does not exit first.
    process.once("SIGTERM", async () => {
       logger.info("========== SIGTERM RECEIVED ==========");
       markNotReady();
@@ -97,7 +97,6 @@ export function registerSignalHandlers(
          server,
          mcpServer,
          shutdownGracefulCloseTimeoutSeconds,
-         agentMcpServer,
       );
    });
 }
@@ -116,7 +115,6 @@ export async function performGracefulShutdownAfterDrain(
    server: Server,
    mcpServer: Server,
    shutdownGracefulCloseTimeoutSeconds: number,
-   agentMcpServer?: Server,
 ): Promise<void> {
    const closeServer = (server: Server, name: string) =>
       new Promise<void>((resolve) => {
@@ -137,9 +135,6 @@ export async function performGracefulShutdownAfterDrain(
    await Promise.all([
       closeServer(server, "Main server"),
       closeServer(mcpServer, "MCP server"),
-      ...(agentMcpServer
-         ? [closeServer(agentMcpServer, "Agent MCP server")]
-         : []),
    ]);
 
    try {

package/src/mcp/error_messages.ts

@@ -3,31 +3,6 @@ export interface ErrorDetails {
    suggestions: string[];
 }
 
-export interface InvalidParamDetail {
-   name: string;
-   reason: string;
-   value?: unknown;
-}
-
-export function getInvalidParamsError(
-   params: InvalidParamDetail[],
-): ErrorDetails {
-   const reasons = params
-      .map(
-         (p) =>
-            `${p.name}: ${p.reason}${p.value !== undefined ? ` (value: ${JSON.stringify(p.value)})` : ""}`,
-      )
-      .join("; ");
-   return {
-      message: `Invalid parameter(s) provided. ${reasons}`,
-      suggestions: [
-         "Check the parameter names and values against the prompt's argument definition.",
-         "Ensure all required parameters are provided and have the correct data types.",
-         "For URI parameters, ensure they are correctly formatted.",
-      ],
-   };
-}
-
 /**
  * Generates error details for a resource not found scenario.
  * @param resourceUriOrContext The URI that was not found, or a context string (e.g., "Package 'X'", "Model 'Y' in package 'X'").
@@ -36,13 +11,9 @@ export function getInvalidParamsError(
 export function getNotFoundError(resourceUriOrContext: string): ErrorDetails {
    const baseMessage = `Resource not found: ${resourceUriOrContext}`;
    const suggestions: string[] = [
-      `Verify the identifier or URI (${resourceUriOrContext}) is spelled correctly and exists. Check capitalization and path separators.`,
-      `If using a URI, ensure it follows the correct format (e.g., malloy://environment/...) and includes the right path segments (e.g., /models/, /sources/, /queries/, /views/).`,
-   ];
-
-   suggestions.push(
+      `Verify the identifier (${resourceUriOrContext}) is spelled correctly and exists. Check capitalization and path separators.`,
       "Check if the resource exists and is correctly named in your Malloy environment structure or the specific model file.",
-   );
+   ];
 
    return {
       message: baseMessage,
@@ -52,7 +23,7 @@ export function getNotFoundError(resourceUriOrContext: string): ErrorDetails {
 
 /**
  * Generates generic error details for internal server errors.
- * @param operation The operation that failed (e.g., 'GetResource', 'ListResources').
+ * @param operation The operation that failed (e.g., 'executeQuery').
  * @param error Optional: The underlying error object or message.
  * @returns ErrorDetails object.
  */
@@ -73,7 +44,7 @@ export function getInternalError(
 
 /**
  * Generates detailed error information for Malloy compilation or query execution errors.
- * @param operation The operation that failed (e.g., 'GetResource (model)', 'executeQuery').
+ * @param operation The operation that failed (e.g., 'executeQuery (load model)', 'executeQuery').
  * @param modelIdentifier A path or URI identifying the model/notebook involved.
  * @param error The underlying Malloy error object or other error.
  * @returns ErrorDetails object.
@@ -144,21 +115,21 @@ export function getMalloyErrorDetails(
          refined = true;
          const [, viewName, sourceName] = viewNotFoundMatch;
          suggestions.unshift(
-            `Suggestion: View '${viewName}' was not found in source '${sourceName}'. Check the view name spelling or try requesting the resource details for the source URI (e.g., 'malloy://.../sources/${sourceName}') to see the list of available views. Views are defined within sources like 'source: ${sourceName} is ... extend { view: ${viewName} is { ... } }'.`,
+            `Suggestion: View '${viewName}' was not found in source '${sourceName}'. Check the view name spelling or call malloy_getContext with sourceName '${sourceName}' to see the list of available views. Views are defined within sources like 'source: ${sourceName} is ... extend { view: ${viewName} is { ... } }'.`,
          );
       } else if (sourceNotFoundMatch) {
          refined = true;
          const [, sourceName] = sourceNotFoundMatch;
          suggestions.unshift(
             `Suggestion: Source '${sourceName}' was not found or could not be accessed. Verify its definition (e.g., \`source: ${sourceName} is table('...')\` or \`duckdb.sql("...")\`) and ensure any associated connections are valid.`,
-            `Suggestion: Check the spelling of '${sourceName}'. You can list sources in the model using ListResources('malloy://.../${modelIdentifier}').`,
+            `Suggestion: Check the spelling of '${sourceName}'. You can list the sources in the package using malloy_getContext.`,
          );
       } else if (queryNotFoundMatch) {
          refined = true;
          const [, queryName] = queryNotFoundMatch;
          suggestions.unshift(
             `Suggestion: Named query '${queryName}' was not found. Verify its definition (e.g., \`query: ${queryName} is source_name -> { ... }\`) within the model '${modelIdentifier}'.`,
-            `Suggestion: Check the spelling of '${queryName}'. Ensure it's a named query (defined with \`query:\`), not a view. You can list named queries using ListResources('malloy://.../${modelIdentifier}').`,
+            `Suggestion: Check the spelling of '${queryName}'. Ensure it's a named query (defined with \`query:\`), not a view. You can list named queries using malloy_getContext.`,
          );
       } else if (fieldNotFoundMatch) {
          refined = true;
@@ -166,7 +137,7 @@ export function getMalloyErrorDetails(
             fieldNotFoundMatch;
          suggestions.unshift(
             `Suggestion: Field '${fieldName}' was not found in ${fieldContextType} '${fieldContextName}'. Check the spelling of the field name within the definition of '${fieldContextName}'.`,
-            `Suggestion: Ensure the field is defined directly or inherited correctly in the '${fieldContextName}' ${fieldContextType}. You can inspect the ${fieldContextType} definition using GetResource.`,
+            `Suggestion: Ensure the field is defined directly or inherited correctly in the '${fieldContextName}' ${fieldContextType}. You can inspect the ${fieldContextType}'s fields using malloy_getContext.`,
          );
       } else if (referenceErrorMatch) {
          refined = true;

package/src/mcp/handler_utils.ts

@@ -1,6 +1,3 @@
-import { URL } from "url";
-import type { ResourceMetadata } from "@modelcontextprotocol/sdk/server/mcp";
-import type { ReadResourceResult } from "@modelcontextprotocol/sdk/types.js";
 import { EnvironmentStore } from "../service/environment_store";
 import {
    AccessDeniedError,
@@ -19,105 +16,6 @@ import {
 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., 'environment', '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.
@@ -202,28 +100,20 @@ export async function getModelForQuery(
 }
 
 /**
- * Constructs a valid malloy:// URI string from its components.
- * Handles encoding of path segments.
+ * Constructs a malloy:// URI string identifying the model a tool response came
+ * from. Attached as `uri` metadata on tool results (get-context, execute-query,
+ * docs-search); it is not a fetchable MCP resource.
  *
- * @param components An object containing the URI parts (environment, package, model, etc.)
- * @param fragment Optional fragment identifier (e.g., #queryResult)
- * @returns A valid malloy:// URI string.
+ * @param components The URI parts (environment, package, and optionally the model).
+ * @param fragment Optional fragment identifier (e.g., "result", "get-context").
+ * @returns A malloy:// URI string.
  */
 export function buildMalloyUri(
    components: {
       environment?: 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
+      resourceType?: "models";
+      resourceName?: string;
    },
    fragment?: string,
 ): string {
@@ -244,20 +134,11 @@ export function buildMalloyUri(
       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://environment/...
-   // We manually construct the string instead.
+   // The URL constructor normalizes malloy://path to malloy:///path, so we
+   // build the string manually to keep the malloy://environment/... shape.
    let uriString = "malloy:/" + path; // Start with one slash after scheme
 
    if (fragment) {

package/src/mcp/mcp_constants.ts

@@ -3,20 +3,4 @@ export const MCP_ERROR_MESSAGES = {
    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) =>
-      `Environment '${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/{agent_server.protocol.spec.ts → server.protocol.spec.ts}

@@ -1,16 +1,17 @@
 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 { initializeMcpServer } from "./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.
+ * End-to-end coverage of the unified MCP server over the real MCP protocol,
+ * using the SDK's in-memory transport (no HTTP, no network, no DuckDB).
+ * Exercises tool registration (including the agent retrieval tools that now
+ * live on the same server), the dual-channel skill 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)", () => {
+describe("MCP server over the MCP protocol (in-memory)", () => {
    let client: Client;
 
    beforeAll(async () => {
@@ -22,19 +23,20 @@ describe("agent MCP server over the MCP protocol (in-memory)", () => {
          },
       } as unknown as EnvironmentStore;
 
-      const server = initializeAgentMcpServer(stubStore);
+      const server = initializeMcpServer(stubStore);
       const [clientTransport, serverTransport] =
          InMemoryTransport.createLinkedPair();
       await server.connect(serverTransport);
-      client = new Client({ name: "agent-protocol-test", version: "0.0.0" });
+      client = new Client({ name: "mcp-protocol-test", version: "0.0.0" });
       await client.connect(clientTransport);
    });
 
-   it("exposes exactly the two agent tools", async () => {
+   it("exposes the agent retrieval tools alongside the core tools", async () => {
       const { tools } = await client.listTools();
-      expect(new Set(tools.map((t) => t.name))).toEqual(
-         new Set(["malloy_getContext", "malloy_searchDocs"]),
-      );
+      const names = new Set(tools.map((t) => t.name));
+      expect(names.has("malloy_getContext")).toBe(true);
+      expect(names.has("malloy_searchDocs")).toBe(true);
+      expect(names.has("malloy_executeQuery")).toBe(true);
    });
 
    it("exposes the skill set as dual-channel prompts", async () => {

package/src/mcp/server.ts

@@ -2,16 +2,10 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { EnvironmentStore } from "../service/environment_store";
 
 import { formatDuration, logger } from "../logger";
-import { registerPromptCapability } from "./prompts/prompt_service.js";
-import { registerEnvironmentResource } from "./resources/environment_resource";
-import { registerModelResource } from "./resources/model_resource";
-import { registerNotebookResource } from "./resources/notebook_resource";
-import { registerPackageResource } from "./resources/package_resource";
-import { registerQueryResource } from "./resources/query_resource";
-import { registerSourceResource } from "./resources/source_resource";
-import { registerViewResource } from "./resources/view_resource";
-import { registerTools } from "./tools/discovery_tools";
+import { registerDocsSearchTool } from "./tools/docs_search_tool";
 import { registerExecuteQueryTool } from "./tools/execute_query_tool";
+import { registerGetContextTool } from "./tools/get_context_tool";
+import skillsBundle from "./skills/skills_bundle.json";
 
 export const testServerInfo = {
    name: "malloy-publisher-mcp-server",
@@ -20,6 +14,14 @@ export const testServerInfo = {
    description: "Provides access to Malloy models and query execution via 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 function initializeMcpServer(
    environmentStore: EnvironmentStore,
 ): McpServer {
@@ -28,35 +30,25 @@ export function initializeMcpServer(
 
    const mcpServer = new McpServer(testServerInfo);
 
-   logger.info("[MCP Init] Registering environment resource...");
-   registerEnvironmentResource(mcpServer, environmentStore);
-   logger.info("[MCP Init] Registering package resource...");
-   registerPackageResource(mcpServer, environmentStore);
-
-   // Register more specific templates first
-   logger.info("[MCP Init] Registering notebook resource...");
-   registerNotebookResource(mcpServer, environmentStore);
-   logger.info("[MCP Init] Registering source resource...");
-   registerSourceResource(mcpServer, environmentStore);
-   logger.info("[MCP Init] Registering query resource...");
-   registerQueryResource(mcpServer, environmentStore);
-   logger.info("[MCP Init] Registering view resource...");
-   registerViewResource(mcpServer, environmentStore);
-
-   // Register the general model template last among resource types
-   logger.info("[MCP Init] Registering model resource...");
-   registerModelResource(mcpServer, environmentStore);
-
-   logger.info("[MCP Init] Registering executeQuery tool...");
    registerExecuteQueryTool(mcpServer, environmentStore);
-
-   registerTools(mcpServer, environmentStore);
-
-   // Note: malloy_getContext and malloy_searchDocs are intentionally NOT registered
-   // here. They run on a separate, isolated agent MCP server (see mcp/agent_server.ts).
-
-   logger.info("[MCP Init] Registering prompt capability...");
-   registerPromptCapability(mcpServer, environmentStore);
+   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 },
+            },
+         ],
+      }));
+   }
 
    const endTime = performance.now();
    logger.info(`[MCP Init] Finished initializeMcpServer`, {

package/src/mcp/skills/build_skills_bundle.ts

@@ -1,5 +1,5 @@
 /**
- * Build a bundled JSON of the agent skills so the agent MCP server can expose them as
+ * Build a bundled JSON of the agent skills so the MCP server can expose them as
  * MCP prompts (dual-channel): skill-aware hosts read the skill files directly, while
  * hosts that only ingest MCP get the same guidance through these prompts.
  *