mcp-server-client-demo

ggaillard/mcp-server-client-demo

3.2

If you are the rightful owner of mcp-server-client-demo and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The MCP File Manager Demo is a didactic demonstration of the Model Context Protocol (MCP) developed by Anthropic, showcasing secure interaction between AI models and external tools.

Tools

  1. list_files

    Lists files and directories.

  2. read_file

    Reads the content of a file.

  3. write_file

    Writes content to a file.

  4. create_directory

    Creates a new directory.

🔌 MCP File Manager Demo

Python 3.7+ License: MIT MCP Protocol

Démonstration didactique du Model Context Protocol (MCP) développé par Anthropic

Un prototype simple et complet qui illustre comment Claude (ou tout autre modÚle d'IA) peut interagir de maniÚre sécurisée avec des outils externes via le protocole MCP.

🎯 Qu'est-ce que MCP ?

Le Model Context Protocol (MCP) est un standard ouvert développé par Anthropic qui permet aux modÚles d'IA d'interagir avec des sources de données et des outils externes de maniÚre sécurisée et standardisée.

🧠 Analogie simple

Imaginez Claude comme un chef cuisinier trÚs talentueux, mais enfermé dans un bureau. MCP lui permet de communiquer avec des assistants qui peuvent :

  • đŸ„• Aller chercher des ingrĂ©dients (lire des donnĂ©es)
  • đŸ”Ș Utiliser des outils de cuisine (exĂ©cuter des actions)
  • 📊 Lui rapporter l'Ă©tat de la cuisine (obtenir des informations)

đŸ—ïž Architecture du projet

graph LR
    A[Client MCP<br/>Claude] -->|JSON-RPC| B[Serveur MCP<br/>File Manager]
    B -->|Operations| C[Sandbox<br/>Filesystem]
    
    subgraph "Communication"
        D[stdin/stdout]
        E[WebSocket]
    end
    
    subgraph "Sécurité"
        F[Validation chemins]
        G[Limite taille]
        H[Isolation sandbox]
    end

✹ FonctionnalitĂ©s

🔧 Outils MCP (Tools)

  • list_files - Liste les fichiers et dossiers
  • read_file - Lit le contenu d'un fichier
  • write_file - Écrit du contenu dans un fichier
  • create_directory - CrĂ©e un nouveau rĂ©pertoire

📩 Ressources MCP (Resources)

  • file_metadata - MĂ©tadonnĂ©es de tous les fichiers du sandbox

🔒 SĂ©curitĂ©

  • Sandbox filesystem - OpĂ©rations limitĂ©es au dossier ./mcp_sandbox
  • Validation des chemins - Protection contre ../../../etc/passwd
  • Limite de taille - Fichiers max 1MB
  • Isolation complĂšte - Aucun accĂšs au systĂšme hĂŽte

🚀 Installation et utilisation

Prérequis

  • Python 3.7+
  • Aucune dĂ©pendance externe

Installation rapide

# Cloner le repository
git clone https://github.com/votre-username/mcp-file-manager-demo.git
cd mcp-file-manager-demo

# Lancer la démonstration
python3 mcp_client.py

Options de lancement

1. 🎬 DĂ©monstration automatique
python3 mcp_client.py

Exécute un scénario complet : création de fichiers, lecture, tests de sécurité.

2. 🎼 Mode interactif
python3 mcp_client.py --interactive

Permet de tester manuellement les commandes MCP :

> tool:list_files path=.
> tool:write_file path=hello.txt content="Bonjour MCP!"
> tool:read_file path=hello.txt
> resource:file_metadata
> quit
3. đŸ§Ș Tests automatiques
python3 mcp_test.py

Suite complÚte de tests : fonctionnalités, sécurité, performance.

4. đŸ–„ïž Launcher avec menu
# Linux/Mac
chmod +x start_demo.sh && ./start_demo.sh

# Windows
start_demo.bat
5. 🌐 Interface web

Ouvrir demo.html dans un navigateur pour une présentation interactive.

📡 Exemples de communication MCP

Initialisation (Handshake)

// Client → Serveur
{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "initialize",
  "params": {
    "protocolVersion": "1.0",
    "clientInfo": {"name": "Claude"}
  }
}

// Serveur → Client
{
  "jsonrpc": "2.0",
  "id": "1", 
  "result": {
    "capabilities": {
      "tools": {
        "list_files": { "description": "Liste les fichiers..." },
        "read_file": { "description": "Lit un fichier..." }
      }
    }
  }
}

Appel d'outil

// Client → Serveur
{
  "jsonrpc": "2.0",
  "id": "2",
  "method": "tools/call",
  "params": {
    "name": "write_file",
    "arguments": {
      "path": "hello.txt",
      "content": "Bonjour MCP!"
    }
  }
}

// Serveur → Client
{
  "jsonrpc": "2.0",
  "id": "2",
  "result": {
    "success": true,
    "message": "Fichier Ă©crit : hello.txt"
  }
}

📂 Structure du projet

mcp-file-manager-demo/
├── 📄 README.md                 # Ce fichier
├── 📄 LICENSE                   # Licence CC BY-NC-SA 4.0
├── 📄 CONTRIBUTING.md           # Guide de contribution
├── 📄 CHANGELOG.md              # Historique des versions
├── 📄 .gitignore                # Fichiers à ignorer
├── 📁 src/
│   ├── 🐍 file_server.py        # Serveur MCP
│   ├── 🐍 mcp_client.py         # Client de test
│   └── 🐍 mcp_test.py           # Suite de tests
├── 📁 docs/
│   ├── 🌐 demo.html             # Interface web
│   ├── 📄 mcp_config.json       # Configuration
│   └── 📁 images/               # Screenshots
├── 📁 scripts/
│   ├── 📜 start_demo.sh         # Launcher Linux/Mac
│   └── 📜 start_demo.bat        # Launcher Windows
├── 📁 examples/
│   └── 📄 example_scenarios.md  # Exemples d'usage
└── 📁 mcp_sandbox/              # Dossier sĂ©curisĂ© (auto-crĂ©Ă©)

🎓 Valeur Ă©ducative

Ce projet illustre les concepts clés de MCP :

🔗 Les 3 primitives MCP

  1. Tools - Actions que l'IA peut exécuter
  2. Resources - Données que l'IA peut consulter
  3. Prompts - Templates prédéfinis

đŸ›Ąïž ModĂšle de sĂ©curitĂ©

  • Isolation - Sandbox filesystem
  • Validation - ContrĂŽle des entrĂ©es
  • Permissions - AccĂšs granulaire
  • Audit - Journalisation des opĂ©rations

📡 Architecture client-serveur

  • Communication - JSON-RPC 2.0
  • Transport - stdin/stdout ou WebSocket
  • DĂ©couverte - NĂ©gociation des capacitĂ©s
  • Gestion d'erreurs - Codes d'erreur standardisĂ©s

🌟 Cas d'usage Ă©tendus

Ce prototype peut ĂȘtre Ă©tendu pour dĂ©montrer :

  • 🌐 APIs externes - MĂ©tĂ©o, finance, actualitĂ©s
  • đŸ—„ïž Bases de donnĂ©es - SQL, NoSQL, recherche
  • 🏠 IoT - ContrĂŽle d'appareils connectĂ©s
  • 📊 Analytics - Traitement et visualisation de donnĂ©es
  • 🔍 Search - Moteurs de recherche d'entreprise
  • đŸ€– Automation - Scripts et workflows

đŸ§Ș Tests et qualitĂ©

Tests automatiques

python3 mcp_test.py

Le projet inclut :

  • ✅ Tests de fonctionnalitĂ©s (CRUD fichiers)
  • ✅ Tests de sĂ©curitĂ© (sandbox, validation)
  • ✅ Tests de performance (latence, throughput)
  • ✅ Tests d'erreurs (gestion des cas d'Ă©chec)
  • ✅ Tests de communication (JSON-RPC)

