@withpica/mcp-server-directory 1.3.0 → 1.4.0

package/src/lib/changelog.ts

@@ -0,0 +1,119 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+
+/**
+ * Runtime CHANGELOG parser. Mirrors scripts/parse-changelog.ts but takes
+ * the markdown body as a string (no fs dependency) so the MCP runtime
+ * can read from a build-time embedded constant. Sister of
+ * mcp-server/src/lib/changelog.ts and team-mcp-server/src/lib/changelog.ts.
+ */
+
+export type ChangelogSectionName =
+  | "Added"
+  | "Changed"
+  | "Fixed"
+  | "Removed"
+  | "Security"
+  | "Deprecated";
+
+export const CHANGELOG_SECTION_NAMES: ChangelogSectionName[] = [
+  "Added",
+  "Changed",
+  "Fixed",
+  "Removed",
+  "Security",
+  "Deprecated",
+];
+
+export interface ChangelogEntry {
+  version: string;
+  date: string | null;
+  sections: Partial<Record<ChangelogSectionName, string[]>>;
+  markdown: string;
+}
+
+const HEADING_RE = /^##\s+\[([^\]]+)\](?:\s*-\s*(\d{4}-\d{2}-\d{2}))?\s*$/;
+const SECTION_RE = /^###\s+(\w+)\s*$/;
+const BULLET_RE = /^-\s+(.*)$/;
+
+export function parseChangelogText(text: string): ChangelogEntry[] {
+  const lines = text.split("\n");
+
+  const entries: ChangelogEntry[] = [];
+  let current: (ChangelogEntry & { _start: number }) | null = null;
+  let currentSection: ChangelogSectionName | null = null;
+  let currentBullet: {
+    entry: ChangelogEntry;
+    section: ChangelogSectionName;
+    index: number;
+  } | null = null;
+
+  const flush = (endLine: number) => {
+    if (current && current.version !== "Unreleased") {
+      current.markdown = lines
+        .slice(current._start, endLine)
+        .join("\n")
+        .trimEnd();
+      const { _start: _start, ...rest } = current;
+      entries.push(rest);
+    }
+    current = null;
+    currentSection = null;
+    currentBullet = null;
+  };
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const headingMatch = line.match(HEADING_RE);
+    if (headingMatch) {
+      flush(i);
+      current = {
+        version: headingMatch[1],
+        date: headingMatch[2] ?? null,
+        sections: {},
+        markdown: "",
+        _start: i,
+      };
+      currentSection = null;
+      continue;
+    }
+
+    if (!current) continue;
+
+    const sectionMatch = line.match(SECTION_RE);
+    if (sectionMatch) {
+      const name = sectionMatch[1] as ChangelogSectionName;
+      if (CHANGELOG_SECTION_NAMES.includes(name)) {
+        currentSection = name;
+        if (!current.sections[name]) current.sections[name] = [];
+      } else {
+        currentSection = null;
+      }
+      currentBullet = null;
+      continue;
+    }
+
+    const bulletMatch = line.match(BULLET_RE);
+    if (bulletMatch && currentSection) {
+      const arr = current.sections[currentSection]!;
+      arr.push(bulletMatch[1].trim());
+      currentBullet = {
+        entry: current,
+        section: currentSection,
+        index: arr.length - 1,
+      };
+      continue;
+    }
+
+    if (currentBullet && line.startsWith("  ") && line.trim().length > 0) {
+      const arr = currentBullet.entry.sections[currentBullet.section]!;
+      arr[currentBullet.index] = `${arr[currentBullet.index]} ${line.trim()}`;
+      continue;
+    }
+
+    currentBullet = null;
+  }
+
+  flush(lines.length);
+
+  return entries;
+}

package/src/prompts/public-question-atlas.ts

