@esaio/esa-mcp-server 0.1.0

package/src/transformers/__tests__/category-transformer.test.ts

@@ -0,0 +1,161 @@
+import { describe, expect, it } from "vitest";
+import {
+  transformCategory,
+  transformCategoryList,
+} from "../category-transformer.js";
+
+describe("transformCategory", () => {
+  it("should transform category with all properties", () => {
+    const category = {
+      name: "api",
+      full_name: "dev/docs/api",
+      count: 15,
+      has_child: true,
+      selected: true,
+    };
+
+    const result = transformCategory(category);
+
+    expect(result).toEqual({
+      full_name: "dev/docs/api",
+      count: 15,
+      has_child: true,
+    });
+  });
+
+  it("should transform category with minimal properties", () => {
+    const category = {
+      name: "simple",
+      count: 5,
+    };
+
+    const result = transformCategory(category);
+
+    expect(result).toEqual({
+      full_name: undefined,
+      count: 5,
+      has_child: false,
+    });
+  });
+});
+
+describe("transformCategoryList", () => {
+  it("should transform category list with all properties", () => {
+    const categoryList = {
+      current_category: "dev/docs",
+      categories: [
+        {
+          name: "api",
+          full_name: "dev/docs/api",
+          count: 10,
+          has_child: true,
+        },
+        {
+          name: "guides",
+          full_name: "dev/docs/guides",
+          count: 5,
+          has_child: false,
+        },
+      ],
+      parent_categories: [
+        {
+          current_category: "dev",
+          categories: [
+            {
+              name: "docs",
+              full_name: "dev/docs",
+              count: 15,
+              has_child: true,
+            },
+          ],
+        },
+      ],
+      no_category: {
+        name: "no_category",
+        count: 3,
+      },
+      descendant_posts: true,
+      total_count: 2,
+      per_page: 20,
+      page: 1,
+      prev_page: null,
+      next_page: null,
+      max_per_page: 100,
+    };
+
+    const result = transformCategoryList(categoryList);
+
+    expect(result).toEqual({
+      current_category: "dev/docs",
+      categories: [
+        {
+          full_name: "dev/docs/api",
+          count: 10,
+          has_child: true,
+        },
+        {
+          full_name: "dev/docs/guides",
+          count: 5,
+          has_child: false,
+        },
+      ],
+      parent_categories: [
+        {
+          current_category: "dev",
+          categories: [
+            {
+              full_name: "dev/docs",
+              count: 15,
+              has_child: true,
+            },
+          ],
+        },
+      ],
+      readme: undefined,
+      no_category: {
+        full_name: undefined,
+        count: 3,
+        has_child: false,
+      },
+      descendant_posts: true,
+      posts: undefined,
+      total_count: 2,
+      per_page: 20,
+      page: 1,
+      prev_page: null,
+      next_page: null,
+      max_per_page: 100,
+    });
+  });
+
+  it("should transform category list with minimal properties", () => {
+    const categoryList = {
+      current_category: "",
+      categories: [],
+      total_count: 0,
+      per_page: 20,
+      page: 1,
+      prev_page: null,
+      next_page: null,
+      max_per_page: 100,
+    };
+
+    const result = transformCategoryList(categoryList);
+
+    expect(result).toEqual({
+      current_category: "",
+      categories: [],
+      parent_categories: undefined,
+      readme: undefined,
+      no_category: undefined,
+      descendant_posts: undefined,
+      posts: undefined,
+      total_count: 0,
+      per_page: 20,
+      page: 1,
+      prev_page: null,
+      next_page: null,
+      max_per_page: 100,
+    });
+  });
+});

package/src/transformers/__tests__/comment-transformer.test.ts

