<div align="center">

# 🚀 MCP Server

### Production-Ready Model Context Protocol Server Built with Python & FastMCP

<p align="center">

A clean, modular, scalable, and Docker-ready implementation of the Model Context Protocol (MCP), designed for AI applications and developer productivity.

</p>

<p align="center">

<img src="https://img.shields.io/badge/Python-3.11+-3776AB?style=for-the-badge&logo=python&logoColor=white"/>

<img src="https://img.shields.io/badge/FastMCP-Latest-009688?style=for-the-badge"/>

<img src="https://img.shields.io/badge/Docker-Ready-2496ED?style=for-the-badge&logo=docker&logoColor=white"/>

<img src="https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge"/>

<img src="https://img.shields.io/badge/Status-Production%20Ready-success?style=for-the-badge"/>

</p>

<p align="center">

<img src="https://img.shields.io/github/stars/golam74/MCP_SERVER?style=social"/>

<img src="https://img.shields.io/github/forks/golam74/MCP_SERVER?style=social"/>

<img src="https://img.shields.io/github/watchers/golam74/MCP_SERVER?style=social"/>

</p>

</div>

---

# 📑 Table of Contents

- 📖 Overview
- ✨ Features
- 🏗 Architecture
- 📂 Project Structure
- 🛠 Tech Stack
- 🚀 Getting Started
- 🐳 Docker
- ⚙ Configuration
- 🧩 Available Tools
- 📜 Logging
- 📊 Roadmap
- 🤝 Contributing
- 📄 License

---

# 📖 Overview

The **MCP Server** is a production-ready implementation of the **Model Context Protocol (MCP)** using **Python** and **FastMCP**.

This project demonstrates how to build scalable, modular, and maintainable MCP servers that can expose reusable tools for AI assistants and MCP-compatible clients.

Unlike simple examples, this repository follows a production-oriented architecture with centralized tool registration, structured logging, Docker support, and a clean project layout.

It serves as both:

- 📚 A learning resource for developers exploring MCP.
- 🏗 A solid foundation for building real-world AI tool servers.

---

# ✨ Features

| Feature | Status |
|----------|--------|
| FastMCP Server | ✅ |
| Modular Architecture | ✅ |
| Central Tool Registry | ✅ |
| Professional Logging | ✅ |
| Tool Execution Logs | ✅ |
| Docker Support | ✅ |
| Docker Compose | ✅ |
| Environment Configuration | ✅ |
| Easy Tool Registration | ✅ |
| Production Ready Structure | ✅ |
| Extensible Design | ✅ |

---

# 🎯 Why This Project?

Most MCP examples available online are intentionally minimal.

This project goes beyond the basics by demonstrating:

- Clean architecture
- Separation of concerns
- Modular tool development
- Production-grade logging
- Dockerized deployment
- Reusable project structure
- Scalable code organization

It is intended to be a strong starting point for developers building AI-powered applications with MCP.

---

# 🏗 Architecture

The project follows a modular architecture to keep the codebase clean, maintainable, and easy to extend.

```mermaid
flowchart TD

    Client["MCP Client"]
    Server["FastMCP Server"]
    Registry["Tool Registry"]
    Calculator["Calculator Tools"]
    Time["Time Tools"]
    File["File Tools"]
    System["System Tools"]
    Math["Math Tools"]
    Text["Text Tools"]
    Utility["Utility Tools"]
    Logger["Logging System"]
    Logs["Log Files"]

    Client --> Server
    Server --> Registry

    Registry --> Calculator
    Registry --> Time
    Registry --> File
    Registry --> System
    Registry --> Math
    Registry --> Text
    Registry --> Utility

    Calculator --> Logger
    Time --> Logger
    File --> Logger
    System --> Logger
    Math --> Logger
    Text --> Logger
    Utility --> Logger

    Logger --> Logs
```

---

# 📂 Project Structure

```text
MCP_SERVER/
│
├── .github/
│   └── workflows/
│       └── ci.yml
│
├── app/
│   ├── tools/
│   │   ├── math_tool.py
│   │   ├── text_tools.py
│   │   └── utility_tools.py
│   │
│   ├── calculator.py
│   ├── datetime_tool.py
│   ├── file_reader.py
│   ├── logger.py
│   ├── log_decorator.py
│   ├── registry.py
│   ├── system_info.py
│   └── time_tool.py
│
├── logs/
│   ├── error.log
│   └── mcp.log
│
├── .dockerignore
├── .env
├── .gitignore
├── CHANGELOG.md
├── config.py
├── CONTRIBUTING.md
├── docker-compose.yml
├── Dockerfile
├── LICENSE
├── pyproject.toml
├── pytest.ini
├── README.md
├── requirements.txt
└── server.py
```

---

# ⚙ Project Workflow

```text
Start Server
      │
      ▼
Create FastMCP Instance
      │
      ▼
Register All Tools
      │
      ▼
Wait For MCP Client
      │
      ▼
Receive Tool Request
      │
      ▼
Execute Tool
      │
      ▼
Write Logs
      │
      ▼
Return Response
```

