ebay-api-mcp-server-node-local 1.0.1 → 1.0.9

package/src/helper/openapi-helper.ts

@@ -0,0 +1,119 @@
+/**
+ * OpenAPI helper functions, including loading OpenAPI documents,
+ * parsing OpenAPI specs, building schemas, and converting to Zod schemas.
+ */
+import SwaggerParser from "@apidevtools/swagger-parser";
+import { type OpenAPIV3 } from "openapi-types";
+import * as fs from "fs";
+import axios from "axios";
+import * as yaml from "js-yaml";
+import util from "util";
+import { z, type ZodTypeAny } from "zod";
+import { buildHeadersFromInput } from "../helper/http-helper.js";
+
+
+
+const SCHEMA_REQUEST_BODY = "requestBody";
+
+/**
+ * Get OpenAPI docs from user config file, which contains urls or paths of OpenAPI specs.
+ */
+export async function getOpenApiDocumentsFromConfigFile(): Promise<OpenAPIV3.Document[]> {
+  const docs: OpenAPIV3.Document[] = [];
+  const urlFile = process.env.EBAY_API_DOC_URL_FILE;
+  let urls: string[] = [];
+  if (urlFile && fs.existsSync(urlFile)) {
+    // url or path each line in the file
+    urls = fs.readFileSync(urlFile, "utf-8").split(/\r?\n/)
+      .map(line => line.trim())
+      .filter(line => line.length > 0 && !line.startsWith("#"));
+  }
+  console.error("Loading OpenAPI specifications from:", urls);
+  // parse opebapi doc from url/path
+  for (const specPath of urls) {
+    try {
+      const doc = await SwaggerParser.dereference(specPath) as OpenAPIV3.Document;
+      docs.push(doc);
+    } catch (e) {
+      console.error(`getOpenApiDocumentsFromConfigFile#[Failed to load OpenAPI doc from the specPath : ${specPath}]`);
+    }
+  }
+  return docs;
+}
+
+// Helper: remove ignored keys recursively
+export function readSchema2Map(obj: unknown): unknown {
+  const SCHEMA_IGNORE_KEYS = ["style", "explode", "exampleSetFlag", "types", "in", "required"];
+  if (Array.isArray(obj)) {
+    return obj.map(readSchema2Map);
+  } else if (obj && typeof obj === "object") {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(obj as Record<string, unknown>)) {
+      if (!SCHEMA_IGNORE_KEYS.includes(k)) {
+        out[k] = readSchema2Map(v);
+      }
+    }
+    return out;
+  }
+  return obj;
+}
+
+/**
+ * Query api spec and parse to OpenAPI document (supports both JSON and YAML)
+ */
+export async function queryAndParseOpenApiDoc(specTitle: string, operationId : string, specUrl: string): Promise<OpenAPIV3.Document> {
+  const url = util.format(specUrl, specTitle, operationId);
+  const apiSpecRes = await axios.get<string>(url,  {
+    headers: buildHeadersFromInput(undefined, false),
+    httpsAgent: new (await import("https")).Agent({
+      rejectUnauthorized: false,
+    })});
+  const docString = apiSpecRes.data;
+  try {
+    // Try parsing as JSON first
+    return JSON.parse(docString) as OpenAPIV3.Document;
+  } catch (jsonError) {
+    try {
+      // If JSON fails, try parsing as YAML
+      return yaml.load(docString) as OpenAPIV3.Document;
+    } catch (yamlError) {
+      const _jsonMsg = jsonError instanceof Error ? jsonError.message : String(jsonError);
+      const _yamlMsg = yamlError instanceof Error ? yamlError.message : String(yamlError);
+      console.error("failed to parse OpenAPI document !!!");
+      return {} as OpenAPIV3.Document;
+    }
+  }
+}
+
+/**
+ * Build schema for an operation's input parameters
+ */
+export function buildOperationSchema(operation: OpenAPIV3.OperationObject): { properties: Record<string, unknown> } {
+  const properties: Record<string, unknown> = {};
+  // handle request param
+  (operation.parameters || []).forEach(param => {
+    if ("$ref" in param) {return;}
+    const paramSchema = readSchema2Map(param);
+    properties[param.name] = paramSchema;
+  });
+  // handle request body
+  if (operation.requestBody && "content" in operation.requestBody &&
+      operation.requestBody.content?.["application/json"]?.schema) {
+    const requestBodySchema = readSchema2Map(operation.requestBody.content["application/json"].schema);
+    properties[SCHEMA_REQUEST_BODY] = requestBodySchema;
+  }
+  return { properties };
+}
+
+/**
+ * Build Zod validation schema
+ */
+export function buildZodSchema(properties: Record<string, unknown>): Record<string, ZodTypeAny> {
+  const zodProperties: Record<string, ZodTypeAny> = {};
+
+  Object.keys(properties).forEach(key => {
+    zodProperties[key] = z.any();
+  });
+
+  return zodProperties;
+}

