@withpica/mcp-server-directory 1.3.0 → 1.4.0

package/dist/server.js

@@ -0,0 +1,223 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { DirectoryClient } from "./client.js";
+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 {
+    server;
+    client;
+    toolRegistry;
+    promptRegistry;
+    skillsRegistry;
+    config;
+    // Logged once after the MCP `initialize` handshake completes so each
+    // session prints a single client-attribution breadcrumb to stderr
+    // (Railway logs / Sentry breadcrumbs). Directory MCP has no DB audit
+    // pipeline today; this is provenance-only.
+    clientAttributionLogged = false;
+    constructor(config) {
+        this.config = config;
+        this.client = new DirectoryClient({
+            baseUrl: config.directoryUrl,
+            debug: config.debug,
+        });
+        this.server = new Server({
+            name: config.serverName,
+            version: config.version,
+        }, {
+            capabilities: {
+                tools: {},
+                resources: {},
+                prompts: {},
+            },
+        });
+        this.toolRegistry = new ToolRegistry(this.client);
+        this.promptRegistry = new PromptRegistry();
+        this.skillsRegistry = new SkillsRegistry();
+        this.setupHandlers();
+    }
+    setupHandlers() {
+        this.server.setRequestHandler(ListToolsRequestSchema, async () => {
+            if (this.config.debug) {
+                console.error("[Directory MCP] Listing tools");
+            }
+            return { tools: this.toolRegistry.listTools() };
+        });
+        this.server.setRequestHandler(ListResourcesRequestSchema, async () => {
+            const resources = [
+                {
+                    uri: "llms://primer",
+                    name: "PICA Domain Primer",
+                    description: "Plain-language description of PICA's domain model, entity relationships, and recommended agent workflows. Read this first.",
+                    mimeType: "text/markdown",
+                },
+                {
+                    uri: "skill://withpica/index.json",
+                    name: "PICA Directory Skills Index",
+                    description: "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({
+                    uri: `skill://withpica/${summary.name}/SKILL.md`,
+                    name: `Skill — ${summary.name}`,
+                    description: summary.description,
+                    mimeType: "text/markdown",
+                });
+            }
+            return { resources };
+        });
+        this.server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+            const { uri } = request.params;
+            if (uri === "llms://primer") {
+                return {
+                    contents: [
+                        {
+                            uri: "llms://primer",
+                            mimeType: "text/markdown",
+                            text: DIRECTORY_PRIMER,
+                        },
+                    ],
+                };
+            }
+            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);
+            }
+            throw new Error(`Resource not found: ${uri}`);
+        });
+        this.server.setRequestHandler(ListPromptsRequestSchema, async () => {
+            return { prompts: this.promptRegistry.listPrompts() };
+        });
+        this.server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+            const { name, arguments: args } = request.params;
+            return await this.promptRegistry.getPrompt(name, args);
+        });
+        this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+            const { name, arguments: args } = request.params;
+            this.logClientAttributionOnce();
+            if (this.config.debug) {
+                console.error(`[Directory MCP] Executing tool: ${name}`, args);
+            }
+            try {
+                return await this.toolRegistry.executeTool(name, args || {});
+            }
+            catch (error) {
+                logError(`Tool execution: ${name}`, error);
+                throw error;
+            }
+        });
+    }
+    /**
+     * Emit a single stderr line per session naming the client that handshook
+     * with us — sourced from `clientInfo` on the MCP `initialize` request.
+     * Self-declared, NOT authenticated; treat as provenance metadata only.
+     *
+     * Directory MCP is unauthenticated and writes no audit rows, so this
+     * stderr breadcrumb is the only attribution surface today. When/if a
+     * directory audit pipeline lands, fold these values into McpAuditEntry
+     * (the wire shape already carries optional client_name + client_version).
+     */
+    logClientAttributionOnce() {
+        if (this.clientAttributionLogged)
+            return;
+        const info = this.server.getClientVersion?.();
+        if (!info)
+            return;
+        this.clientAttributionLogged = true;
+        console.error(`[Directory MCP] client: ${info.name ?? "unknown"} v${info.version ?? "unknown"}`);
+    }
+    /**
+     * Resolve a skill:// URI. ADR-140 Phase 2b — SEP-2640 bridge pattern.
+     * Two URI shapes:
+     *   - skill://withpica/index.json
+     *   - skill://withpica/<name>/SKILL.md
+     */
+    readSkillResource(uri) {
+        if (uri === "skill://withpica/index.json") {
+            const index = this.skillsRegistry.listSkills().map((s) => ({
+                name: s.name,
+                uri: `skill://withpica/${s.name}/SKILL.md`,
+                description: s.description,
+                triggers: s.triggers,
+                audience: s.audience,
+            }));
+            return {
+                contents: [
+                    {
+                        uri,
+                        mimeType: "application/json",
+                        text: JSON.stringify({ skills: index }, null, 2),
+                    },
+                ],
+            };
+        }
+        const match = uri.match(/^skill:\/\/withpica\/([a-z0-9-]+)\/SKILL\.md$/);
+        if (!match) {
+            throw new Error(`Malformed skill URI: ${uri}`);
+        }
+        const name = match[1];
+        if (!this.skillsRegistry.has(name)) {
+            throw new Error(`Skill not found: ${name}`);
+        }
+        const skill = this.skillsRegistry.getSkill(name);
+        const frontmatter = [
+            "---",
+            `name: ${skill.name}`,
+            `description: ${skill.description}`,
+            "triggers:",
+            ...skill.triggers.map((t) => `  - ${t}`),
+            `audience: ${skill.audience}`,
+            "tools_required:",
+            ...skill.tools_required.map((t) => `  - ${t}`),
+            `output: ${skill.output}`,
+            "---",
+            "",
+        ].join("\n");
+        return {
+            contents: [
+                {
+                    uri,
+                    mimeType: "text/markdown",
+                    text: frontmatter + skill.body,
+                },
+            ],
+        };
+    }
+    async start() {
+        const transport = new StdioServerTransport();
+        await this.server.connect(transport);
+        console.error("[Directory MCP] PICA Directory MCP Server started");
+        console.error(`[Directory MCP] Version: ${this.config.version}`);
+        console.error(`[Directory MCP] API URL: ${this.config.directoryUrl}`);
+        console.error("[Directory MCP] Ready to accept connections");
+    }
+    async stop() {
+        await this.server.close();
+        console.error("[Directory MCP] Server stopped");
+    }
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/dist/skills/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Skills Registry — directory MCP, ADR-140 Phase 2b
+ *
+ * Sister of mcp-server/src/skills/index.ts. Same shape, scoped to the public
+ * directory MCP. Body bytes are generated at build time by
+ * `scripts/build-skills.ts` and inlined into `skills.generated.ts`.
+ *
+ * Public/anonymous surface — every skill body must clear the IP-protection
+ * lint (scripts/lint-mcp-tools.ts Rule 14) before publishing. Directory MCP
+ * skills MUST NOT quote from trade-secret directories listed in
+ * `.claude/rules/ip-protection.md`.
+ */
+import { SKILLS, SKILL_NAMES, type Skill } from "./skills.generated.js";
+export interface SkillSummary {
+    name: string;
+    description: string;
+    triggers: string[];
+    audience: string;
+}
+export declare class SkillsRegistry {
+    listNames(): ReadonlyArray<string>;
+    listSkills(): SkillSummary[];
+    getSkill(name: string): Skill;
+    has(name: string): boolean;
+}
+export declare class SkillNotFoundError extends Error {
+    readonly skillName: string;
+    constructor(skillName: string);
+}
+export { SKILLS, SKILL_NAMES };
+export type { Skill };
+//# sourceMappingURL=index.d.ts.map

