@malloy-publisher/server 0.0.207 → 0.0.209

package/src/mcp/agent_server.ts

@@ -0,0 +1,144 @@
+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/server.ts

@@ -52,6 +52,9 @@ export function initializeMcpServer(
 
    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);
 

package/src/mcp/skills/build_skills_bundle.spec.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from "bun:test";
+import { parseSkill, unquote } from "./build_skills_bundle";
+
+describe("build_skills_bundle parseSkill", () => {
+   it("parses name, description, and body from frontmatter", () => {
+      const md =
+         "---\nname: malloy-queries\ndescription: Query patterns.\n---\n# Body\n\nText.";
+      const s = parseSkill(md, "dir");
+      expect(s.name).toBe("malloy-queries");
+      expect(s.description).toBe("Query patterns.");
+      expect(s.body).toBe("# Body\n\nText.");
+   });
+
+   it("keeps colons in the description (line-based, not split on colon)", () => {
+      const md =
+         "---\nname: x\ndescription: Use when: a thing happens.\n---\nbody";
+      expect(parseSkill(md, "dir").description).toBe(
+         "Use when: a thing happens.",
+      );
+   });
+
+   it("tolerates CRLF line endings", () => {
+      const md = "---\r\nname: x\r\ndescription: d\r\n---\r\nbody line";
+      const s = parseSkill(md, "dir");
+      expect(s.name).toBe("x");
+      expect(s.description).toBe("d");
+      expect(s.body).toBe("body line");
+   });
+
+   it("falls back to the dir name and empty description when frontmatter is missing", () => {
+      const s = parseSkill("# Just a body, no frontmatter", "fallback-name");
+      expect(s.name).toBe("fallback-name");
+      expect(s.description).toBe("");
+      expect(s.body).toBe("# Just a body, no frontmatter");
+   });
+
+   it("strips surrounding quotes from values", () => {
+      const md = "---\nname: \"quoted-name\"\ndescription: 'q'\n---\nb";
+      const s = parseSkill(md, "dir");
+      expect(s.name).toBe("quoted-name");
+      expect(s.description).toBe("q");
+   });
+});
+
+describe("build_skills_bundle unquote", () => {
+   it("removes a single layer of surrounding quotes", () => {
+      expect(unquote('"hi"')).toBe("hi");
+      expect(unquote("'hi'")).toBe("hi");
+      expect(unquote("plain")).toBe("plain");
+   });
+});

package/src/mcp/skills/build_skills_bundle.ts

@@ -0,0 +1,66 @@
+/**
+ * Build a bundled JSON of the agent skills so the agent 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.
+ *
+ * Committed as a build-time asset so the server has no runtime dependency on the
+ * skills directory layout. Regenerate when the skills change:
+ *
+ *   bun run packages/server/src/mcp/skills/build_skills_bundle.ts <skills-dir> [out.json]
+ *
+ * <skills-dir> points at the repo's top-level skills/ directory.
+ */
+import * as fs from "fs";
+import * as path from "path";
+
+interface SkillEntry {
+   name: string;
+   description: string;
+   body: string;
+}
+
+export function unquote(s: string): string {
+   return s.trim().replace(/^["']|["']$/g, "");
+}
+
+/** Parse a SKILL.md into its frontmatter name/description and Markdown body. */
+export function parseSkill(md: string, dirName: string): SkillEntry {
+   const text = md.replace(/\r\n/g, "\n"); // tolerate CRLF-committed files
+   const fm = text.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+   const front = fm ? fm[1] : "";
+   const body = (fm ? fm[2] : text).trim();
+   const name = unquote(front.match(/^name:\s*(.+)$/m)?.[1] ?? dirName);
+   const description = unquote(
+      front.match(/^description:\s*(.+)$/m)?.[1] ?? "",
+   );
+   return { name, description, body };
+}
+
+function main(): void {
+   const skillsDir = process.argv[2];
+   const outFile =
+      process.argv[3] || path.join(import.meta.dir, "skills_bundle.json");
+   if (!skillsDir || !fs.existsSync(skillsDir)) {
+      console.error(
+         `skills dir not found: ${skillsDir}\nUsage: bun run build_skills_bundle.ts <skills-dir> [out.json]`,
+      );
+      process.exit(1);
+   }
+
+   const skills: SkillEntry[] = [];
+   for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const skillFile = path.join(skillsDir, entry.name, "SKILL.md");
+      if (!fs.existsSync(skillFile)) continue;
+      skills.push(parseSkill(fs.readFileSync(skillFile, "utf8"), entry.name));
+   }
+   skills.sort((a, b) => a.name.localeCompare(b.name));
+
+   fs.writeFileSync(outFile, JSON.stringify({ skills }));
+   console.log(`Wrote ${skills.length} skills to ${outFile}`);
+}
+
+// Only run when invoked directly (bun run ...), not when imported by a test.
+if (import.meta.main) {
+   main();
+}