SCP Local MCP Server

Instructions

Implementation Reference

• src/server.ts:605-714 (handler)

  Implements the core logic for scp_authorize: validates real email (rejects example.com), checks existing authorization and scopes, discovers SCP endpoint, performs OAuth authorization flow using completeAuthorizationFlow from auth/oauth-client.js, encrypts tokens, and stores authorization info.

  async function handleAuthorize(
    domain: string,
    email: string,
    scopes: string[]
  ) {
    // Validate email - reject example/test emails
    if (email.endsWith('@example.com') || email.includes('example')) {
      return {
        content: [
          {
            type: 'text',
            text: `❌ Invalid email address: ${email}\n\nPlease use a REAL email address, not an example one.\n\nAsk the user: "What email address do you use with ${domain}?"\n\nThen call scp_authorize again with their actual email address.`
          }
        ]
      };
    }
  
    // Check if already authorized
    const existing = await getAuthorization(domain);
  
    if (existing) {
      // Compare requested scopes with existing scopes
      const existingScopes = new Set(existing.scopes);
      const requestedScopes = new Set(scopes);
  
      // Check if scopes are identical
      const scopesMatch =
        existingScopes.size === requestedScopes.size &&
        [...requestedScopes].every(s => existingScopes.has(s));
  
      if (scopesMatch && existing.customer_email === email) {
        // Same scopes and email - just return that they're already authorized
        return {
          content: [
            {
              type: 'text',
              text: `✓ Already authorized with ${domain}\nEmail: ${existing.customer_email}\nScopes: ${existing.scopes.join(', ')}`
            }
          ]
        };
      }
  
      // Scopes are different or email is different - need to re-authorize
      if (existing.customer_email !== email) {
        // Different email - must revoke first
        return {
          content: [
            {
              type: 'text',
              text: `⚠️ Already authorized with ${domain} using ${existing.customer_email}.\n\nTo authorize with a different email (${email}), please revoke the existing authorization first:\nscp_revoke_authorization(domain="${domain}")\n\nThen try authorizing again.`
            }
          ]
        };
      }
  
      // Same email, different scopes - re-authorize
      const addedScopes = [...requestedScopes].filter(s => !existingScopes.has(s));
      const removedScopes = [...existingScopes].filter(s => !requestedScopes.has(s));
  
      console.error(`[SCP] Re-authorizing ${domain} with scope changes:`, {
        added: addedScopes,
        removed: removedScopes
      });
    }
  
    // Discover endpoint
    const discovery = await discoverWithCapabilities(domain);
    if (!discovery) {
      throw new Error(`Could not discover Shopper Context Protocol endpoint for ${domain}`);
    }
  
    const { endpoint, capabilities } = discovery;
  
    // Verify scopes are supported
    if (capabilities && capabilities.scopes_supported) {
      const unsupported = scopes.filter(s => !capabilities.scopes_supported.includes(s));
      if (unsupported.length > 0) {
        throw new Error(`Unsupported scopes: ${unsupported.join(', ')}`);
      }
    }
  
    // Complete OAuth flow (will trigger email verification)
    const { tokenResponse } = await completeAuthorizationFlow(endpoint, email, domain, scopes);
  
    // Store authorization (will update if existing)
    const now = Date.now();
    await storeAuthorization({
      merchant_domain: domain,
      scp_endpoint: endpoint,
      customer_id: tokenResponse.customer_id,
      customer_email: tokenResponse.email,
      access_token_encrypted: encryptToken(tokenResponse.access_token),
      refresh_token_encrypted: encryptToken(tokenResponse.refresh_token),
      expires_at: now + (tokenResponse.expires_in * 1000),
      scopes: tokenResponse.scope.split(' '),
      created_at: existing ? existing.created_at : now, // Preserve original creation time
      updated_at: now
    });
  
    const action = existing ? 'Re-authorized' : 'Connected to';
  
    return {
      content: [
        {
          type: 'text',
          text: `✓ ${action} ${domain}!\nGranted scopes: ${tokenResponse.scope}\nCustomer: ${tokenResponse.email}`
        }
      ]
    };
  }

• src/server.ts:306-327 (registration)

  Registers the scp_authorize tool in the MCP server's ListToolsRequestSchema handler, defining its name, detailed description emphasizing real email usage, and input schema.

    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']
    }
  },

• src/server.ts:308-326 (schema)

  Input schema for scp_authorize tool, specifying required properties: domain (string), email (string), scopes (array of strings).

  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']
  }

• src/server.ts:549-550 (handler)

  Switch case in CallToolRequestSchema handler that routes scp_authorize calls to the handleAuthorize function.

  case 'scp_authorize':
    return await handleAuthorize(args.domain as string, args.email as string, args.scopes as string[]);