ESA MCP Server

Instructions

Implementation Reference

• src/server.ts:37-99 (registration)

  Registration of the search_esa_posts tool, including description, input schema (using imported order/sort schemas), and inline handler that calls ApiClient.searchPosts and formats output.

  server.tool(
    "search_esa_posts",
    "Search posts in esa.io. Response is paginated. " +
      "For efficient search, you can use customized queries like the following: " +
      'keyword for partial match, "keyword" for exact match, ' +
      "keyword1 keyword2 for AND match, " +
      "keyword1 OR keyword2 for OR match, " +
      "-keyword for excluding keywords, " +
      "title:keyword for title match, " +
      "wip:true or wip:false for WIP posts, " +
      "kind:stock or kind:flow for kind match, " +
      "category:category_name for partial match with category name, " +
      "in:category_name for prefix match with category name, " +
      "on:category_name for exact match with category name, " +
      "body:keyword for body match, " +
      "tag:tag_name or tag:tag_name case_sensitive:true for tag match, " +
      "user:screen_name for post author's screen name, " +
      "updated_by:screen_name for post updater's screen name, " +
      "comment:keyword for partial match with comments, " +
      "starred:true or starred:false for starred posts, " +
      "watched:true or watched:false for watched posts, " +
      "watched_by:screen_name for screen name of members watching the post, " +
      "sharing:true or sharing:false for shared posts, " +
      "stars:>3 for posts with more than 3 stars, " +
      "watches:>3 for posts with more than 3 watches, " +
      "comments:>3 for posts with more than 3 comments, " +
      "done:>=3 for posts with 3 or more done items, " +
      "undone:>=3 for posts with 3 or more undone items, " +
      "created:>YYYY-MM-DD for filtering by creation date, " +
      "updated:>YYYY-MM-DD for filtering by update date." +
      "Strongly recommend see get_search_query_document for complete query usage.",
    {
      teamName: z.string().default(getRequiredEnv("DEFAULT_ESA_TEAM")),
      query: z.string(),
      order: orderSchema,
      sort: sortSchema,
      page: z.number().min(1).default(1),
      perPage: z.number().min(1).max(100).default(50),
    },
    async (input) =>
      await formatTool(async () => {
        const posts = await client.searchPosts(
          input.teamName,
          input.query,
          input.order,
          input.sort,
          input.page,
          input.perPage
        )
  
        return {
          content: [
            {
              type: "text",
              text: stringify({
                posts: posts,
                nextPage: input.page + 1,
              }),
            },
          ],
        }
      })
  )

• src/server.ts:76-99 (handler)

  Inline handler function for search_esa_posts: invokes ApiClient.searchPosts with input params and wraps the paginated posts in YAML-formatted text response.

    async (input) =>
      await formatTool(async () => {
        const posts = await client.searchPosts(
          input.teamName,
          input.query,
          input.order,
          input.sort,
          input.page,
          input.perPage
        )
  
        return {
          content: [
            {
              type: "text",
              text: stringify({
                posts: posts,
                nextPage: input.page + 1,
              }),
            },
          ],
        }
      })
  )

• src/api.ts:56-88 (helper)

  ApiClient.searchPosts: core logic calls esa.io search API (getV1TeamsTeamNamePosts), strips body_html and body_md from posts to reduce size, returns post metadata.

  async searchPosts(
    teamName: string,
    query: string,
    order: z.infer<typeof orderSchema>,
    sort: z.infer<typeof sortSchema>,
    page: number,
    perPage: number
  ) {
    const response = await this.callApi(() =>
      getV1TeamsTeamNamePosts(
        teamName,
        {
          q: query,
          order: order,
          sort: sort,
          page: page,
          per_page: perPage,
        },
        {
          headers: {
            Authorization: `Bearer ${getRequiredEnv("ESA_API_KEY")}`,
          },
        }
      )
    )
  
    // esa 的には取ってきちゃうが、LLM が呼むのに全文は大きすぎるので外す
    const posts = (response.data.posts ?? []).map(
      ({ body_html, body_md, ...others }) => others
    )
  
    return posts
  }

• src/schema.ts:1-17 (schema)

  Zod schemas defining 'order' (asc/desc) and 'sort' (created/updated/number/stars/comments/best_match) options used in the search_esa_posts tool schema.

  import { z } from "zod"
  
  export const orderSchema = z
    .union([z.literal("asc"), z.literal("desc")])
    .default("desc")
  
  export const sortSchema = z
    .union([
      z.literal("created"),
      z.literal("updated"),
      z.literal("number"),
      z.literal("stars"),
      z.literal("comments"),
      z.literal("best_match"),
    ])
    .default("best_match")

• src/formatTool.ts:34-61 (helper)

  formatTool utility: wraps tool execution result in MCP CallToolResult format, serializes to YAML text, handles errors.

  export const formatTool = async (
    cb: () => unknown
  ): Promise<CallToolResult> => {
    try {
      const result = await cb()
  
      return {
        content: [
          {
            type: "text",
            text: stringify(toResponse(result)),
          },
        ],
      }
    } catch (error) {
      console.error("Error in formatTool:", error)
  
      return {
        isError: true,
        content: [
          {
            type: "text",
            text: `Error: ${error instanceof Error ? `${error.name}: ${error.message}` : String(error)}`,
          },
        ],
      }
    }
  }