@@ -0,0 +1,129 @@
+import { describe, expect, it } from "vitest";
+import {
+  createLongContentComment,
+  createMockComment,
+  createNullBodyComment,
+} from "../../__tests__/fixtures/mock-comment.js";
+import { transformComment } from "../comment-transformer.js";
+
+describe("transformComment", () => {
+  it("should transform comment data correctly", () => {
+    const mockComment = createMockComment();
+    const result = transformComment(mockComment);
+
+    expect(result).toEqual({
+      id: 123,
+      post_number: 456,
+      url: "https://test-team.esa.example.com/posts/456#comment-123",
+      body_md: "This is a test comment content",
+      created_at: "2024-01-01T00:00:00+09:00",
+      updated_at: "2024-01-01T01:00:00+09:00",
+      created_by: {
+        name: "Test User",
+        screen_name: "testuser",
+        icon: "https://example.com/icon.png",
+        myself: true,
+      },
+      stats: {
+        stargazers_count: 5,
+        star: true,
+      },
+      stargazers: [
+        {
+          created_at: "2024-01-01T02:00:00+09:00",
+          body: "Great comment!",
+          user: {
+            name: "Stargazer User",
+            screen_name: "stargazer",
+            icon: "https://example.com/star-icon.png",
+            myself: false,
+          },
+          name: "Stargazer User",
+          screen_name: "stargazer",
+          icon: "https://example.com/star-icon.png",
+          myself: false,
+          email: "stargazer@example.com",
+          role: "member",
+          posts_count: 10,
+          joined_at: "2024-01-01T00:00:00+09:00",
+          last_accessed_at: "2024-01-01T02:00:00+09:00",
+        },
+      ],
+    });
+  });
+
+  it("should handle comment with no stargazers", () => {
+    const commentWithoutStars = createMockComment({
+      stargazers_count: 0,
+      star: false,
+      stargazers: undefined,
+    });
+    const result = transformComment(commentWithoutStars);
+
+    expect(result.stats).toEqual({
+      stargazers_count: 0,
+      star: false,
+    });
+    expect(result.stargazers).toBe(undefined);
+  });
+
+  it("should handle comment with empty body_md", () => {
+    const commentWithEmptyBody = createNullBodyComment();
+    const result = transformComment(commentWithEmptyBody);
+
+    expect(result.body_md).toBe("");
+  });
+
+  it("should truncate long body_md when truncateBody option is provided", () => {
+    const longComment = createLongContentComment(400);
+
+    const result = transformComment(longComment, { truncateBody: 300 });
+
+    expect(result.body_md).toBe(`${"a".repeat(300)}...`);
+  });
+
+  it("should not truncate short body_md even when truncateBody option is provided", () => {
+    const shortComment = createMockComment({ body_md: "Short comment" });
+
+    const result = transformComment(shortComment, { truncateBody: 300 });
+
+    expect(result.body_md).toBe("Short comment");
+  });
+
+  it("should handle comment with empty body_md when truncateBody option is provided", () => {
+    const commentWithEmptyBody = createNullBodyComment();
+    const result = transformComment(commentWithEmptyBody, {
+      truncateBody: 300,
+    });
+
+    expect(result.body_md).toBe("");
+  });
+
+  it("should preserve all essential comment metadata", () => {
+    const mockComment = createMockComment({
+      id: 999,
+      post_number: 789,
+      url: "https://custom-team.esa.example.com/posts/789#comment-999",
+      created_at: "2024-06-01T12:00:00+09:00",
+      updated_at: "2024-06-01T13:00:00+09:00",
+      created_by: {
+        name: "Custom User",
+        screen_name: "customuser",
+        icon: "https://example.com/custom-icon.png",
+        myself: false,
+      },
+    });
+
+    const result = transformComment(mockComment);
+
+    expect(result.id).toBe(999);
+    expect(result.post_number).toBe(789);
+    expect(result.url).toBe(
+      "https://custom-team.esa.example.com/posts/789#comment-999",
+    );
+    expect(result.created_at).toBe("2024-06-01T12:00:00+09:00");
+    expect(result.updated_at).toBe("2024-06-01T13:00:00+09:00");
+    expect(result.created_by.name).toBe("Custom User");
+    expect(result.created_by.screen_name).toBe("customuser");
+  });
+});

