README.md•5.31 kB
# API Aggregator MCP Server
A **Model Context Protocol (MCP) Server** that provides unified access to multiple external APIs through a single, consistent interface. Built for AI agents and LLMs, this server aggregates weather, news, and financial data into standardized tool calls.
## Features
- ✅ **MCP Protocol Compliant**: Full JSON-RPC 2.0 support with proper tool discovery
- ✅ **Multiple API Integrations**: Weather, news, and stock market data
- ✅ **Unified Error Handling**: Consistent error responses across all APIs
- ✅ **Type-Safe**: Full type hints and Pydantic validation
- ✅ **Async Support**: High-performance async/await throughout
- ✅ **Structured Logging**: Rich, structured logs for monitoring
- ✅ **Environment-Based Config**: Secure API key management
## Quick Start
### 1. Installation
```bash
# Clone the repository
git clone <repository-url>
cd api-aggregator-mcp
# Install dependencies
pip install -r requirements.txt
```
### 2. Configuration
Create a `.env` file with your API keys:
```env
# Required for weather data
OPENWEATHER_API_KEY=your_openweather_api_key_here
# Required for news data
NEWS_API_KEY=your_news_api_key_here
# Required for stock data
ALPHA_VANTAGE_API_KEY=your_alpha_vantage_api_key_here
# Optional server configuration
MCP_SERVER_HOST=localhost
MCP_SERVER_PORT=8000
MCP_SERVER_DEBUG=true
LOG_LEVEL=INFO
```
### 3. Get API Keys
- **OpenWeatherMap**: [Get free API key](https://openweathermap.org/api)
- **News API**: [Get free API key](https://newsapi.org/)
- **Alpha Vantage**: [Get free API key](https://www.alphavantage.co/support/#api-key)
### 4. Run the Server
```bash
python -m src.main
```
The server will start at `http://localhost:8000`
## Available Tools
### 🌤️ Weather Tool: `get_weather`
Get current weather information for any city.
**Parameters:**
- `city` (required): City name
- `country` (optional): Country code (e.g., "US", "GB")
- `units` (optional): Temperature units - "metric" (default), "imperial", or "kelvin"
**Example:**
```json
{
"city": "London",
"country": "GB",
"units": "metric"
}
```
**Response:**
```json
{
"location": {
"city": "London",
"country": "GB",
"coordinates": {"latitude": 51.5074, "longitude": -0.1278}
},
"weather": {
"condition": "Clouds",
"description": "overcast clouds"
},
"temperature": {
"current": 15.2,
"feels_like": 14.8,
"unit": "°C"
},
"humidity": "73%",
"wind": {"speed": "3.5 m/s", "direction": "240°"}
}
```
### 📰 News Tool: `get_news` (Coming Soon)
Get latest news headlines by topic or region.
### 📈 Stock Tool: `get_stock_price` (Coming Soon)
Get current stock prices and financial data.
## API Endpoints
### Health Check
```
GET /
```
### List Available Tools
```
GET /tools
```
### Invoke Tool (REST)
```
POST /tools/{tool_name}
Content-Type: application/json
{
"city": "New York",
"units": "imperial"
}
```
### MCP Protocol Endpoint
```
POST /mcp
Content-Type: application/json
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "get_weather",
"arguments": {
"city": "Tokyo",
"country": "JP"
}
},
"id": "1"
}
```
## Development
### Project Structure
```
api-aggregator-mcp/
├── src/
│ ├── main.py # Application entry point
│ ├── server.py # MCP server implementation
│ ├── tools/ # API tool implementations
│ │ ├── weather.py # Weather API integration
│ │ ├── news.py # News API integration (TODO)
│ │ └── stock.py # Stock API integration (TODO)
│ └── utils/
│ ├── config.py # Configuration management
│ └── errors.py # Error handling utilities
├── tests/ # Unit tests
├── requirements.txt # Dependencies
└── README.md # This file
```
### Running Tests
```bash
pytest tests/
```
### Code Quality
```bash
# Format code
black src/
# Lint code
flake8 src/
# Type checking
mypy src/
```
### Adding New Tools
1. Create a new file in `src/tools/`
2. Implement the service class and handler function
3. Define the tool schema
4. Register in `src/main.py`
Example tool template:
```python
# src/tools/example.py
async def example_handler(parameters: Dict[str, Any]) -> Dict[str, Any]:
"""Handler for example tool."""
# Validate parameters
# Call external API
# Return normalized data
pass
EXAMPLE_TOOL_SCHEMA = {
"type": "object",
"properties": {
"param1": {"type": "string", "description": "..."},
},
"required": ["param1"],
}
```
## Error Handling
All errors are returned in JSON-RPC format:
```json
{
"jsonrpc": "2.0",
"error": {
"code": -32001,
"message": "API key missing for OpenWeatherMap",
"data": {"api": "OpenWeatherMap"}
},
"id": "1"
}
```
Common error codes:
- `-32001`: API key missing
- `-32002`: API key invalid
- `-32003`: External API error
- `-32004`: Rate limit exceeded
- `-32602`: Invalid parameters
## Contributing
1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request
## License
MIT License - see LICENSE file for details.