# MCP Tool Server

A lightweight **Model Context Protocol (MCP) Tool Server** built in Python that exposes real-world tools (weather, stock data, and internet search) over **STDIO transport**.
The server is designed to be discovered and invoked by MCP-compatible clients and future AI agents, and is validated using the official **MCP Inspector**.

---

## 🚀 Overview

This project demonstrates how to build a **correct and production-aligned MCP server** that:

* Exposes reusable tools via MCP
* Integrates real external APIs
* Uses clear tool schemas and contracts
* Separates protocol logic from backend logic
* Can be directly consumed by AI agents in the future

The focus of this project is the **tool layer**, not agent reasoning.
It intentionally stops at the MCP boundary.

---

## 🧠 Architecture & Approach

The design follows a clean separation of responsibilities:

```
MCP Client / Inspector
        │
        │  (STDIO)
        ▼
MCP Server (server/main.py)
        │
        ├── Tool Definitions (server/tools/)
        │       ├── Weather Tool
        │       ├── Stock Price Tool
        │       └── Web Search Tool
        │
        └── Backend Logic (server/backend/data_store.py)
                ├── OpenWeather API
                ├── Stooq Market Data
                └── Google Custom Search
```

* **MCP Server** handles protocol wiring and tool registration
* **Tools** define schemas and execution boundaries
* **Backend layer** contains all external API logic
* **No agent logic is included** (by design)

This mirrors how real AI platforms expose tools internally.

---

## 🛠️ Tools Implemented

### 🌦️ Weather Tool (`get_weather`)

* Fetches real-time weather data by city
* Powered by OpenWeatherMap
* Returns structured, agent-friendly JSON

### 📈 Stock Price Tool (`get_stock_price`)

* Retrieves stock market data for a given symbol
* Uses Stooq public market data (no API key required)
* Automatically normalizes symbols (e.g. `AAPL → aapl.us`)

### 🌐 Web Search Tool (`web_search`)

* Performs internet search using Google Custom Search
* Uses official Google APIs (no scraping)
* Returns clean search results with title, snippet, and link
* Result count is relevance-based and API-controlled

---

## 📂 Project Structure

```
TASK1-MCP-SERVER
│
│
├── server/
│   ├── main.py                  # MCP server entry point
│   │
│   ├── backend/
│   │   └── data_store.py         # External API integrations
│   │
│   ├── tools/
│   │   ├── get_weather.py
│   │   ├── get_stock_price.py
│   │   └── web_search.py
│
├── .env                          # API keys (not committed)
├── requirements.txt
└── README.md
```

---

## ⚙️ Prerequisites

* Python 3.10+
* Node.js (for MCP Inspector)
* OpenWeatherMap API key
* Google Custom Search API key + CSE ID

---

## 📦 Installation

```bash
# Clone repository
git clone <your-repo-url>
cd TASK1-MCP-SERVER

# Create virtual environment
python -m venv venv
source venv/bin/activate    # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt
```

---

## 🔐 Environment Configuration

Create a `.env` file in the project root:

```env
OPENWEATHER_API_KEY=your_openweather_api_key
GOOGLE_API_KEY=your_google_api_key
GOOGLE_CSE_ID=your_custom_search_engine_id
```

**Best practices:**

* `.env` is excluded from version control
* No secrets are hardcoded
* Server fails safely if keys are missing

---

## ▶️ Running the MCP Server

Start the server using the MCP Inspector:

```bash
npx @modelcontextprotocol/inspector python server/main.py
```

The server runs over **STDIO** and exposes all tools automatically.

---

## 🧪 Testing with MCP Inspector

Using the Inspector UI:

1. Select **STDIO** transport
2. Point to `server/main.py`
3. Start the server
4. Invoke tools interactively

### Example Tool Invocations

#### 🌐 Web Search

**Input:**
```json
{
  "query": "Model Context Protocol MCP",
  "num_results": 5
}
```

**Output:**
```json
{
  "results": [
    {
      "title": "Model Context Protocol Documentation",
      "link": "https://modelcontextprotocol.io/",
      "snippet": "The Model Context Protocol (MCP) is an open protocol that standardizes how applications provide context to LLMs..."
    },
    {
      "title": "Introducing the Model Context Protocol",
      "link": "https://anthropic.com/news/model-context-protocol",
      "snippet": "Today, we're introducing the Model Context Protocol (MCP), a new standard for connecting AI assistants..."
    }
  ]
}
```

---

#### 🌦️ Weather Tool

**Input:**
```json
{
  "city": "San Francisco"
}
```

**Output:**
```json
{
  "city": "San Francisco",
  "temperature": 18.5,
  "conditions": "Clear sky",
  "humidity": 65,
  "wind_speed": 3.5
}
```

---

#### 📈 Stock Price Tool

**Input:**
```json
{
  "symbol": "AAPL"
}
```

**Output:**
```json
{
  "symbol": "AAPL",
  "price": 195.89,
  "currency": "USD",
  "timestamp": "2024-01-15T16:00:00",
  "change": "+2.34",
  "change_percent": "+1.21%"
}
```

---

## 🚧 Why STDIO Transport?

**STDIO was chosen because it provides the simplest, most reliable path for tool development and validation.**

### What STDIO Gives You

* **Zero configuration**: No ports, no networking, no HTTP servers to manage
* **Perfect for inspection**: MCP Inspector works flawlessly with STDIO
* **Deterministic lifecycle**: Process starts when called, exits when done
* **Secure by default**: No exposed endpoints or security concerns
* **Easy debugging**: Direct input/output makes testing and troubleshooting straightforward

### Why Not HTTP/SSE?

While HTTP and Server-Sent Events (SSE) transports are valid MCP options, they introduce unnecessary complexity for a tool server:

**HTTP Transport Issues:**
* Requires managing a persistent web server alongside MCP logic
* Adds lifecycle complexity (when to start/stop, connection pooling, etc.)
* Makes local testing harder - you need HTTP clients, manage ports, handle CORS
* Overkill for simple tool execution that doesn't need persistent connections

**SSE Transport Issues:**
* Designed for streaming real-time updates, not one-shot tool calls
* Requires long-lived connections and complex client-side stream handling
* Harder to debug tool execution due to streaming semantics
* More complex error recovery and retry logic
* Inspector support is less mature

### When to Use Other Transports

* **HTTP**: When you need remote deployment or multiple clients calling the server simultaneously
* **SSE**: When building streaming AI agents that need real-time, progressive responses

For a foundational tool server focused on correctness and reliability, STDIO is the right choice. You can always add HTTP transport later without changing any tool implementations.

---

## 💡 What This Project Intentionally Excludes

* AI agent logic
* LangChain / LangGraph workflows
* RAG pipelines
* Memory or planning systems

Those layers are meant to sit **on top of this server**, not inside it.

---

## 🔮 Future Extensions

This server can be extended with:

* AI agents that dynamically discover and call tools
* LangChain or LangGraph integration
* RAG pipelines grounded in web search
* Stateful or memory-based agents
* HTTP transport for remote deployment

No changes to existing tools are required.

---

## ✅ Key Takeaways

* Correct MCP server implementation using STDIO transport
* Real external integrations (weather, stocks, search)
* Clean tool contracts with clear input/output schemas
* Production-style separation of concerns
* Agent-ready foundation that can scale to complex workflows

---

## 📚 Additional Resources

* [Model Context Protocol Documentation](https://modelcontextprotocol.io/)
* [MCP Inspector](https://github.com/modelcontextprotocol/inspector)
* [OpenWeatherMap API](https://openweathermap.org/api)
* [Google Custom Search API](https://developers.google.com/custom-search)

---