# 🧮 Simple MCP Server (built with FastMCP)

![Python](https://img.shields.io/badge/Python-3.10%2B-blue)
![FastMCP](https://img.shields.io/badge/FastMCP-2.12-purple)
![MCP](https://img.shields.io/badge/MCP-STDIO%20%2B%20HTTP-green)

A "Hello World" **MCP (Model Context Protocol) server** built with
[FastMCP](https://gofastmcp.com/) — a small calculator server you can talk to over
**in-memory**, **HTTP**, and **STDIO** transports, plus a **LangGraph ReAct agent**
that uses its tools.

It exposes:

| Type | Name | Description |
|------|------|-------------|
| 🛠️ Tool | `add(a, b)` | Add two integers |
| 🛠️ Tool | `subtract(a, b)` | Subtract `b` from `a` |
| 📄 Resource | `file:///endpoint/{name}` | Returns a template message |
| 📄 Resource | `file://endpoint2/{name}` | Reads a real file from `./path/` |
| 💬 Prompt | `review_code(code)` | A reusable "review this code" template |

---

## Project structure

```
simple-MCP-server-built-with-FastMCP/
├── server.py            # the FastMCP server (tools + resources + prompt)
├── client_inmemory.py   # test in the same process (no network)
├── client_http.py       # connect over HTTP
├── client_stdio.py      # spawn the server as a subprocess (STDIO)
├── agent_example.py     # LangGraph ReAct agent that uses the tools
├── path/                # files served by the file resource
│   ├── README.txt
│   └── examples.txt
├── requirements.txt
├── .env.example         # API key template (for the agent only)
└── README.md
```

---

## Setup

```bash
cd simple-MCP-server-built-with-FastMCP

python -m venv .venv
# Windows (PowerShell):
.\.venv\Scripts\Activate.ps1
# macOS / Linux:
source .venv/bin/activate

pip install -r requirements.txt
```

---

## Run it

### 1. Quick test — in-memory (no network, no API key)
```bash
python client_inmemory.py
```
Calls the tools, lists them, reads both resources, and renders the prompt.

### 2. HTTP transport
Terminal A (start the server):
```bash
python server.py http        # serves http://127.0.0.1:8000/mcp
```
Terminal B (run the client):
```bash
python client_http.py
```

### 3. STDIO transport
```bash
python client_stdio.py       # spawns server.py itself — nothing to start first
```

### 4. ReAct agent (needs an API key)
```bash
# one-time: copy the template and add a key
Copy-Item .env.example .env   # then edit .env  (GROQ_API_KEY is free)
python agent_example.py
```
The agent loads the MCP tools, then answers *"What is 8 + 7? Use the tools."* by
actually calling the `add` tool.

> 💡 Groq is free — get a key at [console.groq.com](https://console.groq.com). The
> agent uses Groq if `GROQ_API_KEY` is set, otherwise OpenAI.

---

## How MCP transports differ

- **In-memory** — client and server share one Python process (simplest; for testing).
- **HTTP** — server runs as a web service; clients connect by URL (good for remote/shared).
- **STDIO** — client launches the server as a child process and talks over stdin/stdout (good for local tools).

The same tools/resources/prompt work over **all three** — only the "wire" changes.

---

## Credits

Based on the IBM Skills Network lab *"Hello World of MCP Servers."* Built with
[FastMCP](https://gofastmcp.com/), [LangGraph](https://github.com/langchain-ai/langgraph),
and [langchain-mcp-adapters](https://github.com/langchain-ai/langchain-mcp-adapters).