@esaio/esa-mcp-server 0.1.0 → 0.2.1

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

@@ -0,0 +1,460 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { createEsaClient } from "../../api_client/index.js";
+import { getAttachment } from "../attachments.js";
+
+// Mock global fetch
+const mockFetch = vi.fn();
+global.fetch = mockFetch;
+
+describe("getAttachment", () => {
+  const mockClient = {
+    GET: vi.fn(),
+  } as unknown as ReturnType<typeof createEsaClient> & {
+    GET: ReturnType<typeof vi.fn>;
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("should return base64-encoded image for small images", async () => {
+    const signedUrl = "https://s3.amazonaws.com/bucket/image.png?signature=123";
+    const imageData = "fake-image-data";
+    const imageBuffer = Buffer.from(imageData);
+
+    // Mock API response with signed URL
+    mockClient.GET.mockResolvedValue({
+      data: {
+        signed_urls: [["/uploads/example/image.png", signedUrl]],
+      },
+      error: undefined,
+      response: {
+        ok: true,
+        status: 200,
+      } as Response,
+    });
+
+    // Mock fetch response for image
+    mockFetch.mockResolvedValue({
+      ok: true,
+      headers: {
+        get: (name: string) => {
+          if (name === "content-type") return "image/png";
+          if (name === "content-length") return String(imageBuffer.length);
+          return null;
+        },
+      },
+      arrayBuffer: async () => {
+        const buffer = Buffer.from(imageData);
+        return buffer.buffer.slice(
+          buffer.byteOffset,
+          buffer.byteOffset + buffer.byteLength,
+        );
+      },
+    });
+
+    const result = await getAttachment(mockClient, {
+      teamName: "test-team",
+      url: "https://dl.esa.io/uploads/example/image.png",
+    });
+
+    expect(mockClient.GET).toHaveBeenCalledWith(
+      "/v1/teams/{team_name}/signed_urls",
+      {
+        params: {
+          path: { team_name: "test-team" },
+          query: {
+            urls: "/uploads/example/image.png",
+            v: 2,
+            expires_in: 300,
+          },
+        },
+      },
+    );
+
+    expect(mockFetch).toHaveBeenCalledWith(signedUrl);
+
+    expect(result).toEqual({
+      content: [
+        {
+          type: "image",
+          data: imageBuffer.toString("base64"),
+          mimeType: "image/png",
+        },
+      ],
+    });
+  });
+
+  it("should return signed URL for large images (over 30MB)", async () => {
+    const signedUrl = "https://s3.amazonaws.com/bucket/large.png?signature=123";
+    const largeSize = 35 * 1024 * 1024; // 35MB
+
+    mockClient.GET.mockResolvedValue({
+      data: {
+        signed_urls: [["/uploads/example/large.png", signedUrl]],
+      },
+      error: undefined,
+      response: {
+        ok: true,
+        status: 200,
+      } as Response,
+    });
+
+    mockFetch.mockResolvedValue({
+      ok: true,
+      headers: {
+        get: (name: string) => {
+          if (name === "content-type") return "image/png";
+          if (name === "content-length") return String(largeSize);
+          return null;
+        },
+      },
+    });
+
+    const result = await getAttachment(mockClient, {
+      teamName: "test-team",
+      url: "/uploads/example/large.png",
+    });
+
+    expect(result).toEqual({
+      content: [
+        {
+          type: "text",
+          text: signedUrl,
+        },
+      ],
+    });
+  });
+
+  it("should return signed URL for non-image files", async () => {
+    const signedUrl = "https://s3.amazonaws.com/bucket/doc.pdf?signature=123";
+
+    mockClient.GET.mockResolvedValue({
+      data: {
+        signed_urls: [["/uploads/example/doc.pdf", signedUrl]],
+      },
+      error: undefined,
+      response: {
+        ok: true,
+        status: 200,
+      } as Response,
+    });
+
+    mockFetch.mockResolvedValue({
+      ok: true,
+      headers: {
+        get: (name: string) => {
+          if (name === "content-type") return "application/pdf";
+          if (name === "content-length") return "1024";
+          return null;
+        },
+      },
+    });
+
+    const result = await getAttachment(mockClient, {
+      teamName: "test-team",
+      url: "https://files.esa.io/uploads/example/doc.pdf",
+    });
+
+    expect(result).toEqual({
+      content: [
+        {
+          type: "text",
+          text: signedUrl,
+        },
+      ],
+    });
+  });
+
+  it("should handle file not found (null signed URL)", async () => {
+    mockClient.GET.mockResolvedValue({
+      data: {
+        signed_urls: [["/uploads/example/missing.png", null]],
+      },
+      error: undefined,
+      response: {
+        ok: true,
+        status: 200,
+      } as Response,
+    });
+
+    const result = await getAttachment(mockClient, {
+      teamName: "test-team",
+      url: "/uploads/example/missing.png",
+    });
+
+    expect(result).toEqual({
+      content: [
+        {
+          type: "text",
+          text: "Error: File not found: /uploads/example/missing.png",
+        },
+      ],
+    });
+  });
+
+  it("should handle fetch failure", async () => {
+    const signedUrl = "https://s3.amazonaws.com/bucket/image.png?signature=123";
+
+    mockClient.GET.mockResolvedValue({
+      data: {
+        signed_urls: [["/uploads/example/image.png", signedUrl]],
+      },
+      error: undefined,
+      response: {
+        ok: true,
+        status: 200,
+      } as Response,
+    });
+
+    mockFetch.mockResolvedValue({
+      ok: false,
+      status: 403,
+      statusText: "Forbidden",
+    });
+
+    const result = await getAttachment(mockClient, {
+      teamName: "test-team",
+      url: "/uploads/example/image.png",
+    });
+
+    expect(result).toEqual({
+      content: [
+        {
+          type: "text",
+          text: "Error: Failed to fetch attachment for /uploads/example/image.png: Failed to fetch attachment: 403 Forbidden",
+        },
+      ],
+    });
+  });
+
+  it("should handle API errors", async () => {
+    const mockError = { error: "not_found", message: "Team not found" };
+
+    mockClient.GET.mockResolvedValue({
+      data: undefined,
+      error: mockError,
+      response: {
+        ok: false,
+        status: 404,
+      } as Response,
+    });
+
+    const result = await getAttachment(mockClient, {
+      teamName: "test-team",
+      url: "/uploads/example/image.png",
+    });
+
+    expect(result).toEqual({
+      content: [
+        {
+          type: "text",
+          text: `Error: ${JSON.stringify(mockError, null, 2)}`,
+        },
+      ],
+    });
+  });
+
+  it("should handle missing teamName", async () => {
+    const result = await getAttachment(mockClient, {
+      teamName: "",
+      url: "/uploads/example/image.png",
+    });
+
+    expect(result).toEqual({
+      content: [
+        {
+          type: "text",
+          text: "Error: Missing required parameter 'teamName'. Use esa_get_teams to list available teams, then retry with teamName specified.",
+        },
+      ],
+    });
+
+    expect(mockClient.GET).not.toHaveBeenCalled();
+  });
+
+  it("should support various image formats (jpeg, png, gif, webp)", async () => {
+    const testCases = [
+      { mimeType: "image/jpeg", url: "/image.jpg" },
+      { mimeType: "image/png", url: "/image.png" },
+      { mimeType: "image/gif", url: "/image.gif" },
+      { mimeType: "image/webp", url: "/image.webp" },
+    ];
+
+    for (const { mimeType, url } of testCases) {
+      vi.clearAllMocks();
+
+      const signedUrl = `https://s3.amazonaws.com/bucket${url}?signature=123`;
+      const imageData = "test-image";
+      const imageBuffer = Buffer.from(imageData);
+
+      mockClient.GET.mockResolvedValue({
+        data: {
+          signed_urls: [[url, signedUrl]],
+        },
+        error: undefined,
+        response: {
+          ok: true,
+          status: 200,
+        } as Response,
+      });
+
+      mockFetch.mockResolvedValue({
+        ok: true,
+        headers: {
+          get: (name: string) => {
+            if (name === "content-type") return mimeType;
+            if (name === "content-length") return String(imageBuffer.length);
+            return null;
+          },
+        },
+        arrayBuffer: async () => {
+          const buffer = Buffer.from(imageData);
+          return buffer.buffer.slice(
+            buffer.byteOffset,
+            buffer.byteOffset + buffer.byteLength,
+          );
+        },
+      });
+
+      const result = await getAttachment(mockClient, {
+        teamName: "test-team",
+        url,
+      });
+
+      expect(result).toEqual({
+        content: [
+          {
+            type: "image",
+            data: imageBuffer.toString("base64"),
+            mimeType,
+          },
+        ],
+      });
+    }
+  });
+
+  it("should return signed URL when forceSignedUrl is true", async () => {
+    const signedUrl = "https://s3.amazonaws.com/bucket/image.png?signature=123";
+
+    mockClient.GET.mockResolvedValue({
+      data: {
+        signed_urls: [["/uploads/example/image.png", signedUrl]],
+      },
+      error: undefined,
+      response: {
+        ok: true,
+        status: 200,
+      } as Response,
+    });
+
+    const result = await getAttachment(mockClient, {
+      teamName: "test-team",
+      url: "/uploads/example/image.png",
+      forceSignedUrl: true,
+    });
+
+    // Should not call fetch when forceSignedUrl is true
+    expect(mockFetch).not.toHaveBeenCalled();
+
+    expect(result).toEqual({
+      content: [
+        {
+          type: "text",
+          text: signedUrl,
+        },
+      ],
+    });
+  });
+
+  it("should return base64 for images under 30MB", async () => {
+    const signedUrl = "https://s3.amazonaws.com/bucket/image.png?signature=123";
+    const imageData = "a".repeat(25 * 1024 * 1024); // 25MB
+    const imageBuffer = Buffer.from(imageData);
+
+    mockClient.GET.mockResolvedValue({
+      data: {
+        signed_urls: [["/uploads/example/image.png", signedUrl]],
+      },
+      error: undefined,
+      response: {
+        ok: true,
+        status: 200,
+      } as Response,
+    });
+
+    mockFetch.mockResolvedValue({
+      ok: true,
+      headers: {
+        get: (name: string) => {
+          if (name === "content-type") return "image/png";
+          if (name === "content-length") return String(imageBuffer.length);
+          return null;
+        },
+      },
+      arrayBuffer: async () => {
+        const buffer = Buffer.from(imageData);
+        return buffer.buffer.slice(
+          buffer.byteOffset,
+          buffer.byteOffset + buffer.byteLength,
+        );
+      },
+    });
+
+    const result = await getAttachment(mockClient, {
+      teamName: "test-team",
+      url: "/uploads/example/image.png",
+    });
+
+    expect(result).toEqual({
+      content: [
+        {
+          type: "image",
+          data: imageBuffer.toString("base64"),
+          mimeType: "image/png",
+        },
+      ],
+    });
+  });
+
+  it("should return signed URL for unsupported image formats", async () => {
+    const signedUrl = "https://s3.amazonaws.com/bucket/image.svg?signature=123";
+    const imageBuffer = Buffer.from("svg-data");
+
+    mockClient.GET.mockResolvedValue({
+      data: {
+        signed_urls: [["/uploads/example/image.svg", signedUrl]],
+      },
+      error: undefined,
+      response: {
+        ok: true,
+        status: 200,
+      } as Response,
+    });
+
+    mockFetch.mockResolvedValue({
+      ok: true,
+      headers: {
+        get: (name: string) => {
+          if (name === "content-type") return "image/svg+xml";
+          if (name === "content-length") return String(imageBuffer.length);
+          return null;
+        },
+      },
+    });
+
+    const result = await getAttachment(mockClient, {
+      teamName: "test-team",
+      url: "/uploads/example/image.svg",
+    });
+
+    expect(result).toEqual({
+      content: [
+        {
+          type: "text",
+          text: signedUrl,
+        },
+      ],
+    });
+  });
+});

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

@@ -1,6 +1,10 @@
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import type { createEsaClient } from "../../api_client/index.js";
-import { getCategories, getTopCategories } from "../categories.js";
+import {
+  getAllCategoryPaths,
+  getCategories,
+  getTopCategories,
+} from "../categories.js";
 
 describe("getCategories", () => {
   const mockClient = {
@@ -224,3 +228,175 @@ describe("getTopCategories", () => {
     expect(mockClient.GET).not.toHaveBeenCalled();
   });
 });
+
+describe("getAllCategoryPaths", () => {
+  const mockClient = {
+    GET: vi.fn(),
+  } as unknown as ReturnType<typeof createEsaClient> & {
+    GET: ReturnType<typeof vi.fn>;
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("should fetch all category paths", async () => {
+    const mockResponse = [
+      { path: null, posts: 5 },
+      { path: "dev", posts: 10 },
+      { path: "dev/docs", posts: 3 },
+      { path: "design", posts: 7 },
+    ];
+
+    mockClient.GET.mockResolvedValue({
+      data: mockResponse,
+      error: undefined,
+      response: { ok: true, status: 200 } as Response,
+    });
+
+    const result = await getAllCategoryPaths(mockClient, {
+      teamName: "test-team",
+    });
+
+    expect(mockClient.GET).toHaveBeenCalledWith(
+      "/v1/teams/{team_name}/categories/paths",
+      {
+        params: {
+          path: { team_name: "test-team" },
+          query: {
+            prefix: undefined,
+            suffix: undefined,
+            match: undefined,
+            exact_match: undefined,
+          },
+        },
+      },
+    );
+
+    expect(result.content[0].text).toContain("dev");
+    expect(result.content[0].text).toContain("design");
+  });
+
+  it("should support prefix filter", async () => {
+    const mockResponse = [
+      { path: "dev", posts: 10 },
+      { path: "dev/docs", posts: 3 },
+    ];
+
+    mockClient.GET.mockResolvedValue({
+      data: mockResponse,
+      error: undefined,
+      response: { ok: true, status: 200 } as Response,
+    });
+
+    const result = await getAllCategoryPaths(mockClient, {
+      teamName: "test-team",
+      prefix: "dev",
+    });
+
+    expect(mockClient.GET).toHaveBeenCalledWith(
+      "/v1/teams/{team_name}/categories/paths",
+      {
+        params: {
+          path: { team_name: "test-team" },
+          query: {
+            prefix: "dev",
+            suffix: undefined,
+            match: undefined,
+            exact_match: undefined,
+          },
+        },
+      },
+    );
+
+    expect(result.content[0].text).toContain("dev");
+  });
+
+  it("should support multiple filters", async () => {
+    const mockResponse = [{ path: "dev/docs", posts: 3 }];
+
+    mockClient.GET.mockResolvedValue({
+      data: mockResponse,
+      error: undefined,
+      response: { ok: true, status: 200 } as Response,
+    });
+
+    const result = await getAllCategoryPaths(mockClient, {
+      teamName: "test-team",
+      prefix: "dev",
+      suffix: "docs",
+    });
+
+    expect(mockClient.GET).toHaveBeenCalledWith(
+      "/v1/teams/{team_name}/categories/paths",
+      {
+        params: {
+          path: { team_name: "test-team" },
+          query: {
+            prefix: "dev",
+            suffix: "docs",
+            match: undefined,
+            exact_match: undefined,
+          },
+        },
+      },
+    );
+
+    expect(result.content[0].text).toContain("dev/docs");
+  });
+
+  it("should handle API errors", async () => {
+    const mockError = { error: "forbidden", message: "Access denied" };
+
+    mockClient.GET.mockResolvedValue({
+      data: undefined,
+      error: mockError,
+      response: { ok: false, status: 403 } as Response,
+    });
+
+    const result = await getAllCategoryPaths(mockClient, {
+      teamName: "test-team",
+    });
+
+    expect(result.content[0].text).toContain("forbidden");
+  });
+
+  it("should handle network errors", async () => {
+    const networkError = new Error("Network connection failed");
+
+    mockClient.GET.mockRejectedValue(networkError);
+
+    const result = await getAllCategoryPaths(mockClient, {
+      teamName: "test-team",
+    });
+
+    expect(result.content[0].text).toContain("Network connection failed");
+  });
+
+  it("should handle non-Error exceptions", async () => {
+    mockClient.GET.mockRejectedValue("Unexpected error");
+
+    const result = await getAllCategoryPaths(mockClient, {
+      teamName: "test-team",
+    });
+
+    expect(result.content[0].text).toContain("Unexpected error");
+  });
+
+  it("should throw MissingTeamNameError when teamName is empty", async () => {
+    const result = await getAllCategoryPaths(mockClient, {
+      teamName: "",
+    });
+
+    expect(result).toEqual({
+      content: [
+        {
+          type: "text",
+          text: "Error: Missing required parameter 'teamName'. Use esa_get_teams to list available teams, then retry with teamName specified.",
+        },
+      ],
+    });
+
+    expect(mockClient.GET).not.toHaveBeenCalled();
+  });
+});

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

@@ -1,4 +1,5 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { MockInstance } from "vitest";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type { MCPContext } from "../../context/mcp-context.js";
 import { setupTools } from "../index.js";
@@ -6,7 +7,7 @@ import { setupTools } from "../index.js";
 describe("setupTools", () => {
   let server: McpServer;
   let context: MCPContext;
-  let consoleErrorSpy: ReturnType<typeof vi.spyOn>;
+  let consoleErrorSpy: MockInstance<typeof console.error>;
 
   beforeEach(() => {
     server = new McpServer({
@@ -23,14 +24,14 @@ describe("setupTools", () => {
     consoleErrorSpy.mockRestore();
   });
 
-  it("should register all 22 tools with correct handlers", () => {
+  it("should register all 24 tools with correct handlers", () => {
     const registerToolSpy = vi.spyOn(server, "registerTool");
 
     setupTools(server, context);
 
-    expect(registerToolSpy).toHaveBeenCalledTimes(22);
+    expect(registerToolSpy).toHaveBeenCalledTimes(24);
 
-    for (let i = 0; i < 22; i++) {
+    for (let i = 0; i < 24; i++) {
       const [toolName, schema, handler] = registerToolSpy.mock.calls[i];
       expect(typeof toolName).toBe("string");
       expect(toolName).toMatch(/^esa_/); // All tools should start with 'esa_'