# MCP Data Server �

A comprehensive Model Context Protocol (MCP) server that provides various data services, starting with real-time weather data and designed for easy extension to other data sources.

## 🚀 Features

- **Modular Architecture**: Easy to extend with new data services
- **Real-time Weather Data**: Get current weather conditions for any city
- **MCP Protocol Compliance**: Fully compatible with the Model Context Protocol
- **TypeScript Support**: Written in TypeScript for better type safety
- **Stdio Transport**: Uses standard input/output for communication
- **Extensible Design**: Ready for news, finance, sports, and other data services

## 📋 Prerequisites

- Node.js (v18 or higher)
- npm or yarn package manager
- TypeScript support

## 🛠️ Installation

1. Clone the repository:
```bash
git clone https://github.com/ParthibanRajasekaran/mcp-weather.git
cd mcp-weather
```

2. Install dependencies:
```bash
npm install
```

3. Build the project (optional):
```bash
npm run build
```

## 🎯 Usage

### Running the Server

#### Development Mode
```bash
npm run dev
```

#### Production Mode
```bash
npm run build
npm start
```

### MCP Configuration

Add the following configuration to your MCP client's configuration file (`.vscode/mcp.json`):

```json
{
    "servers": {
        "mcp-data-server": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "tsx",
                "src/main.ts"
            ]
        }
    }
}
```

## 🔧 Available Services

### Weather Service

#### `getWeather`
Get current weather data for a specified city.

**Parameters:**
- `city` (string): The name of the city to get weather for

**Example Usage:**
```typescript
// MCP client call
const weather = await mcpClient.callTool("getWeather", { city: "London" });
```

**Response Format:**
```json
{
  "latitude": 51.51147,
  "longitude": -0.13078308,
  "current": {
    "time": "2025-07-08T06:15",
    "temperature_2m": 13.9,
    "apparent_temperature": 11,
    "is_day": 1,
    "rain": 0
  },
  "hourly": {
    "time": [...],
    "temperature_2m": [...]
  }
}
```

### 🔮 Future Services (Planned)

- **News Service**: Get latest news from various sources
- **Finance Service**: Stock prices, market data, cryptocurrency
- **Sports Service**: Live scores, team statistics, schedules
- **Social Media Service**: Trending topics, social metrics
- **Maps Service**: Location data, directions, places

## 🏗️ Architecture

### Project Structure

```
mcp-weather/
├── src/
│   ├── main.ts              # Main server entry point
│   ├── services/            # Data service implementations
│   │   └── weather.ts       # Weather service
│   ├── types/               # TypeScript type definitions
│   │   ├── weather.ts       # Weather-related types
│   │   └── service.ts       # Base service interfaces
│   └── utils/               # Utility functions
│       └── registry.ts      # Service registry
├── .vscode/
│   └── mcp.json            # MCP client configuration
├── package.json            # Project dependencies and scripts
├── tsconfig.json           # TypeScript configuration
└── README.md              # This file
```

### Transport Layer
The server uses **StdioServerTransport** for communication:
- **Input**: Standard input (stdin)
- **Output**: Standard output (stdout)
- **Protocol**: JSON-RPC over stdio
- **Benefits**: Simple, reliable, and widely supported

### Service Architecture

Each service follows this pattern:

```typescript
// 1. Define types
interface ServiceInput { /* ... */ }
interface ServiceOutput { /* ... */ }

// 2. Create service class
class MyService {
    async getData(input: ServiceInput): Promise<string> {
        // Implementation
    }
}

// 3. Register with MCP server
server.tool("myTool", "Description", schema, handler);
```

## 🤖 AI Assistant Integration

### Claude Desktop (Available Now)
Your MCP server works with Claude Desktop out of the box! See [`docs/AI_INTEGRATION.md`](docs/AI_INTEGRATION.md) for setup instructions.

### GitHub Copilot (Coming Soon)
GitHub Copilot doesn't support MCP yet, but your server is ready! See [`docs/GITHUB_COPILOT_INTEGRATION.md`](docs/GITHUB_COPILOT_INTEGRATION.md) for:
- Current workarounds using VS Code extensions
- What to expect when MCP support is added
- Example integration patterns

### VS Code Extension Example
Check out [`examples/vscode-extension/`](examples/vscode-extension/) for a working example that integrates your MCP server with VS Code today!

## 🔍 MCP Inspector Integration

For debugging and development, you can use the MCP Inspector:

1. Install the MCP Inspector:
```bash
npm install -g @modelcontextprotocol/inspector
```

2. Run the inspector:
```bash
npx @modelcontextprotocol/inspector npx tsx src/main.ts
```

3. Open the inspector in your browser at `http://localhost:5173`

## 🧪 Development

### Adding New Services

1. **Create Type Definitions** (`src/types/myservice.ts`):
```typescript
export interface MyServiceInput {
    query: string;
}

export const MyServiceSchema = z.object({
    query: z.string().describe("Your query parameter")
});
```

2. **Implement Service** (`src/services/myservice.ts`):
```typescript
export class MyService {
    async getData(input: MyServiceInput): Promise<string> {
        // Your implementation
        return "Service response";
    }
}
```

3. **Register Tool** (in `src/main.ts`):
```typescript
server.tool(
    "myTool",
    "Description of my tool",
    MyServiceSchema,
    async ({ query }: { query: string }) => {
        const result = await myService.getData({ query });
        return {
            content: [{ type: "text", text: result }]
        };
    }
);
```

### Development Scripts
- `npm run dev` - Run in development mode with hot reload
- `npm run build` - Build the TypeScript project
- `npm start` - Run the built project
- `npm test` - Run all tests
- `npm run test:watch` - Run tests in watch mode
- `npm run test:coverage` - Run tests with coverage report