---

# 🛠 Tech Stack

| Technology | Purpose |
|------------|---------|
| 🐍 Python 3.11+ | Programming Language |
| ⚡ FastMCP | MCP Framework |
| 🤖 Model Context Protocol | AI Tool Communication |
| 🐳 Docker | Containerization |
| 📦 Docker Compose | Local Deployment |
| 📝 Logging | Monitoring & Debugging |
| ⚙ python-dotenv | Environment Variables |
| 🧪 Pytest | Future Testing |
| 🔄 GitHub Actions | Future CI/CD |

---

# 🎯 Design Principles

The project is built around a few core engineering principles:

- Modular architecture
- Single Responsibility Principle (SRP)
- Separation of Concerns
- Easy extensibility
- Centralized tool registration
- Consistent logging
- Docker-first deployment
- Clean project organization

---

# 📁 Core Modules

| Module | Responsibility |
|---------|----------------|
| `server.py` | Starts the MCP server |
| `registry.py` | Registers all available tools |
| `logger.py` | Configures application logging |
| `log_decorator.py` | Logs tool execution automatically |
| `config.py` | Central application configuration |
| `calculator.py` | Calculator-related tools |
| `time_tool.py` | Time and date utilities |
| `file_reader.py` | File reading tools |
| `system_info.py` | System information tools |
| `app/tools/` | Additional utility modules |

---

# 🚀 Request Lifecycle

```text
MCP Client
     │
     ▼
FastMCP Server
     │
     ▼
Registry
     │
     ▼
Requested Tool
     │
     ▼
Execute Function
     │
     ▼
Log Request
     │
     ▼
Return Result
```

---

# 📌 Key Advantages

- Clean folder structure
- Easy to maintain
- Easy to test
- Easy to extend
- Production-ready layout
- Reusable architecture
- Docker support
- Consistent logging
- Beginner friendly
- Open-source friendly

---

# 🚀 Getting Started

Follow the steps below to set up the project on your local machine.

---

# 📋 Prerequisites

Before running the project, ensure the following software is installed:

| Software | Version |
|----------|---------|
| Python | 3.11+ |
| Git | Latest |
| Docker *(Optional)* | Latest |
| Docker Compose *(Optional)* | Latest |

Verify your installation:

```bash
python --version
git --version
docker --version
```

---

# 📥 Clone the Repository

```bash
git clone https://github.com/golam74/MCP_SERVER.git
```

Navigate to the project directory:

```bash
cd MCP_SERVER
```

---

# 🐍 Create a Virtual Environment

### Windows

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

Activate it:

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

### Linux / macOS

```bash
python3 -m venv venv
```

Activate it:

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

---

# 📦 Install Dependencies

Upgrade pip:

```bash
python -m pip install --upgrade pip
```

Install project dependencies:

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

---

# ⚙ Environment Variables

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

Example:

```env
APP_NAME=MCP Server
LOG_LEVEL=INFO
```

You can add additional configuration values as your project grows.

---

# ▶ Run the Server

Start the MCP server:

```bash
python server.py
```

Expected output:

```text
============================================================
MCP Server started successfully.
============================================================
```

---

# 🐳 Docker Support

Build the Docker image:

```bash
docker build -t mcp-server .
```

Run the container:

```bash
docker run --rm mcp-server
```

---

# 🐳 Docker Compose

Start the project:

```bash
docker compose up --build
```

Stop the project:

```bash
docker compose down
```

---

# ✅ Verify Installation

Everything is configured correctly if:

- ✅ Virtual environment is activated
- ✅ Dependencies install successfully
- ✅ Server starts without errors
- ✅ Log files are created
- ✅ Docker image builds successfully
- ✅ Docker Compose starts correctly

---

# 📄 Configuration Files

| File | Description |
|------|-------------|
| `server.py` | Application entry point |
| `config.py` | Application configuration |
| `.env` | Environment variables |
| `requirements.txt` | Python dependencies |
| `Dockerfile` | Docker image |
| `docker-compose.yml` | Docker Compose configuration |
| `README.md` | Project documentation |

---

# 📝 Logging

The server automatically creates log files inside the `logs/` directory.

```text
logs/
├── mcp.log
└── error.log
```

Each tool execution is logged with:

- Timestamp
- Tool Name
- Arguments
- Result
- Exceptions (if any)

Example:

```text
2026-07-18 05:38:43 | INFO | Tool Started : add_numbers
2026-07-18 05:38:43 | INFO | Arguments : (10, 20)
2026-07-18 05:38:43 | INFO | Result : 30
2026-07-18 05:38:43 | INFO | Tool Finished : add_numbers
```

---

# 🧩 Available MCP Tools

The server is organized into independent tool modules, making it easy to maintain and extend.