package/dist/skills/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/skills/index.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAExE,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,cAAc;IACzB,SAAS,IAAI,aAAa,CAAC,MAAM,CAAC;IAIlC,UAAU,IAAI,YAAY,EAAE;IAY5B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK;IAQ7B,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;CAG3B;AAED,qBAAa,kBAAmB,SAAQ,KAAK;aACf,SAAS,EAAE,MAAM;gBAAjB,SAAS,EAAE,MAAM;CAI9C;AAED,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;AAC/B,YAAY,EAAE,KAAK,EAAE,CAAC"}

package/dist/skills/index.js

@@ -0,0 +1,50 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+/**
+ * Skills Registry — directory MCP, ADR-140 Phase 2b
+ *
+ * Sister of mcp-server/src/skills/index.ts. Same shape, scoped to the public
+ * directory MCP. Body bytes are generated at build time by
+ * `scripts/build-skills.ts` and inlined into `skills.generated.ts`.
+ *
+ * Public/anonymous surface — every skill body must clear the IP-protection
+ * lint (scripts/lint-mcp-tools.ts Rule 14) before publishing. Directory MCP
+ * skills MUST NOT quote from trade-secret directories listed in
+ * `.claude/rules/ip-protection.md`.
+ */
+import { SKILLS, SKILL_NAMES } from "./skills.generated.js";
+export class SkillsRegistry {
+    listNames() {
+        return SKILL_NAMES;
+    }
+    listSkills() {
+        return SKILL_NAMES.map((name) => {
+            const skill = SKILLS[name];
+            return {
+                name: skill.name,
+                description: skill.description,
+                triggers: skill.triggers,
+                audience: skill.audience,
+            };
+        });
+    }
+    getSkill(name) {
+        const skill = SKILLS[name];
+        if (!skill) {
+            throw new SkillNotFoundError(name);
+        }
+        return skill;
+    }
+    has(name) {
+        return name in SKILLS;
+    }
+}
+export class SkillNotFoundError extends Error {
+    skillName;
+    constructor(skillName) {
+        super(`Skill not found: ${skillName}`);
+        this.skillName = skillName;
+        this.name = "SkillNotFoundError";
+    }
+}
+export { SKILLS, SKILL_NAMES };
+//# sourceMappingURL=index.js.map