@@ -145,8 +145,7 @@ export const PUBLIC_ATLAS: AtlasEntry[] = [
         "No work matched that title in our index. The work may not be " +
         "registered with a society we mirror, or the title may be " +
         "ambiguous — try a writer name or year of release to narrow.",
-      suggest_query_shape:
-        "title + writer | title + year | ISWC if known",
+      suggest_query_shape: "title + writer | title + year | ISWC if known",
     },
   },
   {
@@ -230,8 +229,7 @@ export const PUBLIC_ATLAS: AtlasEntry[] = [
         "No work matched that title. The song may not be in our index " +
         "yet, or the title may be ambiguous (many works share the same " +
         "title) — try a writer name or year of release.",
-      suggest_query_shape:
-        "title + writer | title + year | ISWC if known",
+      suggest_query_shape: "title + writer | title + year | ISWC if known",
     },
   },
   {
@@ -242,8 +240,7 @@ export const PUBLIC_ATLAS: AtlasEntry[] = [
       message:
         "No work matched that title in our index. Try refining with the " +
         "writer's name, year of release, or the ISWC if you have it.",
-      suggest_query_shape:
-        "title + writer | title + year | ISWC if known",
+      suggest_query_shape: "title + writer | title + year | ISWC if known",
     },
   },
   {
@@ -510,8 +507,7 @@ export const PUBLIC_ATLAS: AtlasEntry[] = [
         "No matches in our public directory across works or creators. " +
         "Try narrowing to one entity type (work title or creator name), " +
         "or supply an identifier if you have one.",
-      suggest_query_shape:
-        "title + writer | creator name + role | identifier",
+      suggest_query_shape: "title + writer | creator name + role | identifier",
     },
   },
 
@@ -533,8 +529,7 @@ export const PUBLIC_ATLAS: AtlasEntry[] = [
         "unregistered, registered with a society we don't mirror, or the " +
         "title is ambiguous. Try a writer name or year to narrow, or " +
         "look up by ISWC if you have one.",
-      suggest_query_shape:
-        "title + writer | title + year | ISWC if known",
+      suggest_query_shape: "title + writer | title + year | ISWC if known",
     },
   },
   {
@@ -554,4 +549,18 @@ export const PUBLIC_ATLAS: AtlasEntry[] = [
     ],
     resolves_to: { kind: "tool", name: "directory_skill_list" },
   },
+
+  // ─────────────────────────────────────────────────────────────────
+  // Directory-surface self-introspection — what shipped in this MCP
+  // ─────────────────────────────────────────────────────────────────
+  {
+    question: "what's new in the directory mcp",
+    synonyms: [
+      "what changed in the directory",
+      "directory release notes",
+      "what version is the directory on",
+      "directory changelog",
+    ],
+    resolves_to: { kind: "tool", name: "directory_release_notes" },
+  },
 ];

package/src/server.ts

@@ -16,6 +16,7 @@ import { ToolRegistry } from "./tools/index.js";
 import { PromptRegistry } from "./prompts/index.js";
 import { logError } from "./utils/errors.js";
 import { DIRECTORY_PRIMER } from "./resources/llms-primer.js";
