Een TypeScript MCP-server bouwen met behulp van Azure Container Apps

In dit artikel wordt uitgelegd hoe u een MCP-server (Model Context Protocol) bouwt met behulp van Node.js en TypeScript. De server voert hulpprogramma's en services uit in een serverloze omgeving. Gebruik deze structuur als uitgangspunt om aangepaste MCP-servers te maken.

Naar de code gaan

Verken het MCP-servervoorbeeld (Remote Model Context Protocol) van TypeScript . Het laat zien hoe u Node.js en TypeScript gebruikt om een externe MCP-server te bouwen en deze te implementeren in Azure Container Apps.

Ga naar de sectie met code-scenario's om te begrijpen hoe dit voorbeeld werkt.

Architectuuroverzicht

In het volgende diagram ziet u de eenvoudige architectuur van de voorbeeld-app:

De MCP-server wordt uitgevoerd als een container-app in Azure Container Apps (ACA). Het maakt gebruik van een Node.js/TypeScript-back-end om hulpprogramma's te bieden aan de MCP-client via het Model Context Protocol. Alle tools werken met een backend SQLite-database.

Kosten

Als u kosten laag wilt houden, gebruikt dit voorbeeld de prijscategorieën basis- of verbruiksprijzen voor de meeste resources. Pas de laag zo nodig aan en verwijder resources wanneer u klaar bent om kosten te voorkomen.

Vereiste voorwaarden

1. Visual Studio Code : nieuwste versie ter ondersteuning van MCP Server-ontwikkeling.
2. GitHub Copilot Visual Studio Code-extensie
3. GitHub Copilot Chat Visual Studio Code-extensie
4. Azure Developer CLI (azd)

Een ontwikkelingscontainer bevat alle afhankelijkheden die u nodig hebt voor dit artikel. U kunt deze uitvoeren in GitHub Codespaces (in een browser) of lokaal met behulp van Visual Studio Code.

Als u dit artikel wilt volgen, moet u aan deze vereisten voldoen:

Open ontwikkelomgeving

Volg deze stappen om een vooraf geconfigureerde ontwikkelomgeving in te stellen met alle vereiste afhankelijkheden.

Implementeren en uitvoeren

De voorbeeldopslagplaats bevat alle code- en configuratiebestanden voor de Azure-implementatie van de MCP-server. Met de volgende stappen doorloopt u het azure-implementatieproces van de voorbeeld-MCP-server.

Implementeren in Azure

1. Voer de volgende Azure Developer CLI-opdracht uit voor het inrichten van Azure-resources en de implementatie van broncode:

   azd up
   

2. Gebruik de volgende tabel om de prompts te beantwoorden:

   Snel	Antwoord
   Naam van de omgeving	Houd het kort en kleine letters. Voeg uw naam of alias toe. Bijvoorbeeld: my-mcp-server. Het wordt gebruikt als onderdeel van de naam van de resourcegroep.
   Abonnement	Selecteer het abonnement waarin je de resources wilt creëren.
   Locatie (voor hosting)	Selecteer een locatie bij u in de buurt in de lijst.
   Locatie voor het Azure OpenAI-model	Selecteer een locatie bij u in de buurt in de lijst. Als dezelfde locatie beschikbaar is als uw eerste locatie, selecteert u die.

3. Wacht totdat de app is geïmplementeerd. De implementatie duurt meestal tussen 5 en 10 minuten.

4. Zodra de implementatie is voltooid, hebt u toegang tot de MCP-server met behulp van de URL in de uitvoer. De URL ziet er als volgt uit:

https://<env-name>.<container-id>.<region>.azurecontainerapps.io

1. Kopieer de URL naar het klembord. U hebt deze nodig in de volgende sectie.

De MCP-server configureren in Visual Studio Code

Configureer de MCP-server in uw lokale VS Code-omgeving door de URL toe te voegen aan het mcp.json bestand in de .vscode map.

1. Open het bestand mcp.json in de map .vscode.