package/src/helper/validation-helper.ts

@@ -0,0 +1,296 @@
+/**
+ * Validation helper functions for OpenAPI validation
+ */
+import { type OpenAPIV3 } from "openapi-types";
+import AjvLib from "ajv";
+import { SUPPORTED_CALLING_METHODS, USER_ENVIRONMENT } from "../constant/constants.js";
+const Ajv = AjvLib.default || AjvLib;
+
+/**
+ * Validate request parameters against OpenAPI specification
+ */
+export function validateRequestParameters(
+  url: string,
+  openApiDoc: OpenAPIV3.Document,
+  method: string,
+  input: {
+    urlVariables?: Record<string, unknown>;
+    urlQueryParams?: Record<string, unknown>;
+    headers?: Record<string, string>;
+    requestBody?: Record<string, unknown>;
+  },
+): { isValid: boolean; errors: string[] } {
+  const errors: string[] = [];
+
+  // validate method
+  if (!SUPPORTED_CALLING_METHODS[USER_ENVIRONMENT].includes(method.toLowerCase())) {
+    errors.push(`Method ${method} is not supported in ${USER_ENVIRONMENT} environment`);
+    return { isValid: false, errors };
+  }
+
+  // validate path
+  const {pathValidateRes, apiPath, specPath, specPathItem} = validatePath(openApiDoc, url);
+  if (!pathValidateRes || !specPathItem) {
+    errors.push(`API path ${apiPath} is not valid or not found in OpenAPI specification`);
+    return { isValid: false, errors };
+  }
+
+  // Check if the method exists for the path
+  const operation = specPathItem[method.toLowerCase() as keyof typeof specPathItem] as OpenAPIV3.OperationObject;
+  if (!operation) {
+    errors.push(`Method ${method} not found for path ${specPath} in OpenAPI specification`);
+    return { isValid: false, errors };
+  }
+
+  // Initialize AJV for schema validation
+  const _ajv = new Ajv({ allErrors: true });
+
+  validateUrlPathParam(input.urlVariables, operation.parameters, errors);
+
+  validateUrlQueryParam(input.urlQueryParams, operation.parameters, errors);
+
+  validateUrlHeaders(input.headers, operation.parameters, errors);
+
+  validateUrlRequestBody(input.requestBody, operation.requestBody, errors);
+
+  return { isValid: errors.length === 0, errors };
+}
+
+/**
+ *  Validate the API path against the OpenAPI document
+ */
+export function validatePath(openApiDoc: OpenAPIV3.Document, inputUrl: string): {
+  pathValidateRes : boolean,
+  apiPath : string,
+  specPath : string,
+  specPathItem?: OpenAPIV3.PathItemObject
+} {
+  // Extract the path from the URL (remove base URL part)
+  const apiPath : string = parseApiPathFromUrl(inputUrl);
+  if (!apiPath) {
+    console.error(`input url ${inputUrl} is not valid, please check it.`);
+    return {pathValidateRes : false, apiPath:"", specPath: "", specPathItem: undefined};
+  }
+  // bathPath validation
+  const serverObj = openApiDoc.servers?.[0] || { url: "" };
+  let basePath : string = "";
+  if (serverObj?.variables) {
+    for (const [key, value] of Object.entries(serverObj.variables)) {
+      if (key === "basePath") {
+        basePath = value.default;
+      }
+    }
+  }
+  const basePathRegex = new RegExp(`${basePath.replace(/\{[^}]+\}/g, "[^/]+")  }$`);
+  if (basePath && !basePathRegex.test(apiPath)) {
+    console.error(`API path ${apiPath} does not match the base path ${basePath} in OpenAPI specification.`);
+    return {pathValidateRes : false, apiPath, specPath: "", specPathItem: undefined};
+  }
+
+  // specPath validation
+  for (const specPath of Object.keys(openApiDoc.paths || {})) {
+    const specPathRegex = new RegExp(`${specPath.replace(/\{[^}]+\}/g, "[^/]+")  }$`);
+    if (specPathRegex.test(apiPath) && openApiDoc.paths?.[specPath]) {
+      const specPathItem = openApiDoc.paths[specPath];
+      return { pathValidateRes: true, apiPath, specPath, specPathItem};
+    }
+  }
+
+  return {pathValidateRes : false, apiPath, specPath: "", specPathItem: undefined};
+}
+
+/**
+ *  parse path from the given url by llm
+ */
+export function parseApiPathFromUrl(inputUrl: string): string {
+  try {
+    const urlObj = new URL(inputUrl);
+    return decodeURIComponent(urlObj.pathname); // Decode URL path
+  } catch (urlError) {
+    // If URL parsing fails, try to extract path manually
+    const pathMatch = inputUrl.match(/https?:\/\/[^/]+(.*)$/);
+    if (pathMatch) {
+      return pathMatch[1];
+    }
+    console.error(`Failed to parse API path from URL: ${inputUrl}`);
+    return  "";
+  }
+}
+
+/**
+ *  Validate URL path parameters against OpenAPI specification
+ */
+export function validateUrlPathParam(
+  urlVariables: Record<string, unknown> | undefined,
+  parameters: (OpenAPIV3.ReferenceObject | OpenAPIV3.ParameterObject)[] | undefined,
+  errors: string[],
+): void {
+  // Initialize AJV for schema validation
+  const ajv = new Ajv({ allErrors: true });
+  if (urlVariables) {
+    const pathParams = (parameters || []).filter(
+      (param): param is OpenAPIV3.ParameterObject =>
+        !("$ref" in param) && param.in === "path",
+    );
+
+    for (const param of pathParams) {
+      const value = urlVariables[param.name];
+
+      if (param.required && (value === undefined || value === null)) {
+        errors.push(`Missing required path parameter: ${param.name}`);
+        continue;
+      }
+
+      if (value !== undefined && param.schema) {
+        const validate = ajv.compile(param.schema);
+        if (!validate(value)) {
+          errors.push(`Invalid path parameter ${param.name}: ${ajv.errorsText(validate.errors)}`);
+        }
+      }
+    }
+
+    // Check for extra path parameters not defined in spec
+    const definedPathParams = pathParams.map(p => p.name);
+    const extraParams = Object.keys(urlVariables).filter(key => !definedPathParams.includes(key));
+    if (extraParams.length > 0) {
+      errors.push(`Unknown path parameters: ${extraParams.join(", ")}`);
+    }
+
+    // Check for required path parameters that might be missing from urlVariables
+    const requiredPathParams = (parameters || [])
+      .filter((param): param is OpenAPIV3.ParameterObject =>
+        !("$ref" in param) && param.in === "path" && (param.required === true),
+      )
+      .map(param => param.name);
+    const providedPathParams = Object.keys(urlVariables || {});
+    const missingPathParams = requiredPathParams.filter(param => !providedPathParams.includes(param));
+    if (missingPathParams.length > 0) {
+      errors.push(`Missing required path parameters: ${missingPathParams.join(", ")}`);
+    }
+  }
+}
+
+/**
+ * Validate URL query parameters against OpenAPI specification
+ */
+export function validateUrlQueryParam(
+  urlQueryParams: Record<string, unknown> | undefined,
+  parameters: (OpenAPIV3.ReferenceObject | OpenAPIV3.ParameterObject)[] | undefined,
+  errors: string[],
+): void {
+  const ajv = new Ajv({ allErrors: true });
+  if (urlQueryParams) {
+    const queryParams = (parameters || []).filter(
+      (param): param is OpenAPIV3.ParameterObject =>
+        !("$ref" in param) && param.in === "query",
+    );
+
+    for (const param of queryParams) {
+      const value = urlQueryParams[param.name];
+
+      if (param.required && (value === undefined || value === null || value === "")) {
+        errors.push(`Missing required query parameter: ${param.name}`);
+        continue;
+      }
+
+      if (value !== undefined && param.schema) {
+        const validate = ajv.compile(param.schema);
+        // Convert string values to appropriate types for validation
+        let validationValue = value;
+        if (typeof value === "string" && param.schema && !("$ref" in param.schema) && (param.schema).type) {
+          const schemaObj = param.schema;
+          switch (schemaObj.type) {
+            case "integer":
+            case "number":
+              validationValue = Number(value);
+              break;
+            case "boolean":
+              validationValue = value.toLowerCase() === "true";
+              break;
+            case "array":
+              // Handle comma-separated values for arrays
+              if (param.style === "form" && !param.explode) {
+                validationValue = value.split(",");
+              }
+              break;
+          }
+        }
+
+        if (!validate(validationValue)) {
+          errors.push(`Invalid query parameter ${param.name}: ${ajv.errorsText(validate.errors)}`);
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Validate URL headers against OpenAPI specification
+ */
+export function validateUrlHeaders(
+  headers: Record<string, string> | undefined,
+  parameters: (OpenAPIV3.ReferenceObject | OpenAPIV3.ParameterObject)[] | undefined,
+  errors: string[],
+): void {
+  const ajv = new Ajv({ allErrors: true });
+  if (headers) {
+    const headerParams = (parameters || []).filter(
+      (param): param is OpenAPIV3.ParameterObject =>
+        !("$ref" in param) && param.in === "header",
+    );
+
+    for (const param of headerParams) {
+      const headerName = param.name.toLowerCase();
+      const value = headers[headerName] || headers[param.name];
+
+      if (param.required && (value === undefined || value === null || value === "")) {
+        errors.push(`Missing required header parameter: ${param.name}`);
+        continue;
+      }
+
+      if (value !== undefined && param.schema) {
+        const validate = ajv.compile(param.schema);
+        if (!validate(value)) {
+          errors.push(`Invalid header parameter ${param.name}: ${ajv.errorsText(validate.errors)}`);
+        }
+      }
+    }
+  }
+}
+
+/**
+ *  Validate URL request body against OpenAPI specification
+ */
+export function validateUrlRequestBody(
+  inputBody: Record<string, unknown> | undefined,
+  operationBody: OpenAPIV3.ReferenceObject | OpenAPIV3.RequestBodyObject | undefined,
+  errors: string[],
+): void {
+  const ajv = new Ajv({ allErrors: true, strict: false });
+  if (operationBody && !("$ref" in operationBody)) {
+    const requestBody = operationBody;
+    const isRequired = requestBody.required || false;
+
+    if (isRequired && (!inputBody || Object.keys(inputBody).length === 0)) {
+      errors.push("Missing required request body");
+    } else if (inputBody && Object.keys(inputBody).length > 0) {
+      // Find the appropriate content type schema
+      const contentTypes = ["application/json", "application/x-www-form-urlencoded", "multipart/form-data"];
+      let schema: OpenAPIV3.SchemaObject | undefined;
+
+      for (const contentType of contentTypes) {
+        if (requestBody.content?.[contentType]?.schema) {
+          schema = requestBody.content[contentType].schema as OpenAPIV3.SchemaObject;
+          break;
+        }
+      }
+
+      if (schema) {
+        const validate = ajv.compile(schema);
+        if (!validate(inputBody)) {
+          errors.push(`Invalid request body: ${ajv.errorsText(validate.errors)}`);
+        }
+      }
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+// Load environment variables from .env file
+import * as dotenv from "dotenv";
+dotenv.config();
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerOpenApiTools } from "./service/openapi-service.js";
+import * as constants from "./constant/constants.js";
+
+/**
+ * Check if required environment variables are set for eBay API authentication
+ */
+function checkEnvironmentVariables(): void {
+
+  // environment vals check
+  const missingVars = constants.REQUIRED_ENV_VARS.filter(varName => !process.env[varName]);
+
+  if (missingVars.length > 0) {
+    console.error(`Missing required environment variables: ${missingVars.join(", ")}`);
+    process.exit(1);
+  }
+}
+
+/**
+ * Main function to initialize and run the eBay API MCP Server
+ * This server exposes eBay API endpoints as MCP tools for access via AI models
+ */
+async function main(): Promise<void> {
+  console.error("Starting eBay API MCP Server...");
+  // Check for required environment variables
+  checkEnvironmentVariables();
+  const server = initServer();
+
+  try {
+    // Register the OpenAPI tools with the server
+    await registerOpenApiTools(server);
+    console.error("Successfully registered OpenAPI tools");
+
+    // Create and connect server transport
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("eBay API MCP Server running on stdio transport");
+
+  } catch (error) {
+    console.error("Error starting MCP server:", error instanceof Error ? error.message : String(error));
+    console.error("Stack trace:", error instanceof Error ? error.stack : "No stack trace available");
+    process.exit(1);
+  }
+}
+
+// Run the server
+main().catch((error) => {
+  console.error("Fatal error:", error instanceof Error ? error.message : String(error));
+  console.error("Stack trace:", error instanceof Error ? error.stack : "No stack trace available");
+  process.exit(1);
+});
+
+
+// Create MCP server instance
+function initServer(): McpServer {
+  return new McpServer({
+    name: "ebay-api-mcp-server",
+    version: "1.0.0",
+    capabilities: {
+      resources: {},
+      tools: {},
+    },
+  });
+}

package/src/integration.test.ts

@@ -0,0 +1,140 @@
+import {afterAll, beforeAll, describe, expect, it} from "vitest";
+import {Client} from "@modelcontextprotocol/sdk/client/index.js";
+import {StdioClientTransport} from "@modelcontextprotocol/sdk/client/stdio.js";
+import * as path from "path";
+import * as fs from "fs";
+
+// Define interfaces for type safety
+interface ContentPart {
+  type: string;
+  text: string;
+}
+
+interface CallToolResponse {
+  content: ContentPart[];
+  isError?: boolean;
+}
+
+describe("MCP Server Integration Tests", () => {
+  let client: Client;
+  let transport: StdioClientTransport;
+
+  // Only setup the test environment if we're not skipping tests
+  beforeAll(async () => {
+    try {
+      console.log("Setting up test client...");
+
+      // Use the correct path to your server script
+      // Make sure we're using node with the compiled JS file instead of ts-node
+      const serverScriptPath = path.join(process.cwd(), "src", "index.ts");
+
+      // Check if the file exists
+      if (!fs.existsSync(serverScriptPath)) {
+        throw new Error(`Server script not found at: ${serverScriptPath}`);
+      }
+
+      console.log(`Server script found at: ${serverScriptPath}`);
+
+      // Create the transport with the correct path to the server
+      transport = new StdioClientTransport({
+        command: "node",
+        args: [
+          "--loader", "ts-node/esm",
+          "--experimental-specifier-resolution=node",
+          serverScriptPath,
+        ],
+      });
+
+      // Initialize the client
+      client = new Client({
+        name: "test-client",
+        version: "1.0.0",
+      });
+
+      console.log("Connecting to MCP server...");
+
+      // Add a timeout to the connection attempt
+      const connectionPromise = client.connect(transport);
+      const timeoutPromise = new Promise((_, reject) => {
+        setTimeout(() => reject(new Error("Connection timed out after 15 seconds")), 15000);
+      });
+
+      await Promise.race([connectionPromise, timeoutPromise]);
+      console.log("✅ Client connected successfully");
+
+    } catch (error) {
+      console.error("❌ Error during test setup:", error);
+      // Explicitly failing the test setup
+      throw error;
+    }
+  });
+
+  afterAll(async () => {
+    try {
+      if (client) {
+        console.log("Closing client connection...");
+        await client.close();
+        console.log("✅ Client closed successfully");
+      }
+    } catch (error) {
+      console.error("❌ Error during test cleanup:", error);
+    }
+  });
+
+
+  it("test list tools", async () => {
+    const result = await client.listTools();
+    console.log("Available tools:", result.tools.map(tool => tool.name));
+    expect(result.tools.length).toBeGreaterThan(1);
+  });
+
+  it("test query api", async () => {
+    const response = await client.callTool({
+      name: "queryAPI",
+      arguments: {
+        prompt : "i wanna order api",
+      },
+    }) as CallToolResponse;
+
+    expect(response).toBeDefined();
+    expect(response.content).toBeDefined();
+    expect(response.content.length).toBeGreaterThan(0);
+  });
+
+  it("test invoke api", async () => {
+    const response = await client.callTool({
+      name: "invokeAPI",
+      arguments: {
+        url: "https://api.sandbox.ebay.com/commerce/notification/v1/topic/MARKETPLACE_ACCOUNT_DELETION",
+        method: "GET",
+        headers: {},
+        urlVariables: {},
+        requestBody: {},
+        token : process.env.EBAY_CLIENT_TOKEN
+      },
+    }) as CallToolResponse;
+
+    expect(response).toBeDefined();
+    expect(response.content).toBeDefined();
+    expect(response.content.length).toBeGreaterThan(0);
+  });
+
+  it("test invoke api with pathVals", async () => {
+    const response = await client.callTool({
+      name: "invokeAPI",
+      arguments: {
+        url: "https://api.sandbox.ebay.com/commerce/notification/v1/subscription/{subscription_id}/test",
+        method: "POST",
+        headers: {},
+        urlVariables: {"subscription_id":"1000"},
+        requestBody: {},
+        token: process.env.EBAY_CLIENT_TOKEN
+      },
+    }) as CallToolResponse;
+
+    expect(response).toBeDefined();
+    expect(response.content).toBeDefined();
+    expect(response.content.length).toBeGreaterThan(0);
+  });
+
+});