package/dist/skills/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/skills/index.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAE7D;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,MAAM,EAAE,WAAW,EAAc,MAAM,uBAAuB,CAAC;AASxE,MAAM,OAAO,cAAc;IACzB,SAAS;QACP,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,UAAU;QACR,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;YAC9B,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;YAC3B,OAAO;gBACL,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,WAAW,EAAE,KAAK,CAAC,WAAW;gBAC9B,QAAQ,EAAE,KAAK,CAAC,QAAQ;gBACxB,QAAQ,EAAE,KAAK,CAAC,QAAQ;aACzB,CAAC;QACJ,CAAC,CAAC,CAAC;IACL,CAAC;IAED,QAAQ,CAAC,IAAY;QACnB,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;QAC3B,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,kBAAkB,CAAC,IAAI,CAAC,CAAC;QACrC,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,GAAG,CAAC,IAAY;QACd,OAAO,IAAI,IAAI,MAAM,CAAC;IACxB,CAAC;CACF;AAED,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IACf;IAA5B,YAA4B,SAAiB;QAC3C,KAAK,CAAC,oBAAoB,SAAS,EAAE,CAAC,CAAC;QADb,cAAS,GAAT,SAAS,CAAQ;QAE3C,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AAED,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC"}

package/dist/skills/skills.generated.d.ts

@@ -0,0 +1,18 @@
+/**
+ * GENERATED FILE — DO NOT EDIT BY HAND.
+ *
+ * Regenerated by `scripts/build-skills.ts` from `src/skills/<name>/SKILL.md`.
+ * Runs in `prebuild`. See ADR-140 Phase 2b.
+ */
+export interface Skill {
+    name: string;
+    description: string;
+    triggers: string[];
+    audience: string;
+    tools_required: string[];
+    output: string;
+    body: string;
+}
+export declare const SKILLS: Record<string, Skill>;
+export declare const SKILL_NAMES: ReadonlyArray<string>;
+//# sourceMappingURL=skills.generated.d.ts.map

package/dist/skills/skills.generated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.generated.d.ts","sourceRoot":"","sources":["../../src/skills/skills.generated.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AAEH,MAAM,WAAW,KAAK;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAGD,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAUxC,CAAC;AAEF,eAAO,MAAM,WAAW,EAAE,aAAa,CAAC,MAAM,CAAiC,CAAC"}

package/dist/skills/skills.generated.js