| Category | Description |
|----------|-------------|
| ➕ Calculator Tools | Basic arithmetic operations |
| 🕒 Time Tools | Current date and time utilities |
| 📄 File Reader | Read text files safely |
| 💻 System Information | Operating system and hardware details |
| 🔢 Math Tools | Advanced mathematical utilities |
| 📝 Text Tools | String manipulation and formatting |
| ⚙ Utility Tools | General-purpose helper utilities |

---

# 🚀 Adding a New Tool

Adding a new tool to the server requires only three simple steps.

## Step 1

Create your tool inside the appropriate module.

Example:

```python
@mcp.tool
def square(number: int) -> int:
    return number * number
```

---

## Step 2

Register the tool inside the module.

```python
def register_math_tools(mcp):
    ...
```

---

## Step 3

Import the registration function into:

```text
app/registry.py
```

and register it:

```python
register_math_tools(mcp)
```

That's it!

No changes are required in `server.py`.

---

# 💻 Example Usage

## Calculator

```python
add_numbers(10, 20)

# Output
30
```

---

## Time Tool

```python
get_current_time()
```

Output

```text
10:45:23
```

---

## File Reader

```python
read_file("example.txt")
```

Output

```text
Hello World
```

---

## System Information

```python
get_system_info()
```

Example Output

```text
Operating System : Windows
Python Version   : 3.11
Machine          : AMD64
```

---

# 📜 Logging

Every tool execution is automatically logged.

Logged information includes:

- Tool Name
- Arguments
- Return Value
- Exceptions
- Timestamp

Example

```text
2026-07-18 05:38:43 | INFO | Tool Started : add_numbers
2026-07-18 05:38:43 | INFO | Arguments : (10, 20)
2026-07-18 05:38:43 | INFO | Result : 30
2026-07-18 05:38:43 | INFO | Tool Finished : add_numbers
```

---

# 📊 Project Status

| Feature | Status |
|---------|--------|
| FastMCP Server | ✅ |
| Tool Registry | ✅ |
| Professional Logging | ✅ |
| Docker Support | ✅ |
| Docker Compose | ✅ |
| Environment Configuration | ✅ |
| Modular Architecture | ✅ |
| GitHub Repository | ✅ |
| Unit Tests | 🚧 |
| GitHub Actions | 🚧 |

---

# 🗺 Roadmap

## Version 1.0

- [x] FastMCP Server
- [x] Tool Registration System
- [x] Modular Architecture
- [x] Logging System
- [x] Docker Support
- [x] Docker Compose

---

## Version 1.1

- [ ] Unit Testing
- [ ] GitHub Actions
- [ ] Code Coverage
- [ ] Better Error Handling

---

## Version 1.2

- [ ] Async Tools
- [ ] More Utility Tools
- [ ] Performance Optimization

---

## Version 2.0

- [ ] Authentication
- [ ] Database Support
- [ ] Monitoring Dashboard
- [ ] Plugin Architecture

---

# 🤝 Contributing

Contributions are always welcome!

If you'd like to improve this project, please follow these steps:

1. Fork the repository.
2. Create a new feature branch.

```bash
git checkout -b feature/awesome-feature
```

3. Commit your changes.

```bash
git commit -m "Add awesome feature"
```

4. Push your branch.

```bash
git push origin feature/awesome-feature
```

5. Open a Pull Request.

Please make sure your code follows the existing project structure and coding style.

---

# 🧪 Future Improvements

The following features are planned for future releases:

- Async MCP Tools
- Unit & Integration Tests
- GitHub Actions (CI/CD)
- Code Coverage Reports
- Performance Benchmarking
- Authentication & Authorization
- Database Integration
- Plugin Architecture
- Monitoring Dashboard
- API Documentation

---

# 📈 Project Goals

This repository is designed to serve as:

- 📚 A learning resource for developers exploring MCP.
- 🏗 A production-ready starter template.
- 🤖 A foundation for AI tool development.
- 🚀 A portfolio-quality open-source project.

---

# 🤝 Support

If you find this project useful:

- ⭐ Star the repository
- 🍴 Fork the project
- 🐛 Report bugs
- 💡 Suggest new features
- 🔥 Contribute improvements

Your support helps make the project better for everyone.

---

# 📄 License

This project is licensed under the **MIT License**.

See the [LICENSE](LICENSE) file for more details.

---

# 👨‍💻 Author

## Golam Israil

**AI Engineer | Python Developer | AI Automation Enthusiast**

### Connect with Me

- GitHub: https://github.com/golam74
- LinkedIn: *(Add your LinkedIn profile here)*

---

# 🙏 Acknowledgements

Special thanks to the amazing open-source community and the technologies that made this project possible.

- Python
- FastMCP
- Model Context Protocol (MCP)
- Docker
- GitHub
- Open Source Community

---

# 🌟 If You Like This Project

If this repository helped you learn something new or saved you time:

⭐ Give it a Star

🍴 Fork it

📢 Share it with others

Every contribution and every star motivates further development.

---

<div align="center">

# 🚀 Happy Coding!

### Build • Learn • Share • Grow

Made with ❤️ by **Golam Israil**

</div>