## 🌐 API Details

### Weather Service API
- **Geocoding**: `https://geocoding-api.open-meteo.com/v1/search`
- **Weather**: `https://api.open-meteo.com/v1/forecast`
- **Rate Limit**: Free tier, no authentication required
- **Model**: UKMO Seamless (UK Met Office)

## 🤝 Contributing

We welcome contributions for new data services! Here's how:

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/new-service`
3. Add your service following the architecture above
4. Add tests and documentation
5. Commit your changes: `git commit -m 'Add new service'`
6. Push to the branch: `git push origin feature/new-service`
7. Open a Pull Request

### Service Guidelines
- Each service should be self-contained in its own file
- Use TypeScript for type safety
- Include proper error handling
- Add JSDoc comments for public methods
- Follow the existing code style

## 📄 License

This project is licensed under the ISC License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- [Model Context Protocol](https://github.com/modelcontextprotocol/specification) for the protocol specification
- [Open-Meteo](https://open-meteo.com/) for the free weather API
- [TypeScript](https://www.typescriptlang.org/) for type safety

## 📞 Support

If you encounter any issues or have questions:
1. Check the [Issues](https://github.com/ParthibanRajasekaran/mcp-weather/issues) page
2. Create a new issue with detailed information
3. Contact: rajasekaran.parthiban7@gmail.com

## 🔄 Changelog

### v1.0.0
- Initial release with weather service
- Modular architecture for easy extension
- MCP protocol compliance
- TypeScript implementation
- Stdio transport support

---

Made with ❤️ by [ParthibanRajasekaran](https://github.com/ParthibanRajasekaran) | Ready for extension to any data service!
const server = new McpServer({
    name: "MCP Weather Server",
    version: "1.0.0",
    description: "A server that provides weather data"
});
```

## 🔧 Tools Available

### `getWeather`

Retrieves current weather conditions and forecasts for a specified city.

**Parameters:**
- `city` (string): The name of the city to get weather data for

**Returns:**
- Current temperature, apparent temperature, and conditions
- Hourly temperature forecast for the next 7 days
- Location coordinates and timezone information

**Example Usage:**
```typescript
// Through MCP client
const weatherData = await mcpClient.callTool("getWeather", { city: "London" });
```

## 📁 Project Structure

```
mcp-weather/
├── .vscode/
│   └── mcp.json              # MCP server configuration
├── weather/
│   └── main.ts               # Main server implementation
├── package.json              # Dependencies and scripts
├── tsconfig.json             # TypeScript configuration
└── README.md                 # This file
```

## 🔍 MCP Inspector Integration

To use with the MCP Inspector for debugging and development:

1. **Configure MCP Client**: Add the server to your MCP configuration file (`.vscode/mcp.json`):

```json
{
    "servers": {
        "my-weather-server": {
            "type": "stdio",
            "command": "npx",
            "args": ["-y", "tsx", "weather/main.ts"]
        }
    }
}
```

2. **Launch Inspector**: The server can be inspected using MCP-compatible tools and inspectors.

3. **Debug Mode**: Use the development server for real-time debugging:
```bash
npm run dev
```

## 🌐 API Integration

The server integrates with two Open-Meteo APIs:

### Geocoding API
- **Endpoint**: `https://geocoding-api.open-meteo.com/v1/search`
- **Purpose**: Convert city names to coordinates
- **Features**: Multi-language support, fuzzy matching

### Weather API
- **Endpoint**: `https://api.open-meteo.com/v1/forecast`
- **Purpose**: Retrieve weather data using coordinates
- **Model**: UK Met Office Seamless model (`ukmo_seamless`)
- **Data**: Current conditions + hourly forecasts

## 🛠️ Development

### Available Scripts

```bash
# Development server with hot reload
npm run dev

# Build TypeScript to JavaScript
npm run build

# Start production server
npm start

# Run tests
npm test
```

### Adding New Features

1. **New Tools**: Add tools to the server using the `server.tool()` method
2. **Enhanced Data**: Extend the weather API calls to include more parameters
3. **Error Handling**: Improve error handling for edge cases

## 🌍 Usage Examples

### Basic Weather Query

```typescript
// Get weather for London
const result = await getWeather({ city: "London" });

// Current conditions
console.log(`Temperature: ${result.current.temperature_2m}°C`);
console.log(`Feels like: ${result.current.apparent_temperature}°C`);
console.log(`Rain: ${result.current.rain}mm`);
```

### Multi-City Comparison

```typescript
const cities = ["London", "Paris", "New York", "Tokyo"];
const weatherData = await Promise.all(
    cities.map(city => getWeather({ city }))
);
```

## 🔐 Error Handling

The server includes comprehensive error handling:

- **Invalid Cities**: Returns helpful error messages for non-existent cities
- **API Failures**: Graceful handling of network issues
- **Data Validation**: Input validation using Zod schemas

## 📊 Data Schema

### Current Weather Response

```typescript
interface WeatherResponse {
    latitude: number;
    longitude: number;
    timezone: string;
    current: {
        time: string;
        temperature_2m: number;
        apparent_temperature: number;
        is_day: number;
        rain: number;
    };
    hourly: {
        time: string[];
        temperature_2m: number[];
    };
}
```

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## 📝 License

This project is licensed under the ISC License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- [Open-Meteo](https://open-meteo.com/) for providing free weather data
- [Model Context Protocol](https://modelcontextprotocol.io/) for the MCP specification
- UK Met Office for the weather model data

## 📞 Support

For questions or issues:
- Create an issue on GitHub
- Check the [MCP Documentation](https://modelcontextprotocol.io/docs)

---

Built with ❤️ using the Model Context Protocol