@esaio/esa-mcp-server 0.1.0

package/src/tools/comments.ts

@@ -0,0 +1,258 @@
+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 { transformComment } from "../transformers/comment-transformer.js";
+
+export const getCommentSchema = createSchemaWithTeamName({
+  commentId: z.number().describe("The comment ID to retrieve"),
+  include: z
+    .enum(["stargazers"])
+    .optional()
+    .describe("Specify 'stargazers' to include stargazers in the response"),
+});
+
+export async function getComment(
+  client: ReturnType<typeof createEsaClient>,
+  args: z.infer<typeof getCommentSchema>,
+) {
+  try {
+    if (!args.teamName) {
+      throw new MissingTeamNameError();
+    }
+    const { data, error, response } = await client.GET(
+      "/v1/teams/{team_name}/comments/{comment_id}",
+      {
+        params: {
+          path: { team_name: args.teamName, comment_id: args.commentId },
+          query: {
+            include: args.include,
+          },
+        },
+      },
+    );
+
+    if (error || !response.ok) {
+      return formatToolError(error || response.status);
+    }
+
+    const comment: components["schemas"]["Comment"] = data;
+    const transformed = transformComment(comment);
+
+    return formatToolResponse(transformed);
+  } catch (error) {
+    return formatToolError(error);
+  }
+}
+
+export const createCommentSchema = createSchemaWithTeamName({
+  postNumber: z.number().describe("The post number to comment on"),
+  bodyMd: z.string().describe("The comment content in Markdown format"),
+  user: z
+    .string()
+    .optional()
+    .describe("Comment author's screen_name (owner permission required)"),
+});
+
+export async function createComment(
+  client: ReturnType<typeof createEsaClient>,
+  args: z.infer<typeof createCommentSchema>,
+) {
+  try {
+    if (!args.teamName) {
+      throw new MissingTeamNameError();
+    }
+    const { data, error, response } = await client.POST(
+      "/v1/teams/{team_name}/posts/{post_number}/comments",
+      {
+        params: {
+          path: { team_name: args.teamName, post_number: args.postNumber },
+        },
+        body: {
+          comment: {
+            body_md: args.bodyMd,
+            user: args.user,
+          } as components["schemas"]["CommentInput"],
+        },
+      },
+    );
+
+    if (error || !response.ok) {
+      return formatToolError(error || response.status);
+    }
+
+    const comment: components["schemas"]["Comment"] = data;
+    const transformed = transformComment(comment, { truncateBody: 300 });
+
+    return formatToolResponse(transformed);
+  } catch (error) {
+    return formatToolError(error);
+  }
+}
+
+export const updateCommentSchema = createSchemaWithTeamName({
+  commentId: z.number().describe("The comment ID to update"),
+  bodyMd: z.string().describe("The updated comment content in Markdown format"),
+  user: z
+    .string()
+    .optional()
+    .describe("Comment author's screen_name (owner permission required)"),
+});
+
+export async function updateComment(
+  client: ReturnType<typeof createEsaClient>,
+  args: z.infer<typeof updateCommentSchema>,
+) {
+  try {
+    if (!args.teamName) {
+      throw new MissingTeamNameError();
+    }
+    const { data, error, response } = await client.PATCH(
+      "/v1/teams/{team_name}/comments/{comment_id}",
+      {
+        params: {
+          path: { team_name: args.teamName, comment_id: args.commentId },
+        },
+        body: {
+          comment: {
+            body_md: args.bodyMd,
+            user: args.user,
+          } as components["schemas"]["CommentInput"],
+        },
+      },
+    );
+
+    if (error || !response.ok) {
+      return formatToolError(error || response.status);
+    }
+
+    const comment: components["schemas"]["Comment"] = data;
+    const transformed = transformComment(comment);
+
+    return formatToolResponse(transformed);
+  } catch (error) {
+    return formatToolError(error);
+  }
+}
+
+export const deleteCommentSchema = createSchemaWithTeamName({
+  commentId: z.number().describe("The comment ID to delete"),
+});
+
+export async function deleteComment(
+  client: ReturnType<typeof createEsaClient>,
+  args: z.infer<typeof deleteCommentSchema>,
+) {
+  try {
+    if (!args.teamName) {
+      throw new MissingTeamNameError();
+    }
+    const { error, response } = await client.DELETE(
+      "/v1/teams/{team_name}/comments/{comment_id}",
+      {
+        params: {
+          path: { team_name: args.teamName, comment_id: args.commentId },
+        },
+      },
+    );
+
+    if (error || !response.ok) {
+      return formatToolError(error || response.status);
+    }
+
+    return formatToolResponse({
+      success: true,
+      message: "Comment deleted successfully",
+    });
+  } catch (error) {
+    return formatToolError(error);
+  }
+}
+
+export const getPostCommentsSchema = createSchemaWithTeamName({
+  postNumber: z.number().describe("The post number to get comments for"),
+  page: z.number().optional().describe("Page number (starts from 1)"),
+  perPage: z.number().optional().describe("Number of items per page"),
+});
+
+export async function getPostComments(
+  client: ReturnType<typeof createEsaClient>,
+  args: z.infer<typeof getPostCommentsSchema>,
+) {
+  try {
+    if (!args.teamName) {
+      throw new MissingTeamNameError();
+    }
+    const { data, error, response } = await client.GET(
+      "/v1/teams/{team_name}/posts/{post_number}/comments",
+      {
+        params: {
+          path: { team_name: args.teamName, post_number: args.postNumber },
+          query: {
+            page: args.page,
+            per_page: args.perPage,
+          },
+        },
+      },
+    );
+
+    if (error || !response.ok) {
+      return formatToolError(error || response.status);
+    }
+
+    const comments: components["schemas"]["Comment"][] = data.comments;
+    const transformed = comments.map((comment) =>
+      transformComment(comment, { truncateBody: 300 }),
+    );
+
+    return formatToolResponse({ ...data, comments: transformed });
+  } catch (error) {
+    return formatToolError(error);
+  }
+}
+
+export const getTeamCommentsSchema = createSchemaWithTeamName({
+  page: z.number().optional().describe("Page number (starts from 1)"),
+  perPage: z.number().optional().describe("Number of items per page"),
+});
+
+export async function getTeamComments(
+  client: ReturnType<typeof createEsaClient>,
+  args: z.infer<typeof getTeamCommentsSchema>,
+) {
+  try {
+    if (!args.teamName) {
+      throw new MissingTeamNameError();
+    }
+    const { data, error, response } = await client.GET(
+      "/v1/teams/{team_name}/comments",
+      {
+        params: {
+          path: { team_name: args.teamName },
+          query: {
+            page: args.page,
+            per_page: args.perPage,
+          },
+        },
+      },
+    );
+
+    if (error || !response.ok) {
+      return formatToolError(error || response.status);
+    }
+
+    const comments: components["schemas"]["Comment"][] = data.comments;
+    const transformed = comments.map((comment) =>
+      transformComment(comment, { truncateBody: 300 }),
+    );
+
+    return formatToolResponse({ ...data, comments: transformed });
+  } catch (error) {
+    return formatToolError(error);
+  }
+}