package/src/transformers/__tests__/post-name-normalizer.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from "vitest";
+import { normalizePostName } from "../post-name-normalizer.js";
+
+describe("normalizePostName", () => {
+  it("should split name with slashes", () => {
+    expect(normalizePostName("docs/api/authentication")).toEqual({
+      name: "authentication",
+      category: "docs/api",
+    });
+  });
+
+  it("should not split when category is specified", () => {
+    expect(normalizePostName("docs/guide", "custom")).toEqual({
+      name: "docs/guide",
+      category: "custom",
+    });
+  });
+
+  it("should preserve empty string category", () => {
+    expect(normalizePostName("docs/guide", "")).toEqual({
+      name: "docs/guide",
+      category: "",
+    });
+  });
+
+  it("should handle name without slashes", () => {
+    expect(normalizePostName("simple")).toEqual({
+      name: "simple",
+      category: undefined,
+    });
+  });
+
+  it("should handle trailing slash as undefined name", () => {
+    expect(normalizePostName("folder/")).toEqual({
+      name: undefined,
+      category: "folder",
+    });
+  });
+
+  it("should handle leading slash", () => {
+    expect(normalizePostName("/guide")).toEqual({
+      name: "guide",
+      category: "",
+    });
+  });
+
+  it("should handle undefined name", () => {
+    expect(normalizePostName(undefined, "category")).toEqual({
+      name: undefined,
+      category: "category",
+    });
+  });
+});

package/src/transformers/__tests__/post-transformer.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from "vitest";
+import {
+  createLongContentPost,
+  createMockPost,
+  createNullBodyPost,
+} from "../../__tests__/fixtures/mock-post.js";
+import { transformPost } from "../post-transformer.js";
+
+describe("transformPost", () => {
+  it("should transform post data correctly", () => {
+    const mockPost = createMockPost();
+    const result = transformPost(mockPost);
+
+    expect(result).toEqual({
+      url: mockPost.url,
+      wip: "Shipped",
+      kind: "stock",
+      category_and_title_and_tags: mockPost.full_name,
+      body_md: mockPost.body_md,
+      created_at: mockPost.created_at,
+      updated_at: mockPost.updated_at,
+      created_by: mockPost.created_by,
+      updated_by: mockPost.updated_by,
+      stats: {
+        tasks_count: 3,
+        done_tasks_count: 2,
+        comments_count: 5,
+        stargazers_count: 10,
+        watchers_count: 8,
+      },
+    });
+  });
+
+  it("should transform WIP post correctly", () => {
+    const wipPost = createMockPost({ wip: true });
+    const result = transformPost(wipPost);
+
+    expect(result.wip).toBe("WIP");
+  });
+
+  it("should handle post with undefined body_md", () => {
+    const postWithUndefinedBody = createNullBodyPost();
+    const result = transformPost(postWithUndefinedBody);
+
+    expect(result.body_md).toBe(undefined);
+  });
+
+  it("should truncate long body_md when truncateBody option is provided", () => {
+    const longPost = createLongContentPost(600);
+
+    const result = transformPost(longPost, { truncateBody: 500 });
+
+    expect(result.body_md).toBe(`${"a".repeat(500)}...`);
+  });
+
+  it("should not truncate short body_md even when truncateBody option is provided", () => {
+    const shortPost = createMockPost({ body_md: "Short content" });
+
+    const result = transformPost(shortPost, { truncateBody: 500 });
+
+    expect(result.body_md).toBe("Short content");
+  });
+
+  it("should handle post with undefined body_md when truncateBody option is provided", () => {
+    const postWithUndefinedBody = createNullBodyPost();
+    const result = transformPost(postWithUndefinedBody, { truncateBody: 500 });
+
+    expect(result.body_md).toBe(undefined);
+  });
+});

package/src/transformers/__tests__/query-normalizer.test.ts

