@esaio/esa-mcp-server 0.2.0 → 0.2.2

package/src/tools/search.ts

@@ -1,98 +0,0 @@
-import { z } from "zod";
-import type { createEsaClient } from "../api_client/index.js";
-import { MissingTeamNameError } from "../errors/missing-team-name-error.js";
-import {
-  formatToolError,
-  formatToolResponse,
-} from "../formatters/mcp-response.js";
-import type { components } from "../generated/api-types.js";
-import { createSchemaWithTeamName } from "../schemas/team-name-schema.js";
-import { transformPost } from "../transformers/post-transformer.js";
-import { normalizeSearchQuery } from "../transformers/query-normalizer.js";
-
-export const searchPostsSchema = createSchemaWithTeamName({
-  query: z
-    .string()
-    .describe(`Search query string. Use specific terms, not wildcards like "*". Empty string returns all posts.
-## Important Note for Date Queries:
-**WARNING: Do NOT use 'after:', 'before:', 'since:', or 'until:' syntax (these are from GitHub/Gmail/pplog).
-Use esa-specific date syntax: created:>YYYY-MM-DD, created:<YYYY-MM-DD, updated:>YYYY-MM-DD, updated:<YYYY-MM-DD
-
-## Important Note for Relative Date Queries:
-**CRITICAL: Always get today's actual date from the system before processing
-relative date queries (e.g., "today", "yesterday", "last week", "recent").
-When searching, apply these strategies:
-1. Convert concepts to technical terms (e.g., general descriptions → specific property names, method names, or technical keywords)
-2. Translate between Japanese and English technical terms (e.g., Japanese concepts → English API/property names)
-3. Expand to related technical elements (e.g., one concept → multiple implementation approaches, related technologies, or alternative solutions)
-IMPORTANT: Space-separated terms are treated as AND conditions. Use "OR" operator for alternative terms: "word-break OR word-wrap OR overflow-wrap".
-Advanced search: "tag:release", "category:dev", "wip:false", "keyword:API", "title:設計書".
-Category search: "on:category" (posts directly in category), "in:category" (posts in category and subcategories), "on:/" (uncategorized posts).
-For broader results, use OR between related terms rather than listing them with spaces.`)
-    .transform(normalizeSearchQuery),
-  sort: z
-    .enum([
-      "updated",
-      "created",
-      "number",
-      "stars",
-      "watches",
-      "comments",
-      "best_match",
-    ])
-    .optional()
-    .describe("Sort key"),
-  order: z.enum(["desc", "asc"]).optional().describe("Sort direction"),
-  page: z.number().int().positive().optional().describe("Page number"),
-  perPage: z
-    .number()
-    .int()
-    .min(1)
-    .max(100)
-    .optional()
-    .describe("Items per page"),
-  include: z
-    .enum(["comments"])
-    .optional()
-    .describe("Specify 'comments' to include comments in the response"),
-});
-
-export async function searchPosts(
-  client: ReturnType<typeof createEsaClient>,
-  args: z.infer<typeof searchPostsSchema>,
-) {
-  try {
-    if (!args.teamName) {
-      throw new MissingTeamNameError();
-    }
-
-    const { data, error, response } = await client.GET(
-      "/v1/teams/{team_name}/posts",
-      {
-        params: {
-          path: { team_name: args.teamName },
-          query: {
-            q: args.query,
-            sort: args.sort,
-            order: args.order,
-            page: args.page,
-            per_page: args.perPage,
-            include: args.include,
-          },
-        },
-      },
-    );
-
-    if (error || !response.ok) {
-      return formatToolError(error || response.status);
-    }
-    const posts: components["schemas"]["Post"][] = data.posts;
-    const transformed = posts.map((post) =>
-      transformPost(post, { truncateBody: 500 }),
-    );
-
-    return formatToolResponse(transformed);
-  } catch (error) {
-    return formatToolError(error);
-  }
-}

package/src/tools/teams.ts

