SCP Local MCP Server

Instructions

Implementation Reference

• src/server.ts:719-750 (handler)

  The primary handler function for the 'scp_check_authorization' tool. It checks the authorization status for a given merchant domain using getAuthorizationInfo and returns structured information about the authorization or indicates if not authorized.

  async function handleCheckAuthorization(domain: string) {
    const info = await getAuthorizationInfo(domain);
  
    if (!info.authorized) {
      return {
        content: [
          {
            type: 'text',
            text: `Not authorized with ${domain}`
          }
        ]
      };
    }
  
    const expiresDate = new Date(info.expires_at!).toISOString();
  
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify({
            authorized: true,
            domain,
            customer_email: info.customer_email,
            scopes: info.scopes,
            authorized_at: new Date(info.authorized_at!).toISOString(),
            expires_at: expiresDate
          }, null, 2)
        }
      ]
    };
  }

• src/server.ts:328-341 (schema)

  The input schema definition for the 'scp_check_authorization' tool, specifying that it requires a 'domain' string parameter.

  {
    name: 'scp_check_authorization',
    description: 'Check if authorized with a merchant domain',
    inputSchema: {
      type: 'object',
      properties: {
        domain: {
          type: 'string',
          description: 'Merchant domain'
        }
      },
      required: ['domain']
    }
  },

• src/server.ts:552-553 (registration)

  Registration of the tool handler in the CallToolRequestSchema switch statement, dispatching to handleCheckAuthorization.

  case 'scp_check_authorization':
    return await handleCheckAuthorization(args.domain as string);

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

  Registration of the tool in the ListToolsRequestSchema handler, including it in the list of available tools.

  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/auth/token-manager.ts:94-116 (helper)

  Helper function getAuthorizationInfo used by the tool handler to retrieve authorization details without exposing tokens.

  export async function getAuthorizationInfo(merchantDomain: string): Promise<{
    authorized: boolean;
    customer_email?: string;
    customer_id?: string;
    scopes?: string[];
    authorized_at?: number;
    expires_at?: number;
  }> {
    const auth = await getAuthorization(merchantDomain);
  
    if (!auth) {
      return { authorized: false };
    }
  
    return {
      authorized: true,
      customer_email: auth.customer_email,
      customer_id: auth.customer_id,
      scopes: auth.scopes,
      authorized_at: auth.created_at,
      expires_at: auth.expires_at
    };
  }