@esaio/esa-mcp-server 0.1.0

package/src/resources/__tests__/recent-posts-list.test.ts

@@ -0,0 +1,91 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { withContext } from "../../api_client/with-context.js";
+import type { MCPContext } from "../../context/mcp-context.js";
+import { getTeams } from "../../tools/teams.js";
+import { createRecentPostsResourceList } from "../recent-posts-list.js";
+
+vi.mock("../../api_client/with-context.js");
+vi.mock("../../tools/teams.js");
+
+describe("createRecentPostsResourceList", () => {
+  let context: MCPContext;
+  let consoleErrorSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    context = {} as unknown as MCPContext;
+    consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    consoleErrorSpy.mockRestore();
+  });
+
+  it("should return team resources when teams are available", async () => {
+    const mockTeams = {
+      teams: [
+        { name: "team1", description: "Team One" },
+        { name: "team2", description: "" },
+      ],
+    };
+
+    vi.mocked(withContext).mockResolvedValue({
+      content: [{ text: JSON.stringify(mockTeams) }],
+    } as unknown as Awaited<ReturnType<typeof withContext>>);
+
+    const result = await createRecentPostsResourceList(context);
+
+    expect(withContext).toHaveBeenCalledWith(context, getTeams, {});
+    expect(result).toEqual([
+      {
+        uri: "esa://teams/team1/posts/recent",
+        name: "Recent posts from team1",
+        description: "Recent posts from team1 (Team One)",
+        mimeType: "application/json",
+      },
+      {
+        uri: "esa://teams/team2/posts/recent",
+        name: "Recent posts from team2",
+        description: "Recent posts from team2",
+        mimeType: "application/json",
+      },
+    ]);
+  });
+
+  it("should return empty array when no teams available", async () => {
+    vi.mocked(withContext).mockResolvedValue({
+      content: [{ text: JSON.stringify({ teams: null }) }],
+    } as unknown as Awaited<ReturnType<typeof withContext>>);
+
+    const result = await createRecentPostsResourceList(context);
+
+    expect(result).toEqual([]);
+  });
+
+  it("should return empty array and log error when withContext fails", async () => {
+    const error = new Error("API Error");
+    vi.mocked(withContext).mockRejectedValue(error);
+
+    const result = await createRecentPostsResourceList(context);
+
+    expect(result).toEqual([]);
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      "Failed to list teams:",
+      error,
+    );
+  });
+
+  it("should return empty array when JSON parsing fails", async () => {
+    vi.mocked(withContext).mockResolvedValue({
+      content: [{ text: "invalid json" }],
+    } as unknown as Awaited<ReturnType<typeof withContext>>);
+
+    const result = await createRecentPostsResourceList(context);
+
+    expect(result).toEqual([]);
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      "Failed to list teams:",
+      expect.any(SyntaxError),
+    );
+  });
+});

package/src/resources/__tests__/recent-posts.test.ts