@@ -0,0 +1,14 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+export const SKILLS = {
+    "find-music-for-sync-brief": {
+        name: "find-music-for-sync-brief",
+        description: "Find music in the PICA public directory for a sync brief — translate a mood/vibe/scene description into audio search parameters, run the search, and return a rights-aware shortlist with credit details for licensing.",
+        triggers: ["find music for a sync brief", "find me a track for a film scene", "music for this brief", "find an uplifting indie folk track", "I need music that sounds like"],
+        audience: "sync supervisor / music library / ad agency / film & TV music team",
+        tools_required: ["directory_search_recordings", "directory_lookup_work", "directory_lookup_person"],
+        output: "A rights-aware shortlist — each result with title, artist, audio characteristics (BPM, key, energy), credits summary for licensing contact, and any flags (unattested credits, low registration score, missing ISRC).",
+        body: "# find-music-for-sync-brief\n\nHelp the user find music in PICA's public directory for a sync brief. Translate their description (mood, vibe, scene, era, vocal style) into search parameters, run the search, and return a shortlist that includes the information they need to license — not just the track.\n\nThis is a public skill — any AI agent connected to the directory MCP can use it. The directory only contains works from organisations that have opted in.\n\n## Step 1 — Translate the brief\n\nMost sync briefs are described in natural language. Translate before searching:\n\n| User says | Search parameters |\n|---|---|\n| upbeat / uplifting / driving | `min_energy: 0.6`, `min_danceability: 0.5` |\n| dark / moody / brooding | `max_energy: 0.4`, `key_mode: minor` |\n| chill / ambient / background | `max_energy: 0.4`, `max_bpm: 100` |\n| epic / cinematic | `min_energy: 0.7`, often longer durations |\n| specific BPM (\"around 120bpm\") | `min_bpm: 115`, `max_bpm: 125` |\n| acoustic / sparse | typically lower `danceability` and `energy` |\n| vocal / instrumental | filter on `has_vocals` if available |\n\nIf the user gives an artist or song reference (\"something like X\"), look up that reference first via `directory_lookup_work` or `directory_search_recordings` by title — then mimic its audio profile in the new search.\n\n## Step 2 — Search\n\nCall `directory_search_recordings` with the parameters from step 1. Default limit is fine for an initial scan.\n\nIf the brief is vague, do two searches with slightly different parameters and compare. If too many results, narrow on BPM or key. If too few, widen the BPM range first, then drop key_mode.\n\n## Step 3 — Lookup full details\n\nFor the top 5-10 promising results, call `directory_lookup_work` to get:\n\n- **Who wrote it** — credits with IPI numbers (essential for the licensing contact path)\n- **Whether credits are attested** — an unattested credit means the ownership claim hasn't been verified; flag this\n- **DSP links** (Spotify, Apple Music) — the user wants to listen before shortlisting\n- **Registration score** — higher score = cleaner rights chain = easier to license\n\nFor high-value matches where the user wants to know more about the creator, call `directory_lookup_person` with the IPI to see the writer's broader catalog and collaborator network.\n\n## Step 4 — Present the shortlist\n\nPresent each shortlisted track with:\n\n- **Title, artist** — what the user listens for\n- **Audio profile** — BPM, key, energy (one line, the supervisor's quick filter)\n- **Credits summary** — writers with IPI, publisher if known (this is the licensing path)\n- **DSP links** — so the user can listen\n- **Flags** — unattested credits, low registration score, missing ISRC, multiple writers (= multi-party clearance needed)\n\nIf a track has all green flags (attested credits, high registration score, ISRC present, single or low-count writers), call it out as \"clean to clear.\"\n\n## Step 5 — If no results\n\nIf the search returns nothing, walk the user back through the brief:\n- Widen the BPM range first (most supervisors don't actually mind ±10 BPM)\n- Drop the key filter (key matching matters less than mood for most placements)\n- Drop the energy bounds and search by genre/mood text only\n- Suggest the user expand to adjacent moods (\"uplifting\" → also try \"warm\" or \"hopeful\")\n\nBe honest if the directory is small for a specific style — PICA's directory grows with org opt-ins; some niches are sparse.\n\n## What not to do\n\n- Don't claim to license tracks — this skill returns a shortlist, not a license. The user contacts the rights holder via the credits summary.\n- Don't speculate about pricing — sync fees are negotiated per-placement\n- Don't return results from outside the directory (no general web search, no Spotify metadata directly) — the directory is the source of truth for this skill\n- Don't return tracks with no attested credits without flagging them as \"rights chain unverified\"\n\n## Follow-on skills\n\n- `due-diligence-on-creator` (Stage 2 candidate) — for deeper research on a specific writer before reaching out\n",
+    },
+};
+export const SKILL_NAMES = ["find-music-for-sync-brief"];
+//# sourceMappingURL=skills.generated.js.map

