Kroger MCP Server

Instructions

    Start the OAuth authentication flow with Kroger.
    
    This tool returns a URL that the user needs to open in their browser
    to authenticate with Kroger. After authorization, the user will be
    redirected to a callback URL that they need to copy and paste back.
    
    Returns:
        Dictionary with authorization URL and instructions
    

Implementation Reference

• src/kroger_mcp/tools/auth.py:28-88 (handler)

  Handler function for start_authentication tool. Generates PKCE parameters, builds OAuth authorization URL for Kroger API, and provides user instructions for the browser-based flow.

  @mcp.tool()
  async def start_authentication(ctx: Context = None) -> Dict[str, Any]:
      """
      Start the OAuth authentication flow with Kroger.
      
      This tool returns a URL that the user needs to open in their browser
      to authenticate with Kroger. After authorization, the user will be
      redirected to a callback URL that they need to copy and paste back.
      
      Returns:
          Dictionary with authorization URL and instructions
      """
      global _pkce_params, _auth_state
      
      # Generate PKCE parameters
      _pkce_params = generate_pkce_parameters()
      
      # Generate a state parameter for CSRF protection
      _auth_state = _pkce_params.get('state', _pkce_params.get('code_verifier')[:16])
      
      # Get client_id and redirect_uri from environment
      client_id = os.environ.get("KROGER_CLIENT_ID")
      redirect_uri = os.environ.get("KROGER_REDIRECT_URI", "http://localhost:8000/callback")
      
      if not client_id:
          if ctx:
              await ctx.error("Missing KROGER_CLIENT_ID environment variable")
          return {
              "error": True,
              "message": "Missing KROGER_CLIENT_ID environment variable. Please set up your Kroger API credentials."
          }
      
      # Initialize the Kroger API client
      kroger = KrogerAPI()
      
      # Scopes needed for Kroger API (cart.basic:write is needed for cart operations)
      scopes = "product.compact cart.basic:write"
      
      # Get the authorization URL with PKCE
      auth_url = kroger.authorization.get_authorization_url(
          scope=scopes,
          state=_auth_state,
          code_challenge=_pkce_params["code_challenge"],
          code_challenge_method=_pkce_params["code_challenge_method"]
      )
      
      if ctx:
          await ctx.info(f"Generated auth URL with PKCE: {auth_url}")
      
      return {
          "auth_url": auth_url,
          "instructions": (
              "1. Click this link to authorize: [🔗 Authorize Kroger Access]({auth_url})\n"
              "   - Please present the authorization URL as a clickable markdown link\n"
              "2. Log in to your Kroger account and authorize the application\n"
              "3. After authorization, you'll be redirected to a callback URL\n"
              "4. Copy the FULL redirect URL from your browser's address bar\n"
              "5. Use the complete_authentication tool with that URL to complete the process"
          ).format(auth_url=auth_url)
      }

• src/kroger_mcp/tools/auth_tools.py:7-10 (registration)

  Registers the authentication tools by delegating to auth.register_auth_tools(mcp). This is called from server.py.

  def register_tools(mcp):
      """Register authentication tools with the FastMCP server"""
      register_auth_tools(mcp)

• src/kroger_mcp/server.py:78-78 (registration)

  Site where auth_tools.register_tools is invoked during server initialization, registering the start_authentication tool.

  auth_tools.register_tools(mcp)

• src/kroger_mcp/tools/auth.py:25-27 (registration)

  Function that defines and registers both start_authentication and complete_authentication tools using @mcp.tool() decorators.

  def register_auth_tools(mcp):
      """Register authentication-specific tools with the FastMCP server"""