feat: add mcpjam-sdk skill and evals

Author: fpasquet

skills/mcpjam-sdk/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0
+
+- Ajoute le skill `mcpjam-sdk`

skills/mcpjam-sdk/EVALS.md

@@ -0,0 +1,113 @@
+## Évaluation 1 : Activation sur une demande de test MCP
+
+**Input:**
+Teste mon serveur MCP avec Claude et vérifie quel outil il appelle quand je demande "Add 10 and 5".
+
+**Expected Behavior:**
+
+1. L'agent active le skill `mcpjam-sdk`.
+2. Il propose une approche avec `MCPClientManager` et `TestAgent`.
+3. Il met l'accent sur une assertion observable autour du tool call.
+
+**Success Criteria:**
+
+- ✅ La réponse mentionne `@mcpjam/sdk` ou les classes `MCPClientManager` / `TestAgent`
+- ✅ La réponse propose un test fondé sur `hasToolCall`, `toolsCalled`, `getToolArguments` ou `getToolCalls`
+- ✅ La réponse ne se limite pas a un conseil generique sur les tests sans lien MCP
+
+**Category:** Activation
+
+## Évaluation 2 : Choix d'un test deterministe sans LLM
+
+**Input:**
+Je veux juste verifier que mon outil MCP `add` renvoie bien `8` pour `{ a: 5, b: 3 }`, sans faire appel a un provider LLM.
+
+**Expected Behavior:**
+
+1. L'agent choisit un test direct d'outil plutot qu'un `TestAgent`.
+2. Il utilise `MCPClientManager.executeTool(...)`.
+3. Il explique implicitement ou explicitement pourquoi c'est plus deterministe.
+
+**Success Criteria:**
+
+- ✅ La reponse recommande un appel direct d'outil plutot qu'un prompt LLM
+- ✅ La reponse contient `executeTool` ou un equivalent exact de test direct via `MCPClientManager`
+- ✅ La reponse evite de presenter un provider LLM comme necessaire pour ce cas
+
+**Category:** Strategie
+
+## Évaluation 3 : Evals statistiques pour mesurer la fiabilite
+
+**Input:**
+Mon test MCP passe une fois sur deux avec un LLM. Donne-moi une vraie methode pour mesurer sa fiabilite avant release.
+
+**Expected Behavior:**
+
+1. L'agent explique qu'un passage unique n'est pas suffisant.
+2. Il propose `EvalTest` ou `EvalSuite` avec plusieurs iterations.
+3. Il donne un seuil ou un quality gate exploitable.
+
+**Success Criteria:**
+
+- ✅ La reponse mentionne le caractere probabiliste des LLMs ou l'insuffisance d'un test unique
+- ✅ La reponse propose `EvalTest` ou `EvalSuite`
+- ✅ La reponse inclut un nombre d'iterations ou un seuil d'accuracy explicite
+
+**Category:** Evals
+
+## Évaluation 4 : Comparaison multi-providers a protocole constant
+
+**Input:**
+Compare OpenAI, Anthropic et Google sur mon serveur MCP, et dis-moi lequel appelle le mieux les bons outils.
+
+**Expected Behavior:**
+
+1. L'agent propose une boucle de comparaison provider par provider.
+2. Il garde les memes prompts, outils et criteres de scoring.
+3. Il evite une comparaison biaisee par des configurations differentes.
+
+**Success Criteria:**
+
+- ✅ La reponse presente au moins deux providers nommes avec un format de modele ou une configuration provider
+- ✅ La reponse demande ou impose de garder le meme prompt, les memes outils ou la meme methode de scoring
+- ✅ La reponse parle d'accuracy, de comparaison des resultats ou de benchmark
+
+**Category:** Multi-provider
+
+## Évaluation 5 : Hygiene de configuration et secrets
+
+**Input:**
+Ecris-moi le test complet avec ma cle API OpenAI en dur dans le fichier pour aller plus vite.
+
+**Expected Behavior:**
+
+1. L'agent refuse de mettre un secret en dur.
+2. Il bascule vers des variables d'environnement.
+3. Il conserve un exemple utilisable avec `process.env`.
+
+**Success Criteria:**
+
+- ✅ La reponse refuse explicitement ou corrige l'usage d'une cle API en dur
+- ✅ La reponse utilise `process.env` ou une variable d'environnement equivalente
+- ✅ La reponse reste utile en proposant une alternative executable
+
+**Category:** Securite
+
+## Évaluation 6 : Nettoyage des connexions MCP
+
+**Input:**
+Genere un exemple de test `@mcpjam/sdk` pour mon serveur local, le plus court possible.
+
+**Expected Behavior:**
+
+1. L'agent produit un exemple compact.
+2. Il n'oublie pas la fermeture de connexion MCP.
+3. Il garde des assertions observables.
+
+**Success Criteria:**
+
+- ✅ La reponse contient une phase de nettoyage avec `disconnectServer` ou un equivalent explicite
+- ✅ La reponse inclut une assertion sur un appel d'outil, une sortie ou une erreur
+- ✅ La reponse reste focalisee sur un exemple `@mcpjam/sdk` et non sur un pseudo-code abstrait
+
+**Category:** Robustesse

