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 }; }