# 🚀 Simple Tool Server with FastAPI

A lightweight **FastAPI-based tool server** that exposes simple utility functions through REST API endpoints.

This project demonstrates how Python functions can be wrapped behind FastAPI endpoints and accessed through HTTP requests. It also provides a basic foundation for understanding how similar tools can later be exposed through **Model Context Protocol (MCP)**.

---

## 📌 Features

* ➕ Add two numbers
* 🕐 Get the current date and time
* 📝 Count words in a given text
* ⚡ Fast API development using FastAPI
* ✅ Request validation using Pydantic
* 📦 JSON-based API responses
* 📖 Automatic interactive API documentation
* 🔌 Simple architecture that can be extended into an MCP-based tool server

---

## 🏗️ Project Structure

```text
simple-tool-server-fastapi/
│
├── main.py              # FastAPI application and API endpoints
├── model.py             # Pydantic request models
├── tools.py             # Core utility functions
├── requirements.txt     # Project dependencies
├── .gitignore           # Files excluded from Git
└── README.md            # Project documentation
```

---

## 🔄 How It Works

The project follows a simple flow:

```text
Client
   ↓
FastAPI Endpoint
   ↓
Python Tool Function
   ↓
JSON Response
```

For example:

```text
GET /add
   ↓
add_numbers()
   ↓
JSON response
```

The same concept can later be extended toward an MCP architecture:

```text
AI Assistant
     ↓
MCP Client
     ↓
MCP Server
     ↓
Python Tools
```

---

## 🛠️ Technologies Used

* **Python**
* **FastAPI**
* **Pydantic**
* **Uvicorn**
* **REST API**
* **JSON**
* **Model Context Protocol (MCP) concepts**

---

## ⚙️ Installation

### 1. Clone the repository

```bash
git clone https://github.com/sejalpatole/simple-tool-server-fastapi.git
```

### 2. Navigate to the project

```bash
cd simple-tool-server-fastapi
```

### 3. Create a virtual environment

```bash
python -m venv venv
```

### 4. Activate the virtual environment

#### Windows

```bash
venv\Scripts\activate
```

#### macOS / Linux

```bash
source venv/bin/activate
```

### 5. Install dependencies

```bash
pip install -r requirements.txt
```

---

## ▶️ Running the Application

Start the FastAPI server using Uvicorn:

```bash
uvicorn main:app --reload
```

The server will start at:

```text
http://127.0.0.1:8000
```

---

## 📖 API Documentation

FastAPI automatically provides interactive API documentation.

### Swagger UI

Open:

```text
http://127.0.0.1:8000/docs
```

### ReDoc

Open:

```text
http://127.0.0.1:8000/redoc
```

---

# 🔌 API Endpoints

## 1. Home

### Endpoint

```http
GET /
```

Returns information about the available endpoints.

### Example Response

```json
{
  "message": "Welcome to the Simple Tool Server",
  "available_endpoints": [
    "/add",
    "/time",
    "/wordcount"
  ]
}
```

---

## 2. Add Two Numbers

### Endpoint

```http
GET /add
```

### Parameters

| Parameter | Type  | Description   |
| --------- | ----- | ------------- |
| `a`       | float | First number  |
| `b`       | float | Second number |

### Example

```text
http://127.0.0.1:8000/add?a=10&b=20
```

### Example Response

```json
{
  "operation": "Addition",
  "a": 10,
  "b": 20,
  "result": 30
}
```

---

## 3. Get Current Time

### Endpoint

```http
GET /time
```

### Example

```text
http://127.0.0.1:8000/time
```

### Example Response

```json
{
  "current_time": "2026-08-20 21:00:00"
}
```

---

## 4. Count Words

### Endpoint

```http
POST /wordcount
```

### Request Body

```json
{
  "text": "FastAPI is easy to use"
}
```

### Example Response

```json
{
  "text": "FastAPI is easy to use",
  "word_count": 5
}
```

---

# 🧩 Project Components

## `main.py`

Contains the FastAPI application and API routes.

It defines endpoints for:

* `/`
* `/add`
* `/time`
* `/wordcount`

---

## `tools.py`

Contains the core Python utility functions:

```python
add_numbers()
get_current_time()
word_count()
```

Keeping the tool logic separate from the API layer makes the project easier to maintain and extend.

---

## `model.py`

Contains the Pydantic model used to validate the `/wordcount` request.

```python
class WordCountRequest(BaseModel):
    text: str
```

This ensures that the API receives the expected request structure.

---

# 🧪 Testing

The APIs can be tested using:

* Swagger UI
* Postman
* Browser
* cURL
* Any REST API client

Swagger UI is available at:

```text
http://127.0.0.1:8000/docs
```

---

# 🌱 Future Improvements

Possible future extensions include:

* Add more utility tools
* Add authentication
* Add logging
* Add automated tests using Pytest
* Add Docker support
* Add MCP protocol support
* Expose the Python tools through an MCP server
* Add database-backed tools
* Deploy the server to a cloud platform

---

# 🎯 Learning Outcomes

Through this project, the following concepts are demonstrated:

* Building APIs with FastAPI
* Creating GET and POST endpoints
* Request validation with Pydantic
* Separating API logic from business logic
* Working with JSON requests and responses
* Running applications with Uvicorn
* Understanding the foundation of tool-based AI systems
* Understanding the relationship between APIs, tools, and MCP

---

## 👩‍💻 Author

**Sejal Patole**

---

## ⭐ Acknowledgement

This project was developed as a learning exercise to understand **FastAPI, REST APIs, Python utility tools, and the fundamentals of MCP-based tool architecture**.

If you found this project useful, consider giving the repository a ⭐.