# 🌤️ mcp-foundry

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

![License](https://img.shields.io/badge/license-MIT-blue.svg)
![Node](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)
![TypeScript](https://img.shields.io/badge/typescript-%3E%3D6.0.0-blue)

---

## Table of Contents

- [Overview](#overview)
- [Features](#features)
- [Tech Stack](#tech-stack)
- [Project Structure](#project-structure)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage / Quick Start](#usage--quick-start)
- [Scripts](#scripts)
- [Contributing](#contributing)
- [License](#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](https://nodejs.org/) >=18.0.0
- [npm](https://www.npmjs.com/) >=9.0.0
- [OpenWeather API Key](https://openweathermap.org/api)
- [Google Generative AI API Key](https://ai.google.dev/)

---

## Installation

1. Clone the repository:

```bash
git clone <repository-url>
cd mcp-foundry
```

2. Install dependencies:

```bash
npm install
```

3. Build the projects:

```bash
npm run build
```

Expected output:
```bash
# 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:**

```env
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:

```bash
npm run build
```

2. Start the agent:

```bash
npm start
```

3. Invoke the agent with a natural language query:

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

Expected output:
```bash
# 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.