@@ -0,0 +1,270 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  createExpectedTransformed,
+  createLongContentPost,
+  createMockPost,
+  createNullBodyPost,
+  createWipPost,
+} from "../../__tests__/fixtures/mock-post.js";
+import type { createEsaClient } from "../../api_client/index.js";
+import { getRecentPosts } from "../recent-posts.js";
+
+describe("getRecentPosts", () => {
+  const mockClient = {
+    GET: vi.fn(),
+  } as unknown as ReturnType<typeof createEsaClient> & {
+    GET: ReturnType<typeof vi.fn>;
+  };
+
+  const testUri = "esa://teams/test-team/posts/recent";
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("should return recent posts successfully", async () => {
+    const mockPosts = [
+      createMockPost({
+        number: 1,
+        name: "post1.md",
+        full_name: "dev/post1.md #tag1 #tag2",
+        body_md:
+          "This is a test post content that is quite long and should be truncated",
+        body_html: "<p>This is a test post content</p>",
+        url: "https://test-team.esa.example.com/posts/1",
+        comments_count: 3,
+        tasks_count: 5,
+        done_tasks_count: 2,
+        watchers_count: 7,
+        star: false,
+        watch: false,
+      }),
+      createWipPost({
+        number: 2,
+        name: "post2.md",
+        full_name: "docs/post2.md #wip",
+        body_md: "Short content",
+        body_html: "<p>Short content</p>",
+        url: "https://test-team.esa.example.com/posts/2",
+        created_at: "2024-01-03T00:00:00+09:00",
+        updated_at: "2024-01-04T00:00:00+09:00",
+        stargazers_count: 1,
+        watchers_count: 2,
+        star: true,
+        watch: true,
+      }),
+    ];
+
+    const mockResponse = {
+      posts: mockPosts,
+      page: 1,
+      per_page: 20,
+      total_count: 2,
+      max_per_page: 100,
+    };
+
+    mockClient.GET.mockResolvedValue({
+      data: mockResponse,
+      error: undefined,
+      response: {
+        ok: true,
+        status: 200,
+      } as Response,
+    });
+
+    const result = await getRecentPosts(mockClient, {
+      teamName: "test-team",
+      uri: testUri,
+    });
+
+    expect(mockClient.GET).toHaveBeenCalledWith("/v1/teams/{team_name}/posts", {
+      params: {
+        path: { team_name: "test-team" },
+        query: {
+          sort: "updated",
+          order: "desc",
+        },
+      },
+    });
+
+    const expectedResponse = {
+      posts: mockPosts.map((post) => createExpectedTransformed(post)),
+      page: 1,
+      per_page: 20,
+      total_count: 2,
+      max_per_page: 100,
+    };
+
+    expect(result).toEqual({
+      contents: [
+        {
+          uri: testUri,
+          mimeType: "application/json",
+          text: JSON.stringify(expectedResponse, null, 2),
+        },
+      ],
+    });
+  });
+
+  it("should truncate long body_md content", async () => {
+    const mockPost = createLongContentPost(600);
+
+    mockClient.GET.mockResolvedValue({
+      data: { posts: [mockPost] },
+      error: undefined,
+      response: {
+        ok: true,
+        status: 200,
+      } as Response,
+    });
+
+    const result = await getRecentPosts(mockClient, {
+      teamName: "test-team",
+      uri: testUri,
+    });
+
+    const parsedResult = JSON.parse(result.contents[0].text as string);
+    expect(parsedResult.posts[0].body_md).toBe(`${"a".repeat(500)}...`);
+  });
+
+  it("should handle empty posts array", async () => {
+    mockClient.GET.mockResolvedValue({
+      data: {
+        posts: [],
+        page: 1,
+        per_page: 20,
+        total_count: 0,
+        max_per_page: 100,
+      },
+      error: undefined,
+      response: {
+        ok: true,
+        status: 200,
+      } as Response,
+    });
+
+    const result = await getRecentPosts(mockClient, {
+      teamName: "test-team",
+      uri: testUri,
+    });
+
+    const parsedResult = JSON.parse(result.contents[0].text as string);
+    expect(parsedResult.posts).toEqual([]);
+    expect(parsedResult.total_count).toBe(0);
+  });
+
+  it("should handle API errors", async () => {
+    const mockError = { error: "unauthorized", message: "Invalid token" };
+
+    mockClient.GET.mockResolvedValue({
+      data: undefined,
+      error: mockError,
+      response: {
+        ok: false,
+        status: 404,
+      } as Response,
+    });
+
+    const result = await getRecentPosts(mockClient, {
+      teamName: "test-team",
+      uri: testUri,
+    });
+
+    expect(result).toEqual({
+      contents: [
+        {
+          uri: testUri,
+          mimeType: "application/json",
+          text: `Error: ${JSON.stringify(mockError, null, 2)}`,
+        },
+      ],
+    });
+  });
+
+  it("should handle response status errors", async () => {
+    mockClient.GET.mockResolvedValue({
+      data: undefined,
+      error: undefined,
+      response: {
+        ok: false,
+        status: 500,
+      } as Response,
+    });
+
+    const result = await getRecentPosts(mockClient, {
+      teamName: "test-team",
+      uri: testUri,
+    });
+
+    expect(result).toEqual({
+      contents: [
+        {
+          uri: testUri,
+          mimeType: "application/json",
+          text: "Error: API Response(status: 500)",
+        },
+      ],
+    });
+  });
+
+  it("should handle network errors", async () => {
+    const networkError = new Error("Network connection failed");
+
+    mockClient.GET.mockRejectedValue(networkError);
+
+    const result = await getRecentPosts(mockClient, {
+      teamName: "test-team",
+      uri: testUri,
+    });
+
+    expect(result).toEqual({
+      contents: [
+        {
+          uri: testUri,
+          mimeType: "application/json",
+          text: "Error: Network connection failed",
+        },
+      ],
+    });
+  });
+
+  it("should handle non-Error exceptions", async () => {
+    mockClient.GET.mockRejectedValue("Unexpected error");
+
+    const result = await getRecentPosts(mockClient, {
+      teamName: "test-team",
+      uri: testUri,
+    });
+
+    expect(result).toEqual({
+      contents: [
+        {
+          uri: testUri,
+          mimeType: "application/json",
+          text: "Error: Unexpected error",
+        },
+      ],
+    });
+  });
+
+  it("should handle posts with undefined body_md", async () => {
+    const mockPost = createNullBodyPost();
+
+    mockClient.GET.mockResolvedValue({
+      data: { posts: [mockPost] },
+      error: undefined,
+      response: {
+        ok: true,
+        status: 200,
+      } as Response,
+    });
+
+    const result = await getRecentPosts(mockClient, {
+      teamName: "test-team",
+      uri: testUri,
+    });
+
+    const parsedResult = JSON.parse(result.contents[0].text as string);
+    expect(parsedResult.posts[0].body_md).toBe(undefined);
+  });
+});

