@esaio/esa-mcp-server 0.1.0 → 0.2.1

package/src/tools/attachments.ts

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

@@ -91,3 +91,63 @@ export async function getTopCategories(
     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/index.ts

@@ -2,7 +2,10 @@ 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 { getAttachment, getAttachmentSchema } from "./attachments.js";
 import {
+  getAllCategoryPaths,
+  getAllCategoryPathsSchema,
   getCategories,
   getCategoriesSchema,
   getTopCategories,
@@ -245,6 +248,18 @@ export function setupTools(server: McpServer, context: MCPContext): void {
       withContext(context, getTopCategories, params),
   );
 
+  server.registerTool(
+    "esa_get_all_category_paths",
+    {
+      title: "Get all category paths for organization and structure review",
+      description:
+        "Retrieves all category paths in a team at once to understand the overall category structure. Perfect for category organization, cleanup, migration planning, or finding similar categories. Returns a simple list of paths with post counts, sorted in lexicographic order. Supports filtering (prefix/suffix/match/exact_match) to find categories by pattern. No pagination - gets all categories in one call.",
+      inputSchema: getAllCategoryPathsSchema.shape,
+    },
+    async (params: z.infer<typeof getAllCategoryPathsSchema>) =>
+      withContext(context, getAllCategoryPaths, params),
+  );
+
   server.registerTool(
     "esa_archive_post",
     {
@@ -321,4 +336,16 @@ or request help with esa workflows that you're not familiar with.`,
     async (params: z.infer<typeof searchHelpSchema>) =>
       withContext(context, searchHelp, params),
   );
+
+  server.registerTool(
+    "esa_get_attachment",
+    {
+      title: "Get attachment file from esa",
+      description:
+        "Retrieves an attachment file from esa with signed URLs. For supported images (JPEG, PNG, GIF, WebP) under 30MB, returns base64-encoded data. For other file types, larger images, or when forceSignedUrl is true, returns signed URLs.",
+      inputSchema: getAttachmentSchema.shape,
+    },
+    async (params: z.infer<typeof getAttachmentSchema>) =>
+      withContext(context, getAttachment, params),
+  );
 }

package/.claude/settings.local.json

@@ -1,23 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(npm run build:*)",
-      "WebFetch(domain:openapi-ts.dev)",
-      "WebFetch(domain:docs.esa.io)",
-      "WebFetch(domain:raw.githubusercontent.com)",
-      "Bash(rm:*)",
-      "Bash(mv:*)",
-      "Bash(npm run test:run:*)",
-      "Bash(npm run type-check:*)",
-      "Bash(npm test:*)",
-      "WebFetch(domain:modelcontextprotocol.io)",
-      "Bash(git mv:*)",
-      "Bash(git add:*)",
-      "Bash(node:*)",
-      "Bash(npm run lint:*)",
-      "Bash(git commit:*)",
-      "Bash(grep:*)"
-    ],
-    "deny": []
-  }
-}

package/.envrc

@@ -1,2 +0,0 @@
-export ESA_ACCESS_TOKEN=ep2_BI_DX0c-_GB-dlNEcbVYdJqZhkA4gKQtHvmL9LLWBqo
-export ESA_API_BASE_URL=http://api.lvh.me:3000

package/.node-version

@@ -1 +0,0 @@
-24.4.1