SCP Local MCP Server

Instructions

Implementation Reference

• src/server.ts:786-806 (handler)

  The main handler function for the 'scp_discover' tool. It invokes discoverWithCapabilities and formats the response as MCP tool content.

  async function handleDiscover(domain: string) {
    const discovery = await discoverWithCapabilities(domain);
  
    if (!discovery) {
      throw new Error(`Could not discover Shopper Context Protocol endpoint for ${domain}`);
    }
  
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify({
            domain,
            scp_endpoint: discovery.endpoint,
            discovery_method: 'dns_txt',
            capabilities: discovery.capabilities
          }, null, 2)
        }
      ]
    };
  }

• src/discovery/dns-lookup.ts:171-198 (helper)

  Core helper function that discovers the SCP endpoint using DNS TXT records, caching, or fallbacks, and fetches endpoint capabilities.

  export async function discoverWithCapabilities(domain: string): Promise<{
    endpoint: string;
    capabilities: SCPCapabilities;
  } | null> {
    const endpoint = await discoverSCPEndpoint(domain);
  
    if (!endpoint) {
      return null;
    }
  
    try {
      const capabilities = await fetchCapabilities(endpoint);
  
      // Update cache with capabilities
      await cacheEndpoint({
        domain,
        endpoint,
        capabilities,
        discovered_at: Date.now(),
        ttl: 86400
      });
  
      return { endpoint, capabilities };
    } catch (error) {
      // Capabilities fetch failed, but we have endpoint
      return { endpoint, capabilities: null as any };
    }
  }

• src/server.ts:357-368 (schema)

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

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

• src/server.ts:558-559 (registration)

  Tool registration in the central CallToolRequestSchema switch statement, routing calls to the handleDiscover function.

  case 'scp_discover':
    return await handleDiscover(args.domain as string);

• src/discovery/dns-lookup.ts:15-65 (helper)

  Supporting helper that performs the actual endpoint discovery via test override, demo mode, cache, DNS TXT (_scp._tcp.domain), or fallback HTTP methods.

  export async function discoverSCPEndpoint(domain: string): Promise<string | null> {
    // Check for test endpoint override first
    const testEndpoint = checkTestEndpoint(domain);
    if (testEndpoint) {
      return testEndpoint;
    }
  
    // Check for demo mode
    const config = loadConfig();
    if (config.demo_mode) {
      const demoEndpoint = config.demo_endpoint || 'https://demo.shoppercontextprotocol.io/v1';
      console.error(`[SCP] Demo mode enabled - using ${demoEndpoint} for all domains`);
      return demoEndpoint;
    }
  
    // Check cache first
    const cached = await getCachedEndpoint(domain);
    if (cached) {
      return cached.endpoint;
    }
  
    // Try DNS TXT record
    const dnsEndpoint = await tryDNSDiscovery(domain);
    if (dnsEndpoint) {
      // Cache the result
      await cacheEndpoint({
        domain,
        endpoint: dnsEndpoint,
        capabilities: null,
        discovered_at: Date.now(),
        ttl: 86400 // 24 hours
      });
      return dnsEndpoint;
    }
  
    // Try fallback methods
    const fallbackEndpoint = await tryFallbackDiscovery(domain);
    if (fallbackEndpoint) {
      // Cache the result
      await cacheEndpoint({
        domain,
        endpoint: fallbackEndpoint,
        capabilities: null,
        discovered_at: Date.now(),
        ttl: 86400 // 24 hours
      });
      return fallbackEndpoint;
    }
  
    return null;
  }