🌤️ mcp-foundry

An MCP (Model Context Protocol) server providing AI-powered weather tools via Google Generative AI.

Table of Contents

• Overview

• Features

• Tech Stack

• Project Structure

• Prerequisites

• Installation

• Configuration

• Usage / Quick Start

• Scripts

• Contributing

• License

Related MCP server: MCP Weather Free

Overview

mcp-foundry is a monorepo implementing the Model Context Protocol (MCP) architecture with a weather service backend. It consists of an MCP server that provides weather tools and an AI agent host that uses Google Generative AI (Gemini) to intelligently invoke those tools. The system demonstrates how LLMs can orchestrate tool calls through the MCP standard for structured, reliable tool integration.

Features

• 🌦️ Real-time weather data via OpenWeather API

• 🤖 AI-powered tool orchestration with Gemini

• 📡 Model Context Protocol (MCP) implementation

• 🔌 Stdio-based server transport for inter-process communication

• 🎯 Type-safe tool definitions with Zod schema validation

• 📦 Monorepo structure with separate server and host applications

Tech Stack

Project Structure

mcp-foundry/
├── apps/
│   ├── mcp-server/              # MCP server providing weather tools
│   │   ├── src/
│   │   │   └── index.ts         # Weather tool definitions and MCP server setup
│   │   ├── build/               # Compiled JavaScript
│   │   └── tsconfig.json
│   │
│   └── mcp-host/                # AI agent host orchestrating tool calls
│       ├── src/
│       │   ├── agent.ts         # Gemini AI agent loop
│       │   ├── client.ts        # MCP client connecting to server
│       │   └── mcp-client/      # Client transport layer
│       ├── build/               # Compiled JavaScript
│       └── tsconfig.json
│
├── package.json                 # Workspace dependencies and scripts
├── tsconfig.base.json           # Base TypeScript configuration
├── .env                         # Environment variables (local)
├── .github/
│   └── copilot-instructions.md  # Copilot README generation rules
└── README.md                    # This file

Prerequisites

• Node.js >=18.0.0

• npm >=9.0.0

• OpenWeather API Key

• Google Generative AI API Key

Installation

1. Clone the repository:

git clone <repository-url>
cd mcp-foundry

2. Install dependencies:

npm install

3. Build the projects:

npm run build

Expected output:

# output
# compiles apps/mcp-server/src/**/*.ts → apps/mcp-server/build/
# compiles apps/mcp-host/src/**/*.ts → apps/mcp-host/build/

Configuration

Create a .env file in the repository root with the following variables:

.env example:

OPEN_WEATHER_API=your_openweather_api_key_here
GEMINI_API_KEY=your_gemini_api_key_here

⚠️ Never commit .env to version control. Add it to .gitignore.

Usage / Quick Start

1. Build the projects:

npm run build

2. Start the agent:

npm start

3. Invoke the agent with a natural language query:

node apps/mcp-host/build/agent.js "What's the weather in New York?"

Expected output:

# output
Connected to MCP server
[Gemini response with weather information for New York]

Scripts

Contributing

Contributions are welcome! This project is open to community input and improvements.

Getting Started:

1. Fork the repository

2. Create a feature branch: git checkout -b feat/your-feature (or fix/, docs/, chore/ as needed)

3. Make your changes and commit: git commit -m "description of changes"

4. Push to your fork: git push origin your-branch-name

5. Open a pull request with a description of your changes

Guidelines (non-strict):

• Keep commits logically organized and descriptive

• Add tests if you're adding new functionality

• Update documentation if your changes affect the API or usage

• Be respectful and collaborative in discussions

All contribution levels are welcome — from typo fixes to new features!

License

Distributed under the MIT License. See LICENSE for more information.