MCP Sigmund

# User Guide This document provides comprehensive information for users of MCP Sigmund. ## ⚠️ IMPORTANT LEGAL DISCLAIMER **MCP Sigmund is a learning resource and data analysis tool, NOT a financial advisor.** ### 🚫 **NOT FINANCIAL ADVICE** - **This system does NOT provide financial advice, recommendations, or guidance** - **All insights, analysis, and suggestions are for educational purposes only** - **Users must make their own financial decisions based on their own research and judgment** - **No information from this system should be considered as investment, tax, or financial advice** ### 📚 **Educational Purpose Only** - **MCP Sigmund is designed as a learning resource for understanding personal financial data** - **The system helps users analyze and understand their financial patterns and trends** - **All outputs are intended for educational and informational purposes** - **Users should consult qualified financial professionals for actual financial advice** ### ⚖️ **Regulatory Compliance** - **This system complies with educational tool regulations, not financial advisory regulations** - **No fiduciary relationship is created between the system and users** - **Users retain full responsibility for all financial decisions and their consequences** - **The system does not hold any financial licenses or registrations** ### 🔒 **User Responsibility** - **Users are solely responsible for their financial decisions and actions** - **All financial risks remain with the user** - **Users should verify all information independently** - **Professional financial advice should be sought for important financial decisions** ### 📋 **Limitations** - **Past performance does not guarantee future results** - **Financial markets and personal circumstances change** - **The system may not account for all relevant factors** - **Data accuracy depends on user-provided information** **By using MCP Sigmund, you acknowledge and agree to these terms and understand that this is an educational tool, not a financial advisory service.** ## Configuration with Claude Desktop To use this MCP server with Claude Desktop: 1. Locate your Claude Desktop configuration file: - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` - Windows: `%APPDATA%\\Claude\\claude_desktop_config.json` 2. Add the MCP Sigmund server to your configuration: ```json { "mcpServers": { "sigmund": { "command": "node", "args": [ "/path/to/mcp-sigmund/build/src/index.js" ] } } } ``` Replace `/path/to/mcp-sigmund` with the actual path to this project on your system. ## Smart Formatting & User Experience MCP Sigmund features intelligent formatting that automatically adapts to user context: ### 🎯 **Context Detection** - **Simple queries**: "show balance" → Clean, single balance display - **Recent transactions**: `limit ≤ 10` → User-friendly transaction list - **Analysis queries**: "spending analysis" → Visual breakdown with insights - **Professional context**: "for taxes/accountant" → Detailed professional format - **Developer context**: "raw data/api" → Full technical details ### 🎨 **Display Hints** Every response includes intelligent formatting guidance: ```json { "display_hint": "recent_transactions", "user_profile": "retail_banking", "suggested_format": { "show_account_number": "hidden", "currency_format": "symbol", "transaction_display": "simple", "date_format": "relative" }, "context_hints": [ "Show last few transactions in simple format", "Use 'Today', 'Yesterday', '3 days ago' for dates", "Focus on merchant names and amounts" ] } ``` ### 🔄 **Progressive Disclosure** - **Default experience**: Simple, clean formatting for 90% of users - **Context-aware**: Automatically adapts based on user intent - **No configuration needed**: Users never see formatting options - **Power user support**: Full technical details available when needed ## Available Tools ### Banking Query Tool (`banking_query`) Main tool for financial analysis and data retrieval: - **`accounts`** - Get account information and balances - **`transactions`** - Retrieve transaction history with filtering - **`balance`** - Get account balances with summary - **`overview`** - Financial overview across all providers - **`spending_analysis`** - Analyze spending patterns by category - **`cashflow_analysis`** - Monthly cash flow analysis - **`providers`** - List available data providers ### Data Query Tool (`data_query`) Data management and system operations: - **`get_stats`** - Database statistics and health - **`validate_data`** - Data integrity validation - **`export_data`** - Export data in various formats - **`cleanup_data`** - Data maintenance operations ### Performance Monitor Tool (`performance_monitor`) System monitoring and performance: - **`get_metrics`** - Query performance metrics - **`clear_metrics`** - Clear performance history - **`get_health`** - Database health status - **`get_system_stats`** - System resource usage ## Key Behaviors - **🌐 ALL Providers Default**: When no provider is specified, queries ALL providers by default - **🎯 Smart Formatting**: Automatically provides user-friendly formatting based on context - **🔄 Context Detection**: Recognizes user intent and adapts response format - **📊 Unified Data Format**: All data is normalized across providers with common fields - **🏷️ Provider-Specific Metadata**: Additional provider-specific data in metadata fields - **🔍 Comprehensive Filtering**: Support for date ranges, categories, accounts, and limits ## Example User Experience ### Default Experience (90% of users): ``` User: "show me my balance" AI Response: "Your current balance is €1,400.95" ``` ### Recent Transactions: ``` User: "show my last 2 transactions" AI Response: - Aug 29: Card payment - €175.98 - Aug 25: RCHNR 4567890 - €199.00 ``` ### Spending Analysis: ``` User: "analyze my spending" AI Response: "You spent €7,220.19 in the last 3 months, mostly in 'other' category (26 transactions)" ``` ### Professional Context: ``` User: "transactions for my accountant" AI Response: [Automatically switches to professional format with full details] ``` ## Example Queries Here are some example queries you can ask: ### Simple Queries - "Show me my balance" → Uses `banking_query` with `balance` - "What's my account balance?" → Uses `banking_query` with `balance` ### Transaction Queries - "Show my last 5 transactions" → Uses `banking_query` with `transactions` - "List my recent transactions" → Uses `banking_query` with `transactions` ### Analysis Queries - "What are my spending patterns for the last 3 months?" → Uses `banking_query` with `spending_analysis` - "Show me cash flow analysis" → Uses `banking_query` with `cashflow_analysis` - "Give me a financial overview" → Uses `banking_query` with `overview` ### System Queries - "What providers do I have data from?" → Uses `banking_query` with `providers` - "Show database statistics" → Uses `data_query` with `get_stats` ### Professional Queries - "Export my transactions for my accountant" → Uses `data_query` with `export_data` - "Generate a report for tax purposes" → Automatically switches to professional format ## Clean JSON Responses MCP Sigmund provides clean, structured JSON responses that Claude can easily process and format: ### 🎯 **Structured Data** - **Consistent format**: All responses follow the same JSON structure - **Rich metadata**: Includes display hints and formatting suggestions - **Smart formatting**: Intelligent defaults with progressive disclosure - **Context-aware**: Adapts response format based on query type ### 📊 **Data Quality** - **Normalized data**: Consistent field names across all providers - **Enhanced descriptions**: Simplified transaction descriptions for better UX - **Formatted values**: Currency and date formatting included - **Provider metadata**: Additional context from banking providers ### 🔧 **Technical Features** - **Type-safe**: Full TypeScript support with comprehensive interfaces - **Error handling**: Robust validation and error management - **Performance**: Optimized database queries with proper indexing - **Extensible**: Easy to add new query types and data sources ## Data Structure The PostgreSQL database contains: - **📊 Normalized banking data** with proper relational structure - **💳 Enhanced transaction data** with merchant info, location, and categorization - **🏦 Multiple account types** with various balance types - **🔄 Real-time calculated analytics** from transaction data - **🌐 Provider-agnostic format** with consistent field names - **📈 Rich metadata** stored in JSONB fields for flexibility ## Troubleshooting ### Common Issues **Connection Issues:** - Verify PostgreSQL is running - Check connection string in `src/auth.ts` - Ensure database exists and is accessible **Configuration Issues:** - Make sure `src/auth.ts` exists (copy from `src/auth.example.ts`) - Verify all required environment variables are set - Check file permissions **Performance Issues:** - Monitor database connection pool usage - Check query performance metrics - Verify proper indexing is in place ### Getting Help 1. Check the logs for error messages 2. Verify your configuration matches the examples 3. Ensure all dependencies are installed 4. Check the database connection and schema ## Security Considerations - **🔐 Database Access**: PostgreSQL database contains sensitive financial data - secure appropriately - **🛡️ Configuration**: Never commit `src/auth.ts` to version control (already in .gitignore) - **✅ Validation**: All inputs are validated with comprehensive error handling - **🔒 Data Privacy**: Ensure compliance with financial data regulations - **🚪 Access Control**: Consider implementing authentication for production use - **🔑 Credential Management**: Use environment variables or secure credential stores in production