jefercort/practice-mcp-js

Practice MCP JS

A Model Context Protocol (MCP) server implementation in TypeScript that provides weather information tools for AI assistants.

Description

This project demonstrates how to create an MCP server that exposes weather-related tools to Large Language Models (LLMs). The server provides a fetch-weather tool that retrieves current weather data and forecasts for any city using the Open-Meteo API.

Features

• Weather Tool: Fetch current weather conditions and forecasts for any city
• Input Validation: Uses Zod for robust input/output validation
• MCP Protocol: Compatible with AI assistants that support the Model Context Protocol
• TypeScript: Fully typed implementation for better development experience

Prerequisites

• Node.js (version 14 or higher)
• npm or yarn package manager

Installation

1. Clone the repository:

git clone <repository-url>
cd practice-mcp-js

2. Install dependencies:

npm install

Usage

Running the Server

To start the MCP server:

npx tsx main.ts

The server will start and listen for MCP connections via stdio transport.

Available Tools

fetch-weather

Retrieves weather information for a specified city.

Parameters:

• city (string): Name of the city to get weather information for

Example Response: The tool returns current weather conditions including:

• Temperature
• Precipitation
• Day/night status
• Rain information
• Hourly forecast data

Project Structure

practice-mcp-js/
├── main.ts           # Main server implementation
├── package.json      # Project configuration and dependencies
├── package-lock.json # Dependency lock file
└── README.md         # This file

Dependencies

• @modelcontextprotocol/sdk: Core MCP SDK for server implementation
• zod: Schema validation library for input/output validation

API Integration

This project integrates with the following external APIs:

1. Open-Meteo Geocoding API: For converting city names to coordinates
2. Open-Meteo Weather API: For retrieving weather data and forecasts

How It Works

1. The server creates an MCP server instance with the name "PRO INDUSTRIAL MCP SERVER"
2. It defines a fetch-weather tool that:
   • Accepts a city name as input
   • Geocodes the city name to get coordinates
   • Fetches weather data using the coordinates
   • Returns formatted weather information
3. The server connects via stdio transport for communication with AI assistants

Development

The main server logic is implemented in main.ts:7-55. Key components include:

• Server initialization (main.ts:7-10)
• Tool definition (main.ts:13-50)
• Transport setup (main.ts:54-55)

Error Handling

The weather tool includes error handling for:

• Cities that cannot be found
• API request failures
• Invalid input parameters (via Zod validation)

License

ISC

Contributing

This is a practice project for learning MCP server development. Feel free to fork and experiment with additional tools and features.