Universal MCP Gateway
> A high-performance Model Context Protocol server that bridges Claude Desktop with multiple APIs through intelligent caching and real-time monitoring
A comprehensive MCP server that provides unified access to multiple popular APIs including GitHub, with enterprise-grade features like intelligent caching, performance monitoring, and advanced error handling. Built with modern Node.js practices to demonstrate production-ready development skills.
Features
Phase 1: Core Foundation ✅
- GitHub API Integration: Complete user, repository, and issues management
- Robust Error Handling: Comprehensive error management with retries
- Rate Limiting: Built-in rate limiting with respect for API limits
- Authentication Management: Support for multiple auth strategies
- Input Validation: Strong validation for all inputs
- Configuration System: Environment-based configuration management
Phase 2: Advanced Features ✅
- Intelligent Caching: LRU cache with TTL for optimal performance
- Performance Metrics: Real-time monitoring and analytics
- Memory Management: Automatic cache cleanup and optimization
- Advanced Monitoring: Request tracking, success rates, and error analysis
Available Tools
github-get-user- Get detailed user profile informationgithub-list-repos- List user repositories with filtering and paginationgithub-get-repo- Get comprehensive repository detailsgithub-search-repos- Search repositories with advanced optionsgithub-get-issues- Retrieve repository issues with filteringmcp-get-metrics- View server performance metrics and cache statisticsmcp-clear-cache- Clear the response cache for fresh data
Prerequisites
- Node.js 18+
- npm or yarn
- GitHub Personal Access Token (for authenticated requests)
Installation
Quick Start (5 minutes)
-
Install dependencies
bash npm install -
Get GitHub token (optional but recommended)
- Quick link: https://github.com/settings/tokens
- Required scopes:public_repoorrepo -
Configure environment
bash # Edit .env and add your GITHUB_TOKEN GITHUB_TOKEN=your_github_personal_access_token_here -
Run the server
bash npm start
What You'll See```
Starting Universal API Gateway MCP v1.0.0...
GitHub API: Configured ✅
Universal API Gateway MCP Server is running!
> **Tip:** Even without a GitHub token, you can access public repositories (with rate limits)
## 📊 Performance & Monitoring
### Caching System
- **Intelligent TTL**: Automatically adjusts cache duration based on data type
- **LRU Eviction**: Keeps most relevant data in memory
- **Memory Optimization**: Prevents memory leaks with automatic cleanup
- **Hit Rate Tracking**: Monitor cache effectiveness in real-time
### Performance Metrics
Use the `mcp-get-metrics` tool to see:
- Total requests and success rates
- Average response times
- Cache hit rates and memory usage
- Error distribution and patterns
- Server uptime statistics
### Cache Management
- Use `mcp-clear-cache` to force fresh data retrieval
- Automatic cleanup of expired entries
- Memory usage monitoring and alerts
- Performance impact tracking
## Configuration
### Environment Variables
| Variable | Required | Description |
|----------|----------|-------------|
| `GITHUB_TOKEN` | Recommended | GitHub Personal Access Token for authenticated requests |
| `WEATHER_API_KEY` | Future | OpenWeatherMap API key |
| `NEWS_API_KEY` | Future | NewsAPI key |
| `LOG_LEVEL` | Optional | Logging level (info, debug, error) |
| `CACHE_TTL` | Optional | Cache time-to-live in milliseconds |
### API Configuration
The server uses `src/config/apis.json` to configure API endpoints, rate limits, and retry policies:```json
{
"github": {
"baseUrl": "https://api.github.com",
"authType": "token",
"rateLimit": {
"requests": 5000,
"window": 3600000
},
"timeout": 10000,
"retries": 3
}
}
Usage Examples
Get User Profile```javascript
// Tool: github-get-user
{
"username": "octocat"
}
### List User Repositories```javascript
// Tool: github-list-repos
{
"username": "microsoft",
"type": "owner",
"sort": "stars",
"direction": "desc",
"perPage": 10
}
Search Repositories```javascript
// Tool: github-search-repos
{
"query": "language:javascript topic:react",
"sort": "stars",
"order": "desc",
"perPage": 20
}
### Get Repository Details```javascript
// Tool: github-get-repo
{
"repository": "microsoft/vscode"
}
Get Repository Issues```javascript
// Tool: github-get-issues
{
"repository": "facebook/react",
"state": "open",
"labels": "bug,help wanted",
"sort": "created",
"direction": "desc"
}
## Architecture
### Project Structure```
src/
├── apis/ # API integration modules
│ └── github.js # GitHub API implementation
├── auth/ # Authentication strategies (future)
├── config/ # Configuration management
│ ├── apis.json # API endpoint configurations
│ └── settings.js # Environment and app settings
├── utils/ # Utility modules
│ ├── httpClient.js # HTTP client with retries
│ ├── errorHandler.js # Error handling utilities
│ └── validator.js # Input validation
└── index.js # Main MCP server
Key Components
HttpClient
- Automatic retries with exponential backoff
- Rate limiting enforcement
- Multiple authentication strategies
- Request/response logging
Error Handling
- Custom error types for different scenarios
- Graceful degradation
- Detailed error messages
- API-specific error mapping
Validation
- Input sanitization
- Type checking
- Format validation (GitHub usernames, repo names, etc.)
- Security-focused validation
Development
Running in Development Mode```bash
npm run dev
### Testing```bash
npm test
Linting```bash
npm run lint
```
Security Considerations
- API tokens stored in environment variables
- Input validation prevents injection attacks
- Rate limiting prevents abuse
- Error messages don't expose sensitive information
- Request timeouts prevent hanging connections
Performance Features
- Built-in caching layer (configurable TTL)
- Connection pooling for HTTP requests
- Efficient pagination handling
- Memory-conscious data structures
- Request deduplication
Roadmap
Phase 2 - Additional APIs
- [ ] Weather API integration (OpenWeatherMap)
- [ ] News API integration (NewsAPI)
- [ ] JSONPlaceholder (for testing/demos)
Phase 3 - Advanced Features
- [ ] Redis caching
- [ ] Metrics and monitoring
- [ ] Health check endpoints
- [ ] Plugin architecture
Phase 4 - DevOps
- [ ] Docker containerization
- [ ] CI/CD pipeline
- [ ] Performance benchmarks
- [ ] Load testing
Contributing
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
License
This project is licensed under the MIT License - see the LICENSE file for details.
Acknowledgments
- Model Context Protocol for the MCP SDK
- GitHub API for comprehensive API documentation
- OpenAI for inspiration and best practices
Support
If you encounter any issues or have questions:
- Check the Issues page
- Create a new issue with detailed information
- Contact the maintainer
Built by Shanky0007