@esaio/esa-mcp-server 0.1.0

package/src/api_client/__tests__/index.test.ts

@@ -0,0 +1,149 @@
+import createClient from "openapi-fetch";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import packageJson from "../../../package.json" with { type: "json" };
+import type { paths } from "../../generated/api-types.js";
+import { createEsaClient } from "../index.js";
+
+// Mock openapi-fetch to test client configuration without actual HTTP calls
+vi.mock("openapi-fetch", () => ({
+  default: vi.fn(),
+}));
+
+describe("createEsaClient", () => {
+  // Create mock client with use method to verify middleware registration
+  const createMockClient = () =>
+    ({
+      use: vi.fn(),
+    }) as unknown as ReturnType<typeof createClient<paths>>;
+
+  // Setup test environment with configurable parameters for different test scenarios
+  const setupTest = (overrides?: {
+    apiBaseUrl?: string;
+    apiAccessToken?: string;
+  }) => {
+    const config = {
+      apiBaseUrl: overrides?.apiBaseUrl ?? "https://api.esa.example.com",
+      apiAccessToken: overrides?.apiAccessToken ?? "test-token",
+    };
+
+    const mockClient = createMockClient();
+    const mockCreateClient = vi.mocked(createClient);
+    mockCreateClient.mockReturnValue(mockClient);
+
+    return { config, mockClient, mockCreateClient };
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("should create client with correct baseUrl", () => {
+    const { config, mockCreateClient } = setupTest();
+
+    createEsaClient(config.apiAccessToken, config.apiBaseUrl);
+
+    expect(mockCreateClient).toHaveBeenCalledWith({
+      baseUrl: config.apiBaseUrl,
+    });
+  });
+
+  it("should add User-Agent and Auth middleware to client", () => {
+    const { config, mockClient } = setupTest();
+
+    createEsaClient(config.apiAccessToken, config.apiBaseUrl);
+
+    expect(mockClient.use).toHaveBeenCalledTimes(2);
+    expect(mockClient.use).toHaveBeenNthCalledWith(
+      1,
+      expect.objectContaining({
+        onRequest: expect.any(Function),
+      }),
+    );
+    expect(mockClient.use).toHaveBeenNthCalledWith(
+      2,
+      expect.objectContaining({
+        onRequest: expect.any(Function),
+      }),
+    );
+  });
+
+  it("should return the configured client", () => {
+    const { config, mockClient } = setupTest();
+
+    const result = createEsaClient(config.apiAccessToken, config.apiBaseUrl);
+
+    expect(result).toBe(mockClient);
+  });
+
+  it("should set User-Agent header in middleware", async () => {
+    const { config, mockClient } = setupTest();
+
+    createEsaClient(config.apiAccessToken, config.apiBaseUrl);
+
+    // Get the User-Agent middleware function (first one registered)
+    const useMock = mockClient.use as ReturnType<typeof vi.fn>;
+    const userAgentMiddleware = useMock.mock.calls[0][0];
+
+    // Create mock request to verify User-Agent header is set
+    const mockRequest = {
+      headers: {
+        set: vi.fn(),
+      },
+    };
+
+    await userAgentMiddleware.onRequest({ request: mockRequest });
+
+    expect(mockRequest.headers.set).toHaveBeenCalledWith(
+      "User-Agent",
+      `esa-mcp-server/${packageJson.version} (official)`,
+    );
+  });
+
+  it("should set Authorization header in middleware", async () => {
+    const { config, mockClient } = setupTest();
+
+    createEsaClient(config.apiAccessToken, config.apiBaseUrl);
+
+    // Get the Auth middleware function (second one registered)
+    const useMock = mockClient.use as ReturnType<typeof vi.fn>;
+    const authMiddleware = useMock.mock.calls[1][0];
+
+    // Create mock request to verify Authorization header is set
+    const mockRequest = {
+      headers: {
+        set: vi.fn(),
+      },
+    };
+
+    await authMiddleware.onRequest({ request: mockRequest });
+
+    expect(mockRequest.headers.set).toHaveBeenCalledWith(
+      "Authorization",
+      `Bearer ${config.apiAccessToken}`,
+    );
+  });
+
+  it("should create separate client instances for different tokens", () => {
+    const { config, mockCreateClient, mockClient } = setupTest();
+    const token1 = "token-1";
+    const token2 = "token-2";
+
+    createEsaClient(token1, config.apiBaseUrl);
+    createEsaClient(token2, config.apiBaseUrl);
+
+    expect(mockCreateClient).toHaveBeenCalledTimes(2);
+    expect(mockClient.use).toHaveBeenCalledTimes(4); // 2 middlewares × 2 clients
+  });
+
+  it("should create separate client instances for different base URLs", () => {
+    const { config, mockCreateClient } = setupTest();
+    const url1 = "https://api.esa.example.com";
+    const url2 = "https://api.example.com";
+
+    createEsaClient(config.apiAccessToken, url1);
+    createEsaClient(config.apiAccessToken, url2);
+
+    expect(mockCreateClient).toHaveBeenCalledWith({ baseUrl: url1 });
+    expect(mockCreateClient).toHaveBeenCalledWith({ baseUrl: url2 });
+  });
+});

package/src/api_client/__tests__/middleware.test.ts

@@ -0,0 +1,119 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createAuthMiddleware } from "../middleware.js";
+
+describe("createAuthMiddleware", () => {
+  // Mock console.error to verify rate limit and error logging without console output
+  let consoleErrorSpy: ReturnType<typeof vi.spyOn>;
+
+  // Create test request for authorization header testing
+  const createTestRequest = (url = "https://api.esa.example.com/test") =>
+    new Request(url);
+
+  // Create test response with optional rate limit headers
+  const createTestResponse = (rateLimitHeaders?: {
+    limit?: string;
+    remaining?: string;
+  }) => {
+    const headers: Record<string, string> = {};
+    if (rateLimitHeaders?.limit) {
+      headers["x-ratelimit-limit"] = rateLimitHeaders.limit;
+    }
+    if (rateLimitHeaders?.remaining) {
+      headers["x-ratelimit-remaining"] = rateLimitHeaders.remaining;
+    }
+    return new Response(null, { headers });
+  };
+
+  // Helper to call middleware methods with minimal required context using as unknown as pattern
+  const callOnRequest = (
+    middleware: ReturnType<typeof createAuthMiddleware>,
+    request: Request,
+  ) =>
+    middleware.onRequest?.({
+      request,
+      schemaPath: "/test",
+      params: {},
+      id: "test-id",
+      options: { baseUrl: "https://api.esa.example.com" },
+    } as unknown as Parameters<NonNullable<typeof middleware.onRequest>>[0]);
+
+  const callOnResponse = (
+    middleware: ReturnType<typeof createAuthMiddleware>,
+    response: Response,
+  ) =>
+    middleware.onResponse?.({
+      request: createTestRequest(),
+      response,
+      schemaPath: "/test",
+      params: {},
+      id: "test-id",
+      options: { baseUrl: "https://api.esa.example.com" },
+    } as unknown as Parameters<NonNullable<typeof middleware.onResponse>>[0]);
+
+  const callOnError = (
+    middleware: ReturnType<typeof createAuthMiddleware>,
+    error: Error,
+  ) =>
+    middleware.onError?.({
+      request: createTestRequest(),
+      error,
+      schemaPath: "/test",
+      params: {},
+      id: "test-id",
+      options: { baseUrl: "https://api.esa.example.com" },
+    } as unknown as Parameters<NonNullable<typeof middleware.onError>>[0]);
+
+  beforeEach(() => {
+    consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    consoleErrorSpy.mockRestore();
+  });
+
+  it("should add authorization header", async () => {
+    const middleware = createAuthMiddleware("test-token");
+    const request = createTestRequest();
+
+    expect(middleware.onRequest).toBeDefined();
+    expect(request.headers.get("Authorization")).toBeNull();
+
+    await callOnRequest(middleware, request);
+
+    expect(request.headers.get("Authorization")).toBe("Bearer test-token");
+  });
+
+  it("should log rate limit info when present", async () => {
+    const middleware = createAuthMiddleware("test-token");
+    const response = createTestResponse({ limit: "75", remaining: "50" });
+
+    await callOnResponse(middleware, response);
+    expect(consoleErrorSpy).toHaveBeenCalledWith("Rate limit: 50/75");
+  });
+
+  it("should handle response without rate limit headers", async () => {
+    const middleware = createAuthMiddleware("test-token");
+    const response = createTestResponse();
+
+    await callOnResponse(middleware, response);
+    expect(consoleErrorSpy).not.toHaveBeenCalled();
+  });
+
+  it("should log network errors", async () => {
+    const middleware = createAuthMiddleware("test-token");
+    const error = new Error("Network failed");
+
+    await callOnError(middleware, error);
+    expect(consoleErrorSpy).toHaveBeenCalledWith("Network Error:", error);
+  });
+
+  it("should return the modified request", async () => {
+    const middleware = createAuthMiddleware("test-token");
+    const request = createTestRequest();
+
+    const result = await callOnRequest(middleware, request);
+
+    expect(result).toBe(request);
+    expect(request.headers.get("Authorization")).toBe("Bearer test-token");
+  });
+});

