@withpica/mcp-server-directory 1.0.0 → 1.2.0

package/src/__tests__/tools/people.test.ts

@@ -0,0 +1,112 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+
+import {
+  jest,
+  describe,
+  it,
+  expect,
+  beforeEach,
+  afterEach,
+} from "@jest/globals";
+import { DirectoryPeopleTools } from "../../tools/people";
+import { DirectoryClient } from "../../client";
+
+describe("DirectoryPeopleTools", () => {
+  let peopleTools: DirectoryPeopleTools;
+  let mockClient: jest.Mocked<DirectoryClient>;
+
+  beforeEach(() => {
+    mockClient = { request: jest.fn() } as any;
+    peopleTools = new DirectoryPeopleTools(mockClient);
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it("registers 2 tools", () => {
+    const tools = peopleTools.getTools();
+    expect(tools).toHaveLength(2);
+    const names = tools.map((t) => t.definition.name);
+    expect(names).toContain("directory_list_people");
+    expect(names).toContain("directory_lookup_person");
+  });
+
+  it("exposes the letter filter on list_people", () => {
+    const tool = peopleTools
+      .getTools()
+      .find((t) => t.definition.name === "directory_list_people")!;
+    expect(tool.definition.inputSchema.properties.letter).toBeDefined();
+  });
+
+  describe("directory_list_people", () => {
+    it("calls /people with query params", async () => {
+      mockClient.request.mockResolvedValue({
+        success: true,
+        data: [{ global_creator_id: "gc1", name: "John Doe" }],
+        pagination: { limit: 20, offset: 0, total: 1 },
+      });
+
+      const tool = peopleTools
+        .getTools()
+        .find((t) => t.definition.name === "directory_list_people")!;
+      await tool.executor({ q: "john", isni: "0000000123456789" });
+
+      expect(mockClient.request).toHaveBeenCalledWith("/people", {
+        q: "john",
+        isni: "0000000123456789",
+        limit: "20",
+        offset: "0",
+      });
+    });
+
+    it("calculates offset from page number", async () => {
+      mockClient.request.mockResolvedValue({
+        success: true,
+        data: [],
+        pagination: { limit: 20, offset: 20, total: 50 },
+      });
+
+      const tool = peopleTools
+        .getTools()
+        .find((t) => t.definition.name === "directory_list_people")!;
+      await tool.executor({ page: 2 });
+
+      expect(mockClient.request).toHaveBeenCalledWith("/people", {
+        limit: "20",
+        offset: "20",
+      });
+    });
+  });
+
+  describe("error handling", () => {
+    it("throws on API failure", async () => {
+      mockClient.request.mockRejectedValue(new Error("Network error"));
+      const tool = peopleTools
+        .getTools()
+        .find((t) => t.definition.name === "directory_list_people")!;
+      await expect(tool.executor({})).rejects.toThrow("Network error");
+    });
+  });
+
+  describe("directory_lookup_person", () => {
+    it("calls /people/{id}", async () => {
+      mockClient.request.mockResolvedValue({
+        success: true,
+        data: {
+          global_creator_id: "gc1",
+          name: "John Doe",
+          roles: ["Writer", "Producer"],
+        },
+      });
+
+      const tool = peopleTools
+        .getTools()
+        .find((t) => t.definition.name === "directory_lookup_person")!;
+      const result = await tool.executor({ id: "gc1" });
+
+      expect(mockClient.request).toHaveBeenCalledWith("/people/gc1");
+      expect(result.content).toBeDefined();
+    });
+  });
+});

package/src/__tests__/tools/search.test.ts

@@ -0,0 +1,94 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+
+import {
+  jest,
+  describe,
+  it,
+  expect,
+  beforeEach,
+  afterEach,
+} from "@jest/globals";
+import { DirectorySearchTools } from "../../tools/search";
+import { DirectoryClient } from "../../client";
+
+describe("DirectorySearchTools", () => {
+  let searchTools: DirectorySearchTools;
+  let mockClient: jest.Mocked<DirectoryClient>;
+
+  beforeEach(() => {
+    mockClient = { request: jest.fn() } as any;
+    searchTools = new DirectorySearchTools(mockClient);
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it("registers 1 tool", () => {
+    const tools = searchTools.getTools();
+    expect(tools).toHaveLength(1);
+    expect(tools[0].definition.name).toBe("directory_search");
+  });
+
+  describe("directory_search", () => {
+    it("calls /search with query", async () => {
+      mockClient.request.mockResolvedValue({
+        success: true,
+        data: [
+          { type: "work", id: "w1", title: "Test Song" },
+          { type: "person", id: "p1", name: "Test Artist" },
+        ],
+        pagination: { limit: 20, offset: 0, total: 2 },
+      });
+
+      const tool = searchTools
+        .getTools()
+        .find((t) => t.definition.name === "directory_search")!;
+      const result = await tool.executor({ query: "test" });
+
+      expect(mockClient.request).toHaveBeenCalledWith("/search", {
+        q: "test",
+        limit: "20",
+        offset: "0",
+      });
+      expect(result.content).toBeDefined();
+    });
+
+    it("passes type filter", async () => {
+      mockClient.request.mockResolvedValue({
+        success: true,
+        data: [],
+        pagination: { limit: 20, offset: 0, total: 0 },
+      });
+
+      const tool = searchTools
+        .getTools()
+        .find((t) => t.definition.name === "directory_search")!;
+      await tool.executor({ query: "test", type: "works" });
+
+      expect(mockClient.request).toHaveBeenCalledWith("/search", {
+        q: "test",
+        type: "works",
+        limit: "20",
+        offset: "0",
+      });
+    });
+
+    it("throws on API failure", async () => {
+      mockClient.request.mockRejectedValue(new Error("Network error"));
+      const tool = searchTools
+        .getTools()
+        .find((t) => t.definition.name === "directory_search")!;
+      await expect(tool.executor({ query: "test" })).rejects.toThrow(
+        "Network error",
+      );
+    });
+
+    it("requires query parameter", () => {
+      const tool = searchTools
+        .getTools()
+        .find((t) => t.definition.name === "directory_search")!;
+      expect(tool.definition.inputSchema.required).toContain("query");
+    });
+  });
+});

package/src/__tests__/tools/works.test.ts

@@ -0,0 +1,177 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+
+import {
+  jest,
+  describe,
+  it,
+  expect,
+  beforeEach,
+  afterEach,
+} from "@jest/globals";
+import { DirectoryWorksTools } from "../../tools/works";
+import { DirectoryClient } from "../../client";
+
+describe("DirectoryWorksTools", () => {
+  let worksTools: DirectoryWorksTools;
+  let mockClient: jest.Mocked<DirectoryClient>;
+
+  beforeEach(() => {
+    mockClient = {
+      request: jest.fn(),
+    } as any;
+
+    worksTools = new DirectoryWorksTools(mockClient);
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it("registers 3 tools", () => {
+    const tools = worksTools.getTools();
+    expect(tools).toHaveLength(3);
+    const names = tools.map((t) => t.definition.name);
+    expect(names).toContain("directory_list_works");
+    expect(names).toContain("directory_lookup_work");
+    expect(names).toContain("directory_lookup_isrc");
+  });
+
+  it("exposes letter, sort, and isrc filters on list_works", () => {
+    const tool = worksTools
+      .getTools()
+      .find((t) => t.definition.name === "directory_list_works")!;
+    expect(tool.definition.inputSchema.properties.letter).toBeDefined();
+    expect(tool.definition.inputSchema.properties.sort).toBeDefined();
+    expect(tool.definition.inputSchema.properties.isrc).toBeDefined();
+  });
+
+  it("list_works forwards letter, sort, and isrc to /works", async () => {
+    mockClient.request.mockResolvedValue({
+      success: true,
+      data: [],
+      pagination: { limit: 20, offset: 0, total: 0 },
+    });
+
+    const tool = worksTools
+      .getTools()
+      .find((t) => t.definition.name === "directory_list_works")!;
+    await tool.executor({ letter: "B", sort: "recent", isrc: "USABC1234567" });
+
+    expect(mockClient.request).toHaveBeenCalledWith("/works", {
+      letter: "B",
+      sort: "recent",
+      isrc: "USABC1234567",
+      limit: "20",
+      offset: "0",
+    });
+  });
+
+  describe("directory_list_works", () => {
+    it("calls /works with query params", async () => {
+      mockClient.request.mockResolvedValue({
+        success: true,
+        data: [{ id: "w1", title: "Test Song" }],
+        pagination: { limit: 20, offset: 0, total: 1 },
+      });
+
+      const tool = worksTools
+        .getTools()
+        .find((t) => t.definition.name === "directory_list_works")!;
+      const result = await tool.executor({ q: "test", page: 1 });
+
+      expect(mockClient.request).toHaveBeenCalledWith("/works", {
+        q: "test",
+        limit: "20",
+        offset: "0",
+      });
+      expect(result.content).toBeDefined();
+    });
+
+    it("passes publisher and label filters", async () => {
+      mockClient.request.mockResolvedValue({
+        success: true,
+        data: [],
+        pagination: { limit: 20, offset: 0, total: 0 },
+      });
+
+      const tool = worksTools
+        .getTools()
+        .find((t) => t.definition.name === "directory_list_works")!;
+      await tool.executor({ publisher: "Sony", label: "Columbia" });
+
+      expect(mockClient.request).toHaveBeenCalledWith("/works", {
+        publisher: "Sony",
+        label: "Columbia",
+        limit: "20",
+        offset: "0",
+      });
+    });
+
+    it("calculates offset from page number", async () => {
+      mockClient.request.mockResolvedValue({
+        success: true,
+        data: [],
+        pagination: { limit: 20, offset: 40, total: 100 },
+      });
+
+      const tool = worksTools
+        .getTools()
+        .find((t) => t.definition.name === "directory_list_works")!;
+      await tool.executor({ page: 3 });
+
+      expect(mockClient.request).toHaveBeenCalledWith("/works", {
+        limit: "20",
+        offset: "40",
+      });
+    });
+  });
+
+  describe("directory_lookup_work", () => {
+    it("calls /works/{identifier}", async () => {
+      mockClient.request.mockResolvedValue({
+        success: true,
+        data: { id: "w1", title: "Test Song", iswc: "T-123.456.789-0" },
+      });
+
+      const tool = worksTools
+        .getTools()
+        .find((t) => t.definition.name === "directory_lookup_work")!;
+      const result = await tool.executor({ identifier: "T-123.456.789-0" });
+
+      expect(mockClient.request).toHaveBeenCalledWith("/works/T-123.456.789-0");
+      expect(result.content).toBeDefined();
+    });
+  });
+
+  describe("error handling", () => {
+    it("throws on API failure", async () => {
+      mockClient.request.mockRejectedValue(new Error("Network error"));
+      const tool = worksTools
+        .getTools()
+        .find((t) => t.definition.name === "directory_list_works")!;
+      await expect(tool.executor({})).rejects.toThrow("Network error");
+    });
+  });
+
+  describe("directory_lookup_isrc", () => {
+    it("calls /works with isrc param", async () => {
+      mockClient.request.mockResolvedValue({
+        success: true,
+        data: [{ id: "w1", title: "Test Song" }],
+        pagination: { limit: 20, offset: 0, total: 1 },
+      });
+
+      const tool = worksTools
+        .getTools()
+        .find((t) => t.definition.name === "directory_lookup_isrc")!;
+      const result = await tool.executor({ isrc: "USABC1234567" });
+
+      expect(mockClient.request).toHaveBeenCalledWith("/works", {
+        isrc: "USABC1234567",
+        limit: "100",
+        offset: "0",
+      });
+      expect(result.content).toBeDefined();
+    });
+  });
+});

package/src/client.ts

@@ -0,0 +1,128 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+
+const DEFAULT_TIMEOUT_MS = 15_000;
+const MAX_RETRIES = 2;
+const RETRY_BASE_MS = 500;
+
+function isRetryableStatus(status: number): boolean {
+  return status === 429 || status === 502 || status === 503 || status === 504;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export interface DirectoryClientConfig {
+  baseUrl: string;
+  debug?: boolean;
+}
+
+export class DirectoryClient {
+  private baseUrl: string;
+  private debug: boolean;
+
+  constructor(config: DirectoryClientConfig) {
+    this.baseUrl = config.baseUrl.replace(/\/$/, "");
+    this.debug = config.debug || false;
+  }
+
+  private async fetchWithTimeout(
+    url: string,
+    init: RequestInit,
+    timeoutMs: number,
+  ): Promise<Response> {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      return await fetch(url, { ...init, signal: controller.signal });
+    } catch (err: any) {
+      if (err.name === "AbortError") {
+        throw new Error(`Request timed out after ${timeoutMs}ms: GET ${url}`);
+      }
+      throw err;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  async request<T>(path: string, params?: Record<string, string>): Promise<T> {
+    const url = new URL(`${this.baseUrl}/api/public/directory${path}`);
+    if (params) {
+      Object.entries(params).forEach(([key, value]) => {
+        if (value !== undefined && value !== "") {
+          url.searchParams.set(key, value);
+        }
+      });
+    }
+
+    if (this.debug) {
+      console.error(
+        `[Directory MCP] GET ${url.toString()} (timeout: ${DEFAULT_TIMEOUT_MS}ms)`,
+      );
+    }
+
+    let lastError: Error | undefined;
+
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+      try {
+        const response = await this.fetchWithTimeout(
+          url.toString(),
+          { method: "GET", headers: { Accept: "application/json" } },
+          DEFAULT_TIMEOUT_MS,
+        );
+
+        if (response.ok) {
+          const json: any = await response.json();
+          if (json.success === false) {
+            throw new Error(json.error || "API returned unsuccessful response");
+          }
+          return json as T;
+        }
+
+        const errorText = await response.text();
+
+        // Auth errors — fail fast, never retry
+        if (response.status === 401 || response.status === 403) {
+          throw new Error(
+            `Authentication failed: ${response.status} ${errorText}`,
+          );
+        }
+
+        if (isRetryableStatus(response.status) && attempt < MAX_RETRIES) {
+          const retryAfter = response.headers.get("retry-after");
+          const parsed = retryAfter ? parseInt(retryAfter, 10) : NaN;
+          const delayMs = !isNaN(parsed)
+            ? parsed * 1000
+            : RETRY_BASE_MS * Math.pow(2, attempt);
+          if (this.debug) {
+            console.error(
+              `[Directory MCP] ${response.status} on attempt ${attempt + 1}, retrying in ${delayMs}ms`,
+            );
+          }
+          await sleep(delayMs);
+          continue;
+        }
+
+        throw new Error(`API request failed: ${response.status} ${errorText}`);
+      } catch (err) {
+        lastError = err as Error;
+        if (
+          (err as Error).message?.includes("timed out") &&
+          attempt < MAX_RETRIES
+        ) {
+          const delayMs = RETRY_BASE_MS * Math.pow(2, attempt);
+          if (this.debug) {
+            console.error(
+              `[Directory MCP] timeout on attempt ${attempt + 1}, retrying in ${delayMs}ms`,
+            );
+          }
+          await sleep(delayMs);
+          continue;
+        }
+        throw err;
+      }
+    }
+
+    throw lastError || new Error("Request failed after retries");
+  }
+}

package/src/config.ts

@@ -0,0 +1,23 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+
+export interface ServerConfig {
+  directoryUrl: string;
+  serverName: string;
+  version: string;
+  debug: boolean;
+}
+
+export function loadConfig(): ServerConfig {
+  return {
+    directoryUrl: process.env.PICA_DIRECTORY_URL || "https://withpica.com",
+    serverName: "pica-directory-mcp-server",
+    version: "1.0.0",
+    debug: process.env.DEBUG === "true" || process.env.DEBUG === "1",
+  };
+}
+
+export function validateConfig(config: ServerConfig): void {
+  if (!config.directoryUrl || !config.directoryUrl.startsWith("http")) {
+    throw new Error("Invalid PICA_DIRECTORY_URL");
+  }
+}

package/src/index.ts

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+
+
+import { loadConfig, validateConfig } from "./config.js";
+import { DirectoryMcpServer } from "./server.js";
+
+async function main() {
+  try {
+    const config = loadConfig();
+    validateConfig(config);
+
+    const server = new DirectoryMcpServer(config);
+    await server.start();
+
+    process.on("SIGINT", async () => {
+      console.error("[Directory MCP] Shutting down...");
+      await server.stop();
+      process.exit(0);
+    });
+
+    process.on("SIGTERM", async () => {
+      console.error("[Directory MCP] Shutting down...");
+      await server.stop();
+      process.exit(0);
+    });
+  } catch (error) {
+    console.error(
+      "[Directory MCP] Fatal error:",
+      error instanceof Error ? error.message : String(error),
+    );
+    process.exit(1);
+  }
+}
+
+main();