@esaio/esa-mcp-server 0.2.0 → 0.2.2

package/src/tools/attachments.ts

@@ -1,167 +0,0 @@
-import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-import { z } from "zod";
-import type { createEsaClient } from "../api_client/index.js";
-import { MissingTeamNameError } from "../errors/missing-team-name-error.js";
-import { formatToolError } from "../formatters/mcp-response.js";
-import { createSchemaWithTeamName } from "../schemas/team-name-schema.js";
-
-// Maximum file size for base64 encoding (30MB)
-const MAX_IMAGE_SIZE = 30 * 1024 * 1024;
-
-// Supported image MIME types for base64 encoding
-const SUPPORTED_IMAGE_TYPES = [
-  "image/jpeg",
-  "image/png",
-  "image/gif",
-  "image/webp",
-] as const;
-
-export const getAttachmentSchema = createSchemaWithTeamName({
-  url: z
-    .string()
-    .describe(
-      "Attachment URL. Can be a full URL (https://files.esa.io/..., https://dl.esa.io/...) or a path (/uploads/...)",
-    ),
-  forceSignedUrl: z
-    .boolean()
-    .optional()
-    .describe(
-      "If true, always return signed URLs instead of base64-encoded images. Default is false.",
-    ),
-});
-
-/**
- * Extracts the path from a full URL or returns the input if it's already a path
- */
-function normalizeUrl(url: string): string {
-  // If it's already a path (starts with /), return as-is
-  if (url.startsWith("/")) {
-    return url;
-  }
-
-  try {
-    // Try to parse as URL and extract pathname
-    const urlObj = new URL(url);
-    return urlObj.pathname;
-  } catch {
-    // If URL parsing fails, assume it's already a path
-    return url;
-  }
-}
-
-/**
- * Checks if the MIME type is a supported image format
- */
-function isSupportedImage(mimeType: string): boolean {
-  return SUPPORTED_IMAGE_TYPES.includes(
-    mimeType as (typeof SUPPORTED_IMAGE_TYPES)[number],
-  );
-}
-
-/**
- * Fetches content and returns base64-encoded data if it's a supported image under size limit
- */
-async function fetchAttachment(
-  signedUrl: string,
-  forceSignedUrl: boolean,
-): Promise<
-  | { type: "image"; data: string; mimeType: string }
-  | { type: "text"; text: string }
-> {
-  // If forceSignedUrl is true, always return signed URL
-  if (forceSignedUrl) {
-    return {
-      type: "text" as const,
-      text: signedUrl,
-    };
-  }
-
-  const response = await fetch(signedUrl);
-
-  if (!response.ok) {
-    throw new Error(
-      `Failed to fetch attachment: ${response.status} ${response.statusText}`,
-    );
-  }
-
-  const contentType = response.headers.get("content-type") || "";
-  const contentLength = response.headers.get("content-length");
-  const size = contentLength ? Number.parseInt(contentLength, 10) : 0;
-
-  // Check if it's a supported image and within size limit
-  if (isSupportedImage(contentType) && size > 0 && size <= MAX_IMAGE_SIZE) {
-    const arrayBuffer = await response.arrayBuffer();
-    const buffer = Buffer.from(arrayBuffer);
-    const base64 = buffer.toString("base64");
-
-    return {
-      type: "image" as const,
-      data: base64,
-      mimeType: contentType,
-    };
-  }
-
-  // For non-images or oversized images, return the signed URL
-  return {
-    type: "text" as const,
-    text: signedUrl,
-  };
-}
-
-export async function getAttachment(
-  client: ReturnType<typeof createEsaClient>,
-  args: z.infer<typeof getAttachmentSchema>,
-): Promise<CallToolResult> {
-  try {
-    if (!args.teamName) {
-      throw new MissingTeamNameError();
-    }
-
-    // Normalize URL to path
-    const normalizedUrl = normalizeUrl(args.url);
-
-    // Get signed URL from esa API
-    const { data, error, response } = await client.GET(
-      "/v1/teams/{team_name}/signed_urls",
-      {
-        params: {
-          path: { team_name: args.teamName },
-          query: {
-            urls: normalizedUrl,
-            v: 2,
-            expires_in: 300, // 5 minutes
-          },
-        },
-      },
-    );
-
-    if (error || !response.ok) {
-      return formatToolError(error || response.status);
-    }
-
-    if (!data.signed_urls || data.signed_urls.length === 0) {
-      throw new Error("No signed URLs returned from API");
-    }
-
-    const [originalUrl, signedUrl] = data.signed_urls[0];
-
-    if (signedUrl === null) {
-      throw new Error(`File not found: ${originalUrl}`);
-    }
-
-    const forceSignedUrl = args.forceSignedUrl ?? false;
-
-    try {
-      const result = await fetchAttachment(signedUrl, forceSignedUrl);
-      return { content: [result] };
-    } catch (err) {
-      throw new Error(
-        `Failed to fetch attachment for ${originalUrl}: ${
-          err instanceof Error ? err.message : String(err)
-        }`,
-      );
-    }
-  } catch (err) {
-    return formatToolError(err);
-  }
-}

