magicpod-mcp-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Magic-Pod
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,46 @@
+# magicpod-mcp-server
+
+An MCP (Model Context Protocol) server that integrates your AI agents with MagicPod
+
+## Getting Started
+
+[Cursor](https://cursor.com), [Claude](https://claude.ai/), and many other AI-powered coding tools support MCP servers. You can refer to their official documents on how to configure MCP servers. For example, if you use Claude Desktop, what you have to do to integrate with MagicPod is only to add the following lines in your `claude_desktop_config.json`. 
+
+### MacOS / Linux
+
+```json
+{
+  "mcpServers": {
+    "magicpod-mcp-server": {
+      "command": "npx",
+      "args": ["-y", "magicpod-mcp-server", "--api-token=YOUR-API-TOKEN"]
+    }
+  }
+}
+```
+
+### Windows
+
+```json
+{
+  "mcpServers": {
+    "magicpod-mcp-server": {
+      "command": "cmd",
+      "args": ["/c", "npx", "-y", "magicpod-mcp-server", "--api-token=YOUR-API-TOKEN"]
+    }
+  }
+}
+```
+
+Make sure that you replace `YOUR-API-TOKEN` with your actual MagicPod API token. You can retrieve it on the [integrations](https://app.magicpod.com/accounts/api-token/) screen.
+
+<img width="1015" alt="retrieve API token" src="https://github.com/user-attachments/assets/77931857-284d-4d7f-968b-c6a000f518c1" />
+
+
+## Development
+
+Build
+
+```
+npm run build
+```

package/build/index.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { Command } from "commander";
+import { searchMagicpodArticles } from "./tools/search-magicpod-articles.js";
+import { readMagicpodArticle } from "./tools/read-magicpod-article.js";
+import { initMagicPodApiProxy } from "./tools/magicpod-web-api.js";
+const program = new Command();
+program.option("--api-token <key>", "MagicPod API token to use");
+program.parse(process.argv);
+const options = program.opts();
+if (!options.apiToken) {
+    console.error("--api-token must be provided");
+    process.exit(1);
+}
+async function main() {
+    const baseUrl = process.env.BASE_URL || "https://app.magicpod.com";
+    const proxy = await initMagicPodApiProxy(baseUrl, options.apiToken, [
+        searchMagicpodArticles(),
+        readMagicpodArticle(),
+    ]);
+    await proxy.connect(new StdioServerTransport());
+    console.error("MagicPod MCP Server running on stdio");
+}
+main().catch((error) => {
+    console.error("Fatal error in main():", error);
+    process.exit(1);
+});

package/build/openapi-mcp-server/auth/index.js

@@ -0,0 +1,2 @@
+export * from "./types.js";
+export * from "./template.js";

package/build/openapi-mcp-server/auth/template.js

@@ -0,0 +1,18 @@
+import Mustache from "mustache";
+export function renderAuthTemplate(template, context) {
+    // Disable HTML escaping for URLs
+    Mustache.escape = (text) => text;
+    // Render URL with template variables
+    const renderedUrl = Mustache.render(template.url, context);
+    // Create a new template object with rendered values
+    const renderedTemplate = {
+        ...template,
+        url: renderedUrl,
+        headers: { ...template.headers }, // Create a new headers object to avoid modifying the original
+    };
+    // Render body if it exists
+    if (template.body) {
+        renderedTemplate.body = Mustache.render(template.body, context);
+    }
+    return renderedTemplate;
+}

package/build/openapi-mcp-server/auth/types.js

@@ -0,0 +1 @@
+export {};

package/build/openapi-mcp-server/client/http-client.js

@@ -0,0 +1,177 @@
+import OpenAPIClientAxios from "openapi-client-axios";
+import FormData from "form-data";
+import fs from "fs";
+import { isFileUploadParameter } from "../openapi/file-upload.js";
+export class HttpClientError extends Error {
+    status;
+    data;
+    headers;
+    constructor(message, status, data, headers) {
+        super(`${status} ${message}`);
+        this.status = status;
+        this.data = data;
+        this.headers = headers;
+        this.name = "HttpClientError";
+    }
+}
+export class HttpClient {
+    api;
+    // @ts-ignore
+    client;
+    constructor(config, openApiSpec) {
+        this.client = new (OpenAPIClientAxios.default ?? OpenAPIClientAxios)({
+            definition: openApiSpec,
+            axiosConfigDefaults: {
+                baseURL: config.baseUrl,
+                headers: {
+                    "Content-Type": "application/json",
+                    "User-Agent": "magicpod-mcp-server",
+                    ...config.headers,
+                },
+            },
+        });
+        this.api = this.client.init();
+    }
+    async prepareFileUpload(operation, params) {
+        console.error("prepareFileUpload", { operation, params });
+        const fileParams = isFileUploadParameter(operation);
+        if (fileParams.length === 0)
+            return null;
+        const formData = new FormData();
+        // Handle file uploads
+        for (const param of fileParams) {
+            console.error(`extracting ${param}`, { params });
+            const filePath = params[param];
+            if (!filePath) {
+                throw new Error(`File path must be provided for parameter: ${param}`);
+            }
+            switch (typeof filePath) {
+                case "string":
+                    addFile(param, filePath);
+                    break;
+                case "object":
+                    if (Array.isArray(filePath)) {
+                        let fileCount = 0;
+                        for (const file of filePath) {
+                            addFile(param, file);
+                            fileCount++;
+                        }
+                        break;
+                    }
+                //deliberate fallthrough
+                default:
+                    throw new Error(`Unsupported file type: ${typeof filePath}`);
+            }
+            function addFile(name, filePath) {
+                try {
+                    const fileStream = fs.createReadStream(filePath);
+                    formData.append(name, fileStream);
+                }
+                catch (error) {
+                    throw new Error(`Failed to read file at ${filePath}: ${error}`);
+                }
+            }
+        }
+        // Add non-file parameters to form data
+        for (const [key, value] of Object.entries(params)) {
+            if (!fileParams.includes(key)) {
+                formData.append(key, value);
+            }
+        }
+        return formData;
+    }
+    /**
+     * Execute an OpenAPI operation
+     */
+    async executeOperation(operation, params = {}) {
+        const api = await this.api;
+        const operationId = operation.operationId;
+        if (!operationId) {
+            throw new Error("Operation ID is required");
+        }
+        // Handle file uploads if present
+        const formData = await this.prepareFileUpload(operation, params);
+        // Separate parameters based on their location
+        const urlParameters = {};
+        let bodyParams = formData || { ...params };
+        // Extract path and query parameters based on operation definition
+        if (operation.parameters) {
+            for (const param of operation.parameters) {
+                if ("name" in param && param.name && param.in) {
+                    if (param.in === "path" || param.in === "query") {
+                        if (params[param.name] !== undefined) {
+                            urlParameters[param.name] = params[param.name];
+                            if (!formData) {
+                                delete bodyParams[param.name];
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        // Add all parameters as url parameters if there is no requestBody defined
+        if (!operation.requestBody && !formData) {
+            for (const key in bodyParams) {
+                if (bodyParams[key] !== undefined) {
+                    urlParameters[key] = bodyParams[key];
+                    delete bodyParams[key];
+                }
+            }
+        }
+        const operationFn = api[operationId];
+        if (!operationFn) {
+            throw new Error(`Operation ${operationId} not found`);
+        }
+        try {
+            // If we have form data, we need to set the correct headers
+            const hasBody = Object.keys(bodyParams).length > 0;
+            const headers = formData
+                ? formData.getHeaders()
+                : {
+                    ...(hasBody
+                        ? { "Content-Type": "application/json" }
+                        : { "Content-Type": null }),
+                };
+            const requestConfig = {
+                headers: {
+                    ...headers,
+                },
+            };
+            // first argument is url parameters, second is body parameters
+            console.error("calling operation", {
+                operationId,
+                urlParameters,
+                bodyParams,
+                requestConfig,
+            });
+            // `body` attribute is somehow included in an actual request
+            if ("body" in bodyParams) {
+                bodyParams = bodyParams.body;
+            }
+            const response = await operationFn(urlParameters, hasBody ? bodyParams : undefined, requestConfig);
+            // Convert axios headers to Headers object
+            const responseHeaders = new Headers();
+            Object.entries(response.headers).forEach(([key, value]) => {
+                if (value)
+                    responseHeaders.append(key, value.toString());
+            });
+            return {
+                data: response.data,
+                status: response.status,
+                headers: responseHeaders,
+            };
+        }
+        catch (error) {
+            if (error.response) {
+                console.error("Error in http client", error);
+                const headers = new Headers();
+                Object.entries(error.response.headers).forEach(([key, value]) => {
+                    if (value)
+                        headers.append(key, value.toString());
+                });
+                throw new HttpClientError(error.response.statusText || "Request failed", error.response.status, error.response.data, headers);
+            }
+            throw error;
+        }
+    }
+}

package/build/openapi-mcp-server/index.js

@@ -0,0 +1,2 @@
+export { OpenAPIToMCPConverter } from "./openapi/parser.js";
+export { HttpClient } from "./client/http-client.js";

package/build/openapi-mcp-server/mcp/proxy.js

@@ -0,0 +1,217 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { OpenAPIToMCPConverter } from "../openapi/parser.js";
+import { HttpClient, HttpClientError } from "../client/http-client.js";
+import { zodToJsonSchema } from "openai/_vendor/zod-to-json-schema/index";
+// import this class, extend and return server
+export class MCPProxy {
+    otherTools;
+    server;
+    httpClient;
+    tools;
+    openApiLookup;
+    constructor(name, openApiSpec, apiToken, otherTools) {
+        this.otherTools = otherTools;
+        this.server = new Server({ name, version: "0.1.0" }, { capabilities: { tools: {} } });
+        const baseUrl = openApiSpec.servers?.[0].url;
+        if (!baseUrl) {
+            throw new Error("No base URL found in OpenAPI spec");
+        }
+        this.httpClient = new HttpClient({
+            baseUrl,
+            headers: {
+                ...this.parseHeadersFromEnv(),
+                Authorization: `Token ${apiToken}`,
+            },
+        }, openApiSpec);
+        // Convert OpenAPI spec to MCP tools
+        const converter = new OpenAPIToMCPConverter(openApiSpec);
+        const { tools, openApiLookup } = converter.convertToMCPTools();
+        this.tools = tools;
+        this.openApiLookup = openApiLookup;
+        this.setupHandlers();
+    }
+    removeDescriptions(obj) {
+        if (Array.isArray(obj)) {
+            obj.forEach(this.removeDescriptions);
+        }
+        else if (obj && typeof obj === "object") {
+            for (const key in obj) {
+                if (key === "description") {
+                    // @ts-ignore
+                    delete obj[key];
+                }
+                else {
+                    // @ts-ignore
+                    this.removeDescriptions(obj[key]);
+                }
+            }
+        }
+    }
+    collectRefs(obj) {
+        const refs = [];
+        if (Array.isArray(obj)) {
+            for (const childRefs of obj.map(this.collectRefs)) {
+                for (const childRef of childRefs) {
+                    refs.push(childRef);
+                }
+            }
+        }
+        else if (obj && typeof obj === "object") {
+            for (const key in obj) {
+                if (key === "$ref") {
+                    // @ts-ignore
+                    const ref = obj[key];
+                    refs.push(ref.replaceAll("#/$defs/", ""));
+                }
+                else {
+                    // @ts-ignore
+                    this.collectRefs(obj[key]).forEach(refs.push);
+                }
+            }
+        }
+        return refs;
+    }
+    setupHandlers() {
+        // Handle tool listing
+        this.server.setRequestHandler(ListToolsRequestSchema, async () => {
+            const tools = [];
+            // Add methods as separate tools to match the MCP format
+            Object.entries(this.tools).forEach(([toolName, def]) => {
+                def.methods.forEach((method) => {
+                    const toolNameWithMethod = `${toolName}-${method.name}`;
+                    const truncatedToolName = this.truncateToolName(toolNameWithMethod);
+                    // to reduce the tool list response size
+                    // TODO description is actually required
+                    const inputSchema = JSON.parse(JSON.stringify(method.inputSchema));
+                    this.removeDescriptions(inputSchema);
+                    // 95% of the response size is consumed by $defs
+                    const body = method.inputSchema.properties?.body;
+                    if (body == null || typeof body === "boolean") {
+                        delete inputSchema["$defs"];
+                    }
+                    else {
+                        const refs = this.collectRefs(body);
+                        if (refs.length === 0) {
+                            delete inputSchema["$defs"];
+                        }
+                        else if (inputSchema["$defs"]) {
+                            for (const def of Object.keys(inputSchema["$defs"])) {
+                                if (!refs.includes(def)) {
+                                    delete inputSchema["$defs"][def];
+                                }
+                            }
+                        }
+                    }
+                    tools.push({
+                        name: truncatedToolName,
+                        description: method.description,
+                        inputSchema: inputSchema,
+                    });
+                });
+            });
+            for (const tool of this.otherTools) {
+                tools.push({
+                    name: tool.name,
+                    description: tool.description,
+                    inputSchema: zodToJsonSchema(tool.inputSchema, "input").definitions
+                        ?.input,
+                });
+            }
+            return { tools };
+        });
+        // Handle tool calling
+        this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+            console.error("calling tool", request.params);
+            const { name, arguments: params } = request.params;
+            const tool = this.otherTools.find((t) => t.name === name);
+            if (tool) {
+                return tool.handleRequest(params);
+            }
+            // Find the operation in OpenAPI spec
+            const operation = this.findOperation(name);
+            console.error("operations", this.openApiLookup);
+            if (!operation) {
+                throw new Error(`Method ${name} not found`);
+            }
+            try {
+                // Execute the operation
+                const response = await this.httpClient.executeOperation(operation, params);
+                // Convert response to MCP format
+                return {
+                    content: [
+                        {
+                            type: "text", // currently this is the only type that seems to be used by mcp server
+                            text: JSON.stringify(response.data), // TODO: pass through the http status code text?
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                console.error("Error in tool call", error);
+                if (error instanceof HttpClientError) {
+                    console.error("HttpClientError encountered, returning structured error", error);
+                    const data = error.data?.response?.data ?? error.data ?? {};
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({
+                                    status: "error", // TODO: get this from http status code?
+                                    ...(typeof data === "object" ? data : { data: data }),
+                                }),
+                            },
+                        ],
+                    };
+                }
+                throw error;
+            }
+        });
+    }
+    findOperation(operationId) {
+        return this.openApiLookup[operationId] ?? null;
+    }
+    parseHeadersFromEnv() {
+        const headersJson = process.env.OPENAPI_MCP_HEADERS;
+        if (!headersJson) {
+            return {};
+        }
+        try {
+            const headers = JSON.parse(headersJson);
+            if (typeof headers !== "object" || headers === null) {
+                console.warn("OPENAPI_MCP_HEADERS environment variable must be a JSON object, got:", typeof headers);
+                return {};
+            }
+            return headers;
+        }
+        catch (error) {
+            console.warn("Failed to parse OPENAPI_MCP_HEADERS environment variable:", error);
+            return {};
+        }
+    }
+    getContentType(headers) {
+        const contentType = headers.get("content-type");
+        if (!contentType)
+            return "binary";
+        if (contentType.includes("text") || contentType.includes("json")) {
+            return "text";
+        }
+        else if (contentType.includes("image")) {
+            return "image";
+        }
+        return "binary";
+    }
+    truncateToolName(name) {
+        if (name.length <= 64) {
+            return name;
+        }
+        return name.slice(0, 64);
+    }
+    async connect(transport) {
+        // The SDK will handle stdio communication
+        await this.server.connect(transport);
+    }
+    getServer() {
+        return this.server;
+    }
+}

package/build/openapi-mcp-server/openapi/file-upload.js

@@ -0,0 +1,34 @@
+/**
+ * Identifies file upload parameters in an OpenAPI operation
+ * @param operation The OpenAPI operation object to check
+ * @returns Array of parameter names that are file uploads
+ */
+export function isFileUploadParameter(operation) {
+    const fileParams = [];
+    if (!operation.requestBody)
+        return fileParams;
+    const requestBody = operation.requestBody;
+    const content = requestBody.content || {};
+    // Check multipart/form-data content type for file uploads
+    const multipartContent = content["multipart/form-data"];
+    if (!multipartContent?.schema)
+        return fileParams;
+    const schema = multipartContent.schema;
+    if (schema.type !== "object" || !schema.properties)
+        return fileParams;
+    // Look for properties with type: string, format: binary which indicates file uploads
+    Object.entries(schema.properties).forEach(([propName, prop]) => {
+        const schemaProp = prop;
+        if (schemaProp.type === "string" && schemaProp.format === "binary") {
+            fileParams.push(propName);
+        }
+        // Check for array of files
+        if (schemaProp.type === "array" && schemaProp.items) {
+            const itemSchema = schemaProp.items;
+            if (itemSchema.type === "string" && itemSchema.format === "binary") {
+                fileParams.push(propName);
+            }
+        }
+    });
+    return fileParams;
+}

package/build/openapi-mcp-server/openapi/parser.js

@@ -0,0 +1,470 @@
+export class OpenAPIToMCPConverter {
+    openApiSpec;
+    schemaCache = {};
+    nameCounter = 0;
+    constructor(openApiSpec) {
+        this.openApiSpec = openApiSpec;
+    }
+    /**
+     * Resolve a $ref reference to its schema in the openApiSpec.
+     * Returns the raw OpenAPI SchemaObject or null if not found.
+     */
+    internalResolveRef(ref, resolvedRefs) {
+        if (!ref.startsWith("#/")) {
+            return null;
+        }
+        if (resolvedRefs.has(ref)) {
+            return null;
+        }
+        const parts = ref.replace(/^#\//, "").split("/");
+        let current = this.openApiSpec;
+        for (const part of parts) {
+            current = current[part];
+            if (!current)
+                return null;
+        }
+        resolvedRefs.add(ref);
+        return current;
+    }
+    /**
+     * Convert an OpenAPI schema (or reference) into a JSON Schema object.
+     * Uses caching and handles cycles by returning $ref nodes.
+     */
+    convertOpenApiSchemaToJsonSchema(schema, resolvedRefs, resolveRefs = false) {
+        if ("$ref" in schema) {
+            const ref = schema.$ref;
+            if (!resolveRefs) {
+                if (ref.startsWith("#/components/schemas/")) {
+                    return {
+                        $ref: ref.replace(/^#\/components\/schemas\//, "#/$defs/"),
+                        ...("description" in schema
+                            ? { description: schema.description }
+                            : {}),
+                    };
+                }
+                console.error(`Attempting to resolve ref ${ref} not found in components collection.`);
+                // deliberate fall through
+            }
+            // Create base schema with $ref and description if present
+            const refSchema = { $ref: ref };
+            if ("description" in schema && schema.description) {
+                refSchema.description = schema.description;
+            }
+            // If already cached, return immediately with description
+            if (this.schemaCache[ref]) {
+                return this.schemaCache[ref];
+            }
+            const resolved = this.internalResolveRef(ref, resolvedRefs);
+            if (!resolved) {
+                // TODO: need extensive tests for this and we definitely need to handle the case of self references
+                console.error(`Failed to resolve ref ${ref}`);
+                return {
+                    $ref: ref.replace(/^#\/components\/schemas\//, "#/$defs/"),
+                    description: "description" in schema
+                        ? (schema.description ?? "")
+                        : "",
+                };
+            }
+            else {
+                const converted = this.convertOpenApiSchemaToJsonSchema(resolved, resolvedRefs, resolveRefs);
+                this.schemaCache[ref] = converted;
+                return converted;
+            }
+        }
+        // Handle inline schema
+        const result = {};
+        if (schema.type) {
+            result.type = schema.type;
+        }
+        // Convert binary format to uri-reference and enhance description
+        if (schema.format === "binary") {
+            result.format = "uri-reference";
+            const binaryDesc = "absolute paths to local files";
+            result.description = schema.description
+                ? `${schema.description} (${binaryDesc})`
+                : binaryDesc;
+        }
+        else {
+            if (schema.format) {
+                result.format = schema.format;
+            }
+            if (schema.description) {
+                result.description = schema.description;
+            }
+        }
+        if (schema.enum) {
+            result.enum = schema.enum;
+        }
+        if (schema.default !== undefined) {
+            result.default = schema.default;
+        }
+        // Handle object properties
+        if (schema.type === "object") {
+            result.type = "object";
+            if (schema.properties) {
+                result.properties = {};
+                for (const [name, propSchema] of Object.entries(schema.properties)) {
+                    result.properties[name] = this.convertOpenApiSchemaToJsonSchema(propSchema, resolvedRefs, resolveRefs);
+                }
+            }
+            if (schema.required) {
+                result.required = schema.required;
+            }
+            if (schema.additionalProperties === true ||
+                schema.additionalProperties === undefined) {
+                result.additionalProperties = true;
+            }
+            else if (schema.additionalProperties &&
+                typeof schema.additionalProperties === "object") {
+                result.additionalProperties = this.convertOpenApiSchemaToJsonSchema(schema.additionalProperties, resolvedRefs, resolveRefs);
+            }
+            else {
+                result.additionalProperties = false;
+            }
+        }
+        // Handle arrays - ensure binary format conversion happens for array items too
+        if (schema.type === "array" && schema.items) {
+            result.type = "array";
+            result.items = this.convertOpenApiSchemaToJsonSchema(schema.items, resolvedRefs, resolveRefs);
+        }
+        // oneOf, anyOf, allOf
+        if (schema.oneOf) {
+            result.oneOf = schema.oneOf.map((s) => this.convertOpenApiSchemaToJsonSchema(s, resolvedRefs, resolveRefs));
+        }
+        if (schema.anyOf) {
+            result.anyOf = schema.anyOf.map((s) => this.convertOpenApiSchemaToJsonSchema(s, resolvedRefs, resolveRefs));
+        }
+        if (schema.allOf) {
+            result.allOf = schema.allOf.map((s) => this.convertOpenApiSchemaToJsonSchema(s, resolvedRefs, resolveRefs));
+        }
+        return result;
+    }
+    convertToMCPTools() {
+        const apiName = "API";
+        const openApiLookup = {};
+        const tools = {
+            [apiName]: { methods: [] },
+        };
+        const zip = {};
+        for (const [path, pathItem] of Object.entries(this.openApiSpec.paths || {})) {
+            if (!pathItem)
+                continue;
+            for (const [method, operation] of Object.entries(pathItem)) {
+                if (!this.isOperation(method, operation))
+                    continue;
+                const mcpMethod = this.convertOperationToMCPMethod(operation, method, path);
+                if (mcpMethod) {
+                    const uniqueName = this.ensureUniqueName(mcpMethod.name);
+                    mcpMethod.name = uniqueName;
+                    tools[apiName].methods.push(mcpMethod);
+                    openApiLookup[apiName + "-" + uniqueName] = {
+                        ...operation,
+                        method,
+                        path,
+                    };
+                    zip[apiName + "-" + uniqueName] = {
+                        openApi: { ...operation, method, path },
+                        mcp: mcpMethod,
+                    };
+                }
+            }
+        }
+        return { tools, openApiLookup, zip };
+    }
+    /**
+     * Convert the OpenAPI spec to OpenAI's ChatCompletionTool format
+     */
+    convertToOpenAITools() {
+        const tools = [];
+        for (const [path, pathItem] of Object.entries(this.openApiSpec.paths || {})) {
+            if (!pathItem)
+                continue;
+            for (const [method, operation] of Object.entries(pathItem)) {
+                if (!this.isOperation(method, operation))
+                    continue;
+                const parameters = this.convertOperationToJsonSchema(operation, method, path);
+                const tool = {
+                    type: "function",
+                    function: {
+                        name: operation.operationId,
+                        description: operation.summary || operation.description || "",
+                        parameters: parameters,
+                    },
+                };
+                tools.push(tool);
+            }
+        }
+        return tools;
+    }
+    /**
+     * Convert the OpenAPI spec to Anthropic's Tool format
+     */
+    convertToAnthropicTools() {
+        const tools = [];
+        for (const [path, pathItem] of Object.entries(this.openApiSpec.paths || {})) {
+            if (!pathItem)
+                continue;
+            for (const [method, operation] of Object.entries(pathItem)) {
+                if (!this.isOperation(method, operation))
+                    continue;
+                const parameters = this.convertOperationToJsonSchema(operation, method, path);
+                const tool = {
+                    name: operation.operationId,
+                    description: operation.summary || operation.description || "",
+                    input_schema: parameters,
+                };
+                tools.push(tool);
+            }
+        }
+        return tools;
+    }
+    convertComponentsToJsonSchema() {
+        const components = this.openApiSpec.components || {};
+        const schema = {};
+        for (const [key, value] of Object.entries(components.schemas || {})) {
+            schema[key] = this.convertOpenApiSchemaToJsonSchema(value, new Set());
+        }
+        return schema;
+    }
+    /**
+     * Helper method to convert an operation to a JSON Schema for parameters
+     */
+    convertOperationToJsonSchema(operation, method, path) {
+        const schema = {
+            type: "object",
+            properties: {},
+            required: [],
+            $defs: this.convertComponentsToJsonSchema(),
+        };
+        // Handle parameters (path, query, header, cookie)
+        if (operation.parameters) {
+            for (const param of operation.parameters) {
+                const paramObj = this.resolveParameter(param);
+                if (paramObj && paramObj.schema) {
+                    const paramSchema = this.convertOpenApiSchemaToJsonSchema(paramObj.schema, new Set());
+                    // Merge parameter-level description if available
+                    if (paramObj.description) {
+                        paramSchema.description = paramObj.description;
+                    }
+                    schema.properties[paramObj.name] = paramSchema;
+                    if (paramObj.required) {
+                        schema.required.push(paramObj.name);
+                    }
+                }
+            }
+        }
+        // Handle requestBody
+        if (operation.requestBody) {
+            const bodyObj = this.resolveRequestBody(operation.requestBody);
+            if (bodyObj?.content) {
+                if (bodyObj.content["application/json"]?.schema) {
+                    const bodySchema = this.convertOpenApiSchemaToJsonSchema(bodyObj.content["application/json"].schema, new Set());
+                    if (bodySchema.type === "object" && bodySchema.properties) {
+                        for (const [name, propSchema] of Object.entries(bodySchema.properties)) {
+                            schema.properties[name] = propSchema;
+                        }
+                        if (bodySchema.required) {
+                            schema.required.push(...bodySchema.required);
+                        }
+                    }
+                }
+            }
+        }
+        return schema;
+    }
+    isOperation(method, operation) {
+        return ["get", "post", "put", "delete", "patch"].includes(method.toLowerCase());
+    }
+    isParameterObject(param) {
+        return !("$ref" in param);
+    }
+    isRequestBodyObject(body) {
+        return !("$ref" in body);
+    }
+    resolveParameter(param) {
+        if (this.isParameterObject(param)) {
+            return param;
+        }
+        else {
+            const resolved = this.internalResolveRef(param.$ref, new Set());
+            if (resolved && resolved.name) {
+                return resolved;
+            }
+        }
+        return null;
+    }
+    resolveRequestBody(body) {
+        if (this.isRequestBodyObject(body)) {
+            return body;
+        }
+        else {
+            const resolved = this.internalResolveRef(body.$ref, new Set());
+            if (resolved) {
+                return resolved;
+            }
+        }
+        return null;
+    }
+    resolveResponse(response) {
+        if ("$ref" in response) {
+            const resolved = this.internalResolveRef(response.$ref, new Set());
+            if (resolved) {
+                return resolved;
+            }
+            else {
+                return null;
+            }
+        }
+        return response;
+    }
+    convertOperationToMCPMethod(operation, method, path) {
+        if (!operation.operationId) {
+            console.warn(`Operation without operationId at ${method} ${path}`);
+            return null;
+        }
+        const methodName = operation.operationId.replaceAll("\.", "_");
+        const inputSchema = {
+            $defs: this.convertComponentsToJsonSchema(),
+            type: "object",
+            properties: {},
+            required: [],
+        };
+        // Handle parameters (path, query, header, cookie)
+        if (operation.parameters) {
+            for (const param of operation.parameters) {
+                const paramObj = this.resolveParameter(param);
+                if (paramObj && paramObj.schema) {
+                    const schema = this.convertOpenApiSchemaToJsonSchema(paramObj.schema, new Set(), false);
+                    // Merge parameter-level description if available
+                    if (paramObj.description) {
+                        schema.description = paramObj.description;
+                    }
+                    inputSchema.properties[paramObj.name] = schema;
+                    if (paramObj.required) {
+                        inputSchema.required.push(paramObj.name);
+                    }
+                }
+            }
+        }
+        // Handle requestBody
+        if (operation.requestBody) {
+            const bodyObj = this.resolveRequestBody(operation.requestBody);
+            if (bodyObj?.content) {
+                // Handle multipart/form-data for file uploads
+                // We convert the multipart/form-data schema to a JSON schema and we require
+                // that the user passes in a string for each file that points to the local file
+                if (bodyObj.content["multipart/form-data"]?.schema) {
+                    const formSchema = this.convertOpenApiSchemaToJsonSchema(bodyObj.content["multipart/form-data"].schema, new Set(), false);
+                    if (formSchema.type === "object" && formSchema.properties) {
+                        for (const [name, propSchema] of Object.entries(formSchema.properties)) {
+                            inputSchema.properties[name] = propSchema;
+                        }
+                        if (formSchema.required) {
+                            inputSchema.required.push(...formSchema.required);
+                        }
+                    }
+                }
+                // Handle application/json
+                else if (bodyObj.content["application/json"]?.schema) {
+                    const bodySchema = this.convertOpenApiSchemaToJsonSchema(bodyObj.content["application/json"].schema, new Set(), false);
+                    // Merge body schema into the inputSchema's properties
+                    if (bodySchema.type === "object" && bodySchema.properties) {
+                        for (const [name, propSchema] of Object.entries(bodySchema.properties)) {
+                            inputSchema.properties[name] = propSchema;
+                        }
+                        if (bodySchema.required) {
+                            inputSchema.required.push(...bodySchema.required);
+                        }
+                    }
+                    else {
+                        // If the request body is not an object, just put it under "body"
+                        inputSchema.properties["body"] = bodySchema;
+                        inputSchema.required.push("body");
+                    }
+                }
+            }
+        }
+        // Build description including error responses
+        let description = operation.summary || operation.description || "";
+        if (operation.responses) {
+            const errorResponses = Object.entries(operation.responses)
+                .filter(([code]) => code.startsWith("4") || code.startsWith("5"))
+                .map(([code, response]) => {
+                const responseObj = this.resolveResponse(response);
+                let errorDesc = responseObj?.description || "";
+                return `${code}: ${errorDesc}`;
+            });
+            if (errorResponses.length > 0) {
+                description += "\nError Responses:\n" + errorResponses.join("\n");
+            }
+        }
+        // Extract return type (response schema)
+        const returnSchema = this.extractResponseType(operation.responses);
+        // Generate Zod schema from input schema
+        try {
+            // const zodSchemaStr = jsonSchemaToZod(inputSchema, { module: "cjs" })
+            // console.log(zodSchemaStr)
+            // // Execute the function with the zod instance
+            // const zodSchema = eval(zodSchemaStr) as z.ZodType
+            return {
+                name: methodName,
+                description,
+                inputSchema,
+                ...(returnSchema ? { returnSchema } : {}),
+            };
+        }
+        catch (error) {
+            console.warn(`Failed to generate Zod schema for ${methodName}:`, error);
+            // Fallback to a basic object schema
+            return {
+                name: methodName,
+                description,
+                inputSchema,
+                ...(returnSchema ? { returnSchema } : {}),
+            };
+        }
+    }
+    extractResponseType(responses) {
+        // Look for a success response
+        const successResponse = responses?.["200"] ||
+            responses?.["201"] ||
+            responses?.["202"] ||
+            responses?.["204"];
+        if (!successResponse)
+            return null;
+        const responseObj = this.resolveResponse(successResponse);
+        if (!responseObj || !responseObj.content)
+            return null;
+        if (responseObj.content["application/json"]?.schema) {
+            const returnSchema = this.convertOpenApiSchemaToJsonSchema(responseObj.content["application/json"].schema, new Set(), false);
+            returnSchema["$defs"] = this.convertComponentsToJsonSchema();
+            // Preserve the response description if available and not already set
+            if (responseObj.description && !returnSchema.description) {
+                returnSchema.description = responseObj.description;
+            }
+            return returnSchema;
+        }
+        // If no JSON response, fallback to a generic string or known formats
+        if (responseObj.content["image/png"] || responseObj.content["image/jpeg"]) {
+            return {
+                type: "string",
+                format: "binary",
+                description: responseObj.description || "",
+            };
+        }
+        // Fallback
+        return { type: "string", description: responseObj.description || "" };
+    }
+    ensureUniqueName(name) {
+        if (name.length <= 64) {
+            return name;
+        }
+        const truncatedName = name.slice(0, 64 - 5); // Reserve space for suffix
+        const uniqueSuffix = this.generateUniqueSuffix();
+        return `${truncatedName}-${uniqueSuffix}`;
+    }
+    generateUniqueSuffix() {
+        this.nameCounter += 1;
+        return this.nameCounter.toString().padStart(4, "0");
+    }
+}

package/build/tools/magicpod-web-api.js

@@ -0,0 +1,43 @@
+import { MCPProxy, } from "../openapi-mcp-server/mcp/proxy.js";
+import swagger2openapi from "swagger2openapi";
+const getOpenApiSpec = async (schemaUrl) => {
+    try {
+        const response = await fetch(schemaUrl);
+        if (!response.ok) {
+            throw new Error(`HTTP error! status: ${response.status}`);
+        }
+        const openApiV2Spec = await response.json();
+        return new Promise((resolve, reject) => {
+            swagger2openapi.convertObj(openApiV2Spec, {}, (err, options) => {
+                if (err) {
+                    reject(err);
+                }
+                else {
+                    resolve(options.openapi);
+                }
+            });
+        });
+    }
+    catch (error) {
+        console.error("Failed to parse OpenAPI spec:", error.message);
+        process.exit(1);
+    }
+};
+const unsupportedPaths = [
+    '/v1.0/{organization_name}/{project_name}/batch-runs/{batch_run_number}/screenshots/',
+    '/v1.0/{organization_name}/{project_name}/screenshots/{batch_task_id}/',
+    '/v1.0/magicpod-clients/api/{os}/{tag_or_version}/',
+    '/v1.0/magicpod-clients/local/{os}/{version}/'
+];
+export const initMagicPodApiProxy = async (baseUrl, apiToken, tools) => {
+    const schemaUrl = `${baseUrl}/api/v1.0/doc/?format=openapi`;
+    const openApiSpec = await getOpenApiSpec(schemaUrl);
+    openApiSpec.servers = [{ url: `${baseUrl}/api` }];
+    for (const path of Object.keys(openApiSpec.paths)) {
+        if (unsupportedPaths.includes(path)) {
+            delete openApiSpec.paths[path];
+        }
+    }
+    const proxy = new MCPProxy("magicpod-mcp-server", openApiSpec, apiToken, tools);
+    return proxy;
+};

package/build/tools/read-magicpod-article.js

@@ -0,0 +1,43 @@
+import { z } from "zod";
+const makeRequest = async (articleId, locale) => {
+    const headers = {
+        Accept: "application/json",
+    };
+    try {
+        const url = `https://trident-qa.zendesk.com/api/v2/help_center/${locale}/articles/${articleId}.json`;
+        const response = await fetch(url, { headers });
+        if (!response.ok) {
+            throw new Error(`HTTP error! status: ${response.status}`);
+        }
+        return await response.json();
+    }
+    catch (error) {
+        console.error("Error making request:", error);
+        return null;
+    }
+};
+export const readMagicpodArticle = () => {
+    return {
+        name: "read-magicpod-article",
+        description: "Read a specified article on MagicPod help center",
+        inputSchema: z.object({
+            articleId: z
+                .string()
+                .describe("An article ID of MagicPod Help Center, which can be retrieved by 'search-magicpod-articles' tool"),
+            locale: z
+                .union([z.literal("ja"), z.literal("en-us")])
+                .describe("Article's language"),
+        }),
+        handleRequest: async ({ articleId, locale }) => {
+            const response = await makeRequest(articleId, locale);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(response),
+                    },
+                ],
+            };
+        },
+    };
+};

package/build/tools/search-magicpod-articles.js

@@ -0,0 +1,51 @@
+import { z } from "zod";
+const makeRequest = async (query, locale) => {
+    const headers = {
+        Accept: "application/json",
+    };
+    try {
+        const url = `https://trident-qa.zendesk.com/api/v2/help_center/articles/search.json?query=${query}&locale=${locale}`;
+        const response = await fetch(url, { headers });
+        if (!response.ok) {
+            throw new Error(`HTTP error! status: ${response.status}`);
+        }
+        return await response.json();
+    }
+    catch (error) {
+        console.error("Error making request:", error);
+        return null;
+    }
+};
+export const searchMagicpodArticles = () => {
+    return {
+        name: "search-magicpod-articles",
+        description: "Search the list of articles on MagicPod help center by specified keywords",
+        inputSchema: z.object({
+            query: z
+                .string()
+                .describe("Queries to search MagicPod Help Center's articles, split by whitespaces"),
+            locale: z
+                .union([z.literal("ja"), z.literal("en-us")])
+                .describe("Query's and search target's locale"),
+        }),
+        handleRequest: async ({ query, locale }) => {
+            const response = await makeRequest(query, locale);
+            // The response has "body" field, but it is too large for LLM
+            // So, such large or insignificant fields are filtered here
+            response.results = response.results.map((r) => ({
+                id: r.id,
+                title: r.title,
+                content_tag_ids: r.content_tag_ids,
+                label_names: r.label_names,
+            }));
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(response),
+                    },
+                ],
+            };
+        },
+    };
+};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "magicpod-mcp-server",
+  "version": "0.1.0",
+  "description": "Model Context Protocol server for MagicPod integration",
+  "type": "module",
+  "bin": {
+    "magicpod-mcp-server": "./build/index.js"
+  },
+  "scripts": {
+    "build": "tsc && chmod 755 build/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "magicpod",
+    "test-automation",
+    "model-context-protocol"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Magic-Pod/magicpod-mcp-server.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "build"
+  ],
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.33.1",
+    "@modelcontextprotocol/sdk": "^1.9.0",
+    "@types/mustache": "^4.2.5",
+    "commander": "^13.1.0",
+    "json-schema": "^0.4.0",
+    "mustache": "^4.2.0",
+    "openai": "^4.91.1",
+    "openapi-client-axios": "^7.5.5",
+    "openapi-schema-validator": "^12.1.3",
+    "openapi-types": "^12.1.3",
+    "swagger2openapi": "^7.0.8",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/json-schema": "^7.0.15",
+    "@types/node": "^22.14.0",
+    "@types/swagger2openapi": "^7.0.4",
+    "prettier": "^3.5.3",
+    "typescript": "^5.8.3"
+  }
+}