Servant

Smart Home Assistant Platform

Managing a household involves many small but important tasks: keeping your shopping list up to date, adjusting the heating system, maintaining control over your home calendar so you don't forget to pick up your child when they finish their music lessons, or monitoring some home automation events like temperatures, waterleaking sensors, devices in my wifi network or main door's status. Servant helps you take care of these recurring activities automatically and intelligently—so your home works with you, not against you.

Servant is your home assistant platform to simplify and automate domestic tasks efficiently.

Table of Contents

• Introduction
• Key Features
• Requirements
• Getting Started
• Related Projects & Technologies
• License

Introduction

Servant is a flexible and extensible home assistance platform designed to integrate seamlessly with sensors, actuators, and external systems. Unlike traditional solutions, Servant provides a customizable software architecture that adapts to your needs—whether it’s managing daily tasks, automating workflows, or enabling advanced AI-driven interactions.

Key Features

Modularity

Servant is composed for several modules. Each one corresponds to a logical subsystem. A module provides a set of functionalities provided as action calls and events subscription.

AI Capabilities

MCP implementation. Servant implements the Java SDK MCP server API, providing several Model Context Protocol (MCP) tools. This toolkit allows the integration of Servant in any GenAI Agentic system. The current implementation allows interaction with several modules of servant such as the shopping list, the calendar, temperature monitoring system and the notifications manager which facilitates (Telegram messages) messages publication. In future versions of Servant, new MCP tools will be provided with additional commands and actions.

Large Language Models (LLMs) offer a novel way to interact with your data. In addition to generating content from a given input, LLMs can be utilized to transform heterogeneous and irregular content into structured and more analyzable output. This transformed content can then be used to build a knowledge data model for future activities.

Interaction Human or machine interactions with Servant are possible through the pre-built interfaces:

• Servant provides a RESTful API and integration to its messaging system through WebSockets. You can use these interfaces to build your own data consumer or data tracker agents in your preferred programming language.

• Web interface that allows the creation of web applications.

• Telegram chatbot as an asynchronous human/system interface.

• Google Calendar integration to schedule and run actions at specific times.

• VoIP interface which provides a conversational solution between the user and Servant.

Extensibility

Servant provides an extensible framework, implemented in Java and Kotlin, that allows the integration of new elements like sensors and actuators.

Integration of any kind of device into Internet of Things (IoT) technology is straightforward. Thanks to a distributed messaging system and Java, interfacing with any system to send or receive data from/to the cloud is never difficult. Integration with systems like IFTTT is supported.

Servant provides an MQTT interface to interact with sensors and external actuators. This solution is already integrated with a Zigbee2MQTT solution to connect to other systems.

Smart

• Implementation based on two basic concepts: events and actions. It makes it easy to create advanced algorithms for devices to interact together (sensors and/or actuators) or with external systems.

• Natural language processing for better human/system interaction.

• Scheduler for automatic actions and event triggering.

• Working on integration with OpenAI and a Neo4j knowledge database.

Additional Functionalities

• Includes integrations with MongoDB and Neo4j

• Easy JSON ↔ Java transformation.

Implementation Details

• To simplify development, a Convention over Configuration policy has been adopted. This project implements and abstracts some concepts, providing a mini-framework to simplify development: - Provides an almost 99% friendly object-oriented static way to map and use JSON data. - Improved communication system inside the Vert.x nodes system using Java enum objects. - Toolkit to build state machines with a Java enums language. - Interaction between Java and Kotlin code.

• Asynchronous JVM project (Java & Kotlin) based on Eclipse Vert.x

• Built-in facilities on top of Vert.x Event Bus to handle interaction with events in a controlled way.

Requirements

• Java 21
• Linux-based system

Getting Started

1. Clone the repository
2. Ensure Java 21 is installed
3. Build the project using Maven:

   mvn compile
   

4. Configure your settings in the config file
5. Run the application

Related Projects & Technologies

This project integrates with and builds upon several open-source technologies:

• Messaging & Communication: Eclipse Vert.x, MQTT, WebSockets
• Databases: MongoDB, Neo4j, SQLite
• AI & ML: OpenAI API, Model Context Protocol
• Smart Home: Zigbee2MQTT, MQTT
• External Services: Telegram Bot API, Google Calendar API, AWS SDK
• Build Tools: Apache Maven

License

See the LICENSE file for details.