package/src/tools/categories.ts

@@ -1,153 +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 { transformCategoryList } from "../transformers/category-transformer.js";
-
-export const getCategoriesSchema = createSchemaWithTeamName({
-  select: z.string().describe("Category path to retrieve"),
-  include: z
-    .enum(["posts", "parent_categories"])
-    .optional()
-    .describe("Additional information to include"),
-  descendantPosts: z
-    .boolean()
-    .optional()
-    .describe("Include descendant posts (only effective with include=posts)"),
-  page: z.number().optional().describe("Page number (starts from 1)"),
-  perPage: z.number().optional().describe("Number of items per page"),
-});
-
-export async function getCategories(
-  client: ReturnType<typeof createEsaClient>,
-  args: z.infer<typeof getCategoriesSchema>,
-) {
-  try {
-    if (!args.teamName) {
-      throw new MissingTeamNameError();
-    }
-    const { data, error, response } = await client.GET(
-      "/v1/teams/{team_name}/categories",
-      {
-        params: {
-          path: { team_name: args.teamName },
-          query: {
-            select: args.select,
-            include: args.include,
-            descendant_posts: args.descendantPosts,
-            page: args.page,
-            per_page: args.perPage,
-          },
-        },
-      },
-    );
-
-    if (error || !response.ok) {
-      return formatToolError(error || response.status);
-    }
-
-    const categoryList: components["schemas"]["CategoryList"] = data;
-    const transformed = transformCategoryList(categoryList);
-
-    return formatToolResponse(transformed);
-  } catch (error) {
-    return formatToolError(error);
-  }
-}
-
-export const getTopCategoriesSchema = createSchemaWithTeamName({});
-
-export async function getTopCategories(
-  client: ReturnType<typeof createEsaClient>,
-  args: z.infer<typeof getTopCategoriesSchema>,
-) {
-  try {
-    if (!args.teamName) {
-      throw new MissingTeamNameError();
-    }
-    const { data, error, response } = await client.GET(
-      "/v1/teams/{team_name}/categories/top",
-      {
-        params: {
-          path: { team_name: args.teamName },
-        },
-      },
-    );
-
-    if (error || !response.ok) {
-      return formatToolError(error || response.status);
-    }
-
-    const categoryList: components["schemas"]["CategoryList"] = data;
-    const transformed = transformCategoryList(categoryList);
-
-    return formatToolResponse(transformed);
-  } catch (error) {
-    return formatToolError(error);
-  }
-}
-
-export const getAllCategoryPathsSchema = createSchemaWithTeamName({
-  prefix: z
-    .string()
-    .optional()
-    .describe(
-      "Filter paths starting with specified string (e.g., 'dev' finds 'dev', 'dev/api', 'dev/docs')",
-    ),
-  suffix: z
-    .string()
-    .optional()
-    .describe(
-      "Filter paths ending with specified string (e.g., 'api' finds 'dev/api', 'backend/api')",
-    ),
-  match: z
-    .string()
-    .optional()
-    .describe(
-      "Filter paths containing specified substring anywhere (e.g., 'doc' finds 'docs', 'dev/docs', 'documentation')",
-    ),
-  exactMatch: z
-    .string()
-    .optional()
-    .describe(
-      "Filter paths matching exactly (e.g., 'dev/api' matches only 'dev/api', ignores leading/trailing slashes)",
-    ),
-});
-
-export async function getAllCategoryPaths(
-  client: ReturnType<typeof createEsaClient>,
-  args: z.infer<typeof getAllCategoryPathsSchema>,
-) {
-  try {
-    if (!args.teamName) {
-      throw new MissingTeamNameError();
-    }
-    const { data, error, response } = await client.GET(
-      "/v1/teams/{team_name}/categories/paths",
-      {
-        params: {
-          path: { team_name: args.teamName },
-          query: {
-            prefix: args.prefix,
-            suffix: args.suffix,
-            match: args.match,
-            exact_match: args.exactMatch,
-          },
-        },
-      },
-    );
-
-    if (error || !response.ok) {
-      return formatToolError(error || response.status);
-    }
-
-    return formatToolResponse(data);
-  } catch (error) {
-    return formatToolError(error);
-  }
-}

package/src/tools/comments.ts

@@ -1,258 +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 { 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

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