@malloy-publisher/server 0.0.232 → 0.0.233

package/src/mcp/server.protocol.spec.ts

@@ -16,10 +16,33 @@ describe("MCP server over the MCP protocol (in-memory)", () => {
    let client: Client;
 
    beforeAll(async () => {
-      // searchDocs does not touch the store; getContext's error path only needs
-      // getEnvironment to reject, so a throwing stub is sufficient here.
+      // searchDocs does not touch the store, and the tools' error paths only
+      // need getEnvironment to reject. The one exception is `compiles-badly`,
+      // which resolves to a compileSource returning an error diagnostic: that
+      // is malloy_compile's own isError path (a bad Malloy snippet rather than
+      // a thrown error), and it is only reachable with an environment that
+      // exists.
       const stubStore = {
-         getEnvironment: async (name: string): Promise<never> => {
+         getEnvironment: async (name: string) => {
+            if (name === "compiles-badly") {
+               return {
+                  compileSource: async () => ({
+                     problems: [
+                        {
+                           severity: "error",
+                           message: "'nope' is not defined",
+                           code: "field-not-found",
+                           at: {
+                              range: {
+                                 start: { line: 2, character: 3 },
+                                 end: { line: 2, character: 7 },
+                              },
+                           },
+                        },
+                     ],
+                  }),
+               };
+            }
             throw new Error(`Environment not found: ${name}`);
          },
       } as unknown as EnvironmentStore;
@@ -42,6 +65,43 @@ describe("MCP server over the MCP protocol (in-memory)", () => {
       expect(names.has("malloy_reloadPackage")).toBe(true);
    });
 
+   /**
+    * Tool descriptions are truncated by some clients. `malloy_getContext`'s was
+    * observed arriving cut off mid-sentence at 2271 characters, and what a tail
+    * cut removes is whatever the description put last.
+    *
+    * Two defenses, and the ordering one matters more. No single number is
+    * portable, since the cap belongs to the client and is not published; this
+    * budget only stops silent regrowth past the one length we have watched fail.
+    * The real rule is that contract rules come BEFORE the reference material, so
+    * a cut costs an agent the worked example rather than the invariants it
+    * cannot self-correct without. See docs/agent-skills/tool-description-template.md.
+    */
+   it("keeps every tool description under the truncation budget", async () => {
+      const BUDGET = 2000;
+      const { tools } = await client.listTools();
+      const oversized = tools
+         .filter((t) => (t.description ?? "").length > BUDGET)
+         .map((t) => `${t.name} (${t.description?.length})`);
+      expect(oversized).toEqual([]);
+   });
+
+   it("puts contract rules ahead of the reference sections", async () => {
+      // The section a tail-truncating client drops must never be the invariants.
+      const { tools } = await client.listTools();
+      for (const tool of tools) {
+         const description = tool.description ?? "";
+         const contract = description.indexOf("## Contract rules");
+         if (contract === -1) continue;
+         for (const later of ["## Response", "## Worked example"]) {
+            const index = description.indexOf(later);
+            if (index !== -1) {
+               expect(contract).toBeLessThan(index);
+            }
+         }
+      }
+   });
+
    it("exposes the skill set as dual-channel prompts", async () => {
       const { prompts } = await client.listPrompts();
       expect(prompts.length).toBeGreaterThanOrEqual(24);
@@ -74,18 +134,6 @@ describe("MCP server over the MCP protocol (in-memory)", () => {
       expect(results[0].url.length).toBeGreaterThan(0);
    });
 
-   it("malloy_getContext fails gracefully (isError) for an unknown environment", async () => {
-      const res = await client.callTool({
-         name: "malloy_getContext",
-         arguments: {
-            environmentName: "nope",
-            packageName: "nope",
-            query: "x",
-         },
-      });
-      expect(res.isError).toBe(true);
-   });
-
    /**
     * Assert the tool's OWN error payload, not just isError. The SDK sets
     * isError for any uncaught throw, so `expect(res.isError).toBe(true)` passes
@@ -99,16 +147,48 @@ describe("MCP server over the MCP protocol (in-memory)", () => {
    } {
       const res = result as {
          isError?: boolean;
-         content?: Array<{ type?: string; resource?: { text?: string } }>;
+         content?: Array<{
+            type?: string;
+            text?: string;
+            resource?: { text?: string; mimeType?: string };
+         }>;
       };
       expect(res.isError).toBe(true);
       expect(res.content?.[0]?.type).toBe("resource");
+      expect(res.content?.[0]?.resource?.mimeType).toBe("application/json");
       const payload = JSON.parse(res.content?.[0]?.resource?.text ?? "{}");
       expect(typeof payload.error).toBe("string");
       expect(Array.isArray(payload.suggestions)).toBe(true);
+
+      // The structured payload alone is invisible to a client that renders
+      // only text blocks on an error, which is how a real diagnostic ends up
+      // reported as a bare "Unknown error". Every error must also say it in
+      // plain text.
+      const textBlock = res.content?.find((b) => b.type === "text");
+      expect(textBlock?.text).toContain(payload.error);
+
       return payload;
    }
 
+   it("malloy_getContext returns its own error payload over the protocol", async () => {
+      const res = await client.callTool({
+         name: "malloy_getContext",
+         arguments: {
+            environmentName: "nope",
+            packageName: "nope",
+            query: "x",
+         },
+      });
+      expect(expectToolErrorPayload(res).error).toContain("nope");
+      // getContext answers with `results` at every tier, so an error keeps the
+      // key rather than making callers branch on success first.
+      const payload = JSON.parse(
+         (res.content as Array<{ resource?: { text?: string } }>)[0]?.resource
+            ?.text ?? "{}",
+      );
+      expect(payload.results).toEqual([]);
+   });
+
    it("malloy_compile returns its own error payload over the protocol", async () => {
       const res = await client.callTool({
          name: "malloy_compile",
@@ -122,6 +202,38 @@ describe("MCP server over the MCP protocol (in-memory)", () => {
       expect(expectToolErrorPayload(res).error).toContain("nope");
    });
 
+   it("malloy_compile states a compile diagnostic in text over the protocol", async () => {
+      // The diagnostics path keeps its {status, diagnostics} payload rather
+      // than the {error, suggestions} of the thrown-error path, so it cannot go
+      // through expectToolErrorPayload. What it shares is the invariant that
+      // matters: an isError result is never resource-only. Asserted over the
+      // real transport because a client that renders only text is exactly the
+      // one this was invisible to.
+      const res = await client.callTool({
+         name: "malloy_compile",
+         arguments: {
+            environmentName: "compiles-badly",
+            packageName: "p",
+            modelPath: "m.malloy",
+            source: "run: nope -> { aggregate: c is count() }",
+         },
+      });
+      const content = res.content as Array<{
+         type?: string;
+         text?: string;
+         resource?: { text?: string; mimeType?: string };
+      }>;
+      expect(res.isError).toBe(true);
+      expect(content[0]?.type).toBe("resource");
+      expect(content[0]?.resource?.mimeType).toBe("application/json");
+      expect(JSON.parse(content[0]?.resource?.text ?? "{}").status).toBe(
+         "error",
+      );
+      const textBlock = content.find((b) => b.type === "text");
+      expect(textBlock?.text).toContain("'nope' is not defined");
+      expect(textBlock?.text).toContain("field-not-found");
+   });
+
    it("malloy_reloadPackage returns its own error payload over the protocol", async () => {
       const res = await client.callTool({
          name: "malloy_reloadPackage",

package/src/mcp/skills/build_skills_bundle.ts

@@ -51,14 +51,102 @@ export function isCredible(dirName: string): boolean {
    return dirName.toLowerCase().startsWith("credible-");
 }
 
-/** Read every skill under a skills directory, in the bundle's own order. */
+/** The subdirectory a skill keeps its on-demand detail in. */
+const REFERENCE_DIR = "reference";
+
+/** Prompt name for one reference file: `<skill>/<file stem>`. */
+export function referenceName(skillName: string, file: string): string {
+   return `${skillName}/${path.basename(file, ".md")}`;
+}
+
+/**
+ * Turn a reference file into an entry. These carry no frontmatter, so the
+ * description comes from the first H1, which every reference file in the tree
+ * has ("# Rubric: Correctness", "# Severity, Confidence, Categorization").
+ */
+export function parseReference(
+   md: string,
+   skillName: string,
+   file: string,
+): SkillEntry {
+   const body = md.replace(/\r\n/g, "\n").trim();
+   const heading = body.match(/^#\s+(.+)$/m)?.[1]?.trim();
+   return {
+      name: referenceName(skillName, file),
+      description: heading
+         ? `${heading}. Reference detail for the ${skillName} skill.`
+         : `Reference detail for the ${skillName} skill.`,
+      body,
+   };
+}
+
+/**
+ * Tell an agent that reached this body over MCP where the reference files went.
+ *
+ * The skill text points at them by relative path ("see `reference/rubric-*.md`"),
+ * which is correct for a host reading the skill off disk and unresolvable for
+ * one that received this as a prompt: nothing in the prompt says which directory
+ * to stand in. Rewriting the paths in the source file is not an option, since
+ * that would break the filesystem channel, so the mapping is appended to the
+ * bundled copy only. One source file, one correct rendering per channel.
+ */
+export function referencePointer(skillName: string, files: string[]): string {
+   const stems = files.map((f) => path.basename(f, ".md"));
+   return [
+      `## Reference files over MCP`,
+      ``,
+      `This skill's \`${REFERENCE_DIR}/\` files are served as separate prompts, one per file, fetched only when you ask for them. Where the text above says to read \`${REFERENCE_DIR}/<name>.md\`, get the prompt named \`${skillName}/<name>\` instead.`,
+      ``,
+      `Available: ${stems.join(", ")}.`,
+   ].join("\n");
+}
+
+/** Reference files for one skill, sorted, or [] when it has none. */
+function referenceFiles(skillDir: string): string[] {
+   const dir = path.join(skillDir, REFERENCE_DIR);
+   if (!fs.existsSync(dir)) return [];
+   return fs
+      .readdirSync(dir)
+      .filter((f) => f.endsWith(".md"))
+      .sort();
+}
+
+/**
+ * Read every skill under a skills directory, in the bundle's own order.
+ *
+ * A skill's `reference/` files become entries of their own rather than being
+ * folded into the parent body: they are the skill's on-demand detail (a review
+ * loads the rubrics its scope needs, not all ten), and one prompt per file
+ * keeps that property over MCP. Folding them in would put 83k characters of
+ * malloy-review rubrics in front of an agent that wanted the workflow.
+ */
 export function buildSkills(skillsDir: string): SkillEntry[] {
    const skills: SkillEntry[] = [];
    for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
       if (!entry.isDirectory() || isCredible(entry.name)) continue;
-      const skillFile = path.join(skillsDir, entry.name, "SKILL.md");
+      const skillDir = path.join(skillsDir, entry.name);
+      const skillFile = path.join(skillDir, "SKILL.md");
       if (!fs.existsSync(skillFile)) continue;
-      skills.push(parseSkill(fs.readFileSync(skillFile, "utf8"), entry.name));
+
+      const skill = parseSkill(fs.readFileSync(skillFile, "utf8"), entry.name);
+      const files = referenceFiles(skillDir);
+      if (files.length > 0) {
+         skill.body = `${skill.body}\n\n${referencePointer(skill.name, files)}`;
+      }
+      skills.push(skill);
+
+      for (const file of files) {
+         skills.push(
+            parseReference(
+               fs.readFileSync(
+                  path.join(skillDir, REFERENCE_DIR, file),
+                  "utf8",
+               ),
+               skill.name,
+               file,
+            ),
+         );
+      }
    }
    return skills.sort((a, b) => a.name.localeCompare(b.name));
 }
@@ -77,7 +165,9 @@ function main(): void {
    const skills = buildSkills(skillsDir);
 
    fs.writeFileSync(outFile, JSON.stringify({ skills }));
-   console.log(`Wrote ${skills.length} skills to ${outFile}`);
+   console.log(
+      `Wrote ${skills.length} entries (${skills.filter((s) => !s.name.includes("/")).length} skills plus ${skills.filter((s) => s.name.includes("/")).length} reference files) to ${outFile}`,
+   );
 }
 
 // Only run when invoked directly (bun run ...), not when imported by a test.