🌤️ 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

---

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

Technology	Purpose	Version
TypeScript	Language	^6.0.3
Node.js	Runtime	>=18.0.0
@modelcontextprotocol/sdk	MCP server/client implementation	^1.29.0
@google/genai	Google Generative AI SDK	^2.2.0
dotenv	Environment variable management	^17.4.2
zod	Runtime schema validation	^3.25.76

---

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:

Variable	Description	Required	Example
OPEN_WEATHER_API	OpenWeather API key for weather data	✅	abc123def456
GEMINI_API_KEY	Google Generative AI API key	✅	AIzaXxxx...

.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

Script	Command	Description
build	npm run build:server && npm run build:host	Compile both MCP server and host
build:server	tsc -p apps/mcp-server	Compile MCP server TypeScript to JavaScript
build:host	tsc -p apps/mcp-host	Compile agent host TypeScript to JavaScript
start	node apps/mcp-host/build/agent.js	Run the AI agent
dev	npm run build && npm start	Build and run in one command

---

---

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.