Comment j'ai construit un serveur MCP connecté à Claude Desktop avec Typescript

Le Model Context Protocol (MCP) représente une avancée significative dans la manière dont les assistants d'IA interagissent avec les outils et les sources de données externes. Développé par Anthropic, MCP permet à Claude de communiquer de manière transparente avec des serveurs personnalisés, lui permettant d'accéder à des informations en temps réel, d'exécuter des flux de travail complexes et d'interagir avec des API sans quitter le contexte de la conversation. Cette capacité transforme Claude d'un LLM autonome en un assistant polyvalent capable de tirer parti des fonctionnalités externes tout en maintenant la cohérence de la conversation.

Dans ce guide complet, nous allons parcourir le processus de création d'un serveur MCP TypeScript à partir de zéro et de sa connexion à Claude Desktop. En mettant en œuvre cette intégration, vous permettrez à Claude d'effectuer des tâches telles que la récupération de données en temps réel, l'exécution de calculs ou l'interaction avec votre logique métier personnalisée directement dans les conversations.

Avant de plonger dans notre implémentation du serveur MCP, il est important de mentionner que votre choix d'outil de développement d'API peut avoir un impact significatif sur l'efficacité de votre flux de travail.

Bien que Postman ait longtemps été la norme de l'industrie, Apidog est apparu comme une alternative supérieure qui complète parfaitement les flux de travail de développement modernes comme celui que nous construisons.
Contrairement aux limitations de Postman avec les API en développement, Apidog offre une synchronisation en temps réel entre vos spécifications d'API et vos requêtes, garantissant que votre documentation et vos tests restent automatiquement à jour au fur et à mesure que vos API évoluent.
Avec la création visuelle de spécifications d'API, des exécutions de collections illimitées (par rapport à la limite de 25/mois de Postman) et des fonctionnalités puissantes telles que les requêtes auto-générées et les réponses simulées, Apidog rationalise l'ensemble du cycle de vie de l'API. Ses capacités de test complètes, y compris la création de tests visuels et les exécuteurs auto-hébergés, en font l'outil idéal pour les équipes mettant en œuvre des intégrations complexes comme notre serveur MCP.

Alors que nous construisons notre serveur MCP TypeScript, réfléchissez à la façon dont les fonctionnalités collaboratives et l'approche axée sur le développement d'Apidog peuvent améliorer la productivité de votre équipe et garantir que vos API restent cohérentes, bien testées et entièrement documentées tout au long du processus.

button

Comprendre le Model Context Protocol

Le Model Context Protocol définit une manière standardisée pour Claude de communiquer avec les services externes. Lorsque Claude identifie qu'il a besoin d'informations provenant d'une source externe, il peut invoquer un serveur MCP via une requête JSON spécialement formatée. Le serveur traite cette requête et renvoie les données demandées, que Claude peut ensuite intégrer dans sa réponse.

MCP offre plusieurs avantages par rapport aux approches d'intégration d'IA traditionnelles :

Conscience contextuelle : Claude conserve l'historique complet de la conversation lors des requêtes
Communication bidirectionnelle : Le protocole prend en charge les interactions complexes entre Claude et votre serveur
Sécurité et contrôle : Vous déterminez quelles fonctionnalités exposer et comment les requêtes sont traitées
Expérience transparente : Les utilisateurs interagissent avec Claude naturellement sans avoir besoin de connaître les intégrations sous-jacentes

Conditions préalables

Avant de commencer à construire notre serveur MCP, assurez-vous d'avoir ce qui suit :

Node.js (v18 ou version ultérieure) installé
Un éditeur de code comme Visual Studio Code
Connaissances de base de TypeScript
Application Claude Desktop installée
Familiarité avec Express.js (pour la création des points de terminaison du serveur)

Configuration de votre projet TypeScript

Commençons par créer un nouveau projet TypeScript pour notre serveur MCP :

mkdir claude-mcp-server
cd claude-mcp-server
npm init -y
npm install typescript @types/node ts-node express @types/express cors @types/cors
npx tsc --init

Ensuite, mettez à jour votre tsconfig.json pour inclure ces paramètres :

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "outDir": "./dist",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

Implémentation du serveur MCP

Créez un nouveau fichier appelé server.ts dans le répertoire racine de votre projet. Ce sera le point d'entrée de notre serveur MCP :

import express from 'express';
import cors from 'cors';
import { Request, Response } from 'express';

// Define types for the MCP protocol
interface MCPRequest {
  query: string;
  conversation_id: string;
  request_id: string;
  parameters?: Record<string, any>;
}

interface MCPResponse {
  response: string;
  status: 'success' | 'error';
  error?: string;
}

const app = express();
app.use(cors());
app.use(express.json());

// Health check endpoint
app.get('/health', (req: Request, res: Response) => {
  res.status(200).json({ status: 'healthy' });
});

// MCP endpoint
app.post('/mcp', (req: Request, res: Response) => {
  try {
    const mcpRequest = req.body as MCPRequest;
    console.log('Received MCP request:', JSON.stringify(mcpRequest, null, 2));

    // Process the request based on the query
    const response = processQuery(mcpRequest);
    
    res.status(200).json({
      status: 'success',
      response
    } as MCPResponse);
  } catch (error) {
    console.error('Error processing MCP request:', error);
    res.status(500).json({
      status: 'error',
      error: error instanceof Error ? error.message : 'Unknown error',
      response: 'Sorry, there was an error processing your request.'
    } as MCPResponse);
  }
});