2. Zoek de mcp-server-sse-remote sectie in het bestand. Dit moet er als volgt uitzien:

       "mcp-server-sse-remote": {
       "type": "sse",
       "url": "https://<container-id>.<location>.azurecontainerapps.io/sse"
   }
   

3. Vervang de bestaande url waarde door de URL die u in de vorige stap hebt gekopieerd.

4. Sla het mcp.json bestand op in de .vscode map.

TODO MCP-serverhulpprogramma's gebruiken in agentmodus

Nadat u de MCP-server hebt gewijzigd, kunt u de hulpprogramma's in de agentmodus gebruiken die deze biedt. MCP-hulpprogramma's gebruiken in de agentmodus:

1. Open de chatweergave (Ctrl+Alt+I) en selecteer agentmodus in de vervolgkeuzelijst.

2. Selecteer de knop Extra om de lijst met beschikbare hulpprogramma's weer te geven. U kunt desgewenst de hulpprogramma's selecteren of afwählen die u wilt gebruiken. U kunt hulpmiddelen zoeken door in het zoekvak te typen.

3. Voer een prompt in zoals 'Ik moet een e-mail verzenden naar mijn manager op woensdag' in het chatinvoervak en u ziet hoe hulpprogramma's automatisch worden aangeroepen als dat nodig is, zoals in de volgende schermopname:

   

Gebruik de vervolgkeuzeopties van de knop Doorgaan om het specifieke gereedschap automatisch te bevestigen voor de huidige sessie, in de werkruimte, of bij alle toekomstige aanroepen.

De voorbeeldcode verkennen

In deze sectie vindt u een overzicht van de belangrijkste bestanden en codestructuur in het VOORBEELD van de MCP-server. De code is ingedeeld in verschillende hoofdonderdelen:

• index.ts: het belangrijkste toegangspunt voor de MCP-server, waarmee de Express.js HTTP-server en routering wordt ingesteld.
• server.ts: De transportlaag waarmee Server-Sent Gebeurtenissen (SSE)-verbindingen en MCP-protocolafhandeling worden beheerd.
• tools.ts: bevat bedrijfslogica en hulpprogrammafuncties voor de MCP-server.
• types.ts: Definieert typeScript-typen en interfaces die worden gebruikt op de MCP-server.

index.ts - Hoe de server wordt gestart en HTTP-verbindingen accepteert

Het index.ts bestand is het belangrijkste toegangspunt voor de MCP-server. Hiermee initialiseert u de server, stelt u de Express.js HTTP-server in en definieert u routering voor SSE-eindpunten (Server-Sent Events).

Een MCP-serverinstantie aanmaken

Met het volgende codefragment wordt de MCP-server geïnitialiseerd met behulp van de StreamableHTTPServer klasse, een wrapper rond de MCP-kernklasse Server . Deze klasse verwerkt de transportlaag voor Server-Sent Gebeurtenissen (SSE) en beheert clientverbindingen.

const server = new StreamableHTTPServer(
  new Server(
    {
      name: 'todo-http-server',
      version: '1.0.0',
    },
    {
      capabilities: {
        tools: {},
      },
    }
  )
);

Concepten:

• Samenstellingspatroon: SSEPServer omvat de klasse op laag niveau Server
• Declaratie van mogelijkheden: Server kondigt aan dat deze hulpprogramma's ondersteunt (maar geen resources/prompts)
• Naamconventie: Servernaam wordt onderdeel van MCP-identificatie

Express-routes instellen

Met het volgende codefragment wordt de Express.js-server ingesteld voor het afhandelen van binnenkomende HTTP-aanvragen voor SSE-verbindingen en berichtafhandeling:

router.post('/messages', async (req: Request, res: Response) => {
  await server.handlePostRequest(req, res);
});

router.get('/sse', async (req: Request, res: Response) => {
  await server.handleGetRequest(req, res);
});

Concepten:

• Patroon met twee eindpunten: GET voor het tot stand brengen van een SSE-verbinding, POST voor het verzenden van berichten
• Delegeringspatroon: Express-routes delegeren onmiddellijk naar SSEPServer