package/src/tools/helps.ts

@@ -0,0 +1,50 @@
+import type { z } from "zod";
+import type { createEsaClient } from "../api_client/index.js";
+import { getPost } from "./posts.js";
+import { searchPosts, searchPostsSchema } from "./search.js";
+
+// Documentation team and post constants
+export const HELP_DOCS = {
+  TEAM: "docs",
+  SEARCH_OPTIONS_POST_ID: 104,
+  MARKDOWN_SYNTAX_POST_ID: 49,
+} as const;
+
+// Schema for searchHelp - omit teamName, order, include, and sort from searchPostsSchema
+export const searchHelpSchema = searchPostsSchema.omit({
+  teamName: true,
+  order: true,
+  include: true,
+  sort: true,
+});
+
+export async function getSearchOptionsHelp(
+  client: ReturnType<typeof createEsaClient>,
+  _args: Record<string, never>,
+) {
+  return getPost(client, {
+    teamName: HELP_DOCS.TEAM,
+    postNumber: HELP_DOCS.SEARCH_OPTIONS_POST_ID,
+  });
+}
+
+export async function getMarkdownSyntaxHelp(
+  client: ReturnType<typeof createEsaClient>,
+  _args: Record<string, never>,
+) {
+  return getPost(client, {
+    teamName: HELP_DOCS.TEAM,
+    postNumber: HELP_DOCS.MARKDOWN_SYNTAX_POST_ID,
+  });
+}
+
+export async function searchHelp(
+  client: ReturnType<typeof createEsaClient>,
+  args: z.infer<typeof searchHelpSchema>,
+) {
+  return searchPosts(client, {
+    teamName: HELP_DOCS.TEAM,
+    sort: "best_match",
+    ...args,
+  });
+}

