# Model Context Protocol (MCP) Server

This project is a **lightweight, standardized bridge** that connects Claude and other LLMs to real-world APIs through Anthropic's **Model Context Protocol (MCP)**. This server enables seamless integration between AI applications and external data sources without requiring custom integration work for each API.


## Project Overview

The MCP Server implements Anthropic's open standard protocol to expose multiple API capabilities (tools, resources, and prompts) through a unified interface. This allows any MCP-compatible AI application to interact with various external services including financial data, weather information, news feeds, and GitHub repositories.

## Postman Collection : [Postman Colletion Link](https://imf-gadget-8462.postman.co/workspace/Team-Workspace~36ce1c7f-915a-49dd-840a-5708f6f99460/collection/34642197-8e9d2a0e-4947-4057-84d3-aa4267339e70?action=share&creator=34642197)

*Video not included as the OpenAI API key became invalid before the loom video could be recorded*

## Architecture

```
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Claude/LLM    │◄──►│   MCP Server     │◄──►│  External APIs  │
│   Application   │    │   (This Project) │    │                 │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                              │
                              ▼
                    ┌──────────────────┐
                    │   API Handlers   │
                    │  ┌─────────────┐ │
                    │  │ Finance API │ │
                    │  │ Weather API │ │
                    │  │ News API    │ │
                    │  │ GitHub API  │ │
                    │  └─────────────┘ │
                    └──────────────────┘
```

## Features

### **Multi-API Support**
- **Financial Data**: Real-time stock prices, market data, and financial analytics
- **Weather Services**: Current conditions, forecasts, and weather alerts
- **News Integration**: Latest news articles, headlines, and content aggregation
- **GitHub Integration**: Repository data, commits, issues, and developer statistics

### **MCP Protocol Implementation**
- Standardized tool exposure through MCP specification
- Resource management for external API data
- Prompt templates for common API interactions
- Unified request/response handling

### **Intelligent Request Routing**
- **Mixed Prompt Handler** (`/mcp`): Processes complex queries spanning multiple APIs
- **Dedicated Endpoints**: Individual API access points for specific use cases
- Smart routing based on user intent and query analysis

### **Performance & Reliability**
- **Caching Strategies**: Redis-based caching for frequently accessed data
- **Rate Limiting**: Built-in protection against API quota exhaustion
- **Error Handling**: Robust error recovery and graceful degradation
- **Comprehensive Logging**: Detailed request/response logging for debugging

### **Developer Experience**
- Simple JSON-based request format
- Consistent API responses across all endpoints
- TypeScript implementation for type safety
- Comprehensive documentation and examples

## Tech Stack

### **Core Technologies**
- **Node.js** with **TypeScript**: Server runtime and type safety
- **Express.js**: Web framework and routing
- **MCP Protocol**: Anthropic's standardized AI-API bridge specification

### **External API Integrations**
- **Financial APIs**: Yahoo Finance
- **Weather APIs**: OpenWeatherMap
- **News APIs**: NewsAPI
- **GitHub API**: GitHub Personal Access Token (PAT)

### **Infrastructure**
- **Redis**: Caching layer for performance optimization
- **Docker**: Containerization for easy deployment
- **Prometheus**: Metrics collection and monitoring
- **Grafana**: Visualizes the metrics collected by Prometheus

## Project Structure

```
src/
├── mcpHandler/           # MCP protocol handlers
│   ├── financeHandler.ts
│   ├── githubHandler.ts
│   ├── mcpHandler.ts     # Mixed prompt processor
│   ├── newsHandler.ts
│   └── weatherHandler.ts
├── routes/               # API route definitions
│   ├── financeRoute.ts
│   ├── githubRoute.ts
│   ├── mcpRoute.ts       # Main MCP endpoint
│   ├── newsRoute.ts
│   └── weatherRoute.ts
├── services/             # External API service clients
│   ├── financeService.ts
│   ├── githubService.ts
│   ├── mcpService.ts
│   ├── newsService.ts
│   ├── openai.ts
│   └── weatherService.ts
├── utils/                
│   └── redis.ts          # Redis configuration
└── index.ts              # Application entry point
```

## API Endpoints

### **Mixed Prompt Handler**
```
POST /mcp
```
Processes complex queries that may require data from multiple APIs.

### **Individual API Endpoints**
```
POST /news      - News and article queries
POST /github    - GitHub repository and developer data
POST /weather   - Weather conditions and forecasts
POST /finance   - Financial data and market information
```

### **Request Format**
All endpoints accept a simple JSON payload:
```json
{
  "userMessage": "Your query or request here"
}
```

## Running locally

The entire system can be run locally with a single command using Docker Compose.

```bash
# Build and run with Docker Compose
docker-compose up --build

# Run specific services
docker-compose up redis mcp-server
```

## Configuration

### **Environment Variables**
```env
# Server Configuration
PORT=3000

# Redis Configuration
REDIS_URL=redis://localhost:6379

# API Keys
OPENAI_API_KEY=your_openai_key
ALPHA_VANTAGE_API_KEY=your_finance_key
WEATHER_API_KEY=your_weather_key
NEWS_API_KEY=your_news_key
GITHUB_TOKEN=your_github_token
```

## Usage Examples

### **Financial Data Query**
```bash
curl -X POST http://localhost:3000/finance \
  -H "Content-Type: application/json" \
  -d '{"userMessage": "What is the current price of AAPL stock?"}'
```

### **Mixed Query (Multiple APIs)**
```bash
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"userMessage": "What is the weather like in New York and what are the latest tech news?"}'
```

### **GitHub Repository Analysis**
```bash
curl -X POST http://localhost:3000/github \
  -H "Content-Type: application/json" \
  -d '{"userMessage": "Show me the latest commits in the React repository"}'
```