Back to search
nexlevr-internship-intermediate-task-1-hyfux-business-assistant
MCP serverGitHub
Nexlevr Intermediate Track – Task 1: Building a custom MCP server for business analytics, inventory, and order management.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/chamsoubl--nexlevr-internship-intermediate-task-1-hyfux-business-assistant)HTML
<a href="/listings/chamsoubl--nexlevr-internship-intermediate-task-1-hyfux-business-assistant"><img src="/api/listings/chamsoubl--nexlevr-internship-intermediate-task-1-hyfux-business-assistant/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
pip install -r requirements.txt
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 253 lines
- # Nexlevr Internship – Intermediate Task 1: Build Your Own MCP Server
- **Organization:** [Nexlevr](https://github.com/Nexlevr)
- **Internship Track:** Intermediate
- **Task:** 1 of 3 – Build Your Own MCP Server
- **Project:** HYFUX Business Assistant
- **Developer:** Chems Eddine Blada
- **Technology:** Python, MCP, Supabase
- **Status:** Completed
- ---
- ## About the Internship
- This project is part of the Nexlevr Internship Program, which includes Beginner, Intermediate, and Advanced task tracks.
- This repository documents my work on the first Intermediate-level task, focusing on building a custom Model Context Protocol (MCP) server that allows an AI assistant to interact with business data and perform useful operations through dedicated tools.
- ## Project Overview
- The objective was to build a custom MCP server that exposes useful business functions as tools an AI assistant can discover and execute.
- For this task, I developed **HYFUX Business Assistant**, an MCP server inspired by my HYFUX Mixbar project.
- The server connects to a separate Supabase demo database containing fictional business data. It provides tools for business analytics, inventory management, and order management.
- ## Objectives
- - Understand the Model Context Protocol (MCP).
- - Build a custom MCP server using Python.
- - Connect the server to a Supabase database.
- - Expose business functions as MCP tools.
- - Implement input validation and error handling.
- - Define tool permissions and document their side effects.
- - Test the server and its tools using MCP Inspector.
- - Document the architecture, setup, and usage.
- ## Project Architecture
- The project follows a modular structure, separating database connectivity, business logic, security validation, and MCP tool definitions.
- ```text
- hyfux-business-assistant/
- │
- ├── config/
- │ └── settings.py
- │
- ├── data/
- │ └── sample_inventory.csv
- │
- ├── src/
- │ ├── analytics_tools.py
- │ ├── database.py
- │ ├── inventory_tools.py
- │ ├── mcp_server.py
- │ ├── order_tools.py
- │ └── security.py
- │
- ├── .env.example
- ├── .gitignore
- ├── README.md
- └── requirements.txt
- ```
- ## Implemented MCP Tools
- ### 1. Business Analytics
- **Tool:** `get_business_analytics`
- Retrieves business performance information from the Supabase database.
- **Features:**
- - Calculate total revenue.
- - Calculate average order value.
- - Count total orders.
- - Display order status breakdown.
- - Identify best-selling products.
- **Permissions:**
- - Read-only access.
- - Cannot modify business records.
- **Business Use Case:** Business owners can ask an AI assistant to analyze sales performance and retrieve useful business insights.
- ### 2. Inventory Management
- **Tool:** `manage_inventory`
- Provides inventory operations through four available actions.
- | Action | Description | Permission |
- |---|---|---|
- | `check` | Retrieve inventory information | Read-only |
- | `low_stock` | Identify ingredients at or below minimum stock | Read-only |
- | `receive` | Add newly received stock | Write |
- | `consume` | Record ingredient consumption | Write |
- **Security and Validation:**
- - Validates ingredient names.
- - Requires positive finite quantities.
- - Rejects consumption exceeding available stock.
- - Returns structured error responses.
- **Business Use Case:** An AI assistant can check stock levels, identify ingredients that need restocking, and update inventory records.
- ### 3. Order Management
- **Tool:** `manage_orders`
- Provides order retrieval and management through four available actions.
- | Action | Description | Permission |
- |---|---|---|
- | `list` | Retrieve all orders | Read-only |
- | `get` | Retrieve an order and its items | Read-only |
- | `summary` | Count orders by status | Read-only |
- | `update_status` | Change an order's status | Write |
- **Security and Validation:**
- - Validates order numbers.
- - Validates requested order statuses.
- - Enforces permitted status transitions.
- - Rejects invalid status changes.
- - Returns structured error responses.
- **Valid Order Statuses:**
- `pending`, `preparing`, `ready`, `delivered`, `cancelled`.
- **Business Use Case:** An AI assistant can retrieve customer orders, check their status, and update order progress while respecting predefined business rules.
- ## Database Integration
- The MCP server connects to a separate Supabase demo project using the Supabase Python client.
- The database contains the following tables:
- - `products`
- - `inventory`
- - `orders`
- - `order_items`
- - `business_settings`
- The demo database uses fictional business records and is separate from the production HYFUX project.
- Database credentials are loaded through environment variables and are not included in this repository.
- ## Security and Permissions
- Security was considered throughout the implementation.
- - Environment variables are used for database credentials.
- - `.env` is excluded from Git using `.gitignore`.
- - `.env.example` provides placeholder configuration.
- - Row Level Security (RLS) is enabled on the demo database tables.
- - Direct table privileges are revoked from the `anon` and `authenticated` roles.
- - Input validation is implemented for inventory quantities, ingredient names, and order numbers.
- - Inventory and order operations enforce business rules.
- - Tools document which operations are read-only and which modify database records.
- **Important:** The Supabase secret key is used only by the Python backend and must never be exposed publicly.
- ## Testing and Verification
- The project was tested using Python and MCP Inspector.
- Verification included:
- - Testing the Supabase database connection.
- - Running business analytics operations.
- - Retrieving inventory records.
- - Testing inventory stock updates.
- - Retrieving and summarizing customer orders.
- - Testing order status updates.
- - Checking invalid inventory quantities.
- - Rejecting inventory consumption exceeding available stock.
- - Rejecting invalid order numbers.
- - Rejecting invalid order status transitions.
- - Confirming that all three MCP tools are available through MCP Inspector.
- ## Running the Project
- ### 1. Clone the Repository
- ```bash
- git clone https://github.com/chamsoubl/nexlevr-internship-intermediate-task-1-hyfux-business-assistant.git
- cd nexl evr-internship-intermediate-task-1-hyfux-business-assistant
- ```
- **Use this corrected directory command instead:**
- ```bash
- cd nexl evr-internship-intermediate-task-1-hyfux-business-assistant
- ```
- ### 2. Create a Virtual Environment
- ```bash
- python -m venv .venv
- ```
- Activate it on Windows:
- ```powershell
- .venv\Scripts\Activate.ps1
- ```
- ### 3. Install Dependencies
- ```bash
- pip install -r requirements.txt
- ```
- ### 4. Configure Environment Variables
- Create a local `.env` file using `.env.example` as a template.
- Add your own Supabase demo project credentials:
- ```dotenv
- SUPABASE_URL=your_supabase_project_url
- SUPABASE_SECRET_KEY=your_supabase_secret_key
- ```
- Never commit your `.env` file or expose your Supabase secret key.
- ### 5. Run the MCP Inspector
- ```bash
- mcp dev src/mcp_server.py --with supabase --with python-dotenv
- ```
- Use MCP Inspector to discover and test the three available tools.
- ## Technologies and Tools
- - Python
- - Model Context Protocol (MCP)
- - Supabase
- - PostgreSQL
- - Supabase Python Client
- - python-dotenv
- - MCP Inspector
- - Git and GitHub
- ---
- **[Nexlevr](https://github.com/Nexlevr) Internship – Intermediate Track | Task 1 of 3**
- **Project:** HYFUX Business Assistant – MCP Server
- **Repository:** `nexlevr-internship-intermediate-task-1-hyfux-business-assistant`
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.