package/src/resources/index.ts

@@ -0,0 +1,33 @@
+import {
+  type McpServer,
+  ResourceTemplate,
+} from "@modelcontextprotocol/sdk/server/mcp.js";
+import { withContext } from "../api_client/with-context.js";
+import type { MCPContext } from "../context/mcp-context.js";
+
+import { getRecentPosts } from "./recent-posts.js";
+import { createRecentPostsResourceList } from "./recent-posts-list.js";
+
+export function setupResources(server: McpServer, context: MCPContext): void {
+  console.error("Setting up MCP resources...");
+
+  server.registerResource(
+    "esa_recent_posts",
+    new ResourceTemplate("esa://teams/{teamName}/posts/recent", {
+      list: async () => {
+        const resources = await createRecentPostsResourceList(context);
+        return { resources };
+      },
+    }),
+    {
+      title: "Recent Posts",
+      description: "Fetch recent updated posts from esa team",
+      mimeType: "application/json",
+    },
+    async (uri, params) =>
+      withContext(context, getRecentPosts, { ...params, uri: uri.href } as {
+        teamName: string;
+        uri: string;
+      }),
+  );
+}

package/src/resources/recent-posts-list.ts

@@ -0,0 +1,22 @@
+import { withContext } from "../api_client/with-context.js";
+import type { MCPContext } from "../context/mcp-context.js";
+import { getTeams } from "../tools/teams.js";
+
+export async function createRecentPostsResourceList(context: MCPContext) {
+  try {
+    const result = await withContext(context, getTeams, {});
+    const data = JSON.parse(result.content[0].text as string);
+
+    return (
+      data.teams?.map((team: { name: string; description: string }) => ({
+        uri: `esa://teams/${team.name}/posts/recent`,
+        name: `Recent posts from ${team.name}`,
+        description: `Recent posts from ${team.name}${team.description ? ` (${team.description})` : ""}`,
+        mimeType: "application/json",
+      })) || []
+    );
+  } catch (error) {
+    console.error("Failed to list teams:", error);
+    return [];
+  }
+}

package/src/resources/recent-posts.ts

@@ -0,0 +1,45 @@
+import type { createEsaClient } from "../api_client/index.js";
+import {
+  formatResourceError,
+  formatResourceResponse,
+} from "../formatters/mcp-response.js";
+import type { components } from "../generated/api-types.js";
+import { transformPost } from "../transformers/post-transformer.js";
+
+const RECENT_POSTS_QUERY = {
+  sort: "updated",
+  order: "desc",
+} as const;
+
+export async function getRecentPosts(
+  client: ReturnType<typeof createEsaClient>,
+  args: { teamName: string; uri: string },
+) {
+  const { teamName, uri } = args;
+  try {
+    const { data, error, response } = await client.GET(
+      "/v1/teams/{team_name}/posts",
+      {
+        params: {
+          path: { team_name: teamName },
+          query: RECENT_POSTS_QUERY,
+        },
+      },
+    );
+
+    if (error || !response.ok) {
+      return formatResourceError(error || response.status, uri);
+    }
+
+    const transformed = {
+      ...data,
+      posts: data.posts?.map((post: components["schemas"]["Post"]) =>
+        transformPost(post, { truncateBody: 500 }),
+      ),
+    };
+
+    return formatResourceResponse(transformed, uri);
+  } catch (error) {
+    return formatResourceError(error, uri);
+  }
+}

package/src/schemas/team-name-schema.ts

@@ -0,0 +1,19 @@
+import { z } from "zod";
+import { normalizeTeamName } from "../transformers/team-name-normalizer.js";
+
+export const teamNameSchema = z
+  .string()
+  .default("")
+  .describe(
+    "Team name (required). Use esa_get_teams first to see available teams.",
+  )
+  .transform(normalizeTeamName);
+
+export function createSchemaWithTeamName<T extends z.ZodRawShape>(
+  schema: T,
+): z.ZodObject<T & { teamName: typeof teamNameSchema }> {
+  return z.object({
+    teamName: teamNameSchema,
+    ...schema,
+  });
+}

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

