Skip to content
Back to search

nexlevr-internship-intermediate-task-1-hyfux-business-assistant

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/chamsoubl--nexlevr-internship-intermediate-task-1-hyfux-business-assistant/badge.svg)](/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
  1. # Nexlevr Internship – Intermediate Task 1: Build Your Own MCP Server
  2. **Organization:** [Nexlevr](https://github.com/Nexlevr)
  3. **Internship Track:** Intermediate
  4. **Task:** 1 of 3 – Build Your Own MCP Server
  5. **Project:** HYFUX Business Assistant
  6. **Developer:** Chems Eddine Blada
  7. **Technology:** Python, MCP, Supabase
  8. **Status:** Completed
  9. ---
  10. ## About the Internship
  11. This project is part of the Nexlevr Internship Program, which includes Beginner, Intermediate, and Advanced task tracks.
  12. 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.
  13. ## Project Overview
  14. The objective was to build a custom MCP server that exposes useful business functions as tools an AI assistant can discover and execute.
  15. For this task, I developed **HYFUX Business Assistant**, an MCP server inspired by my HYFUX Mixbar project.
  16. The server connects to a separate Supabase demo database containing fictional business data. It provides tools for business analytics, inventory management, and order management.
  17. ## Objectives
  18. - Understand the Model Context Protocol (MCP).
  19. - Build a custom MCP server using Python.
  20. - Connect the server to a Supabase database.
  21. - Expose business functions as MCP tools.
  22. - Implement input validation and error handling.
  23. - Define tool permissions and document their side effects.
  24. - Test the server and its tools using MCP Inspector.
  25. - Document the architecture, setup, and usage.
  26. ## Project Architecture
  27. The project follows a modular structure, separating database connectivity, business logic, security validation, and MCP tool definitions.
  28. ```text
  29. hyfux-business-assistant/
  30. │
  31. ├── config/
  32. │ └── settings.py
  33. │
  34. ├── data/
  35. │ └── sample_inventory.csv
  36. │
  37. ├── src/
  38. │ ├── analytics_tools.py
  39. │ ├── database.py
  40. │ ├── inventory_tools.py
  41. │ ├── mcp_server.py
  42. │ ├── order_tools.py
  43. │ └── security.py
  44. │
  45. ├── .env.example
  46. ├── .gitignore
  47. ├── README.md
  48. └── requirements.txt
  49. ```
  50. ## Implemented MCP Tools
  51. ### 1. Business Analytics
  52. **Tool:** `get_business_analytics`
  53. Retrieves business performance information from the Supabase database.
  54. **Features:**
  55. - Calculate total revenue.
  56. - Calculate average order value.
  57. - Count total orders.
  58. - Display order status breakdown.
  59. - Identify best-selling products.
  60. **Permissions:**
  61. - Read-only access.
  62. - Cannot modify business records.
  63. **Business Use Case:** Business owners can ask an AI assistant to analyze sales performance and retrieve useful business insights.
  64. ### 2. Inventory Management
  65. **Tool:** `manage_inventory`
  66. Provides inventory operations through four available actions.
  67. | Action | Description | Permission |
  68. |---|---|---|
  69. | `check` | Retrieve inventory information | Read-only |
  70. | `low_stock` | Identify ingredients at or below minimum stock | Read-only |
  71. | `receive` | Add newly received stock | Write |
  72. | `consume` | Record ingredient consumption | Write |
  73. **Security and Validation:**
  74. - Validates ingredient names.
  75. - Requires positive finite quantities.
  76. - Rejects consumption exceeding available stock.
  77. - Returns structured error responses.
  78. **Business Use Case:** An AI assistant can check stock levels, identify ingredients that need restocking, and update inventory records.
  79. ### 3. Order Management
  80. **Tool:** `manage_orders`
  81. Provides order retrieval and management through four available actions.
  82. | Action | Description | Permission |
  83. |---|---|---|
  84. | `list` | Retrieve all orders | Read-only |
  85. | `get` | Retrieve an order and its items | Read-only |
  86. | `summary` | Count orders by status | Read-only |
  87. | `update_status` | Change an order's status | Write |
  88. **Security and Validation:**
  89. - Validates order numbers.
  90. - Validates requested order statuses.
  91. - Enforces permitted status transitions.
  92. - Rejects invalid status changes.
  93. - Returns structured error responses.
  94. **Valid Order Statuses:**
  95. `pending`, `preparing`, `ready`, `delivered`, `cancelled`.
  96. **Business Use Case:** An AI assistant can retrieve customer orders, check their status, and update order progress while respecting predefined business rules.
  97. ## Database Integration
  98. The MCP server connects to a separate Supabase demo project using the Supabase Python client.
  99. The database contains the following tables:
  100. - `products`
  101. - `inventory`
  102. - `orders`
  103. - `order_items`
  104. - `business_settings`
  105. The demo database uses fictional business records and is separate from the production HYFUX project.
  106. Database credentials are loaded through environment variables and are not included in this repository.
  107. ## Security and Permissions
  108. Security was considered throughout the implementation.
  109. - Environment variables are used for database credentials.
  110. - `.env` is excluded from Git using `.gitignore`.
  111. - `.env.example` provides placeholder configuration.
  112. - Row Level Security (RLS) is enabled on the demo database tables.
  113. - Direct table privileges are revoked from the `anon` and `authenticated` roles.
  114. - Input validation is implemented for inventory quantities, ingredient names, and order numbers.
  115. - Inventory and order operations enforce business rules.
  116. - Tools document which operations are read-only and which modify database records.
  117. **Important:** The Supabase secret key is used only by the Python backend and must never be exposed publicly.
  118. ## Testing and Verification
  119. The project was tested using Python and MCP Inspector.
  120. Verification included:
  121. - Testing the Supabase database connection.
  122. - Running business analytics operations.
  123. - Retrieving inventory records.
  124. - Testing inventory stock updates.
  125. - Retrieving and summarizing customer orders.
  126. - Testing order status updates.
  127. - Checking invalid inventory quantities.
  128. - Rejecting inventory consumption exceeding available stock.
  129. - Rejecting invalid order numbers.
  130. - Rejecting invalid order status transitions.
  131. - Confirming that all three MCP tools are available through MCP Inspector.
  132. ## Running the Project
  133. ### 1. Clone the Repository
  134. ```bash
  135. git clone https://github.com/chamsoubl/nexlevr-internship-intermediate-task-1-hyfux-business-assistant.git
  136. cd nexl evr-internship-intermediate-task-1-hyfux-business-assistant
  137. ```
  138. **Use this corrected directory command instead:**
  139. ```bash
  140. cd nexl evr-internship-intermediate-task-1-hyfux-business-assistant
  141. ```
  142. ### 2. Create a Virtual Environment
  143. ```bash
  144. python -m venv .venv
  145. ```
  146. Activate it on Windows:
  147. ```powershell
  148. .venv\Scripts\Activate.ps1
  149. ```
  150. ### 3. Install Dependencies
  151. ```bash
  152. pip install -r requirements.txt
  153. ```
  154. ### 4. Configure Environment Variables
  155. Create a local `.env` file using `.env.example` as a template.
  156. Add your own Supabase demo project credentials:
  157. ```dotenv
  158. SUPABASE_URL=your_supabase_project_url
  159. SUPABASE_SECRET_KEY=your_supabase_secret_key
  160. ```
  161. Never commit your `.env` file or expose your Supabase secret key.
  162. ### 5. Run the MCP Inspector
  163. ```bash
  164. mcp dev src/mcp_server.py --with supabase --with python-dotenv
  165. ```
  166. Use MCP Inspector to discover and test the three available tools.
  167. ## Technologies and Tools
  168. - Python
  169. - Model Context Protocol (MCP)
  170. - Supabase
  171. - PostgreSQL
  172. - Supabase Python Client
  173. - python-dotenv
  174. - MCP Inspector
  175. - Git and GitHub
  176. ---
  177. **[Nexlevr](https://github.com/Nexlevr) Internship – Intermediate Track | Task 1 of 3**
  178. **Project:** HYFUX Business Assistant – MCP Server
  179. **Repository:** `nexlevr-internship-intermediate-task-1-hyfux-business-assistant`

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.