@@ -1,157 +0,0 @@
-import { z } from "zod";
-import type { createEsaClient } from "../api_client/index.js";
-import { MissingTeamNameError } from "../errors/missing-team-name-error.js";
-import {
-  formatToolError,
-  formatToolResponse,
-} from "../formatters/mcp-response.js";
-import type { components } from "../generated/api-types.js";
-import { createSchemaWithTeamName } from "../schemas/team-name-schema.js";
-
-export const getTeamsSchema = z.object({
-  page: z.number().optional().describe("Page number (starts from 1)"),
-  perPage: z.number().optional().describe("Number of items per page"),
-  role: z.enum(["member", "owner"]).optional().describe("Filter by role"),
-});
-
-export async function getTeams(
-  client: ReturnType<typeof createEsaClient>,
-  args: z.infer<typeof getTeamsSchema> = {},
-) {
-  try {
-    const { data, error, response } = await client.GET("/v1/teams", {
-      params: {
-        query: {
-          page: args.page,
-          per_page: args.perPage,
-          role: args.role,
-        },
-      },
-    });
-
-    if (error || !response.ok) {
-      return formatToolError(error || response.status);
-    }
-
-    const transformed = {
-      ...data,
-      teams: data.teams?.map((team: components["schemas"]["Team"]) => ({
-        url: team.url,
-        name: team.name,
-        description: team.description,
-      })),
-    };
-
-    return formatToolResponse(transformed);
-  } catch (error) {
-    return formatToolError(error);
-  }
-}
-
-export const getTeamStatsSchema = createSchemaWithTeamName({});
-
-export async function getTeamStats(
-  client: ReturnType<typeof createEsaClient>,
-  args: z.infer<typeof getTeamStatsSchema>,
-) {
-  try {
-    if (!args.teamName) {
-      throw new MissingTeamNameError();
-    }
-    const { data, error, response } = await client.GET(
-      `/v1/teams/{team_name}/stats`,
-      {
-        params: {
-          path: { team_name: args.teamName },
-        },
-      },
-    );
-
-    if (error || !response.ok) {
-      return formatToolError(error || response.status);
-    }
-
-    return formatToolResponse(data);
-  } catch (error) {
-    return formatToolError(error);
-  }
-}
-
-export const getTeamTagsSchema = createSchemaWithTeamName({
-  page: z.number().optional().describe("Page number (starts from 1)"),
-  perPage: z.number().optional().describe("Number of items per page"),
-});
-
-export async function getTeamTags(
-  client: ReturnType<typeof createEsaClient>,
-  args: z.infer<typeof getTeamTagsSchema>,
-) {
-  try {
-    if (!args.teamName) {
-      throw new MissingTeamNameError();
-    }
-    const { data, error, response } = await client.GET(
-      `/v1/teams/{team_name}/tags`,
-      {
-        params: {
-          path: { team_name: args.teamName },
-          query: {
-            page: args.page,
-            per_page: args.perPage,
-          },
-        },
-      },
-    );
-
-    if (error || !response.ok) {
-      return formatToolError(error || response.status);
-    }
-
-    return formatToolResponse(data);
-  } catch (error) {
-    return formatToolError(error);
-  }
-}
-
-export const getTeamMembersSchema = createSchemaWithTeamName({
-  page: z.number().optional().describe("Page number (starts from 1)"),
-  perPage: z.number().optional().describe("Number of items per page"),
-  sort: z
-    .enum(["posts_count", "joined", "last_accessed"])
-    .optional()
-    .describe("Sort criteria"),
-  order: z.enum(["desc", "asc"]).optional().describe("Sort order"),
-});
-
-export async function getTeamMembers(
-  client: ReturnType<typeof createEsaClient>,
-  args: z.infer<typeof getTeamMembersSchema>,
-) {
-  try {
-    if (!args.teamName) {
-      throw new MissingTeamNameError();
-    }
-    const { data, error, response } = await client.GET(
-      `/v1/teams/{team_name}/members`,
-      {
-        params: {
-          path: { team_name: args.teamName },
-          query: {
-            page: args.page,
-            per_page: args.perPage,
-            sort: args.sort,
-            order: args.order,
-          },
-        },
-      },
-    );
-
-    if (error || !response.ok) {
-      return formatToolError(error || response.status);
-    }
-
-    return formatToolResponse(data);
-  } catch (error) {
-    return formatToolError(error);
-  }
-}

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

@@ -1,161 +0,0 @@
-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

@@ -1,129 +0,0 @@
-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

@@ -1,53 +0,0 @@
-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

@@ -1,70 +0,0 @@
-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);
-  });
-});