App Store Connect MCP Server

Instructions

Implementation Reference

• src/handlers/devices.ts:13-35 (handler)

  The main handler function that implements the list_devices tool logic. It constructs query parameters from input args and calls the App Store Connect API endpoint '/devices'.

  async listDevices(args: {
    limit?: number;
    sort?: DeviceSortOptions;
    filter?: DeviceFilters;
    fields?: {
      devices?: DeviceFieldOptions[];
    };
  } = {}): Promise<ListDevicesResponse> {
    const { limit = 100, sort, filter, fields } = args;
    
    const params: Record<string, any> = {
      limit: sanitizeLimit(limit)
    };
  
    if (sort) {
      params.sort = sort;
    }
  
    Object.assign(params, buildFilterParams(filter));
    Object.assign(params, buildFieldParams(fields));
  
    return this.client.get<ListDevicesResponse>('/devices', params);
  }

• src/types/devices.ts:1-47 (schema)

  TypeScript interfaces and types defining the input parameters (filters, sort, fields) and output response structure (ListDevicesResponse) for the list_devices tool.

  export type DevicePlatform = "IOS" | "MAC_OS";
  export type DeviceStatus = "ENABLED" | "DISABLED";
  export type DeviceClass = "APPLE_WATCH" | "IPAD" | "IPHONE" | "IPOD" | "APPLE_TV" | "MAC";
  
  export interface Device {
    id: string;
    type: string;
    attributes: {
      name: string;
      platform: DevicePlatform;
      udid: string;
      deviceClass: DeviceClass;
      status: DeviceStatus;
      model?: string;
      addedDate?: string;
    };
  }
  
  export interface ListDevicesResponse {
    data: Device[];
  }
  
  export interface DeviceFilters {
    name?: string;
    platform?: DevicePlatform;
    status?: DeviceStatus;
    udid?: string;
    deviceClass?: DeviceClass;
  }
  
  export type DeviceSortOptions = 
    | "name" | "-name"
    | "platform" | "-platform"
    | "status" | "-status"
    | "udid" | "-udid"
    | "deviceClass" | "-deviceClass"
    | "model" | "-model"
    | "addedDate" | "-addedDate";
  
  export type DeviceFieldOptions = 
    | "name"
    | "platform"
    | "udid"
    | "deviceClass"
    | "status"
    | "model"
    | "addedDate";

• src/index.ts:1380-1381 (registration)

  Registers the dispatch handler for the "list_devices" tool call, mapping it to the DeviceHandlers.listDevices method.

  case "list_devices":
    return { toolResult: await this.deviceHandlers.listDevices(args as any) };

• src/index.ts:637-694 (registration)

  Tool registration in the listTools response, defining the name, description, and inputSchema for "list_devices".

    name: "list_devices",
    description: "Get a list of all devices registered to your team",
    inputSchema: {
      type: "object",
      properties: {
        limit: {
          type: "number",
          description: "Maximum number of devices to return (default: 100, max: 200)",
          minimum: 1,
          maximum: 200
        },
        sort: {
          type: "string",
          description: "Sort order for the results",
          enum: [
            "name", "-name", "platform", "-platform", "status", "-status",
            "udid", "-udid", "deviceClass", "-deviceClass", "model", "-model",
            "addedDate", "-addedDate"
          ]
        },
        filter: {
          type: "object",
          properties: {
            name: { type: "string", description: "Filter by device name" },
            platform: { 
              type: "string", 
              description: "Filter by platform",
              enum: ["IOS", "MAC_OS"]
            },
            status: { 
              type: "string", 
              description: "Filter by status",
              enum: ["ENABLED", "DISABLED"]
            },
            udid: { type: "string", description: "Filter by device UDID" },
            deviceClass: { 
              type: "string", 
              description: "Filter by device class",
              enum: ["APPLE_WATCH", "IPAD", "IPHONE", "IPOD", "APPLE_TV", "MAC"]
            }
          }
        },
        fields: {
          type: "object",
          properties: {
            devices: {
              type: "array",
              items: {
                type: "string",
                enum: ["name", "platform", "udid", "deviceClass", "status", "model", "addedDate"]
              },
              description: "Fields to include for each device"
            }
          }
        }
      }
    }
  },

• src/handlers/devices.ts:8-10 (helper)

  The DeviceHandlers class constructor that receives the AppStoreConnectClient instance, used to instantiate the handler.

  import { sanitizeLimit, buildFilterParams, buildFieldParams } from '../utils/index.js';
  
  export class DeviceHandlers {