package/dist/skills/skills.generated.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.generated.js","sourceRoot":"","sources":["../../src/skills/skills.generated.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAoB7D,MAAM,CAAC,MAAM,MAAM,GAA0B;IAC3C,2BAA2B,EAAE;QAC3B,IAAI,EAAE,2BAA2B;QACjC,WAAW,EAAE,yNAAyN;QACtO,QAAQ,EAAE,CAAC,6BAA6B,EAAC,kCAAkC,EAAC,sBAAsB,EAAC,oCAAoC,EAAC,+BAA+B,CAAC;QACxK,QAAQ,EAAE,oEAAoE;QAC9E,cAAc,EAAE,CAAC,6BAA6B,EAAC,uBAAuB,EAAC,yBAAyB,CAAC;QACjG,MAAM,EAAE,uNAAuN;QAC/N,IAAI,EAAE,ijIAAijI;KACxjI;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,WAAW,GAA0B,CAAC,2BAA2B,CAAC,CAAC"}

package/dist/tools/__tests__/release-notes.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=release-notes.test.d.ts.map

package/dist/tools/__tests__/release-notes.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"release-notes.test.d.ts","sourceRoot":"","sources":["../../../src/tools/__tests__/release-notes.test.ts"],"names":[],"mappings":""}

package/dist/tools/__tests__/release-notes.test.js

@@ -0,0 +1,49 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+import { DirectoryReleaseNotesTools } from "../release-notes.js";
+describe("DirectoryReleaseNotesTools.directory_release_notes", () => {
+    const client = {};
+    const tools = new DirectoryReleaseNotesTools(client).getTools();
+    const tool = tools.find((t) => 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);
+    });
+});
+//# sourceMappingURL=release-notes.test.js.map

package/dist/tools/__tests__/release-notes.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"release-notes.test.js","sourceRoot":"","sources":["../../../src/tools/__tests__/release-notes.test.ts"],"names":[],"mappings":"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"}

package/dist/tools/chain.d.ts

@@ -0,0 +1,12 @@
+import { DirectoryClient } from "../client.js";
+import { ToolDefinition, ToolExecutor } from "./index.js";
+export declare class DirectoryChainTools {
+    private client;
+    constructor(client: DirectoryClient);
+    getTools(): Array<{
+        definition: ToolDefinition;
+        executor: ToolExecutor;
+    }>;
+    private chainLookup;
+}
+//# sourceMappingURL=chain.d.ts.map

package/dist/tools/chain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chain.d.ts","sourceRoot":"","sources":["../../src/tools/chain.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1D,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,MAAM,CAAkB;gBAEpB,MAAM,EAAE,eAAe;IAInC,QAAQ,IAAI,KAAK,CAAC;QAAE,UAAU,EAAE,cAAc,CAAC;QAAC,QAAQ,EAAE,YAAY,CAAA;KAAE,CAAC;YAgE3D,WAAW;CAyC1B"}

package/dist/tools/chain.js