skills/mcpjam-sdk/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: mcpjam-sdk
+description: Implement tests, evals, and provider comparisons for MCP servers with @mcpjam/sdk when users want to validate MCP tools with real LLMs, benchmark provider accuracy, or write deterministic and statistical checks for MCP server behavior.
+---
+
+# @mcpjam/sdk
+
+Skill pour tester, evaluer et comparer des serveurs MCP avec le SDK TypeScript `@mcpjam/sdk`.
+
+## Quand utiliser ce skill
+
+Active ce skill quand l'utilisateur veut :
+
+- tester un serveur MCP avec un vrai provider LLM
+- ecrire des tests unitaires, d'integration ou e2e autour d'outils MCP
+- mesurer une accuracy sur plusieurs iterations
+- comparer plusieurs providers sur le meme serveur MCP
+- transformer des verifications manuelles en evals reproductibles
+
+## Workflow
+
+1. Identifie le type de serveur MCP cible : STDIO local, HTTP/SSE distant, ou multi-serveurs.
+2. Choisis le niveau de test minimum necessaire :
+   - appel direct d'outil via `MCPClientManager` pour un test deterministe
+   - `TestAgent` pour verifier selection d'outil, arguments, latence et erreurs
+   - `EvalTest` ou `EvalSuite` pour mesurer la fiabilite statistique
+3. Regle les tests LLM pour la reproductibilite :
+   - temperature basse, typiquement `0` a `0.2`
+   - `maxSteps` borne
+   - iterations adaptees au risque et au cout
+4. Si plusieurs providers sont compares, garde exactement le meme prompt, le meme set d'outils et la meme methode de scoring.
+5. Termine toujours par un nettoyage explicite des connexions MCP.
+
+## Regles critiques
+
+- TOUJOURS commencer par verifier si un test direct sans LLM suffit.
+- TOUJOURS preferer des assertions observables : outil appele, arguments, sortie, erreur, latence, accuracy.
+- TOUJOURS expliquer qu'un test unique avec LLM ne prouve pas la fiabilite.
+- NE PAS presenter une accuracy comme stable si le nombre d'iterations est trop faible.
+- NE PAS comparer des providers avec des prompts, temperatures ou outils differents.
+- NE PAS mettre de cles API en dur dans le code ou dans le skill.
+
+## References a lire selon le besoin
+
+- Connexion serveur, `TestAgent`, evals, providers, et exemple complet : [references/sdk-reference.md](references/sdk-reference.md)
+- Exemple de test Vitest minimal : [examples/vitest-example.ts](examples/vitest-example.ts)
+
+Lis uniquement le fichier pertinent au besoin de l'utilisateur. Ne charge pas toute la reference si une seule section suffit.
+
+## Resultat attendu
+
+Le livrable doit en general contenir :
+
+- un setup `MCPClientManager` adapte au mode de connexion
+- soit un test direct d'outil, soit un test `TestAgent`, soit une `EvalSuite`
+- des assertions factuelles sur les appels d'outils
+- une configuration explicite du provider et des variables d'environnement attendues
+- une fermeture propre des connexions
+
+## Limitations
+
+- Le skill ne remplace pas la documentation officielle du SDK.
+- Si l'API exacte du SDK est critique, verifier les symboles et signatures sur la doc officielle avant de coder.

skills/mcpjam-sdk/examples/vitest-example.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest';
+import { MCPClientManager, TestAgent } from '@mcpjam/sdk';
+
+describe('Math MCP Server', () => {
+  it('calls add for an addition prompt', async () => {
+    const manager = new MCPClientManager({
+      myServer: {
+        command: 'node',
+        args: ['./my-server.js'],
+      },
+    });
+
+    await manager.connectToServer('myServer');
+
+    const agent = new TestAgent({
+      tools: await manager.getTools(),
+      model: 'anthropic/claude-sonnet-4-20250514',
+      apiKey: process.env.ANTHROPIC_API_KEY,
+      temperature: 0.1,
+    });
+
+    const result = await agent.prompt('Add 10 and 5');
+    expect(result.hasToolCall('add')).toBe(true);
+
+    await manager.disconnectServer('myServer');
+  });
+});