Medusa MCP Server

Instructions

Implementation Reference

• src/services/medusa-store.ts:83-127 (handler)

  The core handler logic for the PostCartsIdComplete tool (and all store POST tools). It constructs query parameters and body from input, then uses the Medusa SDK to perform a POST request to the /carts/{id}/complete endpoint.

      handler: async (
          input: InferToolHandlerInput<any, ZodTypeAny>
      ): Promise<any> => {
          const query = new URLSearchParams(input);
          const body = Object.entries(input).reduce(
              (acc, [key, value]) => {
                  if (
                      parameters.find(
                          (p) => p.name === key && p.in === "body"
                      )
                  ) {
                      acc[key] = value;
                  }
                  return acc;
              },
              {} as Record<string, any>
          );
          if (method === "get") {
              console.error(
                  `Fetching ${refPath} with GET ${query.toString()}`
              );
              const response = await this.sdk.client.fetch(refPath, {
                  method: method,
                  headers: {
                      "Content-Type": "application/json",
                      "Accept": "application/json",
                      "Authorization": `Bearer ${process.env.PUBLISHABLE_KEY}`
                  },
                  query: query
              });
              return response;
          } else {
              const response = await this.sdk.client.fetch(refPath, {
                  method: method,
                  headers: {
                      "Content-Type": "application/json",
                      "Accept": "application/json",
                      "Authorization": `Bearer ${process.env.PUBLISHABLE_KEY}`
                  },
                  body: JSON.stringify(body)
              });
              return response;
          }
      }
  };

• src/services/medusa-store.ts:54-82 (schema)

  Dynamically generates the input schema for PostCartsIdComplete using Zod schemas inferred from the OpenAPI spec parameters for the corresponding operation.

  inputSchema: {
      ...parameters
          .filter((p) => p.in != "header")
          .reduce((acc, param) => {
              switch (param.schema.type) {
                  case "string":
                      acc[param.name] = z.string().optional();
                      break;
                  case "number":
                      acc[param.name] = z.number().optional();
                      break;
                  case "boolean":
                      acc[param.name] = z.boolean().optional();
                      break;
                  case "array":
                      acc[param.name] = z
                          .array(z.string())
                          .optional();
                      break;
                  case "object":
                      acc[param.name] = z.object({}).optional();
                      break;
                  default:
                      acc[param.name] = z.string().optional();
              }
              return acc;
          }, {} as any)
  },

• src/index.ts:35-42 (registration)

  Registers the PostCartsIdComplete tool (among others from medusaStoreService.defineTools()) with the MCP server.

  tools.forEach((tool) => {
      server.tool(
          tool.name,
          tool.description,
          tool.inputSchema,
          tool.handler
      );
  });

• src/services/medusa-store.ts:131-137 (helper)

  The method that iterates over the store OpenAPI spec to create tool definitions, including PostCartsIdComplete via wrapPath for the POST /carts/{id}/complete path.

  defineTools(store = storeJson): any[] {
      const paths = Object.entries(store.paths) as [string, SdkRequestType][];
      const tools = paths.map(([path, refFunction]) =>
          this.wrapPath(path, refFunction)
      );
      return tools;
  }

• src/utils/define-tools.ts:21-59 (helper)

  Wrapper around the inner handler that formats the response as MCP-compliant text/JSON output or error, used for all tools including PostCartsIdComplete.

  const wrappedHandler = async (
      input: InferToolHandlerInput<Zod.ZodAny, Zod.ZodAny>,
      _: RequestHandlerExtra
  ): Promise<{
      content: CallToolResult["content"];
      isError?: boolean;
      statusCode?: number;
  }> => {
      try {
          const result = await tool.handler(input);
          return {
              content: [
                  {
                      type: "text",
                      text: JSON.stringify(result, null, 2)
                  }
              ]
          };
      } catch (error) {
          return {
              content: [
                  {
                      type: "text",
                      text: `Error: ${
                          error instanceof Error
                              ? error.message
                              : String(error)
                      }`
                  }
              ],
              isError: true
          };
      }
  };
  
  return {
      ...tool,
      handler: wrappedHandler
  };