Card Agent With Fastmcp And Conv Flow
card_agent_with_fastmcp_and_conv_flow
Ask AI about Card Agent With Fastmcp And Conv Flow
Powered by Claude Β· Grounded in docs
I know everything about Card Agent With Fastmcp And Conv Flow. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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:
- Orchestration Layer / Workflow Engine: Manages workflow activation, OpenAI API calls, tool calls, and session state
- OpenAI Client: Communicates with the OpenAI API for intent recognition and response generation
- FastMCP Client: (Legacy support) Uses the FastMCP SDK as a fallback option
- Mock FastMCP Server: Provides a testing environment that implements the FastMCP protocol
- Tool Abstraction Layer: Routes calls to specific tool implementations
- Workflows: Structured processes for different user intents (recommendations, card details, comparisons, etc.)
- Tools: Implementations for various functionalities (card data, credit score guidance, spending analysis, etc.)
- 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
- 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 keyFLASK_SECRET_KEY: Secret key for Flask session managementFASTMCP_SERVER_URL: URL of the FastMCP server (for legacy support)DEBUG: Set toTruefor development,Falsefor production
Running the Application
-
Start the Flask server (this will also start the mock FastMCP server in a separate thread):
python -m app.mainThis will start:
- The main Flask application on port 5000
- The mock FastMCP server on port 9000
-
Open your browser and navigate to:
http://localhost:5000 -
Start chatting with the agent!
-
To test the FastMCP client independently, you can run:
python test_mcp_client.pyThis 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
httpxto communicate with the FastMCP server. The client supports listing resources, reading resource content, processing queries, and generating responses. It also includes a convenientprocess_and_generatemethod for one-step query processing and response generation. -
Environment Variables: Configuration is stored in the
.envfile, 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.pyscript 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 convenientprocess_and_generatemethod 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:
- Modularity: Clear separation between the client application and the server that handles AI processing.
- Testability: The mock server allows for end-to-end testing without an actual FastMCP server.
- Scalability: The FastMCP server can be deployed separately and scaled independently of the client application.
- Flexibility: The FastMCP server implementation can be changed without affecting the client application.
- 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.
