Square Model Context Protocol Server

Instructions

Implementation Reference

• server.ts:189-237 (handler)

  Core execution logic for the 'make_api_request' tool. Dispatches requests to specific Square API service handlers based on service and method parameters, handles errors, and enforces write permissions.

  async (params) => {
    try {
      const { service, method, request } = params;
      const serviceName = service.charAt(0).toUpperCase() + service.slice(1);
      
      const methods = serviceMethodsMap[serviceName];
      if (!methods) {
        throw new Error(`Invalid service: ${service}. Available services: ${JSON.stringify(Object.keys(serviceMethodsMap), null, 2)}`);
      }
  
      const handlers = serviceHandlersMap[serviceName];
      if (!methods[method]) {
        throw new Error(`Invalid method ${method} for service ${service}. Available methods: ${JSON.stringify(Object.keys(methods), null, 2)}`);
      }
      
  
      // Support read-only mode if desired
      const methodInfo = methods[method];
      if (process.env.DISALLOW_WRITES == "true" && methodInfo?.isWrite) {
        throw new Error(`Write operations are not allowed in this environment. Please set DISALLOW_WRITES to false to enable write operations. Attempted operation: ${service}.${method}`);
      }
  
      const handler = handlers[method];
      if (!handler) {
        throw new Error(`No handler found for ${service}.${method}`);
      }
  
      const token = await getAccessToken();
      const result = await handler(token, request || {});
  
      return {
        content: [{
          type: "text",
          text: result as string
        }]
      };
    } catch (err: any) {
      return {
        content: [{
          type: "text",
          text: JSON.stringify({
            error: err.message,
            details: err.errors || err.stack
          }, null, 2)
        }],
        isError: true
      };
    }
  });

• server.ts:184-188 (schema)

  Zod input schema defining parameters for the 'make_api_request' tool: service, method, and optional request body.

  {
    service: z.string().describe("The Square API service category (e.g., 'catalog', 'payments')"),
    method: z.string().describe("The API method to call (e.g., 'list', 'create')"),
    request: z.object({}).passthrough().optional().describe("The request object for the API call.")
  },

• server.ts:180-237 (registration)

  MCP server registration of the 'make_api_request' tool, including name, description, schema, and handler function.

  server.tool(
    "make_api_request",
    `Unified tool for all Square API operations. Be sure to get types before calling. Available services:
    ${Object.keys(serviceMethodsMap).map(name => name.toLowerCase()).join(", ")}.`,
    {
      service: z.string().describe("The Square API service category (e.g., 'catalog', 'payments')"),
      method: z.string().describe("The API method to call (e.g., 'list', 'create')"),
      request: z.object({}).passthrough().optional().describe("The request object for the API call.")
    },
    async (params) => {
      try {
        const { service, method, request } = params;
        const serviceName = service.charAt(0).toUpperCase() + service.slice(1);
        
        const methods = serviceMethodsMap[serviceName];
        if (!methods) {
          throw new Error(`Invalid service: ${service}. Available services: ${JSON.stringify(Object.keys(serviceMethodsMap), null, 2)}`);
        }
  
        const handlers = serviceHandlersMap[serviceName];
        if (!methods[method]) {
          throw new Error(`Invalid method ${method} for service ${service}. Available methods: ${JSON.stringify(Object.keys(methods), null, 2)}`);
        }
        
  
        // Support read-only mode if desired
        const methodInfo = methods[method];
        if (process.env.DISALLOW_WRITES == "true" && methodInfo?.isWrite) {
          throw new Error(`Write operations are not allowed in this environment. Please set DISALLOW_WRITES to false to enable write operations. Attempted operation: ${service}.${method}`);
        }
  
        const handler = handlers[method];
        if (!handler) {
          throw new Error(`No handler found for ${service}.${method}`);
        }
  
        const token = await getAccessToken();
        const result = await handler(token, request || {});
  
        return {
          content: [{
            type: "text",
            text: result as string
          }]
        };
      } catch (err: any) {
        return {
          content: [{
            type: "text",
            text: JSON.stringify({
              error: err.message,
              details: err.errors || err.stack
            }, null, 2)
          }],
          isError: true
        };
      }
    });