Proceslevenscyclusbeheer

Het volgende codefragment verwerkt de levenscyclus van de server, inclusief het starten van de server en het correct afsluiten van de server op beëindigingssignalen:

process.on('SIGINT', async () => {
  log.error('Shutting down server...');
  await server.close();
  process.exit(0);
});

Concepten:

• Probleemloos afsluiten: Opschonen op Ctrl+C
• Asynchroon opschonen: de bewerking voor het sluiten van de server is asynchroon
• Resourcebeheer: belangrijk voor SSE-verbindingen

Transportlaag: server.ts

Het server.ts bestand implementeert de transportlaag voor de MCP-server, met name het verwerken van Server-Sent gebeurtenissenverbindingen (SSE) en het routeren van MCP-protocolberichten.

Een SSE-clientverbinding instellen en een transport maken

De SSEPServer klasse is de belangrijkste transportlaag voor het verwerken van Server-Sent Gebeurtenissen (SSE) in de MCP-server. De SSEServerTransport klasse wordt gebruikt om individuele clientverbindingen te beheren. Het beheert meerdere transporten en hun levenscyclus.

export class SSEPServer {
  server: Server;
  transport: SSEServerTransport | null = null;
  transports: Record<string, SSEServerTransport> = {};

  constructor(server: Server) {
    this.server = server;
    this.setupServerRequestHandlers();
  }
}

Concepten:

• Staatsbeheer: houdt zowel huidig transport als alle transporten bij
• Sessie-mapping: transports object wijst sessie-id's toe aan transportexemplaren
• Constructordelegering: hiermee stelt u onmiddellijk verzoekafhandelaars in

SSE-verbindingsinrichting (handleGetRequest)

De handleGetRequest methode is verantwoordelijk voor het tot stand brengen van een nieuwe SSE-verbinding wanneer een client een GET-aanvraag naar het /sse eindpunt doet.

async handleGetRequest(req: Request, res: Response) {
  log.info(`GET ${req.originalUrl} (${req.ip})`);
  try {
    log.info("Connecting transport to server...");
    this.transport = new SSEServerTransport("/messages", res);
    TransportsCache.set(this.transport.sessionId, this.transport);

    res.on("close", () => {
      if (this.transport) {
        TransportsCache.delete(this.transport.sessionId);
      }
    });

    await this.server.connect(this.transport);
    log.success("Transport connected. Handling request...");
  } catch (error) {
    // Error handling...
  }
}

Concepten:

• Transport maken: nieuw SSEServerTransport voor elke GET-aanvraag
• Sessiebeheer: automatisch gegenereerde sessie-id opgeslagen in cache
• Event handlers: Reiniging bij het sluiten van de verbinding
• MCP-verbinding: server.connect() protocolverbinding tot stand brengt
• Asynchrone stroom: De installatie van de verbinding is asynchroon met foutgrenzen

Berichtverwerking (handlePostRequest)

De handlePostRequest methode verwerkt binnenkomende POST-aanvragen voor het verwerken van MCP-berichten die door de client worden verzonden. Hierbij wordt de sessie-id van de queryparameters gebruikt om het juiste transportvoorbeeld te vinden.

async handlePostRequest(req: Request, res: Response) {
  log.info(`POST ${req.originalUrl} (${req.ip}) - payload:`, req.body);

  const sessionId = req.query.sessionId as string;
  const transport = TransportsCache.get(sessionId);
  if (transport) {
    await transport.handlePostMessage(req, res, req.body);
  } else {
    log.error("Transport not initialized. Cannot handle POST request.");
    res.status(400).json(/* error response */);
  }
}

Concepten:

• Sessiezoekactie: queryparameter gebruikt sessionId om transport te vinden
• Sessievalidatie: valideert eerst de SSE-verbinding.
• Berichtdelegering: Transport verwerkt de werkelijke verwerking van berichten
• Foutberichten: Juiste HTTP-foutcodes voor ontbrekende sessies

