Card Agent

A conversational AI agent that helps users find, compare, and apply for credit cards. This project implements a hybrid architecture combining LLM-based language understanding with explicit workflow-driven business logic and tool integration. The system uses the FastMCP SDK for improved modularity, testability, and standardized AI application integration.

Architecture Overview

The Card Agent follows a CALM-inspired approach, separating natural language understanding/generation from structured workflows that manage business logic and tool calls. It uses the OpenAI API for language understanding and generation, with the FastMCP SDK available as a fallback option:

1. Orchestration Layer / Workflow Engine: Manages workflow activation, OpenAI API calls, tool calls, and session state
2. OpenAI Client: Communicates with the OpenAI API for intent recognition and response generation
3. FastMCP Client: (Legacy support) Uses the FastMCP SDK as a fallback option
4. Mock FastMCP Server: Provides a testing environment that implements the FastMCP protocol
5. Tool Abstraction Layer: Routes calls to specific tool implementations
6. Workflows: Structured processes for different user intents (recommendations, card details, comparisons, etc.)
7. Tools: Implementations for various functionalities (card data, credit score guidance, spending analysis, etc.)
8. Web Interface: Responsive chat UI with FAQ buttons for common questions and workflow visualization panel

Project Structure

card_agent/
├── app/                        # Main application code
│   ├── __init__.py             # Package initialization
│   ├── main.py                 # Flask app and API endpoints
│   ├── orchestrator.py         # Orchestration layer / workflow engine
│   ├── openai_client.py        # OpenAI API client implementation
│   ├── mcp_client.py           # FastMCP client implementation (legacy support)
│   ├── mock_mcp_server.py      # Mock FastMCP server implementation
│   ├── llm_services.py         # LLM service interaction (used by mock server)
│   ├── workflow_tracker.py     # Tracks conversation flow for visualization
│   ├── tool_abstraction.py     # Tool abstraction layer
│   ├── tools/                  # Tool implementations
│   │   ├── __init__.py
│   │   ├── chase_card_api.py   # Credit card data
│   │   ├── credit_score.py     # Credit score guidance
│   │   ├── spending_analyzer.py # Spending analysis
│   │   ├── comparison.py       # Card comparison
│   │   └── web_search.py       # Web search for application info
│   └── workflows/              # Workflow implementations
│       ├── __init__.py
│       ├── base_workflow.py    # Base workflow class
│       ├── workflow_registry.py # Maps intents to workflows
│       ├── recommendation_workflow.py # Card recommendation
│       ├── details_workflow.py # Card details
│       ├── comparison_workflow.py # Card comparison
│       ├── credit_score_workflow.py # Credit score guidance
│       ├── spending_analyzer_workflow.py # Spending analysis
│       ├── application_workflow.py # Application process
│       ├── general_info_workflow.py # General information
│       ├── greeting_workflow.py # Greeting/welcome
│       └── unclear_workflow.py  # Unclear/out-of-scope
├── static/                     # Frontend assets
│   ├── index.html              # Main HTML page with FAQ buttons
│   ├── css/                    # CSS stylesheets
│   │   └── style.css           # Main stylesheet
│   ├── js/                     # JavaScript files
│   │   └── chat.js             # Chat functionality
│   └── img/                    # Images
├── .env                        # Environment variables
├── requirements.txt            # Python dependencies
└── README.md                   # This file

Features

• Intent-Based Workflow Activation: Recognizes user intents and activates appropriate workflows
• Structured Parameter Collection: Workflows gather required parameters for tool calls
• Tool Abstraction: Consistent interface for calling various tools
• Session Management: Maintains conversation context and workflow state
• FastMCP Client-Server Architecture: Modular design with clear separation of concerns
• Mock FastMCP Server: Testing environment that simulates the FastMCP server
• Error Handling: Graceful handling of FastMCP server or tool failures
• Transparency: Clear disclaimers and explanations of agent capabilities
• Responsive UI: Mobile-friendly chat interface

