MCP PiShock Server

English | Français

---

English

HTTP streamable MCP (Model Context Protocol) server for controlling PiShock devices via their REST API.

Features

• SHOCK: Activates electric shock function with duration (1-15s) and intensity (1-100)
• VIBRATE: Activates vibration function with duration and intensity (1-100)
• BEEP: Activates beep sound function with duration
• Authentication: Bearer token protection
• MCP Protocol: Full MCP 2025-06-18 protocol support with tool discovery
• Docker: Containerized with environment variable configuration

Configuration

1. Copy .env.example to .env:

cp .env.example .env

2. Fill in the environment variables in .env:

PISHOCK_USERNAME=your_username
PISHOCK_APIKEY=your_api_key
PISHOCK_CODE=your_share_code
MCP_AUTH_TOKEN=secure_random_token
SCRIPT_NAME=MCP_Server

Getting PiShock Credentials

1. Create an account on PiShock.com
2. In the Account section:
   • Get your Username
   • Generate an API Key
   • Create a Share Code with desired limitations

Deployment

With Docker Compose (recommended)

docker-compose up -d

With Docker

docker build -t pishock-mcp-server .
docker run -d \
  -p 8000:8000 \
  --env-file .env \
  --name pishock-mcp-server \
  pishock-mcp-server

Local Development

pip install -r requirements.txt
python app.py

MCP Client Usage

The server implements the full MCP protocol. MCP clients will automatically:

1. Initialize with the server using the initialize method
2. Discover tools using tools/list to see available SHOCK, VIBRATE, BEEP functions
3. Call tools using tools/call with the appropriate parameters

Authentication

All requests require a Bearer token in the Authorization header:

Authorization: Bearer YOUR_MCP_AUTH_TOKEN

Available Tools

• SHOCK: {"name": "SHOCK", "arguments": {"duration": 2, "intensity": 10}}
• VIBRATE: {"name": "VIBRATE", "arguments": {"duration": 3, "intensity": 50}}
• BEEP: {"name": "BEEP", "arguments": {"duration": 1}}

Direct API Usage (Compatibility)

For non-MCP clients, direct endpoints are available:

# Shock
curl -X POST "http://localhost:8000/mcp/SHOCK" \
  -H "Authorization: Bearer your_token" \
  -H "Content-Type: application/json" \
  -d '{"duration": 1, "intensity": 5}'

# Vibrate
curl -X POST "http://localhost:8000/mcp/VIBRATE" \
  -H "Authorization: Bearer your_token" \
  -H "Content-Type: application/json" \
  -d '{"duration": 2, "intensity": 30}'

# Beep
curl -X POST "http://localhost:8000/mcp/BEEP" \
  -H "Authorization: Bearer your_token" \
  -H "Content-Type: application/json" \
  -d '{"duration": 1}'

Monitoring

• Health Check: GET /health
• API Documentation: http://localhost:8000/docs
• MCP Info: GET /mcp
• Logs: docker-compose logs -f

Security

⚠️ WARNING: Shock devices are not designed for human use and can cause serious injury including cardiac events. Never use near the heart or if you have heart conditions.

• Use strong authentication tokens
• Limit network access to the server
• Configure appropriate limits in PiShock
• Monitor usage logs

Limitations

• Shock duration: 1-15 seconds (PiShock API limit)
• Intensity: 1-100 (PiShock API limit)
• One command at a time per share code
• Device must be online and connected

---

Serveur MCP PiShock (Français)

Serveur MCP (Model Context Protocol) HTTP streamable pour contrôler les dispositifs PiShock via leur API REST.

Fonctionnalités

• SHOCK: Active la fonction de choc électrique avec durée (1-15s) et intensité (1-100)
• VIBRATE: Active la fonction de vibration avec durée et intensité (1-100)
• BEEP: Active la fonction de bip sonore avec durée
• Authentification: Protection par token Bearer
• Protocole MCP: Support complet du protocole MCP 2025-06-18 avec découverte d'outils
• Docker: Containerisé avec toutes les variables d'environnement

Configuration

1. Copiez .env.example vers .env:

cp .env.example .env

2. Remplissez les variables d'environnement dans .env:

PISHOCK_USERNAME=votre_nom_utilisateur
PISHOCK_APIKEY=votre_cle_api
PISHOCK_CODE=votre_code_partage
MCP_AUTH_TOKEN=un_token_securise_aleatoire
SCRIPT_NAME=MCP_Server

Obtenir les identifiants PiShock

1. Créez un compte sur PiShock.com
2. Dans la section Account :
   • Récupérez votre Username
   • Générez une API Key
   • Créez un Share Code avec les limitations désirées

Déploiement

Avec Docker Compose (recommandé)

docker-compose up -d

Avec Docker

docker build -t pishock-mcp-server .
docker run -d \
  -p 8000:8000 \
  --env-file .env \
  --name pishock-mcp-server \
  pishock-mcp-server

Développement local

pip install -r requirements.txt
python app.py

Utilisation avec un client MCP

Le serveur implémente le protocole MCP complet. Les clients MCP vont automatiquement :

1. S'initialiser avec le serveur via la méthode initialize
2. Découvrir les outils via tools/list pour voir les fonctions SHOCK, VIBRATE, BEEP disponibles
3. Appeler les outils via tools/call avec les paramètres appropriés

Authentification

Toutes les requêtes nécessitent un token Bearer dans l'header Authorization :

Authorization: Bearer YOUR_MCP_AUTH_TOKEN

Outils disponibles

• SHOCK: {"name": "SHOCK", "arguments": {"duration": 2, "intensity": 10}}
• VIBRATE: {"name": "VIBRATE", "arguments": {"duration": 3, "intensity": 50}}
• BEEP: {"name": "BEEP", "arguments": {"duration": 1}}

Utilisation API directe (Compatibilité)

Pour les clients non-MCP, des endpoints directs sont disponibles :

# Shock
curl -X POST "http://localhost:8000/mcp/SHOCK" \
  -H "Authorization: Bearer your_token" \
  -H "Content-Type: application/json" \
  -d '{"duration": 1, "intensity": 5}'

# Vibrate
curl -X POST "http://localhost:8000/mcp/VIBRATE" \
  -H "Authorization: Bearer your_token" \
  -H "Content-Type: application/json" \
  -d '{"duration": 2, "intensity": 30}'

# Beep
curl -X POST "http://localhost:8000/mcp/BEEP" \
  -H "Authorization: Bearer your_token" \
  -H "Content-Type: application/json" \
  -d '{"duration": 1}'

Surveillance

• Health Check: GET /health
• Documentation API: http://localhost:8000/docs
• Informations MCP: GET /mcp
• Logs: docker-compose logs -f

Sécurité

⚠️ AVERTISSEMENT: Les dispositifs de choc ne sont pas conçus pour un usage humain et peuvent causer des blessures graves y compris des événements cardiaques. Ne jamais utiliser près du cœur ou si vous avez des problèmes cardiaques.

• Utilisez des tokens d'authentification forts
• Limitez l'accès réseau au serveur
• Configurez des limites appropriées dans PiShock
• Surveillez les logs d'utilisation

Limitations

• Durée de choc : 1-15 secondes (limite API PiShock)
• Intensité : 1-100 (limite API PiShock)
• Une seule commande à la fois par share code
• Le dispositif doit être en ligne et connecté