+import { CHANGELOG_MD } from "./lib/changelog.generated.js";
 import { SkillsRegistry } from "./skills/index.js";
 
 export class DirectoryMcpServer {
@@ -88,6 +89,13 @@ export class DirectoryMcpServer {
             "Enumeration of downloadable directory skill methodologies (SEP-2640 bridge). Each entry maps a kebab-case name to its skill:// URI, description, and trigger phrases.",
           mimeType: "application/json",
         },
+        {
+          uri: "release-notes://withpica/mcp-server-directory/latest",
+          name: "Release Notes — @withpica/mcp-server-directory",
+          description:
+            "Full CHANGELOG.md for the PICA directory MCP server. For just the last few releases, agents can call directory_release_notes.",
+          mimeType: "text/markdown",
+        },
       ];
       for (const summary of this.skillsRegistry.listSkills()) {
         resources.push({
@@ -115,6 +123,17 @@ export class DirectoryMcpServer {
             ],
           };
         }
+        if (uri === "release-notes://withpica/mcp-server-directory/latest") {
+          return {
+            contents: [
+              {
+                uri,
+                mimeType: "text/markdown",
+                text: CHANGELOG_MD,
+              },
+            ],
+          };
+        }
         if (uri.startsWith("skill://withpica/")) {
           return this.readSkillResource(uri);
         }

package/src/tools/__tests__/release-notes.test.ts

@@ -0,0 +1,62 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+
+import { DirectoryReleaseNotesTools } from "../release-notes.js";
+import type { DirectoryClient } from "../../client.js";
+
+describe("DirectoryReleaseNotesTools.directory_release_notes", () => {
+  const client = {} as DirectoryClient;
+  const tools = new DirectoryReleaseNotesTools(client).getTools();
+  const tool = tools.find(
+    (t: { definition: { name: string } }) =>
+      t.definition.name === "directory_release_notes",
+  )!;
+
+  it("registers as a single tool named directory_release_notes", () => {
+    expect(tools).toHaveLength(1);
+    expect(tool).toBeDefined();
+  });
+
+  it("returns the last 3 releases by default", async () => {
+    const result = await tool.executor({});
+    const data = JSON.parse(result.content[0].text);
+    expect(data.package).toBe("@withpica/mcp-server-directory");
+    expect(data.current_version).toMatch(/^\d+\.\d+\.\d+$/);
+    expect(Array.isArray(data.releases)).toBe(true);
+    expect(data.releases.length).toBeLessThanOrEqual(3);
+    expect(data.releases.length).toBeGreaterThan(0);
+    expect(data.resource_uri).toBe(
+      "release-notes://withpica/mcp-server-directory/latest",
+    );
+  });
+
+  it("respects since_version (strictly greater)", async () => {
+    const result = await tool.executor({ since_version: "0.0.1" });
+    const data = JSON.parse(result.content[0].text);
+    expect(data.releases.length).toBeGreaterThan(0);
+    for (const r of data.releases) {
+      expect(r.version).not.toBe("0.0.1");
+    }
+  });
+
+  it("filters to specified sections", async () => {
+    const result = await tool.executor({ sections: ["Added"] });
+    const data = JSON.parse(result.content[0].text);
+    for (const r of data.releases) {
+      for (const k of Object.keys(r.sections)) {
+        expect(k).toBe("Added");
+      }
+    }
+  });
+
+  it("returns empty releases array when since_version exceeds current_version", async () => {
+    const result = await tool.executor({ since_version: "99.0.0" });
+    const data = JSON.parse(result.content[0].text);
+    expect(data.releases).toEqual([]);
+  });
+
+  it("clamps limit to max 20", async () => {
+    const result = await tool.executor({ limit: 9999 });
+    const data = JSON.parse(result.content[0].text);
+    expect(data.releases.length).toBeLessThanOrEqual(20);
+  });
+});

package/src/tools/index.ts

@@ -7,6 +7,7 @@ import { DirectorySearchTools } from "./search.js";
 import { DirectoryRecordingsTools } from "./recordings.js";
 import { DirectoryChainTools } from "./chain.js";
 import { DirectorySkillsTools } from "./skills.js";
+import { DirectoryReleaseNotesTools } from "./release-notes.js";
 import { formatError, logError, ToolExecutionError } from "../utils/errors.js";
 
 /**
@@ -54,6 +55,7 @@ export class ToolRegistry {
       new DirectoryRecordingsTools(client),
       new DirectoryChainTools(client),
       new DirectorySkillsTools(),
+      new DirectoryReleaseNotesTools(client),
     ];
 
     for (const group of groups) {

package/src/tools/release-notes.ts

@@ -0,0 +1,148 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+
+/* eslint-disable @typescript-eslint/no-explicit-any -- ToolExecutor signature uses Record<string, any> */
+
+/**
+ * directory_release_notes — what shipped in the PICA directory MCP.
+ *
+ * Reads CHANGELOG.md embedded at build time via scripts/build-changelog.ts.
+ * Sister of pica_release_notes (creator MCP) and team_release_notes (team MCP).
+ *
+ * Public-facing MCP — no trade-secret content in the description (per
+ * .claude/rules/ip-protection.md). The CHANGELOG body is the same file
+ * shipped in the npm tarball, already vetted as public.
+ */
+
+import { DirectoryClient } from "../client.js";
+import { ToolDefinition, ToolExecutor, ToolResult } from "./index.js";
+import {
+  parseChangelogText,
+  type ChangelogSectionName,
+  CHANGELOG_SECTION_NAMES,
+} from "../lib/changelog.js";
+import {
+  CHANGELOG_MD,
+  PACKAGE_NAME,
+  PACKAGE_VERSION,
+} from "../lib/changelog.generated.js";
+
+const RESOURCE_URI = "release-notes://withpica/mcp-server-directory/latest";
+const DEFAULT_LIMIT = 3;
+const MAX_LIMIT = 20;
+
+function compareSemver(a: string, b: string): number {
+  const parse = (v: string) => v.split(".").map((n) => parseInt(n, 10) || 0);
+  const [a1, a2, a3] = parse(a);
+  const [b1, b2, b3] = parse(b);
+  if (a1 !== b1) return a1 - b1;
+  if (a2 !== b2) return a2 - b2;
+  return a3 - b3;
+}
+
+export class DirectoryReleaseNotesTools {
+  constructor(private client: DirectoryClient) {}
+
+  getTools(): Array<{ definition: ToolDefinition; executor: ToolExecutor }> {
+    return [
+      {
+        definition: {
+          name: "directory_release_notes",
+          tier: "read",
+          description:
+            "Use when the user asks: 'what's new in the directory mcp', " +
+            "'what changed in the directory', 'directory release notes', " +
+            "'what version is the directory on'. " +
+            "Returns recent releases of the PICA directory MCP server — " +
+            "what shipped in the public catalogue surface itself. " +
+            "NOT for catalogue content searches (use directory_search / " +
+            "directory_list_works / directory_chain for those). " +
+            "Returns { package, current_version, releases: [{ version, date, sections, markdown }], resource_uri }. " +
+            "Defaults to the last 3 releases; use `since_version` to bound the output " +
+            "or `sections` to filter to Added/Fixed/etc.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              since_version: {
+                type: "string",
+                description:
+                  "If set, returns only releases strictly greater than this version " +
+                  "(semver-compared). Versions equal to since_version are excluded.",
+              },
+              limit: {
+                type: "number",
+                description: `Maximum number of releases to return. Default ${DEFAULT_LIMIT}, max ${MAX_LIMIT}.`,
+              },
+              sections: {
+                type: "array",
+                items: { type: "string", enum: [...CHANGELOG_SECTION_NAMES] },
+                description:
+                  "Filter each release's sections to only these names " +
+                  "(e.g. ['Added', 'Fixed']). Sections not in the list are omitted from output.",
+              },
+            },
+          },
+        },
+        executor: this.releaseNotes.bind(this),
+      },
+    ];
+  }
+
+  private releaseNotes: ToolExecutor = async (
+    args: Record<string, any>,
+  ): Promise<ToolResult> => {
+    const sinceVersion =
+      typeof args.since_version === "string" ? args.since_version : null;
+    const rawLimit =
+      typeof args.limit === "number" ? args.limit : DEFAULT_LIMIT;
+    const limit = Math.max(1, Math.min(MAX_LIMIT, Math.floor(rawLimit)));
+    const sectionFilter: ChangelogSectionName[] | null = Array.isArray(
+      args.sections,
+    )
+      ? args.sections.filter((s: unknown): s is ChangelogSectionName =>
+          CHANGELOG_SECTION_NAMES.includes(s as ChangelogSectionName),
+        )
+      : null;
+
+    const all = parseChangelogText(CHANGELOG_MD);
+
+    let filtered = all;
+    if (sinceVersion) {
+      filtered = all.filter((e) => compareSemver(e.version, sinceVersion) > 0);
+    }
+    filtered = filtered.slice(0, limit);
+
+    const releases = filtered.map((e) => {
+      const sections = sectionFilter
+        ? Object.fromEntries(
+            Object.entries(e.sections).filter(([k]) =>
+              sectionFilter.includes(k as ChangelogSectionName),
+            ),
+          )
+        : e.sections;
+      return {
+        version: e.version,
+        date: e.date,
+        sections,
+        markdown: e.markdown,
+      };
+    });
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            {
+              package: PACKAGE_NAME,
+              current_version: PACKAGE_VERSION,
+              releases,
+              resource_uri: RESOURCE_URI,
+            },
+            null,
+            2,
+          ),
+        },
+      ],
+    };
+  };
+}