MCP Protocol Handler Instelling (setupServerRequestHandlers)

De setupServerRequestHandlers methode registreert de volgende handlers voor MCP-protocolaanvragen:

• Een handler voor ListToolsRequestSchema die retourneert de lijst met beschikbare todo-hulpprogramma's.
• Een handler voor CallToolRequestSchema die zoekt en voert het aangevraagde hulpprogramma uit met de opgegeven argumenten.

Deze methode maakt gebruik van Zod-schema's om de verwachte aanvraag- en antwoordindelingen te definiëren.

private setupServerRequestHandlers() {
  this.server.setRequestHandler(ListToolsRequestSchema, async (_request) => {
    return {
      tools: TodoTools,
    };
  });
  
  this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
    const { name, arguments: args } = request.params;
    
    const tool = TodoTools.find((tool) => tool.name === name);
    if (!tool) {
      return this.createJSONErrorResponse(`Tool "${name}" not found.`);
    }
    
    const response = await tool.execute(args as any);
    return { content: [{ type: "text", text: response }] };
  });
}

Concepten:

• Schema-Based routering: maakt gebruik van Zod-schema's voor een typeveilige afhandeling van verzoeken.
• Detectie van hulpprogramma's: ListToolsRequestSchema retourneert een statische TodoTools-matrix
• Uitvoering van hulpprogramma's: CallToolRequestSchema hulpprogramma's zoeken en uitvoeren
• Foutafhandeling: Probleemloze verwerking van onbekende hulpprogramma's
• Antwoordindeling: MCP-compatibele antwoordstructuur
• TypeVeiligheid: TypeScript-typen zorgen ervoor dat het juiste argument wordt doorgegeven

Bedrijfslogica: tools.ts

Het tools.ts bestand definieert de werkelijke functionaliteit die beschikbaar is voor MCP-clients:

• Metagegevens van hulpprogramma 's (naam, beschrijving, schema's)
• Invoervalidatieschema's
• Uitvoeringslogica voor hulpprogramma's
• Integratie met databaselaag

Deze MCP-server definieert vier hulpprogramma's voor TODO-beheer:

• add_todo: Hiermee maakt u een nieuw TODO-item
• complete_todo: Hiermee wordt een TODO-item als voltooid gemarkeerd
• delete_todo: Verwijdert een TODO-item
• list_todos: geeft een overzicht van alle takenlijstitems
• update_todo_text: Hiermee wordt de tekst van een bestaand TODO-item bijgewerkt

Definitiepatroon voor hulpprogramma's

De hulpprogramma's worden gedefinieerd als een matrix van objecten, die elk een specifieke takenlijstbewerking vertegenwoordigen. In het volgende codefragment wordt het addTodo hulpprogramma gedefinieerd:

{
  name: "addTodo",
  description: "Add a new TODO item to the list...",
  inputSchema: {
    type: "object",
    properties: {
      text: { type: "string" },
    },
    required: ["text"],
  },
  outputSchema: { type: "string" },
  async execute({ text }: { text: string }) {
    const info = await addTodo(text);
    return `Added TODO: ${text} (id: ${info.lastInsertRowid})`;
  },
}

Elke definitie van het hulpprogramma heeft:

• name: Unieke id voor het hulpprogramma
• description: Korte beschrijving van het doel van het hulpmiddel
• inputSchema: Zod-schema waarmee de verwachte invoerindeling wordt gedefinieerd
• outputSchema: Zod-schema waarmee de verwachte uitvoerindeling wordt gedefinieerd
• execute: Functie die de logica van het hulpprogramma implementeert

Deze hulpprogrammadefinities worden geïmporteerd in server.ts en geëxposeerd via de ListToolsRequestSchema handler.

Concepten:

• Modulair toolontwerp: elk hulpmiddel is een zelfstandig object
• JSON-schemavalidatie: inputSchema definieert verwachte parameters
• Type Veiligheid: TypeScript-typen komen overeen met schemadefinities
• Asynchrone uitvoering: alle uitvoeringen van hulpprogramma's zijn asynchroon
• Databaseintegratie: geïmporteerde databasefuncties aanroepen
• Human-Readable-antwoorden: retourneert opgemaakte tekenreeksen, niet onbewerkte gegevens