package/src/api_client/__tests__/with-context.test.ts

@@ -0,0 +1,98 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { createEsaClient } from "../index.js";
+import { withContext } from "../with-context.js";
+
+// Mock createEsaClient to test context handling without real API client creation
+vi.mock("../index.js", () => ({
+  createEsaClient: vi.fn(),
+}));
+
+describe("withContext", () => {
+  const mockCreateEsaClient = vi.mocked(createEsaClient);
+
+  // Mock client instance to verify it's passed to handlers correctly
+  const mockClient: Partial<ReturnType<typeof createEsaClient>> = {};
+
+  // Mock handler function to verify arguments and return values
+  const mockHandler = vi.fn();
+
+  // Create test context with default values and optional overrides
+  const createTestContext = (overrides?: {
+    apiAccessToken?: string;
+    apiBaseUrl?: string;
+  }) => ({
+    apiAccessToken: overrides?.apiAccessToken ?? "test-token",
+    apiBaseUrl: overrides?.apiBaseUrl ?? "https://api.esa.example.com",
+  });
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockCreateEsaClient.mockReturnValue(
+      mockClient as ReturnType<typeof createEsaClient>,
+    );
+  });
+
+  it("should create client and call handler for StdioContext", async () => {
+    const context = createTestContext();
+    const expectedResult = { success: true };
+    mockHandler.mockResolvedValue(expectedResult);
+
+    const result = await withContext(context, mockHandler, "arg1", "arg2");
+
+    expect(mockCreateEsaClient).toHaveBeenCalledWith(
+      context.apiAccessToken,
+      context.apiBaseUrl,
+    );
+    expect(mockHandler).toHaveBeenCalledWith(mockClient, "arg1", "arg2");
+    expect(result).toBe(expectedResult);
+  });
+
+  it("should work with different apiBaseUrl", async () => {
+    const context = createTestContext({
+      apiBaseUrl: "https://api.example.com",
+    });
+
+    await withContext(context, mockHandler);
+
+    expect(mockCreateEsaClient).toHaveBeenCalledWith(
+      context.apiAccessToken,
+      context.apiBaseUrl,
+    );
+  });
+
+  it("should throw error for unsupported context type", async () => {
+    // Create invalid context missing required apiAccessToken property
+    const invalidContext = {
+      someOtherProperty: "value",
+    };
+
+    await expect(
+      withContext(
+        invalidContext as unknown as Parameters<typeof withContext>[0],
+        mockHandler,
+      ),
+    ).rejects.toThrow(
+      "Unsupported context type. Only StdioContext is currently supported.",
+    );
+  });
+
+  it("should handle handler errors correctly", async () => {
+    const context = createTestContext();
+    const handlerError = new Error("Handler failed");
+    mockHandler.mockRejectedValue(handlerError);
+
+    await expect(withContext(context, mockHandler)).rejects.toThrow(
+      "Handler failed",
+    );
+  });
+
+  it("should pass through handler arguments correctly", async () => {
+    const context = createTestContext();
+    const args = [{ page: 1 }, { per_page: 20 }, "extra"];
+    mockHandler.mockResolvedValue("success");
+
+    await withContext(context, mockHandler, ...args);
+
+    expect(mockHandler).toHaveBeenCalledWith(mockClient, ...args);
+  });
+});