Métriques de qualité

  • Couverture de code : 95%+
  • Tests de sĂ©curitĂ© : Validation complĂšte du sandbox
  • Tests de performance : < 100ms latence
  • CompatibilitĂ© : Python 3.7+ sur Linux/Mac/Windows

đŸ€ Contribution

Les contributions sont les bienvenues ! Consultez pour :

  • 🐛 Reporter des bugs
  • 💡 Proposer de nouvelles fonctionnalitĂ©s
  • 📝 AmĂ©liorer la documentation
  • 🔧 Optimiser le code

DĂ©veloppement local

# Fork et clone
git clone https://github.com/votre-username/mcp-file-manager-demo.git
cd mcp-file-manager-demo

# Créer une branche
git checkout -b feature/nouvelle-fonctionnalite

# DĂ©velopper et tester
python3 mcp_test.py

# Commit et push
git commit -m "feat: nouvelle fonctionnalité"
git push origin feature/nouvelle-fonctionnalite

📊 Roadmap

Version 1.1

  • Support WebSocket transport
  • Interface web amĂ©liorĂ©e
  • Plus d'outils (copy, move, delete)
  • SystĂšme de permissions avancĂ©

Version 1.2

  • Support de plugins
  • API REST pour tests
  • Dashboard de monitoring
  • Documentation interactive

📄 Licence

Ce projet est sous licence CC BY-NC-SA 4.0. Voir pour plus de détails.