Medusa MCP Server

Instructions

Implementation Reference

• src/services/medusa-store.ts:82-126 (handler)

  The handler function for the PostCartsIdShippingMethods tool (and all store API tools). It parses input into query/body params based on OpenAPI parameters and executes the POST request via Medusa SDK to /carts/{id}/shipping-methods 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-81 (schema)

  Generates the Zod input schema for the tool based on the OpenAPI parameters from store.json spec for the POST /carts/{id}/shipping-methods 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-41 (registration)

  Registers all dynamically generated tools, including PostCartsIdShippingMethods, with the MCP server.

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

• src/index.ts:15-17 (registration)

  Calls defineTools() on MedusaStoreService to generate and collect the tool definitions, including the one for PostCartsIdShippingMethods.

      ...medusaStoreService.defineTools(),
      ...medusaAdminService.defineTools()
  ];

• src/utils/define-tools.ts:16-60 (helper)

  Utility that wraps the raw tool handler to conform to MCP protocol response format, used for all tools including PostCartsIdShippingMethods.

  export const defineTool = (
      cb: (zod: typeof z) => ToolDefinition<any, ZodAny, any>
  ) => {
      const tool = cb(z);
  
      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
      };
  };