ESA MCP Server

Instructions

Implementation Reference

• src/server.ts:135-165 (handler)

  MCP tool registration, schema, and handler implementation for 'create_esa_post'. The handler extracts parameters, calls ApiClient.createPost, and formats the response using formatTool.

  server.tool(
    "create_esa_post",
    "Create a new post in esa.io. Required parameters: name. Optional parameters: body_md, tags, category, wip (default: true), message.",
    {
      teamName: z.string().default(getRequiredEnv("DEFAULT_ESA_TEAM")),
      name: z.string(),
      body_md: z.string().optional(),
      tags: z.array(z.string()).optional(),
      category: z.string().optional(),
      wip: z.boolean().default(true),
      message: z.string().optional(),
    },
    async (input) =>
      await formatTool(async () => {
        const { teamName: createTeamName, ...postData } = input
        return client.createPost(createTeamName, postData).then((data) => ({
          success: true,
          number: data.number,
          full_name: data.full_name,
          url: data.url,
          wip: data.wip,
          created_at: data.created_at,
          message: data.message,
          kind: data.kind,
          tags: data.tags,
          category: data.category,
          revision_number: data.revision_number,
          created_by: data.created_by,
        }))
      })
  )

• src/server.ts:139-146 (schema)

  Zod input schema for the create_esa_post tool defining parameters like teamName, name, body_md, etc.

    teamName: z.string().default(getRequiredEnv("DEFAULT_ESA_TEAM")),
    name: z.string(),
    body_md: z.string().optional(),
    tags: z.array(z.string()).optional(),
    category: z.string().optional(),
    wip: z.boolean().default(true),
    message: z.string().optional(),
  },

• src/api.ts:111-125 (helper)

  ApiClient.createPost helper function that makes the actual API call to esa.io to create the post using the generated esaAPI client.

  async createPost(teamName: string, post: PostInput) {
    return this.callApi(() =>
      postV1TeamsTeamNamePosts(
        teamName,
        {
          post,
        },
        {
          headers: {
            Authorization: `Bearer ${this.apiKey}`,
          },
        }
      )
    ).then((response) => response.data)
  }

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

  formatTool utility wraps the tool callback to format output as YAML text content and handle errors appropriately for MCP response.

  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)}`,
          },
        ],
      }
    }
  }