my-first-mcp

Un serveur MCP (Model Context Protocol) construit avec TypeScript, Express et le SDK officiel @modelcontextprotocol/sdk. Ce serveur utilise le transport Streamable HTTP (spec 2025-03-26+) avec gestion multi-clients.

Outils disponibles

Le serveur expose les tools suivants :

1. add : Additionne deux nombres (a et b).
2. get_pokemon : Récupère les informations d'un Pokémon via PokeAPI (paramètre : name).
3. get_weather : Récupère la météo actuelle via Open-Meteo (paramètres : latitude et longitude).
4. qui_est_l_avenir : Une petite blague qui retourne le nom : "Marie".

Prérequis

• Node.js (version 18+)
• npm

🚀 Utilisation simple

La méthode la plus simple pour utiliser le serveur dans votre client MCP est de l'exécuter via npx. Ajoutez la configuration suivante à votre client (Claude Desktop, Cursor, etc.) :

{
  "mcpServers": {
    "my-first-mcp": {
      "type": "local",
      "command": ["npx", "@raknjarasoa/my-first-mcp"]
    }
  }
}

Alternativement, vous pouvez installer le paquet globalement en premier :

npm install -g @raknjarasoa/my-first-mcp

Puis utiliser npx my-first-mcp dans le terminal.

⚙️ Développement local

Pour les développements sur le code du serveur, clonez le projet et utilisez la configuration "remote" pour le transport Streamable HTTP.

1. Cloner le projet :

   git clone https://github.com/raknjarasoa/my-first-mcp.git
   cd my-first-mcp

2. Installer les dépendances :

   npm install

3. Configurer l'environnement : Copier le fichier .env.example vers .env

   cp .env.example .env

   Vous pouvez configurer le port (défaut: 3000) et une clé API_KEY si vous souhaitez mettre en place l'authentification (401 géré).

4. Lancer en développement (rechargement à chaud avec tsx) :

   npm run dev

Configuration client pour le développement (Remote)

Pour se connecter au serveur de développement en local (le endpoint unique Streamable HTTP est POST /mcp), utilisez la configuration suivante :

{
  "mcpServers": {
    "my-first-mcp": {
      "type": "remote",
      "url": "http://localhost:3000/mcp",
      "enabled": true
    }
  }
}

(Note : référez-vous à la documentation spécifique de votre client pour la syntaxe exacte. La majorité des clients modernes supportent l'URL Streamable HTTP nativement.)

📁 Architecture du projet

src/
├── index.ts           # Serveur Express + Streamable HTTP transport
├── mcp.ts             # Factory MCP Server + registre de tools
├── tools/
│   ├── add.ts         # Tool: addition
│   ├── get-pokemon.ts # Tool: PokeAPI
│   ├── get-weather.ts # Tool: Open-Meteo
│   └── qui-est-l-avenir.ts  # Tool: blague
└── utils/
    └── fetch.ts       # Fetch wrapper avec timeout

Ajouter un nouvel outil

1. Créez src/tools/mon-outil.ts en exportant definition et handler.
2. Importez-le dans src/mcp.ts et ajoutez-le au tableau tools.
3. C'est tout — aucun if/else à modifier, le registre dynamique gère le dispatch.

Architecture & Choix Techniques

• Streamable HTTP : Transport moderne (remplace SSE), gestion multi-clients via sessions.
• Express : Serveur HTTP robuste avec routage et gestion d'erreurs standardisée (JSON-RPC).
• TypeScript ESM : Typage strict et imports modernes ("type": "module").
• Native fetch : Aucune dépendance HTTP tierce, timeouts intégrés via AbortController.
• Health check : GET /health pour monitoring et orchestration.
• Graceful shutdown : Fermeture propre de toutes les sessions actives sur SIGTERM/SIGINT.

💡 Exemples de Prompts

Une fois le serveur configuré dans votre client MCP (Claude Desktop, Cursor, RooCode, etc.), voici quelques exemples de requêtes en langage naturel que vous pouvez lui adresser :

• Addition (add) : "Combien font 12345 et 67890 ?" ou "Utilise l'outil add pour calculer 42 + 84."
• Pokémon (get_pokemon) : "Quelles sont les caractéristiques de Pikachu ?" ou "Donne-moi des informations sur le Pokémon Mewtwo."
• Météo (get_weather) : "Quelle est la météo actuelle à Paris (latitude 48.85, longitude 2.35) ?" ou "Fait-il beau à Tokyo météo (35.68, 139.69) ?"
• Easter egg (qui_est_l_avenir) : "Qui est l'avenir ?" ou "Demande à l'outil qui_est_l_avenir."