Occams-Om/AICFO-MCP-SERVER

📊 Occams CFO - AI-Powered Financial Analysis Platform

A comprehensive CFO-grade financial analysis platform powered by OpenAI and the Model Context Protocol (MCP). Upload your QuickBooks CSV exports and get detailed, board-level financial reports with actionable insights.

✨ Features

• AI-Powered Analysis: Uses OpenAI GPT models to generate comprehensive CFO reports
• MCP Integration: Leverages Model Context Protocol for reliable tool execution
• Code Interpreter: Dynamic Python code execution for custom financial calculations
• 40+ Pre-built Metrics: Instant calculation of key financial indicators
• Board-Ready Reports: 10-12 page detailed analysis suitable for board presentations
• Interactive Web UI: Easy-to-use Streamlit interface for file uploads and report generation

🏗️ Architecture

┌─────────────────────────────────────────────────────────┐
│                    Streamlit Web UI                      │
│         (streamlit_app.py / streamlit_app_with_...)     │
└─────────────────────────┬───────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│              OpenAI Agent (GPT-4/GPT-4o)                │
│                  with MCP Tool Access                    │
└─────────────────────────┬───────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│                MCP Server (FastMCP)                      │
│        occams_cfo_server.py / ..._with_code_interpreter │
│                                                          │
│  Available Tools:                                        │
│  ├── calculate_financial_metrics()                      │
│  ├── build_cfo_report_context()                         │
│  ├── profile_csvs()                                     │
│  └── code_interpreter() (enhanced version)              │
└─────────────────────────────────────────────────────────┘

📁 Project Structure

occams-cfo/
├── README.md                                    # This file
├── requirements.txt                             # Python dependencies
├── .env.example                                 # Environment variables template
│
├── streamlit_app.py                            # Standard Streamlit UI
├── streamlit_app_with_code_interpreter.py      # Enhanced UI with code execution
│
├── occams_cfo_server.py                        # Standard MCP server
├── occams_cfo_server_with_code_interpreter.py  # Enhanced MCP server with code interpreter
│
├── cfo-agent.py                                # Command-line agent runner
├── multi_csv_profiler.py                       # CSV profiling utilities
├── test_code_interpreter.py                    # Test script for code interpreter
│
├── data/                                       # Sample data directory
│   ├── AR_Aging.csv
│   ├── AP_Aging.csv
│   ├── Balance_Sheet.csv
│   ├── Profit_and_Loss.csv
│   ├── Cash_Flow.csv
│   └── General_Ledger.csv
│
├── uploaded_data/                              # Standard app uploads
└── uploaded_data_code_interpreter/             # Enhanced app uploads

🚀 Quick Start

Prerequisites

• Python 3.10 or higher
• OpenAI API key with access to GPT-4 or GPT-4o

Installation

1. Clone the repository

   git clone https://github.com/yourusername/occams-cfo.git
   cd occams-cfo
   

2. Create and activate a virtual environment (recommended)

   python -m venv venv
   
   # On macOS/Linux
   source venv/bin/activate
   
   # On Windows
   venv\Scripts\activate
   

3. Install dependencies

   pip install -r requirements.txt
   

4. Set up your OpenAI API key

   Option A - Environment variable:

   export OPENAI_API_KEY="sk-your-api-key-here"
   

   Option B - Create a .env file:

   echo 'OPENAI_API_KEY=sk-your-api-key-here' > .env
   

   Option C - Enter directly in the Streamlit app sidebar

Running the Application

Option 1: Streamlit Web Interface (Recommended)

Standard Version:

streamlit run streamlit_app.py

Enhanced Version with Code Interpreter:

streamlit run streamlit_app_with_code_interpreter.py

Then open your browser to http://localhost:8501

Option 2: Command Line

python cfo-agent.py --data-dir ./data

For enhanced version:

python cfo-agent.py --data-dir ./data --server-script ./occams_cfo_server_with_code_interpreter.py

📊 Required CSV Files

Your QuickBooks exports should include these files:

Expected CSV Format

AR/AP Aging files should have columns:

• Customer/Vendor, Current, 1-30, 31-60, 61-90, >90, Total

Balance Sheet should have columns:

• Month, Cash, AR, Inventory, Fixed Assets, Total Assets, AP, Credit Cards, Loans, Owner's Equity

Profit & Loss should have columns:

• Month, Revenue, COGS, Gross Profit, Operating Expenses, Operating Income, Net Income

🔧 Configuration

Environment Variables

Model Settings

The default model is configured in the agent setup. To change it, modify the model parameter in the Agent initialization:

agent = Agent(
    name="Occams CFO Agent",
    model="gpt-4o",  # or "gpt-4", "gpt-4-turbo"
    ...
)

📈 What You Get

The generated CFO report includes:

1. Executive Summary - High-level overview of financial health
2. Trends and Patterns - Analysis of financial trajectories
3. Risks and Concerns - Identified financial risks with severity ratings
4. Wins and Opportunities - Positive developments and growth opportunities
5. Path to Profitability - Strategic roadmap with specific targets
6. CFO Recommendations - Prioritized action items with timelines
7. KPIs to Monitor - Key metrics with target values
8. Financial Projections - Scenario-based forecasts

Sample Metrics Calculated

• Liquidity: Current ratio, working capital, cash position
• AR Analysis: Total AR, aging breakdown, customer concentration
• AP Analysis: Total AP, aging breakdown, vendor count
• Profitability: Gross margin, operating margin, net margin
• Growth: Revenue growth, gross profit growth
• Leverage: Debt-to-equity, debt-to-assets ratios
• Efficiency: DSO, DPO, cash conversion cycle (enhanced version)

🧮 Standard vs Enhanced Version

🔒 Security

• API keys are never stored or logged
• Code interpreter runs in a sandboxed environment
• Only pandas and numpy available in code execution
• CSV files are read-only during analysis
• No network access from code interpreter

🐛 Troubleshooting

"OPENAI_API_KEY not set"

# Set the environment variable
export OPENAI_API_KEY="sk-your-key-here"

# Or enter it in the Streamlit sidebar

"MCP server failed to start"

# Test the server directly
python occams_cfo_server.py
# Should wait for input (Ctrl+C to exit)

"Missing required files"

Ensure your CSV files contain the keywords:

• AR Aging: filename contains "ar" and "aging"
• AP Aging: filename contains "ap" and "aging"
• Balance Sheet: filename contains "balance" and "sheet"
• P&L: filename contains "profit" and "loss" (or "p&l")

"Column not found"

Check that your CSV files have the expected column names. The system expects QuickBooks-style exports.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the file for details.

🙏 Acknowledgments

• OpenAI Agents SDK - For the powerful agent framework
• FastMCP - For the MCP server implementation
• Streamlit - For the beautiful web interface
• Model Context Protocol - For the tool integration standard

📞 Support

If you encounter any issues or have questions:

1. Check the Troubleshooting section
2. Open an Issue
3. Review existing issues for solutions

Built with ❤️ by Occams Advisory