@malloy-publisher/server 0.0.225 → 0.0.227

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.
  *