@@ -0,0 +1,226 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { createEsaClient } from "../../api_client/index.js";
+import { getCategories, getTopCategories } from "../categories.js";
+
+describe("getCategories", () => {
+  const mockClient = {
+    GET: vi.fn(),
+  } as unknown as ReturnType<typeof createEsaClient> & {
+    GET: ReturnType<typeof vi.fn>;
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("should fetch categories for a specific path", async () => {
+    const mockResponse = {
+      current_category: "dev/docs",
+      categories: [
+        {
+          name: "api",
+          full_name: "dev/docs/api",
+          count: 5,
+          has_child: true,
+        },
+      ],
+      total_count: 1,
+      per_page: 20,
+      page: 1,
+      prev_page: null,
+      next_page: null,
+      max_per_page: 100,
+    };
+
+    mockClient.GET.mockResolvedValue({
+      data: mockResponse,
+      error: undefined,
+      response: { ok: true, status: 200 } as Response,
+    });
+
+    const result = await getCategories(mockClient, {
+      teamName: "test-team",
+      select: "dev/docs",
+    });
+
+    expect(mockClient.GET).toHaveBeenCalledWith(
+      "/v1/teams/{team_name}/categories",
+      {
+        params: {
+          path: { team_name: "test-team" },
+          query: {
+            select: "dev/docs",
+            include: undefined,
+            descendant_posts: undefined,
+            page: undefined,
+            per_page: undefined,
+          },
+        },
+      },
+    );
+
+    expect(result.content[0].text).toContain("dev/docs");
+  });
+
+  it("should handle API errors", async () => {
+    const mockError = { error: "not_found", message: "Category not found" };
+
+    mockClient.GET.mockResolvedValue({
+      data: undefined,
+      error: mockError,
+      response: { ok: false, status: 404 } as Response,
+    });
+
+    const result = await getCategories(mockClient, {
+      teamName: "test-team",
+      select: "nonexistent",
+    });
+
+    expect(result.content[0].text).toContain("not_found");
+  });
+
+  it("should handle network errors", async () => {
+    const networkError = new Error("Network connection failed");
+
+    mockClient.GET.mockRejectedValue(networkError);
+
+    const result = await getCategories(mockClient, {
+      teamName: "test-team",
+      select: "dev/docs",
+    });
+
+    expect(result.content[0].text).toContain("Network connection failed");
+  });
+
+  it("should handle non-Error exceptions", async () => {
+    mockClient.GET.mockRejectedValue("Unexpected error");
+
+    const result = await getCategories(mockClient, {
+      teamName: "test-team",
+      select: "dev/docs",
+    });
+
+    expect(result.content[0].text).toContain("Unexpected error");
+  });
+
+  it("should throw MissingTeamNameError when teamName is empty", async () => {
+    const result = await getCategories(mockClient, {
+      teamName: "",
+      select: "dev",
+    });
+
+    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();
+  });
+});
+
+describe("getTopCategories", () => {
+  const mockClient = {
+    GET: vi.fn(),
+  } as unknown as ReturnType<typeof createEsaClient> & {
+    GET: ReturnType<typeof vi.fn>;
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("should fetch top-level categories", async () => {
+    const mockResponse = {
+      current_category: "",
+      categories: [
+        { name: "dev", full_name: "dev", count: 15, has_child: true },
+        { name: "design", full_name: "design", count: 8, has_child: false },
+      ],
+      total_count: 2,
+      per_page: 20,
+      page: 1,
+      prev_page: null,
+      next_page: null,
+      max_per_page: 100,
+    };
+
+    mockClient.GET.mockResolvedValue({
+      data: mockResponse,
+      error: undefined,
+      response: { ok: true, status: 200 } as Response,
+    });
+
+    const result = await getTopCategories(mockClient, {
+      teamName: "test-team",
+    });
+
+    expect(mockClient.GET).toHaveBeenCalledWith(
+      "/v1/teams/{team_name}/categories/top",
+      {
+        params: { path: { team_name: "test-team" } },
+      },
+    );
+
+    expect(result.content[0].text).toContain("dev");
+    expect(result.content[0].text).toContain("design");
+  });
+
+  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 getTopCategories(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 getTopCategories(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 getTopCategories(mockClient, {
+      teamName: "test-team",
+    });
+
+    expect(result.content[0].text).toContain("Unexpected error");
+  });
+
+  it("should throw MissingTeamNameError when teamName is empty", async () => {
+    const result = await getTopCategories(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();
+  });
+});