@@ -0,0 +1,109 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+export class DirectoryChainTools {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    getTools() {
+        return [
+            {
+                definition: {
+                    name: "directory_chain",
+                    tier: "read",
+                    description: "Use when the user asks: 'show me the rights chain for X', " +
+                        "'give me everything on this song', 'what's the full picture for X?', " +
+                        "'trace the chain from this writer to that work'. " +
+                        "Graph lookup — resolves a query, ISWC, or ISRC to its full rights chain in one call. " +
+                        "Each result bundles the work, its writers and publishers (names + roles, no IPIs or splits), " +
+                        "the linked recording (ISRC, DSP presence, duration), and audio characteristics (BPM, key, energy). " +
+                        "Prefer over stitching list_works + lookup_work + lookup_person when you want the whole graph " +
+                        "around a track in a single round-trip. " +
+                        "Supports audio-only queries (min_bpm, key, mood, etc.) when you don't have a text query. " +
+                        "→ then: directory_lookup_work (deeper work detail), directory_lookup_person (research a named writer)",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            q: {
+                                type: "string",
+                                description: "Free-text query (work title, creator name, etc.). Minimum 2 characters.",
+                            },
+                            identifier: {
+                                type: "string",
+                                description: "ISWC or ISRC — direct identifier lookup",
+                            },
+                            min_bpm: { type: "number", description: "Minimum BPM" },
+                            max_bpm: { type: "number", description: "Maximum BPM" },
+                            key: {
+                                type: "string",
+                                description: "Musical key (e.g. 'C', 'F#', 'Bb')",
+                            },
+                            key_mode: {
+                                type: "string",
+                                enum: ["major", "minor"],
+                                description: "Key mode",
+                            },
+                            min_energy: {
+                                type: "number",
+                                description: "Minimum energy (0–1)",
+                            },
+                            max_energy: {
+                                type: "number",
+                                description: "Maximum energy (0–1)",
+                            },
+                            mood: {
+                                type: "string",
+                                description: "Mood filter (exact match)",
+                            },
+                            limit: {
+                                type: "number",
+                                description: "Max results (default 10, max 20)",
+                            },
+                        },
+                    },
+                },
+                executor: this.chainLookup.bind(this),
+            },
+        ];
+    }
+    async chainLookup(args) {
+        const params = {};
+        if (args.q)
+            params.q = String(args.q);
+        if (args.identifier)
+            params.identifier = String(args.identifier);
+        const numericKeys = [
+            "min_bpm",
+            "max_bpm",
+            "min_energy",
+            "max_energy",
+            "limit",
+        ];
+        for (const k of numericKeys) {
+            if (args[k] != null)
+                params[k] = String(args[k]);
+        }
+        if (args.key)
+            params.key = args.key;
+        if (args.key_mode)
+            params.key_mode = args.key_mode;
+        if (args.mood)
+            params.mood = args.mood;
+        const response = await this.client.request("/chain", params);
+        const results = response.results || [];
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: results.length === 0
+                        ? "No chain results."
+                        : `Found ${results.length} chain result(s). See structuredContent for the full graph.`,
+                },
+            ],
+            structuredContent: {
+                total: response.total ?? results.length,
+                results,
+            },
+        };
+    }
+}
+//# sourceMappingURL=chain.js.map

package/dist/tools/chain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chain.js","sourceRoot":"","sources":["../../src/tools/chain.ts"],"names":[],"mappings":"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"}

package/dist/tools/index.d.ts

@@ -0,0 +1,36 @@
+import { DirectoryClient } from "../client.js";
+/**
+ * ADR-230 — authority tier on every directory_* tool. Sister of the
+ * creator + team MCP's `Tier` declaration. Every directory tool is
+ * `read` (public catalogue lookup with no mutation surface), but the
+ * field is required for cross-surface uniformity and lint enforcement.
+ */
+export type Tier = "read" | "draft" | "write" | "destructive";
+export interface ToolDefinition {
+    name: string;
+    /** ADR-230 — see {@link Tier}. Required on every directory tool. */
+    tier: Tier;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: Record<string, any>;
+        required?: string[];
+        additionalProperties?: boolean;
+    };
+}
+export interface ToolResult {
+    content: Array<{
+        type: string;
+        text: string;
+    }>;
+    structuredContent?: Record<string, unknown>;
+    isError?: boolean;
+}
+export type ToolExecutor = (args: Record<string, any>) => Promise<any>;
+export declare class ToolRegistry {
+    private tools;
+    constructor(client: DirectoryClient);
+    listTools(): ToolDefinition[];
+    executeTool(name: string, args: Record<string, any>): Promise<any>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAU/C;;;;;GAKG;AACH,MAAM,MAAM,IAAI,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,GAAG,aAAa,CAAC;AAE9D,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,IAAI,EAAE,IAAI,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE;QACX,IAAI,EAAE,MAAM,CAAC;QACb,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAChC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;QACpB,oBAAoB,CAAC,EAAE,OAAO,CAAC;KAChC,CAAC;CACH;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5C,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;AAEvE,qBAAa,YAAY;IACvB,OAAO,CAAC,KAAK,CAGX;gBAEU,MAAM,EAAE,eAAe;IAoBnC,SAAS,IAAI,cAAc,EAAE;IAIvB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC;CAgBzE"}