// Function to process different query types
function processQuery(request: MCPRequest): string {
  const { query, parameters } = request;

  // Example query handling - customize this for your use case
  switch (query) {
    case 'getCurrentTime':
      return `The current time is ${new Date().toLocaleTimeString()}`;
    
    case 'getWeather':
      const location = parameters?.location || 'Unknown';
      // In a real app, you would call a weather API here
      return `The weather in ${location} is currently sunny and 72°F`;
    
    case 'calculateSum':
      if (parameters?.numbers && Array.isArray(parameters.numbers)) {
        const sum = parameters.numbers.reduce((a: number, b: number) => a + b, 0);
        return `The sum of the numbers is ${sum}`;
      }
      return 'Invalid parameters for sum calculation';

    default:
      return `Unrecognized query: ${query}`;
  }
}

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`MCP server running on port ${PORT}`);
});

Exécution de votre serveur MCP

Pour exécuter votre serveur, exécutez :

npx ts-node server.ts

Votre serveur MCP devrait maintenant être en cours d'exécution sur le port 3000 (ou votre port spécifié).

Connexion à Claude Desktop

Maintenant que votre serveur MCP est en cours d'exécution, vous devez configurer Claude Desktop pour vous y connecter. Voici comment :

Ouvrez l'application Claude Desktop
Accédez aux paramètres (généralement dans le coin supérieur droit)
Accédez à la section « Fonctionnalités expérimentales »
Activez le bouton bascule « Model Context Protocol »
Ajoutez un nouveau point de terminaison MCP avec l'URL http://localhost:3000/mcp
Enregistrez vos paramètres

Claude Desktop pourra désormais communiquer avec votre serveur MCP personnalisé.

Test de l'intégration

Pour tester votre serveur MCP avec Claude, essayez de poser à Claude des questions qui déclencheraient les requêtes spécifiques que vous avez implémentées. Par exemple :

« Quelle heure est-il en ce moment ? » (devrait déclencher la requête getCurrentTime)
« Quel temps fait-il à San Francisco ? » (devrait déclencher la requête getWeather avec « San Francisco » comme paramètre d'emplacement)
« Pouvez-vous calculer la somme de 5, 10, 15 et 20 ? » (devrait déclencher la requête calculateSum)

Lorsque Claude reconnaît qu'il a besoin d'informations externes pour répondre à ces questions, il enverra automatiquement une requête MCP à votre serveur et intégrera la réponse dans sa réponse.

Extension de votre serveur MCP

Le serveur de base que nous avons construit n'est qu'un point de départ. Voici quelques idées pour étendre ses fonctionnalités :

Ajouter l'authentification

Pour sécuriser votre serveur MCP, ajoutez l'authentification :

// Middleware for basic auth
const authenticateMCP = (req: Request, res: Response, next: Function) => {
  const apiKey = req.headers['x-api-key'];
  if (!apiKey || apiKey !== process.env.MCP_API_KEY) {
    return res.status(401).json({
      status: 'error',
      error: 'Unauthorized',
      response: 'Authentication failed'
    });
  }
  next();
};

// Apply middleware to MCP endpoint
app.post('/mcp', authenticateMCP, (req: Request, res: Response) => {
  // Existing handler code
});

Implémenter l'intégration de la base de données

Connectez votre serveur MCP à une base de données pour récupérer ou stocker des informations :

import { MongoClient } from 'mongodb';

// Initialize database connection
const dbClient = new MongoClient('mongodb://localhost:27017');
let db: any;

async function connectToDb() {
  await dbClient.connect();
  db = dbClient.db('mcpDatabase');
  console.log('Connected to database');
}

connectToDb().catch(console.error);

// Add a query handler for database interactions
case 'getUserData':
  if (parameters?.userId) {
    const user = await db.collection('users').findOne({ id: parameters.userId });
    return user ? JSON.stringify(user) : 'User not found';
  }
  return 'Invalid user ID';

Ajouter la prise en charge des webhooks

Implémentez la fonctionnalité de webhook pour notifier les services externes :

case 'sendNotification':
  if (parameters?.message && parameters?.destination) {
    // Call external notification service
    await fetch('https://your-webhook-url.com', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ message: parameters.message })
    });
    return `Notification sent to ${parameters.destination}`;
  }
  return 'Invalid notification parameters';

Meilleures pratiques pour le développement de serveurs MCP

Gérer les erreurs avec élégance : Toujours intercepter les exceptions et renvoyer des messages d'erreur informatifs
Implémenter la journalisation : Enregistrer toutes les requêtes et réponses à des fins de débogage et d'audit
Utiliser les interfaces TypeScript : Définir des interfaces claires pour toutes les structures de données
Définir des délais d'attente : Implémenter des délais d'attente des requêtes pour éviter les opérations en attente
Valider les entrées : Valider soigneusement tous les paramètres d'entrée avant le traitement
Ajouter des tests unitaires : Testez minutieusement vos gestionnaires de requêtes pour garantir la fiabilité

Conclusion

La création d'un serveur MCP TypeScript ouvre des possibilités intéressantes pour étendre les capacités de Claude. En suivant ce guide, vous avez créé une base pour intégrer Claude à vos propres services et données. Le Model Context Protocol permet une expérience utilisateur transparente où Claude peut accéder à des informations externes sans interrompre le flux de la conversation.

Au fur et à mesure que MCP continue d'évoluer, nous pouvons nous attendre à des intégrations encore plus sophistiquées entre les grands modèles de langage et les systèmes externes. Que vous construisiez des outils de productivité, des systèmes de gestion des connaissances ou des applications métier personnalisées, MCP offre un moyen puissant de combiner l'intelligence de Claude avec vos fonctionnalités spécialisées.

Commencez à explorer les possibilités en étendant votre serveur avec des gestionnaires de requêtes supplémentaires spécifiques à vos cas d'utilisation et partagez vos expériences avec la communauté croissante des développeurs MCP.