package/src/api_client/index.ts

@@ -0,0 +1,29 @@
+import createClient from "openapi-fetch";
+import packageJson from "../../package.json" with { type: "json" };
+import type { paths } from "../generated/api-types.js";
+import { createAuthMiddleware } from "./middleware.js";
+
+const packageVersion = packageJson.version;
+
+function createUserAgentMiddleware(version: string) {
+  return {
+    async onRequest({ request }: { request: Request }) {
+      request.headers.set("User-Agent", `esa-mcp-server/${version} (official)`);
+      return request;
+    },
+  };
+}
+
+export function createEsaClient(
+  apiAccessToken: string,
+  apiBaseUrl: string = "https://api.esa.io",
+) {
+  const client = createClient<paths>({
+    baseUrl: apiBaseUrl,
+  });
+
+  client.use(createUserAgentMiddleware(packageVersion));
+  client.use(createAuthMiddleware(apiAccessToken));
+
+  return client;
+}

package/src/api_client/middleware.ts

@@ -0,0 +1,21 @@
+import type { Middleware } from "openapi-fetch";
+
+export function createAuthMiddleware(apiAccessToken: string): Middleware {
+  return {
+    async onRequest({ request }) {
+      request.headers.set("Authorization", `Bearer ${apiAccessToken}`);
+      return request;
+    },
+    async onResponse({ response }) {
+      const rateLimit = response.headers.get("x-ratelimit-limit");
+      const remaining = response.headers.get("x-ratelimit-remaining");
+      if (rateLimit && remaining) {
+        console.error(`Rate limit: ${remaining}/${rateLimit}`);
+      }
+      return response;
+    },
+    async onError({ error }) {
+      console.error("Network Error:", error);
+    },
+  };
+}

