@esaio/esa-mcp-server 0.1.0

package/src/tools/post-actions.ts

@@ -0,0 +1,132 @@
+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 { normalizeTeamName } from "../transformers/team-name-normalizer.js";
+import { createPost, updatePost } from "./posts.js";
+
+export const archivePostSchema = createSchemaWithTeamName({
+  postNumber: z.number().describe("The post number to archive"),
+  message: z.string().optional().describe("Archive message for the post"),
+});
+
+export async function archivePost(
+  client: ReturnType<typeof createEsaClient>,
+  args: z.infer<typeof archivePostSchema>,
+) {
+  try {
+    if (!args.teamName) {
+      throw new MissingTeamNameError();
+    }
+    const { data, error, response } = await client.GET(
+      "/v1/teams/{team_name}/posts/{post_number}",
+      {
+        params: {
+          path: { team_name: args.teamName, post_number: args.postNumber },
+        },
+      },
+    );
+
+    if (error || !response.ok) {
+      return formatToolError(error || response.status);
+    }
+
+    const post: components["schemas"]["Post"] = data;
+    const currentCategory = post.category || "";
+
+    if (currentCategory.startsWith("Archived/")) {
+      return formatToolResponse({
+        message: "Post is already archived",
+        category: currentCategory,
+      });
+    }
+
+    const archivedCategory =
+      currentCategory === "" ? "Archived" : `Archived/${currentCategory}`;
+
+    return await updatePost(client, {
+      teamName: args.teamName,
+      postNumber: args.postNumber,
+      category: archivedCategory,
+      message: args.message || "Archive post",
+    });
+  } catch (error) {
+    return formatToolError(error);
+  }
+}
+
+export const shipPostSchema = createSchemaWithTeamName({
+  postNumber: z.number().describe("The post number to ship"),
+});
+
+export async function shipPost(
+  client: ReturnType<typeof createEsaClient>,
+  args: z.infer<typeof shipPostSchema>,
+) {
+  try {
+    if (!args.teamName) {
+      throw new MissingTeamNameError();
+    }
+    return await updatePost(client, {
+      teamName: args.teamName,
+      postNumber: args.postNumber,
+      wip: false,
+      message: "Ship It!",
+    });
+  } catch (error) {
+    return formatToolError(error);
+  }
+}
+
+export const duplicatePostSchema = createSchemaWithTeamName({
+  postNumber: z
+    .number()
+    .describe("The source post number to prepare for duplication"),
+  targetTeamName: z
+    .string()
+    .optional()
+    .describe("The name of the esa team")
+    .transform((val) => (val ? normalizeTeamName(val) : undefined)),
+});
+
+export async function duplicatePost(
+  client: ReturnType<typeof createEsaClient>,
+  args: z.infer<typeof duplicatePostSchema>,
+) {
+  try {
+    if (!args.teamName) {
+      throw new MissingTeamNameError();
+    }
+    const { data, error, response } = await client.GET(
+      "/v1/teams/{team_name}/posts/new",
+      {
+        params: {
+          path: { team_name: args.teamName },
+          query: {
+            parent_post_id: args.postNumber,
+          },
+        },
+      },
+    );
+
+    if (error || !response.ok) {
+      return formatToolError(error || response.status);
+    }
+
+    const postNew = data.post as components["schemas"]["PostNew"];
+
+    return createPost(client, {
+      teamName: args.targetTeamName || args.teamName,
+      name: postNew.name,
+      bodyMd: postNew.body_md,
+      wip: true,
+    });
+  } catch (error) {
+    return formatToolError(error);
+  }
+}

package/src/tools/posts.ts