@@ -0,0 +1,98 @@
+import { describe, expect, it } from "vitest";
+import { normalizeSearchQuery } from "../query-normalizer.js";
+
+describe("normalizeSearchQuery", () => {
+  describe("wildcard normalization", () => {
+    it("should convert * to empty string", () => {
+      expect(normalizeSearchQuery("*")).toBe("");
+    });
+
+    it("should not convert * when part of a larger query", () => {
+      expect(normalizeSearchQuery("user:* tag:release")).toBe(
+        "user:* tag:release",
+      );
+    });
+  });
+
+  describe("date syntax normalization", () => {
+    it("should convert after: to created:>", () => {
+      expect(normalizeSearchQuery("after:2025-08-16")).toBe(
+        "created:>2025-08-16",
+      );
+    });
+
+    it("should convert before: to created:<", () => {
+      expect(normalizeSearchQuery("before:2025-08-16")).toBe(
+        "created:<2025-08-16",
+      );
+    });
+
+    it("should convert since: to created:>", () => {
+      expect(normalizeSearchQuery("since:2025-08-16")).toBe(
+        "created:>2025-08-16",
+      );
+    });
+
+    it("should convert until: to created:<", () => {
+      expect(normalizeSearchQuery("until:2025-08-16")).toBe(
+        "created:<2025-08-16",
+      );
+    });
+
+    it("should handle case-insensitive matching", () => {
+      expect(normalizeSearchQuery("AFTER:2025-08-16")).toBe(
+        "created:>2025-08-16",
+      );
+      expect(normalizeSearchQuery("After:2025-08-16")).toBe(
+        "created:>2025-08-16",
+      );
+    });
+
+    it("should handle multiple date patterns in one query", () => {
+      expect(
+        normalizeSearchQuery(
+          "user:fukayatsu after:2025-08-16 before:2025-08-22",
+        ),
+      ).toBe("user:fukayatsu created:>2025-08-16 created:<2025-08-22");
+    });
+
+    it("should not convert partial matches", () => {
+      expect(normalizeSearchQuery("notafter:2025-08-16")).toBe(
+        "notafter:2025-08-16",
+      );
+      expect(normalizeSearchQuery("after:notadate")).toBe("after:notadate");
+    });
+
+    it("should handle complex queries with mixed syntax", () => {
+      expect(
+        normalizeSearchQuery(
+          "user:fukayatsu after:2025-08-01 tag:release wip:false",
+        ),
+      ).toBe("user:fukayatsu created:>2025-08-01 tag:release wip:false");
+    });
+  });
+
+  describe("no transformation needed", () => {
+    it("should not modify valid esa syntax", () => {
+      expect(normalizeSearchQuery("created:>2025-08-16")).toBe(
+        "created:>2025-08-16",
+      );
+      expect(normalizeSearchQuery("updated:<2025-08-16")).toBe(
+        "updated:<2025-08-16",
+      );
+    });
+
+    it("should preserve normal search queries", () => {
+      expect(normalizeSearchQuery("user:fukayatsu tag:release")).toBe(
+        "user:fukayatsu tag:release",
+      );
+      expect(normalizeSearchQuery("category:dev wip:false")).toBe(
+        "category:dev wip:false",
+      );
+    });
+
+    it("should handle empty string", () => {
+      expect(normalizeSearchQuery("")).toBe("");
+    });
+  });
+});

package/src/transformers/__tests__/team-name-normalizer.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from "vitest";
+import { normalizeTeamName } from "../team-name-normalizer.js";
+
+describe("normalizeTeamName", () => {
+  it("should extract team name from URL-like input", () => {
+    expect(normalizeTeamName("docs.example.com")).toBe("docs");
+    expect(normalizeTeamName("my-team.example.com")).toBe("my-team");
+    expect(normalizeTeamName("company.example.com")).toBe("company");
+  });
+
+  it("should leave normal team names unchanged", () => {
+    expect(normalizeTeamName("docs")).toBe("docs");
+    expect(normalizeTeamName("my-team")).toBe("my-team");
+  });
+
+  it("should handle edge cases", () => {
+    expect(normalizeTeamName("")).toBe("");
+    expect(normalizeTeamName(".")).toBe("");
+    expect(normalizeTeamName("team.")).toBe("team");
+  });
+});

package/src/transformers/category-transformer.ts

