Submit
ParthibanRajasekaran

MCP Data Server �

Updated

A Model Context Protocol (MCP) server that provides real-time data

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:
git clone https://github.com/ParthibanRajasekaran/mcp-weather.git
cd mcp-weather
  1. Install dependencies:
npm install
  1. Build the project (optional):
npm run build

🎯 Usage

Running the Server

Development Mode
npm run dev
Production Mode
npm run build
npm start

MCP Configuration

Add the following configuration to your MCP client's configuration file (.vscode/mcp.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:

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

Response Format:

{
  "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:

// 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);

🔍 MCP Inspector Integration

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

  1. Install the MCP Inspector:
npm install -g @modelcontextprotocol/inspector
  1. Run the inspector:
npx @modelcontextprotocol/inspector npx tsx src/main.ts
  1. Open the inspector in your browser at http://localhost:5173

🧪 Development

Adding New Services

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

export const MyServiceSchema = z.object({
    query: z.string().describe("Your query parameter")
});
  1. Implement Service (src/services/myservice.ts):
export class MyService {
    async getData(input: MyServiceInput): Promise<string> {
        // Your implementation
        return "Service response";
    }
}
  1. Register Tool (in src/main.ts):
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 tests (when implemented)

🌐 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 file for details.

🙏 Acknowledgments

📞 Support

If you encounter any issues or have questions:

  1. Check the Issues page
  2. Create a new issue with detailed information
  3. Contact: [email protected]

🔄 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 | 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):
{
    "servers": {
        "my-weather-server": {
            "type": "stdio",
            "command": "npx",
            "args": ["-y", "tsx", "weather/main.ts"]
        }
    }
}

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

  2. Debug Mode: Use the development server for real-time debugging:

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

# 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

// 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

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

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 file for details.

🙏 Acknowledgments

📞 Support

For questions or issues:

Built with ❤️ using the Model Context Protocol

MCP Server · Populars

MCP Server · New