@@ -0,0 +1,179 @@
+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 { normalizePostName } from "../transformers/post-name-normalizer.js";
+import { transformPost } from "../transformers/post-transformer.js";
+
+export const getPostSchema = createSchemaWithTeamName({
+  postNumber: z.number().describe("The post number to retrieve"),
+  include: z
+    .enum(["comments"])
+    .optional()
+    .describe("Specify 'comments' to include comments in the response"),
+});
+
+export async function getPost(
+  client: ReturnType<typeof createEsaClient>,
+  args: z.infer<typeof getPostSchema>,
+) {
+  try {
+    if (!args.teamName) {
+      throw new MissingTeamNameError();
+    }
+    const { data, error, response } = await client.GET(
+      "/v1/teams/{team_name}/posts/{post_number}",
+      {
+        params: {
+          path: { team_name: args.teamName, post_number: args.postNumber },
+          query: {
+            include: args.include,
+          },
+        },
+      },
+    );
+
+    if (error || !response.ok) {
+      return formatToolError(error || response.status);
+    }
+    const post: components["schemas"]["Post"] = data;
+    const transformed = transformPost(post);
+
+    return formatToolResponse(transformed);
+  } catch (error) {
+    return formatToolError(error);
+  }
+}
+
+export const createPostSchema = createSchemaWithTeamName({
+  name: z.string().describe("The post name (title)"),
+  bodyMd: z.string().optional().describe("The post content in Markdown format"),
+  tags: z.array(z.string()).optional().describe("Tags for the post"),
+  category: z.string().optional().describe("Category path (e.g., 'dev/docs')"),
+  wip: z
+    .boolean()
+    .default(true)
+    .describe(
+      "Whether the post is Work In Progress. Set to false to ship it (mark as complete and ready to be published)",
+    ),
+  message: z.string().optional().describe("Update message for the post"),
+});
+
+export async function createPost(
+  client: ReturnType<typeof createEsaClient>,
+  args: z.infer<typeof createPostSchema>,
+) {
+  try {
+    if (!args.teamName) {
+      throw new MissingTeamNameError();
+    }
+    const { name, category } = normalizePostName(args.name, args.category);
+
+    const { data, error, response } = await client.POST(
+      "/v1/teams/{team_name}/posts",
+      {
+        params: {
+          path: { team_name: args.teamName },
+        },
+        body: {
+          post: {
+            name: name,
+            body_md: args.bodyMd,
+            tags: args.tags,
+            category: category,
+            wip: args.wip,
+            message: args.message,
+          } as components["schemas"]["PostCreateInput"],
+        },
+      },
+    );
+
+    if (error || !response.ok) {
+      return formatToolError(error || response.status);
+    }
+
+    const post: components["schemas"]["Post"] = data;
+    const transformed = transformPost(post);
+
+    return formatToolResponse(transformed);
+  } catch (error) {
+    return formatToolError(error);
+  }
+}
+
+export const updatePostSchema = createSchemaWithTeamName({
+  postNumber: z.number().describe("The post number to update"),
+  name: z.string().optional().describe("The post name (title)"),
+  bodyMd: z.string().optional().describe("The post content in Markdown format"),
+  tags: z.array(z.string()).optional().describe("Tags for the post"),
+  category: z.string().optional().describe("Category path (e.g., 'dev/docs')"),
+  wip: z
+    .boolean()
+    .optional()
+    .describe(
+      "Whether the post is Work In Progress. Set to false to ship it (mark as complete and ready to be published)",
+    ),
+  message: z.string().optional().describe("Update message for the post"),
+  originalRevision: z
+    .object({
+      bodyMd: z.string(),
+      number: z.number(),
+      user: z.string(),
+    })
+    .optional()
+    .describe("Original revision to check for conflicts"),
+});
+
+export async function updatePost(
+  client: ReturnType<typeof createEsaClient>,
+  args: z.infer<typeof updatePostSchema>,
+) {
+  try {
+    if (!args.teamName) {
+      throw new MissingTeamNameError();
+    }
+    const { name, category } = normalizePostName(args.name, args.category);
+
+    const { data, error, response } = await client.PATCH(
+      "/v1/teams/{team_name}/posts/{post_number}",
+      {
+        params: {
+          path: { team_name: args.teamName, post_number: args.postNumber },
+        },
+        body: {
+          post: {
+            name: name,
+            body_md: args.bodyMd,
+            tags: args.tags,
+            category: category,
+            wip: args.wip,
+            message: args.message,
+            original_revision: args.originalRevision
+              ? {
+                  body_md: args.originalRevision.bodyMd,
+                  number: args.originalRevision.number,
+                  user: args.originalRevision.user,
+                }
+              : undefined,
+          } as components["schemas"]["PostUpdateInput"],
+        },
+      },
+    );
+
+    if (error || !response.ok) {
+      return formatToolError(error || response.status);
+    }
+
+    const post: components["schemas"]["Post"] = data;
+    const transformed = transformPost(post);
+
+    return formatToolResponse(transformed);
+  } catch (error) {
+    return formatToolError(error);
+  }
+}

package/src/tools/search.ts

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

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