mcp-server-boilerplate by pl974 - MCP Server

🚀 MCP Server Boilerplate - Full Stack

Un boilerplate complet avec serveur MCP, API backend FastAPI, et interface web React pour gérer vos outils Model Context Protocol avec Claude.

✨ Fonctionnalités

Serveur MCP

✅ Support stdio (Claude Desktop local)
✅ Support HTTP/SSE (déploiement production)
✅ Outils d'exemple personnalisables
✅ Détecteur de mots-clés (exemple: Thibaut)
✅ Logging automatique dans la base de données

Backend FastAPI

✅ API REST complète avec authentification JWT
✅ Gestion des utilisateurs (User/Admin)
✅ Tracking de l'utilisation des outils MCP
✅ Logs d'activité
✅ Base de données SQLite avec SQLAlchemy

Frontend React

✅ Interface moderne avec Vite + React
✅ Dashboard Utilisateur
✅ Dashboard Admin avec statistiques
✅ Gestion des utilisateurs
✅ Visualisation des logs MCP

🏗️ Structure du projet

mcp-server-boilerplate/
├── server.py                 # Serveur MCP principal
├── requirements.txt          # Dépendances Python
├── setup.bat                 # Script d'installation Windows
├── start_backend.bat         # Démarrer l'API
├── start_frontend.bat        # Démarrer le frontend
│
├── backend/                  # API FastAPI
│   ├── main.py              # Application FastAPI
│   ├── auth.py              # Authentification JWT
│   └── schemas.py           # Schémas Pydantic
│
├── database/                 # Base de données
│   ├── models.py            # Modèles SQLAlchemy
│   ├── seed.py              # Données initiales
│   └── mcp_boilerplate.db   # SQLite database
│
├── tools/                    # Outils MCP
│   ├── example_tool.py      # Outils d'exemple
│   ├── api_bridge.py        # Bridge API REST
│   ├── thibaut_detector.py  # Détecteur custom
│   └── database_tool.py     # Outils BDD
│
└── frontend/                 # Interface React
    ├── src/
    │   ├── components/
    │   │   ├── Login.jsx
    │   │   ├── UserDashboard.jsx
    │   │   └── AdminDashboard.jsx
    │   ├── api/
    │   │   └── auth.js
    │   └── App.jsx
    └── package.json

🔧 Installation

Prérequis

Python 3.11+
Node.js 18+
uv (recommandé) ou pip

Installation rapide

# 1. Cloner le projet
git clone https://github.com/votre-username/mcp-server-boilerplate.git
cd mcp-server-boilerplate

# 2. Installer les dépendances Python
uv venv
uv pip install -r requirements.txt

# 3. Initialiser la base de données
python database/seed.py

# 4. Installer les dépendances frontend
cd frontend
npm install
cd ..

🚀 Démarrage

1. Démarrer le Backend API

# Terminal 1
.venv\Scripts\python.exe backend/main.py

L'API sera accessible sur http://localhost:8000

2. Démarrer le Frontend

# Terminal 2
cd frontend
npm run dev

L'interface sera accessible sur http://localhost:5173

3. Configurer le Serveur MCP pour Claude Desktop

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mon-serveur-mcp": {
      "command": "C:\\chemin\\vers\\.venv\\Scripts\\python.exe",
      "args": ["C:\\chemin\\vers\\server.py"],
      "env": {
        "MCP_MODE": "stdio",
        "DEBUG": "true"
      }
    }
  }
}

Redémarrez Claude Desktop pour charger le serveur MCP.

🔑 Comptes par défaut

Admin: admin@example.com / admin123
User: user@example.com / user123

🛠️ Outils MCP disponibles

Outils d'exemple

example_hello: Salutation multilingue (fr/en/es)
example_calculate: Calculatrice (add/subtract/multiply/divide)

Outils API Bridge

api_get_data: GET vers API externe
api_post_data: POST vers API externe

Détecteur Custom

thibaut_check_message: Détecte le mot "Thibaut" et réagit

Outils Database

db_get_user_stats: Stats d'un utilisateur
db_log_tool_usage: Log d'utilisation d'outil

📊 Utilisation de l'interface

Dashboard Utilisateur

Voir ses statistiques d'utilisation
Historique des outils MCP utilisés
Activités récentes

Dashboard Admin

Vue d'ensemble: Statistiques globales
Utilisateurs: Gestion complète (créer, modifier, supprimer)
Activités: Logs détaillés de toutes les actions
Outils MCP: Tracking de l'utilisation des outils via Claude

📝 Créer vos propres outils

1. Créer un nouveau fichier dans `tools/`

# tools/mon_outil.py
from mcp.types import Tool, TextContent
from typing import List

class MonOutil:
    def get_tools(self) -> List[Tool]:
        return [
            Tool(
                name="mon_outil_action",
                description="Description de votre outil",
                inputSchema={
                    "type": "object",
                    "properties": {
                        "param": {
                            "type": "string",
                            "description": "Paramètre d'entrée"
                        }
                    },
                    "required": ["param"]
                }
            )
        ]

    async def execute(self, name: str, arguments: dict) -> List[TextContent]:
        if name == "mon_outil_action":
            result = f"Traitement de: {arguments.get('param')}"
            return [TextContent(type="text", text=result)]

        return [TextContent(type="text", text="Outil inconnu")]

2. Enregistrer dans `server.py`

from tools.mon_outil import MonOutil

mon_outil = MonOutil()

@app.list_tools()
async def list_tools():
    tools = []
    tools.extend(mon_outil.get_tools())
    return tools

@app.call_tool()
async def call_tool(name, arguments):
    if name.startswith("mon_outil_"):
        return await mon_outil.execute(name, arguments)

🔒 Sécurité

⚠️ Changez SECRET_KEY dans backend/auth.py en production
⚠️ N'utilisez pas SQLite en production (PostgreSQL recommandé)
⚠️ Activez HTTPS en production
⚠️ Limitez les CORS aux domaines autorisés
⚠️ Ne committez JAMAIS les fichiers .env avec des clés API

🌐 Déploiement Production

Backend + MCP Server

# Dockerfile
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["python", "backend/main.py"]

Frontend

cd frontend
npm run build
# Servir le dossier dist/ avec nginx ou autre

🧪 Tests

# Tests Python
pytest tests/ -v

# Tests Frontend (à ajouter)
cd frontend
npm test

📚 Documentation

🤝 Contribution

Les contributions sont les bienvenues ! N'hésitez pas à :

Fork le projet
Créer une branche (git checkout -b feature/nouvelle-fonctionnalite)
Commit vos changements
Push vers la branche
Ouvrir une Pull Request

📄 Licence

MIT License - Utilisez librement pour vos projets !

Créé avec ❤️ pour faciliter le développement MCP avec Claude