package/src/tools/index.ts

@@ -0,0 +1,324 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { z } from "zod";
+import { withContext } from "../api_client/with-context.js";
+import type { MCPContext } from "../context/mcp-context.js";
+import {
+  getCategories,
+  getCategoriesSchema,
+  getTopCategories,
+  getTopCategoriesSchema,
+} from "./categories.js";
+import {
+  createComment,
+  createCommentSchema,
+  deleteComment,
+  deleteCommentSchema,
+  getComment,
+  getCommentSchema,
+  getPostComments,
+  getPostCommentsSchema,
+  getTeamComments,
+  getTeamCommentsSchema,
+  updateComment,
+  updateCommentSchema,
+} from "./comments.js";
+import {
+  getMarkdownSyntaxHelp,
+  getSearchOptionsHelp,
+  searchHelp,
+  searchHelpSchema,
+} from "./helps.js";
+import {
+  archivePost,
+  archivePostSchema,
+  duplicatePost,
+  duplicatePostSchema,
+  shipPost,
+  shipPostSchema,
+} from "./post-actions.js";
+import {
+  createPost,
+  createPostSchema,
+  getPost,
+  getPostSchema,
+  updatePost,
+  updatePostSchema,
+} from "./posts.js";
+import { searchPosts, searchPostsSchema } from "./search.js";
+import {
+  getTeamMembers,
+  getTeamMembersSchema,
+  getTeamStats,
+  getTeamStatsSchema,
+  getTeams,
+  getTeamsSchema,
+  getTeamTags,
+  getTeamTagsSchema,
+} from "./teams.js";
+
+export function setupTools(server: McpServer, context: MCPContext): void {
+  console.error("Setting up MCP tools...");
+
+  server.registerTool(
+    "esa_get_teams",
+    {
+      title: "Get user's accessible esa teams",
+      description: "Retrieves a list of esa teams that the user has access to.",
+      inputSchema: getTeamsSchema.shape,
+    },
+    async (params: z.infer<typeof getTeamsSchema>) =>
+      withContext(context, getTeams, params),
+  );
+
+  server.registerTool(
+    "esa_get_team_stats",
+    {
+      title: "Get team statistics",
+      description:
+        "Retrieves team statistics including member count, posts count (total/WIP/shipped), comments, stars, watches, and daily/weekly/monthly active users",
+      inputSchema: getTeamStatsSchema.shape,
+    },
+    async (params: z.infer<typeof getTeamStatsSchema>) =>
+      withContext(context, getTeamStats, params),
+  );
+
+  server.registerTool(
+    "esa_get_team_tags",
+    {
+      title: "Get team tags",
+      description:
+        "Retrieves all tags used in posts within a team, along with the count of posts for each tag",
+      inputSchema: getTeamTagsSchema.shape,
+    },
+    async (params: z.infer<typeof getTeamTagsSchema>) =>
+      withContext(context, getTeamTags, params),
+  );
+
+  server.registerTool(
+    "esa_get_team_members",
+    {
+      title: "Get team members",
+      description:
+        "Retrieves all members of a team with their roles and profile information",
+      inputSchema: getTeamMembersSchema.shape,
+    },
+    async (params: z.infer<typeof getTeamMembersSchema>) =>
+      withContext(context, getTeamMembers, params),
+  );
+
+  server.registerTool(
+    "esa_get_post",
+    {
+      title: "Get a specific esa post",
+      description:
+        "Retrieves a specific post from an esa team by post number, with optional comments included.",
+      inputSchema: getPostSchema.shape,
+    },
+    async (params: z.infer<typeof getPostSchema>) =>
+      withContext(context, getPost, params),
+  );
+
+  server.registerTool(
+    "esa_search_posts",
+    {
+      title: "Search Posts",
+      description: "Search for posts in esa.io",
+      inputSchema: searchPostsSchema.shape,
+    },
+    async (params: z.infer<typeof searchPostsSchema>) =>
+      withContext(context, searchPosts, params),
+  );
+
+  server.registerTool(
+    "esa_create_post",
+    {
+      title: "Create a new esa post",
+      description:
+        "Creates a new post in an esa team with optional tags, category, and WIP status.",
+      inputSchema: createPostSchema.shape,
+    },
+    async (params: z.infer<typeof createPostSchema>) =>
+      withContext(context, createPost, params),
+  );
+
+  server.registerTool(
+    "esa_update_post",
+    {
+      title: "Update an existing esa post",
+      description:
+        "Updates an existing post in an esa team by post number. You can update the title, content, tags, category, and WIP status. To ship a post (mark as complete), set wip to false - this is preferred over using esa_ship_post when updating other fields simultaneously.",
+      inputSchema: updatePostSchema.shape,
+    },
+    async (params: z.infer<typeof updatePostSchema>) =>
+      withContext(context, updatePost, params),
+  );
+
+  server.registerTool(
+    "esa_get_comment",
+    {
+      title: "Get a specific comment",
+      description:
+        "Retrieves a specific comment by comment ID, with optional stargazers included.",
+      inputSchema: getCommentSchema.shape,
+    },
+    async (params: z.infer<typeof getCommentSchema>) =>
+      withContext(context, getComment, params),
+  );
+
+  server.registerTool(
+    "esa_create_comment",
+    {
+      title: "Create a new comment on a post",
+      description: "Creates a new comment on an existing post in an esa team.",
+      inputSchema: createCommentSchema.shape,
+    },
+    async (params: z.infer<typeof createCommentSchema>) =>
+      withContext(context, createComment, params),
+  );
+
+  server.registerTool(
+    "esa_update_comment",
+    {
+      title: "Update an existing comment",
+      description: "Updates an existing comment in an esa team by comment ID.",
+      inputSchema: updateCommentSchema.shape,
+    },
+    async (params: z.infer<typeof updateCommentSchema>) =>
+      withContext(context, updateComment, params),
+  );
+
+  server.registerTool(
+    "esa_delete_comment",
+    {
+      title: "Delete a comment",
+      description: "Deletes a comment from an esa team by comment ID.",
+      inputSchema: deleteCommentSchema.shape,
+    },
+    async (params: z.infer<typeof deleteCommentSchema>) =>
+      withContext(context, deleteComment, params),
+  );
+
+  server.registerTool(
+    "esa_get_post_comments",
+    {
+      title: "Get comments for a specific post",
+      description:
+        "Retrieves a list of comments for a specific post with pagination support.",
+      inputSchema: getPostCommentsSchema.shape,
+    },
+    async (params: z.infer<typeof getPostCommentsSchema>) =>
+      withContext(context, getPostComments, params),
+  );
+
+  server.registerTool(
+    "esa_get_team_comments",
+    {
+      title: "Get team comments",
+      description:
+        "Retrieves a list of comments in a team with pagination support.",
+      inputSchema: getTeamCommentsSchema.shape,
+    },
+    async (params: z.infer<typeof getTeamCommentsSchema>) =>
+      withContext(context, getTeamComments, params),
+  );
+
+  server.registerTool(
+    "esa_get_categories",
+    {
+      title: "Get categories for a specific path",
+      description:
+        "Retrieves category information and subcategories for a specific category path, with optional posts and parent categories included",
+      inputSchema: getCategoriesSchema.shape,
+    },
+    async (params: z.infer<typeof getCategoriesSchema>) =>
+      withContext(context, getCategories, params),
+  );
+
+  server.registerTool(
+    "esa_get_top_categories",
+    {
+      title: "Get top-level categories",
+      description: "Retrieves all top-level categories for a team",
+      inputSchema: getTopCategoriesSchema.shape,
+    },
+    async (params: z.infer<typeof getTopCategoriesSchema>) =>
+      withContext(context, getTopCategories, params),
+  );
+
+  server.registerTool(
+    "esa_archive_post",
+    {
+      title: "Archive a post",
+      description:
+        "Archives a post by moving it to the Archived/ category. If the post is in 'dev/docs', it becomes 'Archived/dev/docs'. Posts without category go to 'Archived'.",
+      inputSchema: archivePostSchema.shape,
+    },
+    async (params: z.infer<typeof archivePostSchema>) =>
+      withContext(context, archivePost, params),
+  );
+
+  server.registerTool(
+    "esa_ship_post",
+    {
+      title: "Ship a post",
+      description:
+        "Ships a post by setting wip to false. This marks the post as complete and ready to be published. Use this only when you need to ship without making other changes - if you're also updating title, content, or other fields, use esa_update_post with wip: false instead.",
+      inputSchema: shipPostSchema.shape,
+    },
+    async (params: z.infer<typeof shipPostSchema>) =>
+      withContext(context, shipPost, params),
+  );
+
+  server.registerTool(
+    "esa_duplicate_post",
+    {
+      title: "Prepare a post for duplication",
+      description:
+        "Prepares a post for duplication by retrieving its name and body_md content. Returns the name and body_md that can be used with esa_create_post to create a duplicate of the original post.",
+      inputSchema: duplicatePostSchema.shape,
+    },
+    async (params: z.infer<typeof duplicatePostSchema>) =>
+      withContext(context, duplicatePost, params),
+  );
+
+  server.registerTool(
+    "esa_get_search_options_help",
+    {
+      title: "Get esa search options documentation",
+      description: `Get esa search syntax documentation when you need to construct complex
+search queries. Use this BEFORE esa_search_posts if you're unsure how to
+translate user's search requirements into proper esa query syntax (e.g., date
+ranges, tag filters, category searches, advanced operators).`,
+      inputSchema: {},
+    },
+    async (params: Record<string, never>) =>
+      withContext(context, getSearchOptionsHelp, params),
+  );
+
+  server.registerTool(
+    "esa_get_markdown_syntax_help",
+    {
+      title: "Get esa Markdown syntax documentation",
+      description: `Get esa Markdown and formatting documentation when unsure about syntax.
+Use this BEFORE using any tools with *_md parameters (like esa_create_post,
+esa_update_post, esa_create_comment, esa_update_comment) if you need
+clarification on Markdown syntax, esa-specific extensions, or formatting options.`,
+      inputSchema: {},
+    },
+    async (params: Record<string, never>) =>
+      withContext(context, getMarkdownSyntaxHelp, params),
+  );
+
+  server.registerTool(
+    "esa_search_help",
+    {
+      title: "Search esa documentation and help",
+      description: `Search esa documentation for features, terminology, and specifications.
+Use this when users mention esa-specific terms, ask about esa functionality,
+or request help with esa workflows that you're not familiar with.`,
+      inputSchema: searchHelpSchema.shape,
+    },
+    async (params: z.infer<typeof searchHelpSchema>) =>
+      withContext(context, searchHelp, params),
+  );
+}