@@ -0,0 +1,36 @@
+import type { components } from "../generated/api-types.js";
+
+export function transformCategory(category: components["schemas"]["Category"]) {
+  return {
+    full_name: category.full_name,
+    count: category.count,
+    has_child: category.has_child || false,
+  };
+}
+
+export function transformCategoryList(
+  categoryList: components["schemas"]["CategoryList"],
+) {
+  return {
+    current_category: categoryList.current_category,
+    categories: categoryList.categories?.map(transformCategory) || [],
+    parent_categories: categoryList.parent_categories?.map(
+      (parentCategory) => ({
+        current_category: parentCategory.current_category,
+        categories: parentCategory.categories?.map(transformCategory) || [],
+      }),
+    ),
+    readme: categoryList.readme,
+    no_category: categoryList.no_category
+      ? transformCategory(categoryList.no_category)
+      : undefined,
+    descendant_posts: categoryList.descendant_posts,
+    posts: categoryList.posts,
+    total_count: categoryList.total_count,
+    per_page: categoryList.per_page,
+    page: categoryList.page,
+    prev_page: categoryList.prev_page,
+    next_page: categoryList.next_page,
+    max_per_page: categoryList.max_per_page,
+  };
+}

package/src/transformers/comment-transformer.ts

@@ -0,0 +1,34 @@
+import type { components } from "../generated/api-types.js";
+
+export interface CommentTransformOptions {
+  truncateBody?: number;
+}
+
+export function transformComment(
+  comment: components["schemas"]["Comment"],
+  options: CommentTransformOptions = {},
+) {
+  const { truncateBody } = options;
+
+  let bodyMd = comment.body_md;
+  if (truncateBody && bodyMd && bodyMd.length > truncateBody) {
+    bodyMd = `${bodyMd.slice(0, truncateBody)}...`;
+  }
+
+  return {
+    id: comment.id,
+    post_number: comment.post_number,
+    url: comment.url,
+    body_md: bodyMd,
+    created_at: comment.created_at,
+    updated_at: comment.updated_at,
+    created_by: comment.created_by,
+    stats: {
+      stargazers_count: comment.stargazers_count,
+      star: comment.star,
+    },
+    stargazers: comment.stargazers,
+  };
+}
+
+export type TransformedComment = ReturnType<typeof transformComment>;

package/src/transformers/post-name-normalizer.ts

@@ -0,0 +1,30 @@
+export interface PostNameParts {
+  name?: string;
+  category?: string;
+}
+
+export function normalizePostName(
+  name?: string,
+  category?: string,
+): PostNameParts {
+  if (!name) {
+    return { name, category };
+  }
+
+  if (category !== undefined) {
+    return { name, category };
+  }
+
+  if (name.includes("/")) {
+    const parts = name.split("/");
+    const extractedName = parts.pop();
+    const extractedCategory = parts.join("/");
+
+    return {
+      name: extractedName || undefined,
+      category: extractedCategory,
+    };
+  }
+
+  return { name, category };
+}

package/src/transformers/post-transformer.ts

@@ -0,0 +1,38 @@
+import type { components } from "../generated/api-types.js";
+
+export interface PostTransformOptions {
+  truncateBody?: number;
+}
+
+export function transformPost(
+  post: components["schemas"]["Post"],
+  options: PostTransformOptions = {},
+) {
+  const { truncateBody } = options;
+
+  let bodyMd = post.body_md;
+  if (truncateBody && bodyMd && bodyMd.length > truncateBody) {
+    bodyMd = `${bodyMd.slice(0, truncateBody)}...`;
+  }
+
+  return {
+    url: post.url,
+    wip: post.wip ? "WIP" : ("Shipped" as const),
+    kind: post.kind,
+    category_and_title_and_tags: post.full_name,
+    body_md: bodyMd,
+    created_at: post.created_at,
+    updated_at: post.updated_at,
+    created_by: post.created_by,
+    updated_by: post.updated_by,
+    stats: {
+      tasks_count: post.tasks_count,
+      done_tasks_count: post.done_tasks_count,
+      comments_count: post.comments_count,
+      stargazers_count: post.stargazers_count,
+      watchers_count: post.watchers_count,
+    },
+  };
+}
+
+export type TransformedPost = ReturnType<typeof transformPost>;