SCP Local MCP Server

Instructions

Implementation Reference

• src/server.ts:828-848 (handler)

  The MCP tool handler for scp_get_orders. Checks authorization, retrieves valid access token, calls SCP client to fetch orders, and returns JSON-formatted response.

   * Tool handler: scp_get_orders
   */
  async function handleGetOrders(domain: string, params: any) {
    const { auth, accessToken } = await checkAuthorizationOrThrow(domain);
    const token = await accessToken;
  
    const data = await scpClient.getOrders(auth.scp_endpoint, token, {
      limit: params.limit || 10,
      offset: params.offset || 0,
      status: params.status
    });
  
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(data, null, 2)
        }
      ]
    };
  }

• src/server.ts:371-397 (schema)

  Input schema and description for the scp_get_orders tool, defining parameters domain (required), limit, offset, status.

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

• src/server.ts:561-562 (registration)

  Tool handler registration in the CallToolRequestSchema switch statement dispatching to handleGetOrders.

  case 'scp_get_orders':
    return await handleGetOrders(args.domain as string, args);

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

  Helper function that checks if authorized for the domain and returns auth info and access token promise, or throws detailed error.

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

• src/http/client.ts:94-100 (helper)

  HTTP client helper that wraps the generic JSON-RPC request specifically for the 'scp.get_orders' method.

  export async function getOrders(
    endpoint: string,
    accessToken: string,
    params?: { limit?: number; offset?: number; status?: string[] }
  ): Promise<any> {
    return makeRPCRequest(endpoint, accessToken, 'scp.get_orders', params);
  }