OXII Smart Home MCP Server

Modern documentation for the device-control MCP stack that pairs with the FastAPI chatbot. Use this guide the same way you would the chatbot docs: it covers setup, commands, tooling, and troubleshooting for standalone MCP development.

🔎 Overview

mcp/oxii-server/
├── main.py            # Boots the FastMCP process and registers tools
├── tools/             # Tool implementations (auth, device control, cronjobs…)
├── client.py          # Quick demo client for manual testing
├── docker-compose.yml # Containerized runtime (exposes :9031)
└── .env.example       # Sample environment for OXII credentials

✅ Prerequisites

• Python 3.10 or newer (Poetry will manage dependencies), or Docker Engine 20.10+

• OXII account credentials with device access (phone, password, country)

• Network access to the OXII staging/prod API defined in OXII_BASE_URL

⚙️ Environment configuration

Create a working copy of the environment file and fill in the secrets:

cp .env.example .env

🚀 Running the server

Option 1 – Local Poetry workflow

poetry install
poetry run python main.py

This starts the server at http://localhost:9031/sse.

Option 2 – Docker Compose

cp .env.example .env  # if you have not already
docker compose up --build -d

The compose stack exposes port 9031 on the host. Combine this with the chatbot by pointing OXII_MCP_SERVER_URL to http://host.docker.internal:9031/sse inside the chatbot container.

✅ Verifying the service

1. Use the bundled client

poetry run python client.py

Select a tool from the prompt and provide the required parameters to confirm end-to-end connectivity.

2. Visit the built-in docs UI

• Human friendly docs: http://host.docker.internal:9031/docx

• Machine readable catalogue: http://host.docker.internal:9031/docs.json

3. Curl the SSE handshake

curl -N http://localhost:9031/sse

You should see an initial JSON payload describing the MCP capabilities.

🧰 Tool catalogue

Below is a quick reference for each registered MCP tool. All payloads are JSON structures passed through the MCP protocol.

ℹ️ Detailed schemas live in tools/ next to each function. Review those modules for argument validation and API payload shapes.

🔄 Working with the chatbot

1. Start the MCP server (local or Docker) and ensure port 9031 is reachable from the chatbot environment.

2. In chatbot/.env, set OXII_MCP_SERVER_URL=http://host.docker.internal:9031/sse when running the chatbot in Docker.

3. Restart the chatbot container (docker compose restart app) to apply env changes.

4. Use the chatbot endpoint POST /ai/agent-oxii with a valid OXII token—the agent will automatically call the MCP tools.

🧪 Testing & diagnostics

• Unit checks – Run poetry run pytest if you add tests (seed file test_tools.py is available as a template).

• Token validation – Use chatbot/test_folders/testing_api.py to fetch a fresh token before invoking tools.

• Logs – With DEBUG=true, the server prints detailed traces for each MCP call. In Docker, view them with docker compose logs -f oxii-server.

🛠 Troubleshooting

📚 Further reading

• Model Context Protocol (MCP) specification

• LangChain MCP Adapters

• chatbot/README.md for the FastAPI-side integration guide.