package/src/api_client/with-context.ts

@@ -0,0 +1,26 @@
+import { createEsaClient } from "../api_client/index.js";
+import type { MCPContext } from "../context/mcp-context.js";
+
+export async function withContext<T extends unknown[], R>(
+  context: MCPContext,
+  handler: (
+    client: ReturnType<typeof createEsaClient>,
+    ...args: T
+  ) => Promise<R>,
+  ...args: T
+): Promise<R> {
+  let client: ReturnType<typeof createEsaClient>;
+
+  if ("apiAccessToken" in context && "apiBaseUrl" in context) {
+    client = createEsaClient(
+      context.apiAccessToken as string,
+      context.apiBaseUrl as string,
+    );
+  } else {
+    throw new Error(
+      "Unsupported context type. Only StdioContext is currently supported.",
+    );
+  }
+
+  return handler(client, ...args);
+}

package/src/config/__tests__/index.test.ts

@@ -0,0 +1,65 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import packageJson from "../../../package.json" with { type: "json" };
+
+describe("config", () => {
+  beforeEach(() => {
+    vi.resetModules();
+    vi.stubEnv("ESA_ACCESS_TOKEN", undefined);
+    vi.stubEnv("ESA_API_BASE_URL", undefined);
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  describe("config object", () => {
+    it("should have correct default values", async () => {
+      const { config } = await import("../index.js");
+
+      expect(config.esa.apiBaseUrl).toBe("https://api.esa.io");
+      expect(config.server.name).toBe("esa-mcp-server");
+      expect(config.server.version).toBe(packageJson.version);
+      expect(config.server.description).toBe("Official MCP server for esa.io");
+    });
+
+    it("should use environment variables when set", async () => {
+      vi.stubEnv("ESA_ACCESS_TOKEN", "test-token");
+      vi.stubEnv("ESA_API_BASE_URL", "https://api.esa.localhost");
+
+      const { config } = await import("../index.js");
+
+      expect(config.esa.apiAccessToken).toBe("test-token");
+      expect(config.esa.apiBaseUrl).toBe("https://api.esa.localhost");
+    });
+  });
+
+  describe("validateConfig", () => {
+    it("should throw error when ESA_ACCESS_TOKEN is not set", async () => {
+      vi.stubEnv("ESA_ACCESS_TOKEN", undefined);
+
+      const { validateConfig } = await import("../index.js");
+
+      expect(() => validateConfig()).toThrow(
+        "ESA_ACCESS_TOKEN environment variable is required",
+      );
+    });
+
+    it("should not throw error when ESA_ACCESS_TOKEN is set", async () => {
+      vi.stubEnv("ESA_ACCESS_TOKEN", "valid-token");
+
+      const { validateConfig } = await import("../index.js");
+
+      expect(() => validateConfig()).not.toThrow();
+    });
+
+    it("should throw error when ESA_ACCESS_TOKEN is empty string", async () => {
+      vi.stubEnv("ESA_ACCESS_TOKEN", "");
+
+      const { validateConfig } = await import("../index.js");
+
+      expect(() => validateConfig()).toThrow(
+        "ESA_ACCESS_TOKEN environment variable is required",
+      );
+    });
+  });
+});

package/src/config/index.ts

@@ -0,0 +1,20 @@
+import packageJson from "../../package.json" with { type: "json" };
+import type { StdioContext } from "../context/stdio-context.js";
+
+export const config = {
+  esa: {
+    apiAccessToken: process.env.ESA_ACCESS_TOKEN || "",
+    apiBaseUrl: process.env.ESA_API_BASE_URL || "https://api.esa.io",
+  } satisfies StdioContext,
+  server: {
+    name: "esa-mcp-server",
+    version: packageJson.version,
+    description: "Official MCP server for esa.io",
+  },
+} as const;
+
+export function validateConfig(): void {
+  if (!config.esa.apiAccessToken) {
+    throw new Error("ESA_ACCESS_TOKEN environment variable is required");
+  }
+}

package/src/context/mcp-context.ts

@@ -0,0 +1 @@
+export type MCPContext = Record<string, unknown>;

package/src/context/stdio-context.ts

@@ -0,0 +1,6 @@
+import type { MCPContext } from "./mcp-context.js";
+
+export interface StdioContext extends MCPContext {
+  apiAccessToken: string;
+  apiBaseUrl: string;
+}

package/src/errors/missing-team-name-error.ts

@@ -0,0 +1,8 @@
+export class MissingTeamNameError extends Error {
+  constructor() {
+    super(
+      "Missing required parameter 'teamName'. Use esa_get_teams to list available teams, then retry with teamName specified.",
+    );
+    this.name = "MissingTeamNameError";
+  }
+}

package/src/formatters/__tests__/mcp-response.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, it } from "vitest";
+import {
+  formatPromptError,
+  formatPromptResponse,
+  formatResourceError,
+  formatResourceResponse,
+  formatToolError,
+  formatToolResponse,
+} from "../mcp-response.js";
+
+describe("response formatters", () => {
+  describe("formatToolResponse", () => {
+    it("should format data as JSON text content", () => {
+      const data = { key: "value", count: 42 };
+      const result = formatToolResponse(data);
+
+      expect(result.content[0].type).toBe("text");
+      expect(result.content[0].text).toBe(JSON.stringify(data, null, 2));
+    });
+  });
+
+  describe("formatResourceResponse", () => {
+    it("should format data as JSON resource with URI and mimeType", () => {
+      const data = { resource: "data" };
+      const uri = "esa://resource/123";
+      const result = formatResourceResponse(data, uri);
+
+      expect(result.contents[0]).toEqual({
+        uri,
+        mimeType: "application/json",
+        text: JSON.stringify(data, null, 2),
+      });
+    });
+  });
+
+  describe("formatPromptResponse", () => {
+    it("should format message as user role content", () => {
+      const message = "This is a prompt message";
+      const result = formatPromptResponse(message);
+
+      expect(result.messages[0]).toEqual({
+        role: "user",
+        content: {
+          type: "text",
+          text: message,
+        },
+      });
+    });
+  });
+});
+
+describe("error formatters", () => {
+  it("should format Error instances consistently", () => {
+    const error = new Error("test error");
+
+    expect(formatToolError(error).content[0].text).toBe("Error: test error");
+    expect(formatResourceError(error, "uri").contents[0].text).toBe(
+      "Error: test error",
+    );
+    expect(formatPromptError(error).messages[0].content.text).toBe(
+      "Error: test error",
+    );
+  });
+
+  it("should format status codes as API responses", () => {
+    const status = 404;
+
+    expect(formatToolError(status).content[0].text).toBe(
+      "Error: API Response(status: 404)",
+    );
+    expect(formatResourceError(status, "uri").contents[0].text).toBe(
+      "Error: API Response(status: 404)",
+    );
+  });
+
+  it("should format object errors as JSON strings", () => {
+    const error = { code: "NOT_FOUND", message: "Resource not found" };
+    const expectedText = `Error: ${JSON.stringify(error, null, 2)}`;
+
+    expect(formatToolError(error).content[0].text).toBe(expectedText);
+    expect(formatResourceError(error, "uri").contents[0].text).toBe(
+      expectedText,
+    );
+    expect(formatPromptError(error).messages[0].content.text).toBe(
+      expectedText,
+    );
+  });
+
+  it("should maintain correct structure for each error formatter", () => {
+    const error = new Error("test");
+    const uri = "test://uri";
+
+    const toolResult = formatToolError(error);
+    expect(toolResult).toHaveProperty("content");
+    expect(Array.isArray(toolResult.content)).toBe(true);
+
+    const resourceResult = formatResourceError(error, uri);
+    expect(resourceResult).toHaveProperty("contents");
+    expect(resourceResult.contents[0].uri).toBe(uri);
+    expect(resourceResult.contents[0].mimeType).toBe("application/json");
+
+    const promptResult = formatPromptError(error);
+    expect(promptResult).toHaveProperty("messages");
+    expect(promptResult.messages[0].role).toBe("user");
+  });
+});