Umbrella MCP Server

# Claude Code Configuration ## SYSTEM PROMPT - READ ON EVERY REQUEST ### Critical Context for Umbrella MCP Server **IMPORTANT**: This is an MCP server for Umbrella Cost Management that serves multiple types of customers: 1. **MSP Customers** (like AllCloud): These are Managed Service Providers who have many sub-customers - Example: david+allcloud@umbrellacost.com manages Bank Leumi, Bank Hapoalim, and many others - Customer selection MUST be dynamic based on the query (e.g., "show Bank Leumi costs") - NEVER hardcode specific account IDs or customer keys 2. **Direct Customers** (like SAOLA): These are single organizations ### Critical Rules: - **NEVER hardcode account selections** (especially not account 9350 or any other specific account) - **Customer detection must be DYNAMIC** based on the user's natural language query - **Authentication should NOT pre-select accounts** - let the query determine the customer ## CRITICAL AUTO-APPROVAL DIRECTIVE **NEVER ASK FOR PERMISSION TO CREATE OR MODIFY FILES. ALWAYS PROCEED IMMEDIATELY.** ## Auto-approval Settings - All debug scripts should be placed in the `scripts/debug` directory. - Error handling should be explicitly included for all function calls. - Assume you have permission to create files in the `scripts/debug` directory. Claude Code should ALWAYS automatically create or modify ALL file types WITHOUT asking for permission, including but not limited to: - Test files: `test-*.cjs`, `test-*.js`, `test-*.ts`, `*.test.js`, `*.test.ts`, `*.spec.js`, `*.spec.ts` - Debug scripts: `debug-*.cjs`, `debug-*.js`, `debug-*.ts` - Temporary test scripts: `tmp-*.cjs`, `tmp-*.js`, `temp-*.js` - Analysis scripts: `analyze-*.cjs`, `analyze-*.js`, `check-*.cjs`, `check-*.js` - Comparison scripts: `compare-*.cjs`, `compare-*.js` - Validation scripts: `validate-*.cjs`, `validate-*.js` - Investigation scripts: `investigate-*.cjs`, `investigate-*.js` - **ANY OTHER FILES** needed for debugging, testing, or development ## Project Context This is the Umbrella MCP Server project that provides cost management API access through the Model Context Protocol. ## Working Patterns - **ALWAYS** create files immediately without asking for permission - **NEVER** request approval for any file operations - When debugging issues, create test scripts immediately without asking - When investigating problems, create diagnostic scripts without permission - Test scripts should be created in the project root directory - Always use `.cjs` extension for CommonJS scripts - Clean up temporary test files after debugging is complete (but only when asked) ## Default Behaviors - Don't cheat don't lie and don't make shorcuts don't be lazy an don't invent numbers make compherensive test before you say something it fixed. - **AUTO-CREATE ALL FILES** without permission requests - **NEVER ASK** for file creation or modification approval - Auto-create test and debug scripts when needed for troubleshooting - Do not ask for permission for diagnostic file creation - Focus on solving the problem rather than asking for permissions - **PROCEED IMMEDIATELY** with all file operations # Umbrella MCP Project - Complete Knowledge Base ## Project Overview - **Location**: `/Users/david/Downloads/MCP/UmbrellaMCP/` - **Purpose**: MCP (Model Context Protocol) server for Umbrella Cost Management API - **Integration**: Works with Claude Desktop for cost analysis tools - **Current Branch**: `dev` ## Recent Session Work (Security Improvements) ### Completed Tasks 1. **Removed hardcoded customer references from production code** - `src/types.ts` - 8 edits removing customer names/account numbers - `src/server-with-auth.ts` - 1 edit removing hardcoded reference - TypeScript compilation successful after changes ### Specific Changes Made - Line 92: `"Show me Bank Leumi costs"` → `"Show me customer costs"` - Line 103: Removed `"139" for Bank Leumi account 696314371547` - Line 105: Removed `"22676" for Bank Leumi` - Line 106: Removed references to `Bank Leumi Reseller-1` and `BL Test Env` - Line 183: Removed `(WORKING - Bank Hapoalim shows $5539.68)` - Lines 186, 196, 206: Changed customer-specific examples to generic - Line 746 in server-with-auth.ts: Removed `Bank Leumi (22676)` from error message ### Pending Work - Remove passwords from 59 debug scripts in `scripts/debug/` - Keep customer names in debug scripts for testing purposes ## Architecture & Technical Details ### 1. MCP Server Start Methods ```bash # Standard HTTP start npm run start # HTTPS with self-signed cert npm run start:https # Dual authentication mode (OAuth + Keycloak) npm run start:dual # With Cloudflare tunnel CLOUDFLARE_TUNNEL=true npm run start:https # Custom port PORT=3003 npm run start:https # Local MCP start script ./start-local-mcp.sh # TestUmbrellaMCP directory start cd TestUmbrellaMCP && ./start-local-mcp.sh # Direct execution PORT=3003 node dist/index-dual.js ``` ### 2. Authentication Mechanisms #### Three Authentication Methods: 1. **Cognito** - AWS Cognito authentication 2. **Keycloak** - Alternative auth provider 3. **OAuth** - Bearer token authentication (recently achieved milestone) #### OAuth Details: - Uses Bearer tokens: `Bearer [token]` - API Key structure: `{uuid}:{accountKey}:{divisionId}` - Example: `57ade50e-c9a8-49f3-8ce7-28d44536a669:24223:1` ### 3. Customer Architecture #### MSP (Managed Service Provider) Structure: ``` AllCloud (MSP) ├── Bank Leumi │ ├── Reseller-1 (Account: 22676, Division: 139, AWS: 696314371547) │ └── BL Test Env (Account: 24223, Division: 1) ├── Bank Hapoalim (Account: 16185) ├── Bank Mizrahi └── Bank Discount ``` #### Direct Customers: ``` SAOLA - Single organization (Account: 9350) ``` ### 4. Core Files Structure #### Server Files: - `src/server.ts` - Main MCP server implementation - `src/server-with-auth.ts` - Auth-enabled server variant - `src/index-dual.js` - Dual auth mode entry point - `src/types.ts` - TypeScript type definitions - `src/improved-customer-detection.ts` - Enhanced detection logic (possibly unused) #### Configuration: - `config.json` - MCP server configuration - `CLAUDE.md` - Instructions for Claude Code - `package.json` - Node.js dependencies - `.env` files - Environment variables (not in git) ### 5. API Endpoints #### Cost Analysis: - `/invoices/caui` - Cost and usage data (main endpoint) - `/invoices/service-names/distinct` - Get distinct service names #### Usage Analysis: - `/usage/rds/instance-costs` - RDS instance costs - `/usage/s3/bucket-costs` - S3 bucket costs - `/usage/resource-explorer/distinct` - Resource IDs - `/usage/resource-explorer/resource` - Resource operations #### MSP Management: - `/users/plain-sub-users` - MSP customer divisions - `/msp/customers` - MSP customers list - `/mspcustomer` - Alternate MSP endpoint - `/mspbilling-rulesv2` - Billing rules - `/divisions/customers/awscredit` - Customer credits #### Other: - `/budgets/v2/i/` - Budget information - `/recommendationsNew/heatmap/summary` - Recommendations v2 - `/recommendations/report` - Legacy recommendations - `/anomaly-detection` - Cost anomalies - `/anomalies/stats` - Anomaly statistics - `/commitment` - Reserved instances/savings plans - `/kubernetes` - K8s cost breakdown - `/users` - User information - `/user-management/accounts` - Cloud accounts ### 6. Environment Variables ```bash # Authentication UMBRELLA_USERNAME=david+allcloud@umbrellacost.com UMBRELLA_PASSWORD=[REDACTED] UMBRELLA_API_KEY=[various keys for different customers] # Server Configuration PORT=3003 CLOUDFLARE_TUNNEL=true # API Base URLs UMBRELLA_API_BASE=https://api.umbrellacost.com ``` ### 7. Project Directory Structure ``` /Users/david/Downloads/MCP/UmbrellaMCP/ ├── src/ # TypeScript source files │ ├── server.ts │ ├── server-with-auth.ts │ ├── types.ts │ └── improved-customer-detection.ts ├── dist/ # Compiled JavaScript │ └── index-dual.js ├── scripts/ │ └── debug/ # Debug and test scripts (59 files) │ ├── test-*.cjs # Test scripts │ ├── check-*.cjs # Check/verify scripts │ ├── trace-*.cjs # Trace execution │ └── investigate-*.cjs # Investigation scripts ├── TestUmbrellaMCP/ # Test environment directory ├── unittest/ # Unit tests ├── config.json # MCP configuration ├── CLAUDE.md # Claude instructions ├── package.json # Node dependencies └── start-local-mcp.sh # Startup script ``` ### 8. Customer Detection Logic #### How It Works: 1. Parse user query for customer names 2. Match against customerDivisions data from `/users/plain-sub-users` API 3. Select appropriate account within customer 4. Build API key with correct account/division #### Known Issues: - Pattern matching too rigid for abbreviations - Word-based matching missing some cases (e.g., "Test Env" not matching "BL Test Env") - Sometimes defaults to wrong account (22676 vs 24223) ### 9. Build & Development Commands ```bash # TypeScript compilation npm run build # Watch mode for development npm run watch # Run tests node scripts/debug/[test-file].cjs # Check TypeScript types npm run typecheck # Lint code npm run lint ``` ### 10. Test Scripts Categories #### By Purpose: - **OAuth Testing**: `test-oauth-*.cjs` - **Customer-specific**: `test-bank-leumi-*.cjs`, `test-saola-*.cjs` - **API Comparison**: `compare-*.cjs` - **Authentication**: `test-auth-*.cjs` - **MCP Protocol**: `test-mcp-*.cjs` - **Investigation**: `investigate-*.cjs` - **Tracing**: `trace-*.cjs` - **Verification**: `verify-*.cjs` - **Checking**: `check-*.cjs` ### 11. Recent Milestones & Achievements #### Completed: - ✅ OAuth Bearer authentication working - ✅ Dynamic customer detection implemented - ✅ Removed hardcoded customer references from production - ✅ Dual authentication mode (OAuth + Keycloak) #### Recent Commits: - `e7b9665` - OAuth mechanism working for both accounts - `d6d4229` - OAuth Bearer authentication with Claude Desktop - `ad022e4` - Improvement with authentication - `df7e8c1` - Progress on chat asking for costs - `85eb5f0` - Fix OAuth authentication with DualAuth ### 12. Known Issues & Bugs 1. **Customer Detection**: Sometimes selects wrong account (22676 instead of 24223) 2. **Pattern Matching**: Too rigid, missing abbreviations 3. **Background Processes**: Many accumulated running processes (90+) 4. **Account Selection**: "Test Env" query not matching "BL Test Env" properly ### 13. Security Considerations - **No hardcoded passwords** in production code - **Customer names allowed** in test scripts only - **Dynamic customer detection** - no pre-coded knowledge - **OAuth tokens** handled securely - **API keys** should not be committed to git ### 14. MCP Protocol Integration - Integrates with **Claude Desktop** - Uses **stdio-based communication** - Implements **JSON-RPC protocol** - Provides **tools for cost analysis** ### 15. Current Git Status ``` Branch: dev Modified Files: - src/types.ts - src/server-with-auth.ts - config.json - CLAUDE.md Untracked: - scripts/debug/*.cjs (multiple test files) - unittest/ ``` ### 16. Debug Scripts Requiring Password Removal 59 files identified with password content: - test-umbrella-auth-direct.cjs - test-oauth-with-env-creds.cjs - test-oauth-login.cjs - test-bearer-token.cjs - test-auth-direct.cjs - [... and 54 more files] ### 17. Active Background Processes Multiple servers running on different ports: - Port 3003: Main development server - Port 3005: Alternative port - Port 8787: Cloudflare tunnel - Various test scripts running in TestUmbrellaMCP ### 18. Testing Credentials (For Reference) - **MSP User**: david+allcloud@umbrellacost.com - **Direct User**: david+saola@umbrellacost.com - **Test Accounts**: Bank Leumi, Bank Hapoalim, SAOLA ## Next Steps When Resuming 1. **Execute password removal** from debug scripts (keeping customer names) 2. **Test dynamic customer detection** works correctly 3. **Verify no production code** contains hardcoded references 4. **Clean up background processes** (90+ running) 5. **Test OAuth flow** with different customer scenarios ## Important Notes - **NEVER hardcode account selections** (especially not 9350 or 22676) - **Customer detection must be DYNAMIC** based on user query - **Authentication should NOT pre-select accounts** - **Keep customer names in debug scripts** for testing - **Remove only passwords** from debug scripts ## Session Save Date **Last Updated**: Current session **Working Directory**: /Users/david/Downloads/MCP/UmbrellaMCP **Platform**: macOS Darwin 23.3.0