Setup and Installation

1. Clone the repository:

   git clone <repository-url>
   

Configuration

OpenAI API Key

This application uses the OpenAI API for natural language understanding and generation. You need to provide your OpenAI API key in the .env file:

OPENAI_API_KEY=your_openai_api_key_here

You can obtain an API key by signing up at OpenAI's platform.

Environment Variables

The following environment variables can be configured in the .env file:

• OPENAI_API_KEY: Your OpenAI API key
• FLASK_SECRET_KEY: Secret key for Flask session management
• FASTMCP_SERVER_URL: URL of the FastMCP server (for legacy support)
• DEBUG: Set to True for development, False for production

Running the Application

1. Start the Flask server (this will also start the mock FastMCP server in a separate thread):

   python -m app.main
   

   This will start:

   • The main Flask application on port 5000
   • The mock FastMCP server on port 9000

2. Open your browser and navigate to:

   http://localhost:5000
   

3. Start chatting with the agent!

4. To test the FastMCP client independently, you can run:

   python test_mcp_client.py
   

   This will test all FastMCP client methods against the mock FastMCP server.

Development Notes

• FastMCP Server: Currently uses a mock implementation running on port 9000 for development and testing. The mock server provides both FastMCP SDK endpoints (under /mcp) and legacy HTTP endpoints (at the root). Replace with a real FastMCP server for production.

• FastMCP Client: Uses synchronous HTTP requests via httpx to communicate with the FastMCP server. The client supports listing resources, reading resource content, processing queries, and generating responses. It also includes a convenient process_and_generate method for one-step query processing and response generation.

• Environment Variables: Configuration is stored in the .env file, including the FastMCP server URL and port. Update these values as needed for your environment.

• Tool Implementations: Uses mock data for development. Integrate with real APIs for production.

• Session Storage: Uses in-memory storage for development. Implement persistent storage for production.

• Testing: The test_mcp_client.py script allows for testing all FastMCP client methods against the mock FastMCP server.

• Security: Implement proper authentication and authorization for production.

FastMCP Client-Server Architecture

The application has been refactored to use a FastMCP client-server architecture. FastMCP is a high-performance implementation of the Machine Comprehension Platform (MCP). For detailed information about the FastMCP integration, please refer to the MCP_INTEGRATION.md file.

• FastMCP Client: Handles communication with the FastMCP server using synchronous HTTP requests via httpx. It provides methods for listing resources, reading resource content, processing queries, and generating responses. The client also includes a convenient process_and_generate method for one-step query processing and response generation.

• Mock FastMCP Server: Provides a testing environment that implements both FastMCP SDK endpoints (under /mcp) and legacy HTTP endpoints (at the root). It runs on port 9000 in a separate thread alongside the main application.

• Orchestrator: Updated to use the FastMCP client for intent recognition and response generation, with improved error handling and fallback mechanisms.

This architecture provides several benefits:

1. Modularity: Clear separation between the client application and the server that handles AI processing.
2. Testability: The mock server allows for end-to-end testing without an actual FastMCP server.
3. Scalability: The FastMCP server can be deployed separately and scaled independently of the client application.
4. Flexibility: The FastMCP server implementation can be changed without affecting the client application.
5. Standardization: Uses the FastMCP SDK for consistent API interactions.

Example Interactions

• "What's the best Chase card for travel?"
• "Tell me about the Chase Sapphire Preferred card."
• "Compare the Sapphire Preferred and Sapphire Reserve."
• "What credit score do I need for Chase cards?"
• "I spend a lot on dining and groceries, what card is best?"
• "How do I apply for the Freedom Flex card?"
• "What are the benefits of Chase Ultimate Rewards?"

License

This project is for demonstration purposes only and is not affiliated with Chase Bank.

Disclaimer

This agent provides information about Chase credit cards for educational purposes only. It does not provide financial advice, and all information should be verified with Chase directly before making any financial decisions.