MCP ChatGPT Multi-Server Suite

# MCP ChatGPT App - Multi-Server Suite A comprehensive TypeScript ChatGPT App suite using the Model Context Protocol (MCP) SDK with Express. This project includes **four powerful MCP servers** for different use cases. ## 🎯 Available MCP Servers 1. **📊 Stock Market MCP** (Port 3000) - Real-time top movers from Alpha Vantage 2. **💱 Currency Converter MCP** (Port 3001) - Convert between 160+ world currencies 3. **🌍 World Time MCP** (Port 3002) - Convert time across global timezones 4. **📏 Units Converter MCP** (Port 3003) - Convert measurements across 10 categories ## Features - 🚀 **MCP Server Integration**: Uses @modelcontextprotocol/sdk to expose tools - 🎨 **Beautiful UI**: Dark mode with DaisyUI, Tailwind CSS, and Anime.js animations - 📱 **Responsive Design**: Works on desktop and mobile - 🔄 **Real-time Data**: Live data from various APIs - 🌐 **Ngrok Ready**: Easy to expose via ngrok for external access - ⚡ **Multi-Server Support**: Run all servers simultaneously or individually ## Prerequisites - Node.js (v16 or higher) - Alpha Vantage API key (free at https://www.alphavantage.co/support/#api-key) - **Required for Stock Market server only** - ngrok (for external access) - optional ## Setup 1. **Install dependencies:** ```bash npm install ``` 2. **Set up environment variables:** ```bash # Copy the example file cp .env.example .env # Edit .env and add your Alpha Vantage API key # Or set it as a system environment variable export ALPHA_VANTAGE_API_KEY=your_api_key_here ``` 3. **Build the TypeScript project:** ```bash npm run build ``` ## Running the Servers ### Quick Start - All Servers Start all four servers at once: ```bash ./start-all-servers.sh ``` This starts: - Stock Market MCP on http://localhost:3000 - Currency Converter MCP on http://localhost:3001 - World Time MCP on http://localhost:3002 - Units Converter MCP on http://localhost:3003 Stop all servers: ```bash ./stop-all-servers.sh ``` ### Individual Servers Start servers individually using their dedicated scripts: ```bash ./start.sh # Stock Market (Port 3000) ./start-currency.sh # Currency Converter (Port 3001) ./start-time.sh # World Time (Port 3002) ./start-units.sh # Units Converter (Port 3003) ``` ### Using NPM Scripts Development mode (with auto-reload): ```bash npm run dev # Stock Market npm run dev-currency # Currency Converter npm run dev-time # World Time npm run dev-units # Units Converter ``` Production mode: ```bash npm run start # Stock Market npm run start-currency # Currency Converter npm run start-time # World Time npm run start-units # Units Converter ``` ## Exposing with ngrok To make your servers accessible externally (e.g., for ChatGPT integration): ```bash ngrok http 3000 # Stock Market ngrok http 3001 # Currency Converter ngrok http 3002 # World Time ngrok http 3003 # Units Converter ``` ngrok will provide you with a public URL that you can use to access your server. ## Architecture ### 1. Stock Market MCP Server (`src/server.ts`) **MCP Tools:** - `topMovers` - Fetches top gainers, losers, and most actively traded stocks **Endpoints:** - `GET /` - Serves the web interface - `POST /mcp` - MCP JSON-RPC endpoint - `GET /mcp/tools/list` - Lists available tools - `POST /mcp/tools/call` - Calls MCP tools **Frontend:** `public/index.html` ### 2. Currency Converter MCP Server (`src/currency-server.ts`) **MCP Tools:** - `convertCurrency` - Convert between currencies - `getSupportedCurrencies` - List all supported currencies - `getExchangeRates` - Get all rates for a base currency **Features:** - 160+ world currencies - Real-time exchange rates - Free API (no key required) **Frontend:** `public-currency/index.html` ### 3. World Time MCP Server (`src/time-server.ts`) **MCP Tools:** - `convertTime` - Convert time between timezones - `getCurrentTime` - Get current time in a timezone - `getSupportedTimezones` - List all supported timezones - `getWorldClocks` - Get time in multiple timezones **Features:** - 30+ major world timezones - DST detection - UTC offset calculation **Frontend:** `public-time/index.html` ### 4. Units Converter MCP Server (`src/units-server.ts`) **MCP Tools:** - `convertUnits` - Convert between different units - `getSupportedUnits` - List units by category - `getCategories` - List all unit categories **Features:** - 10 categories (length, weight, temperature, volume, area, speed, pressure, energy, power, data) - 70+ different units - Automatic category detection **Frontend:** `public-units/index.html` ### Common Features All servers include: - **Express Server**: Serves the frontend and handles API requests - **MCP Protocol**: Full MCP JSON-RPC 2.0 implementation - **CORS Enabled**: Ready for cross-origin requests - **Beautiful UI**: Dark mode with DaisyUI, Tailwind CSS, and Anime.js - **ChatGPT Ready**: Compatible with ChatGPT Actions ## API Usage Examples ### Stock Market MCP ```bash curl -X POST http://localhost:3000/mcp/tools/call \ -H "Content-Type: application/json" \ -d '{"name":"topMovers","arguments":{"limit":5}}' ``` ### Currency Converter MCP ```bash curl -X POST http://localhost:3001/mcp/tools/call \ -H "Content-Type: application/json" \ -d '{"name":"convertCurrency","arguments":{"from":"USD","to":"EUR","amount":100}}' ``` ### World Time MCP ```bash curl -X POST http://localhost:3002/mcp/tools/call \ -H "Content-Type: application/json" \ -d '{"name":"getCurrentTime","arguments":{"timezone":"America/New_York"}}' ``` ### Units Converter MCP ```bash curl -X POST http://localhost:3003/mcp/tools/call \ -H "Content-Type: application/json" \ -d '{"name":"convertUnits","arguments":{"from":"meter","to":"foot","value":100}}' ``` ### MCP JSON-RPC Format All servers support the MCP protocol via POST to `/mcp`: ```bash curl -X POST http://localhost:3001/mcp \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "convertCurrency", "arguments": {"from": "USD", "to": "EUR", "amount": 100} } }' ``` ## Technologies Used - **Backend**: - TypeScript - Express.js - @modelcontextprotocol/sdk - Axios - Alpha Vantage API - **Frontend**: - HTML5 - Tailwind CSS - DaisyUI - Anime.js - Vanilla JavaScript ## 📚 Documentation For detailed information about each server: - **[MCP_SERVERS_GUIDE.md](MCP_SERVERS_GUIDE.md)** - Comprehensive guide for all servers - **[QUICKSTART.md](QUICKSTART.md)** - Quick start guide - **[CHATGPT_INTEGRATION.md](CHATGPT_INTEGRATION.md)** - ChatGPT integration guide ## Troubleshooting ### API Key Issues If you see a warning about `ALPHA_VANTAGE_API_KEY not set`: - This only affects the Stock Market server - Make sure you've set the environment variable - Check that your `.env` file is in the project root - Verify the API key is valid at https://www.alphavantage.co/ ### Port Already in Use If a port is already in use, you can either: 1. Stop the process using that port: `lsof -i :3000` then `kill <PID>` 2. Set a different port: `PORT=3005 npm run dev` ### Build Errors If you encounter build errors: ```bash rm -rf dist node_modules npm install npm run build ``` ### CORS Issues All servers are configured with CORS enabled. If you still experience issues, check your browser console for specific CORS errors. ### Server Won't Start Make sure all dependencies are installed and TypeScript is built: ```bash npm install npm run build ./start-all-servers.sh ``` ## 🤝 Contributing Feel free to submit issues, fork the repository, and create pull requests for any improvements. ## 📄 License ISC