Hulpmiddelmatrix exporteren

De hulpprogramma's worden geëxporteerd als een statische matrix, zodat ze eenvoudig kunnen worden geïmporteerd en gebruikt op de server. Elk hulpprogramma is een object met de bijbehorende metagegevens en uitvoeringslogica. Met deze structuur kan de MCP-server hulpprogramma's dynamisch detecteren en uitvoeren op basis van clientaanvragen.

export const TodoTools = [
  { /* addTodo */ },
  { /* listTodos */ },
  { /* completeTodo */ },
  { /* deleteTodo */ },
  { /* updateTodoText */ },
];

Concepten:

• Statische registratie: hulpprogramma's gedefinieerd tijdens de laadtijd van de module
• Matrixstructuur: Eenvoudige matrix maakt hulpprogramma's eenvoudig te herhalen
• Importeren/exporteren: Duidelijke scheiding van de logica van de server

Foutafhandeling bij het uitvoeren van hulpprogramma's

De functie van execute elk hulpprogramma verwerkt fouten probleemloos en retourneert duidelijke berichten in plaats van uitzonderingen te genereren. Deze aanpak zorgt ervoor dat de MCP-server een naadloze gebruikerservaring biedt.

Hulpprogramma's verwerken verschillende foutscenario's:

async execute({ id }: { id: number }) {
  const info = await completeTodo(id);
  if (info.changes === 0) {
    return `TODO with id ${id} not found.`;
  }
  return `Marked TODO ${id} as completed.`;
}

Concepten:

• Controle van databasereacties: wordt gebruikt info.changes om fouten te detecteren
• Graceful Degradatie: retourneert beschrijvende foutberichten versus gooien
• User-Friendly fouten: berichten die geschikt zijn voor AI-interpretatie

Gegevenslaag: db.ts

Het db.ts bestand beheert de SQLite-databaseverbinding en verwerkt CRUD-bewerkingen voor de TAKEN-app. Het better-sqlite3-bibliotheek wordt gebruikt voor synchrone databasetoegang.

Database-initialisatie

De database initialiseert door verbinding te maken met SQLite en tabellen te maken als deze niet bestaan. Het volgende codefragment toont het initialisatieproces:

const db = new Database(":memory:", {
  verbose: log.info,
});

try {
  db.pragma("journal_mode = WAL");
  db.prepare(
    `CREATE TABLE IF NOT EXISTS ${DB_NAME} (
     id INTEGER PRIMARY KEY AUTOINCREMENT,
     text TEXT NOT NULL,
     completed INTEGER NOT NULL DEFAULT 0
   )`
  ).run();
  log.success(`Database "${DB_NAME}" initialized.`);
} catch (error) {
  log.error(`Error initializing database "${DB_NAME}":`, { error });
}

Concepten:

• In-Memory Database: :memory: betekent dat gegevens verloren gaan bij opnieuw opstarten (alleen demo/testen)
• WAL-modus: Write-Ahead Logboekregistratie voor betere prestaties
• Schemadefinitie: Eenvoudige TODO-tabel met automatisch incrementeerde ID
• Foutafhandeling: Probleemloze verwerking van initialisatiefouten
• Integratie van logboekregistratie: databasebewerkingen worden vastgelegd voor foutopsporing

CRUD-bewerkingspatronen

Het db.ts bestand bevat vier belangrijke CRUD-bewerkingen voor het beheren van TAKENLIJSTitems:

Bewerking maken:

export async function addTodo(text: string) {
  log.info(`Adding TODO: ${text}`);
  const stmt = db.prepare(`INSERT INTO todos (text, completed) VALUES (?, 0)`);
  return stmt.run(text);
}

Leesbewerking:

export async function listTodos() {
  log.info("Listing all TODOs...");
  const todos = db.prepare(`SELECT id, text, completed FROM todos`).all() as Array<{
    id: number;
    text: string;
    completed: number;
  }>;
  return todos.map(todo => ({
    ...todo,
    completed: Boolean(todo.completed),
  }));
}

Updatebewerking:

export async function completeTodo(id: number) {
  log.info(`Completing TODO with ID: ${id}`);
  const stmt = db.prepare(`UPDATE todos SET completed = 1 WHERE id = ?`);
  return stmt.run(id);
}

Verwijderbewerking:

export async function deleteTodo(id: number) {
  log.info(`Deleting TODO with ID: ${id}`);
  const row = db.prepare(`SELECT text FROM todos WHERE id = ?`).get(id) as
    | { text: string }
    | undefined;
  if (!row) {
    log.error(`TODO with ID ${id} not found`);
    return null;
  }
  db.prepare(`DELETE FROM todos WHERE id = ?`).run(id);
  log.success(`TODO with ID ${id} deleted`);
  return row;
}

Concepten:

• Voorbereide instructies: Bescherming tegen SQL-injectie
• Typecasting: Expliciete TypeScript-typen voor queryresultaten
• Gegevenstransformatie: SQLite-gehele getallen converteren naar booleaanse waarden
• Atomische bewerkingen: elke functie is één databasetransactie
• Consistentie van retourwaarde: metagegevens van de functie retourbewerking
• Defensieve programmering: patroon Check-before-delete

Schemaontwerp

Het databaseschema wordt gedefinieerd in het db.ts bestand met behulp van een eenvoudige SQL-instructie. De todos tabel heeft drie velden:

CREATE TABLE todos (
  id INTEGER PRIMARY KEY AUTOINCREMENT,  -- Unique identifier
  text TEXT NOT NULL,                    -- TODO description  
  completed INTEGER NOT NULL DEFAULT 0   -- Boolean as integer
);

Helperhulpprogramma's: helpers/ directory

De helpers/ map biedt hulpprogrammafuncties en -klassen voor de server.

Gestructureerde logboekregistratie voor foutopsporing en bewaking: helpers/logs.ts

Het helpers/logs.ts bestand biedt een gestructureerd hulpprogramma voor logboekregistratie voor de MCP-server. De debug-bibliotheek wordt gebruikt voor logboekregistratie en chalk voor gekleurde uitvoer in de console.

export const logger = (namespace: string) => {
  const dbg = debug('mcp:' + namespace);
  const log = (colorize: ChalkInstance, ...args: any[]) => {
    const timestamp = new Date().toISOString();
    const formattedArgs = [timestamp, ...args].map((arg) => {
      if (typeof arg === 'object') {
        return JSON.stringify(arg, null, 2);
      }
      return arg;
    });
    dbg(colorize(formattedArgs.join(' ')));
  };

  return {
    info(...args: any[]) { log(chalk.cyan, ...args); },
    success(...args: any[]) { log(chalk.green, ...args); },
    warn(...args: any[]) { log(chalk.yellow, ...args); },
    error(...args: any[]) { log(chalk.red, ...args); },
  };
};

Sessiebeheer voor SSE-transporten: helpers/cache.ts

Het helpers/cache.ts bestand maakt gebruik van een Map bestand voor het opslaan van SSE-transporten per sessie-id. Met deze methode kan de server snel actieve verbindingen vinden en beheren.

import type { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse";

export const TransportsCache = new Map<string, SSEServerTransport>();

Samenvatting van uitvoeringsstroom

In het volgende diagram ziet u het volledige aanvraagtraject van de client naar de MCP-server en terug, waaronder het uitvoeren van hulpprogramma's en databasebewerkingen:

Het opschonen van GitHub Codespaces

Hulp krijgen

Meld uw probleem aan bij de problemen van de opslagplaats.

Verwante middelen

• Inleiding tot agents en het modelcontextprotocol
• Een .NET OpenAI-agent bouwen met behulp van een MCP-server in Azure Container Apps