MCP ChatGPT Multi-Server Suite

# ✅ Setup Complete! ## 🎉 Your MCP ChatGPT App is Ready! ### Project Structure ``` MCPAddIn/ ├── src/ │ └── server.ts # MCP Server with Express & topMovers tool ├── public/ │ └── index.html # ChatGPT App frontend with responsive UI ├── dist/ # Compiled JavaScript ├── package.json # Dependencies ├── tsconfig.json # TypeScript configuration ├── start.sh # Easy startup script ├── ngrok.sh # ngrok tunnel script ├── QUICKSTART.md # Quick start guide └── README.md # Full documentation ``` ## 🚀 Next Steps ### 1. Get Your Alpha Vantage API Key **Option A: Free API Key (Recommended)** ```bash # Get your free key at: https://www.alphavantage.co/support/#api-key export ALPHA_VANTAGE_API_KEY=your_api_key_here ``` **Option B: Use Demo Key (Limited)** ```bash export ALPHA_VANTAGE_API_KEY=demo # Note: Demo key has very limited requests ``` ### 2. Start the Server ```bash ./start.sh ``` The server will start on `http://localhost:3000` ### 3. View in Browser Open your browser and navigate to: ``` http://localhost:3000 ``` You should see: - 🚀 **Top Gainers** table with the biggest stock winners - 📉 **Top Losers** table with the biggest stock losers - 🔥 **Most Actively Traded** table with highest volume stocks ### 4. (Optional) Expose via ngrok In a **new terminal window**: ```bash ./ngrok.sh ``` This will give you a public URL like `https://abc123.ngrok.io` that you can share or integrate with ChatGPT. ## 🛠️ Features Implemented ✅ **MCP Server Integration** - Uses `@modelcontextprotocol/sdk` - Exposes `topMovers` tool - REST API endpoints for tool calling ✅ **Alpha Vantage Integration** - Hits `TOP_GAINERS_LOSERS` endpoint - Returns top gainers, losers, and most actively traded - Configurable result limits ✅ **ChatGPT App Frontend** - Calls `window.openai.callTool('topMovers', { limit })` on load - Responsive tables with DaisyUI + Tailwind CSS - Dark mode theme - Anime.js animations - Auto-refresh functionality ✅ **Express Server** - Serves static frontend - Handles MCP tool calls - CORS enabled - Error handling ✅ **Development Tools** - TypeScript for type safety - Auto-build scripts - Development mode with hot reload - Helper scripts for easy startup ## 📊 How to Use the App ### Basic Usage 1. **Auto-load**: Data loads automatically when you open the page 2. **Adjust Results**: Use the number input to show more/fewer results (1-20) 3. **Refresh**: Click the 🔄 Refresh button to get updated data ### API Integration The app exposes these endpoints: **List Tools:** ```bash GET http://localhost:3000/mcp/tools/list ``` **Call Tool:** ```bash POST http://localhost:3000/mcp/tools/call Content-Type: application/json { "name": "topMovers", "arguments": { "limit": 10 } } ``` ### window.openai.callTool In the ChatGPT app context: ```javascript const data = await window.openai.callTool('topMovers', { limit: 10 }); // Returns: { top_gainers: [...], top_losers: [...], most_actively_traded: [...] } ``` ## 🎨 UI Features - **Dark Mode**: Beautiful gradient hero section with purple theme - **Responsive Tables**: Works on desktop, tablet, and mobile - **Color Coding**: - Green for positive changes - Red for negative changes - **Animations**: - Loading dots animation - Smooth fade-in for tables - Staggered row animations - **Live Updates**: Metadata shows last update time ## 🔧 Development Commands ```bash # Install dependencies npm install # Build TypeScript npm run build # Development mode (auto-reload) npm run dev # Production mode npm start # Watch mode (auto-build on changes) npm run watch ``` ## 📝 Environment Variables ```bash # Required export ALPHA_VANTAGE_API_KEY=your_key_here # Optional export PORT=3000 # Default: 3000 ``` ## 🌐 ngrok Integration ngrok allows you to expose your local server to the internet: 1. **Install ngrok** (if not already installed): ```bash brew install ngrok # or download from https://ngrok.com/download ``` 2. **Start your server** (Terminal 1): ```bash ./start.sh ``` 3. **Start ngrok** (Terminal 2): ```bash ./ngrok.sh ``` 4. **Copy the public URL**: ``` https://abc123.ngrok.io ``` 5. **Share or integrate** with ChatGPT! ## 📚 Documentation - **QUICKSTART.md**: Quick 3-step guide to get running - **README.md**: Full documentation with architecture details - **env.example**: Example environment variables ## ⚡ Quick Test Test the API directly: ```bash # Set your API key export ALPHA_VANTAGE_API_KEY=your_key_here # Start server ./start.sh # In another terminal, test the endpoint curl -X POST http://localhost:3000/mcp/tools/call \ -H "Content-Type: application/json" \ -d '{"name":"topMovers","arguments":{"limit":5}}' ``` ## 🎯 What's Next? Your app is fully functional! You can: 1. **Customize the UI**: Edit `public/index.html` to change colors, layout, etc. 2. **Add More Tools**: Extend `src/server.ts` with additional MCP tools 3. **Add Charts**: Integrate Chart.js or similar for visualizations 4. **Add Filtering**: Allow users to filter by sector, market cap, etc. 5. **Add Favorites**: Let users save their favorite stocks ## 🐛 Troubleshooting **Server won't start:** - Check if port 3000 is in use: `lsof -i :3000` - Use a different port: `PORT=3001 ./start.sh` **API Key issues:** - Verify it's set: `echo $ALPHA_VANTAGE_API_KEY` - Check it's valid at https://www.alphavantage.co/ - Make sure to export it in your terminal **No data showing:** - Open browser console (F12) for errors - Check server logs for API errors - Verify Alpha Vantage API is working **ngrok not working:** - Install: `brew install ngrok` - Make sure server is running first - Check if port 3000 is correct ## 💡 Tips 1. **Permanent API Key**: Add to `~/.zshrc`: ```bash echo 'export ALPHA_VANTAGE_API_KEY=your_key' >> ~/.zshrc source ~/.zshrc ``` 2. **Auto-start**: Create a launchd service for automatic startup 3. **Rate Limits**: Free Alpha Vantage key has 5 requests/minute, 500/day 4. **Caching**: Consider adding Redis for caching to avoid API limits ## 🙏 Credits - **MCP SDK**: @modelcontextprotocol/sdk - **Alpha Vantage**: Market data API - **DaisyUI**: Beautiful UI components - **Anime.js**: Smooth animations --- **Happy Trading! 📈📊** Need help? Check the README.md or open an issue!