# satelia-mcp-starter

Une base de depart propre et minimale pour creer votre propre serveur MCP en TypeScript.

## C'est quoi ?

Un serveur MCP (Model Context Protocol) est un petit programme qui ajoute des "outils" a Claude. Une fois branche a Claude Desktop, vous pouvez demander a Claude d'utiliser ces outils pendant une conversation.

Ce depot contient deja :

- un serveur fonctionnel, pret a lancer ;
- UN outil d'exemple, `compter-mots`, qui compte les mots et les caracteres d'un texte ;
- un emplacement clairement balise pour ajouter vos propres outils.

L'idee : vous clonez ce depot, vous lancez quelques commandes, et vous construisez vos outils par-dessus sans avoir a tout recreer.

## Prerequis

- Node.js version 18 ou superieure. Pour verifier, ouvrez un terminal et tapez : `node --version`
- Si Node n'est pas installe, telechargez-le sur le site officiel : https://nodejs.org (choisissez la version "LTS").

## Installation, etape par etape

1. Cloner le depot, puis entrer dans le dossier :

   ```bash
   git clone <adresse-du-depot>
   cd satelia-mcp-starter
   ```

2. Installer les dependances (les librairies dont le projet a besoin) :

   ```bash
   npm install
   ```

3. Construire le projet (transformer le code TypeScript en JavaScript executable) :

   ```bash
   npm run build
   ```

   Si tout se passe bien, un dossier `build` apparait. Il contient le fichier `build/index.js` que Claude utilisera.

## Connecter le serveur a Claude Desktop

Claude Desktop lit un fichier de configuration ou vous declarez vos serveurs MCP.

1. Recuperez le chemin ABSOLU vers `build/index.js`. Depuis le dossier du projet :

   ```bash
   pwd
   ```

   Cela affiche le chemin du dossier, par exemple `/Users/vous/satelia-mcp-starter`. Le chemin complet vers le fichier sera donc `/Users/vous/satelia-mcp-starter/build/index.js`.

2. Ouvrez le fichier de configuration de Claude Desktop :

   - macOS : `~/Library/Application Support/Claude/claude_desktop_config.json`
   - Windows : `%APPDATA%\Claude\claude_desktop_config.json`

3. Ajoutez votre serveur dans la section `mcpServers` (remplacez le chemin par le votre) :

   ```json
   {
     "mcpServers": {
       "satelia-mcp-starter": {
         "command": "node",
         "args": ["/Users/vous/satelia-mcp-starter/build/index.js"]
       }
     }
   }
   ```

4. Fermez puis rouvrez Claude Desktop. Votre outil `compter-mots` doit maintenant etre disponible. Essayez de demander a Claude : "Combien de mots dans cette phrase ?"

Note : a chaque fois que vous modifiez le code, relancez `npm run build`, puis redemarrez Claude Desktop pour qu'il prenne en compte la nouvelle version.

## Ajouter votre propre outil

Tout se passe dans le fichier `src/index.ts`. Cherchez le bloc bien visible :

```
// ====== AJOUTEZ VOTRE OUTIL ICI ======
```

En 4 etapes simples :

1. Copiez l'exemple commente situe juste sous ce bloc (l'outil `saluer`).
2. Retirez les `//` en debut de ligne pour activer le code.
3. Adaptez : le nom de l'outil, sa description, ses champs d'entree (`inputSchema`) et ce que renvoie le handler.
4. Lancez `npm run build` pour verifier que tout compile, puis redemarrez Claude Desktop.

Conseil : decrivez chaque champ avec `.describe("...")` en francais. Plus la description est claire, mieux Claude saura quand et comment utiliser votre outil.

## Tester sans rebuild

Pendant que vous developpez, vous pouvez lancer le serveur directement depuis le code source, sans passer par `npm run build` :

```bash
npm run dev
```

Le serveur demarre et affiche un message de confirmation. C'est pratique pour verifier rapidement qu'il n'y a pas d'erreur. Pour l'arreter, appuyez sur `Ctrl + C`.

### Tester visuellement avec l'inspecteur

Pour voir vos outils et les essayer dans une petite interface, sans passer par Claude Desktop :

```bash
npm run build
npx @modelcontextprotocol/inspector node build/index.js
```

Une page s'ouvre dans le navigateur : vous y voyez la liste de vos outils et pouvez les appeler a la main pour verifier leur resultat.

## Commandes utiles

- `npm run build` : compile le projet dans le dossier `build`.
- `npm run start` : lance la version compilee (`build/index.js`).
- `npm run dev` : lance directement le code source, ideal pour tester pendant le developpement.

## Licence

MIT. Voir le fichier `LICENSE`.