SCP Local MCP Server

Instructions

Implementation Reference

• src/server.ts:851-867 (handler)

  Primary handler function for the scp_get_loyalty tool. Validates authorization, retrieves the access token, calls the HTTP client to fetch loyalty data from the merchant's SCP endpoint, and returns the result as formatted JSON.

   * Tool handler: scp_get_loyalty
   */
  async function handleGetLoyalty(domain: string) {
    const { auth, accessToken } = await checkAuthorizationOrThrow(domain);
    const token = await accessToken;
  
    const data = await scpClient.getLoyalty(auth.scp_endpoint, token);
  
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(data, null, 2)
        }
      ]
    };
  }

• src/server.ts:399-412 (schema)

  Input schema definition registered for the scp_get_loyalty tool, requiring a 'domain' parameter.

  {
    name: 'scp_get_loyalty',
    description: 'Get loyalty status and points from a merchant. Domain must be authorized first.',
    inputSchema: {
      type: 'object',
      properties: {
        domain: {
          type: 'string',
          description: 'Merchant domain'
        }
      },
      required: ['domain']
    }
  },

• src/server.ts:303-538 (registration)

  Tool registration within the ListToolsRequestSchema handler, where scp_get_loyalty is included in the list of available tools with its schema.

  server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: [
      {
        name: 'scp_authorize',
        description: 'BEFORE USING THIS ENSURE THE DOMAIN SUPPORTS SCP BY CALLING scp_discover FIRST. Authorize access to a merchant\'s customer context via SCP. Must be called before accessing any customer data. IMPORTANT: You must ask the user for their REAL email address - never use placeholder emails like user@example.com. Ask: "What email address do you use with [Merchant]?" and wait for their response.',
        inputSchema: {
          type: 'object',
          properties: {
            domain: {
              type: 'string',
              description: 'Merchant domain (e.g., \'acmestore.com\')'
            },
            email: {
              type: 'string',
              description: 'Customer\'s REAL email address (must ask user for this - never use example.com or placeholder emails)'
            },
            scopes: {
              type: 'array',
              items: { type: 'string' },
              description: 'Requested scopes (e.g., [\'orders\', \'loyalty\', \'intent:read\']). Best practice: request all needed scopes upfront.'
            }
          },
          required: ['domain', 'email', 'scopes']
        }
      },
      {
        name: 'scp_check_authorization',
        description: 'Check if authorized with a merchant domain',
        inputSchema: {
          type: 'object',
          properties: {
            domain: {
              type: 'string',
              description: 'Merchant domain'
            }
          },
          required: ['domain']
        }
      },
      {
        name: 'scp_revoke_authorization',
        description: 'Revoke authorization with a merchant domain',
        inputSchema: {
          type: 'object',
          properties: {
            domain: {
              type: 'string',
              description: 'Merchant domain'
            }
          },
          required: ['domain']
        }
      },
      {
        name: 'scp_discover',
        description: 'Discover SCP endpoint for a merchant domain via DNS',
        inputSchema: {
          type: 'object',
          properties: {
            domain: {
              type: 'string',
              description: 'Merchant domain'
            }
          },
          required: ['domain']
        }
      },
      {
        name: 'scp_get_orders',
        description: 'Get order history from a merchant. Domain must be authorized first.',
        inputSchema: {
          type: 'object',
          properties: {
            domain: {
              type: 'string',
              description: 'Merchant domain'
            },
            limit: {
              type: 'number',
              description: 'Maximum number of orders to return',
              default: 10
            },
            offset: {
              type: 'number',
              description: 'Number of orders to skip',
              default: 0
            },
            status: {
              type: 'array',
              items: { type: 'string' },
              description: 'Filter by order status (e.g., [\'delivered\', \'shipped\'])'
            }
          },
          required: ['domain']
        }
      },
      {
        name: 'scp_get_loyalty',
        description: 'Get loyalty status and points from a merchant. Domain must be authorized first.',
        inputSchema: {
          type: 'object',
          properties: {
            domain: {
              type: 'string',
              description: 'Merchant domain'
            }
          },
          required: ['domain']
        }
      },
      {
        name: 'scp_get_offers',
        description: 'Get active personalized offers from a merchant. Domain must be authorized first.',
        inputSchema: {
          type: 'object',
          properties: {
            domain: {
              type: 'string',
              description: 'Merchant domain'
            },
            active_only: {
              type: 'boolean',
              description: 'Only return active offers',
              default: true
            }
          },
          required: ['domain']
        }
      },
      {
        name: 'scp_get_preferences',
        description: 'Get saved customer preferences (sizes, styles, addresses) from a merchant. Domain must be authorized first.',
        inputSchema: {
          type: 'object',
          properties: {
            domain: {
              type: 'string',
              description: 'Merchant domain'
            }
          },
          required: ['domain']
        }
      },
      {
        name: 'scp_get_intents',
        description: 'Get shopping intents from a merchant. Domain must be authorized first.',
        inputSchema: {
          type: 'object',
          properties: {
            domain: {
              type: 'string',
              description: 'Merchant domain'
            },
            status: {
              type: 'array',
              items: { type: 'string' },
              description: 'Filter by status (e.g., [\'active\', \'in_progress\'])'
            },
            limit: {
              type: 'number',
              description: 'Maximum number of intents to return',
              default: 10
            }
          },
          required: ['domain']
        }
      },
      {
        name: 'scp_create_intent',
        description: 'Create a new shopping intent with a merchant. Domain must be authorized with intent:create scope.',
        inputSchema: {
          type: 'object',
          properties: {
            domain: {
              type: 'string',
              description: 'Merchant domain'
            },
            base_intent: {
              type: 'string',
              description: 'Natural language description of the shopping goal'
            },
            context: {
              type: 'object',
              description: 'Additional context about the intent'
            },
            mechanism: {
              type: 'string',
              description: 'How the intent was created',
              default: 'conversational_ai'
            },
            ai_assistant: {
              type: 'string',
              description: 'Name of the AI assistant'
            },
            visibility: {
              type: 'string',
              description: 'Who can see this intent',
              enum: ['merchant_only', 'shared_with_customer'],
              default: 'merchant_only'
            }
          },
          required: ['domain', 'base_intent']
        }
      },
      {
        name: 'scp_update_intent',
        description: 'Update an existing shopping intent. Domain must be authorized with intent:write scope.',
        inputSchema: {
          type: 'object',
          properties: {
            domain: {
              type: 'string',
              description: 'Merchant domain'
            },
            intent_id: {
              type: 'string',
              description: 'Intent ID to update'
            },
            status: {
              type: 'string',
              description: 'New status'
            },
            context: {
              type: 'object',
              description: 'Updated context'
            },
            add_milestone: {
              type: 'string',
              description: 'Add a milestone note'
            }
          },
          required: ['domain', 'intent_id']
        }
      }
    ]
  }));

• src/http/client.ts:102-107 (helper)

  Helper function in the HTTP client that performs the actual JSON-RPC call to the merchant's SCP endpoint for retrieving loyalty information.

  export async function getLoyalty(
    endpoint: string,
    accessToken: string
  ): Promise<any> {
    return makeRPCRequest(endpoint, accessToken, 'scp.get_loyalty');
  }

• src/server.ts:811-825 (helper)

  Shared helper function used by scp_get_loyalty and other data-access tools to check authorization and retrieve the access token, throwing a helpful error if not authorized.

  async function checkAuthorizationOrThrow(domain: string): Promise<{ auth: any; accessToken: Promise<string> }> {
    const auth = await getAuthorization(domain);
  
    if (!auth) {
      const errorMessage = `❌ Not authorized with ${domain}.\n\n` +
        `Please authorize first by calling:\n` +
        `scp_authorize with domain="${domain}", email="your@email.com", and scopes=["orders", "loyalty", "preferences", "intent:read", "intent:create"]`;
      throw new Error(errorMessage);
    }
  
    return {
      auth,
      accessToken: getValidAccessToken(domain)
    };
  }