Erstellung eines Elasticsearch MCP-Servers mit TypeScript
Erfahren Sie, wie Sie mit TypeScript und Claude Desktop einen Elasticsearch MCP-Server erstellen.
Bei der Arbeit mit großen Wissensdatenbanken in Elasticsearch ist das Finden von Informationen nur die halbe Miete. Entwickler müssen häufig Ergebnisse aus mehreren Dokumenten zusammenführen, Zusammenfassungen erstellen und Antworten bis zu ihren Quellen zurückverfolgen. Um dies zu erreichen, bietet das Modellkontextprotokoll (MCP) eine standardisierte Möglichkeit, Elasticsearch mit LLM-gestützten Anwendungen zu verbinden. Während Elastic offizielle Lösungen anbietet, wie den Elastic Agent Builder (der unter anderem einen MCP-Endpoint zu seinen Features zählt), ermöglicht die Entwicklung eines benutzerdefinierten MCP-Servers die volle Kontrolle über die Suchlogik, die Ergebnisformatierung und die Art und Weise, wie abgerufene Inhalte an ein LLM zur Synthese, Zusammenfassung und Zitierung weitergegeben werden.
In diesem Artikel untersuchen wir die Vorteile der Entwicklung eines benutzerdefinierten Elasticsearch MCP-Servers und zeigen, wie man einen in TypeScript erstellt, der Elasticsearch mit LLM-gestützten Anwendungen verbindet.
Warum einen benutzerdefinierten Elasticsearch MCP-Server entwickeln?
Elastic bietet einige Alternativen für MCP-Server:
Wenn Sie mehr Kontrolle darüber benötigen, wie Ihr MCP-Server mit Elasticsearch interagiert, bietet Ihnen die Entwicklung eines eigenen benutzerdefinierten Servers die nötige Flexibilität, um ihn genau an Ihre Bedürfnisse anzupassen. Zum Beispiel ist der MCP-Endpoint von Agent Builder auf Elasticsearch Query Language (ES|QL) Abfragen beschränkt, während ein benutzerdefinierter Server die Verwendung des vollständigen Abfrage-DSL ermöglicht. Sie erhalten außerdem die Kontrolle über die Formatierung der Ergebnisse, bevor sie an das LLM weitergeleitet werden, und können zusätzliche Verarbeitungsschritte integrieren, wie die OpenAI-gestützte Zusammenfassung, die wir in dieses Tutorial implementieren.
Am Ende dieses Artikels verfügen Sie über einen MCP-Server in TypeScript, der in einem Elasticsearch-Index gespeicherte Informationen durchsucht, zusammenfasst und Zitate bereitstellt. Wir verwenden Elasticsearch für den Abruf, das gpt-4o-mini-Modell von OpenAI zur Zusammenfassung und Erzeugung von Zitaten sowie Claude Desktop als MCP-Client und Benutzeroberfläche, um Nutzeranfragen zu empfangen und darauf zu reagieren. Das Endergebnis ist ein interner Wissensassistent, der Entwicklern dabei hilft, Best Practices in der technischen Dokumentation ihres Unternehmens zu entdecken und zu synthetisieren.
Voraussetzungen:
Node.js 20+
Elasticsearch
OpenAI-API-Schlüssel
Claude Desktop
Was ist MCP?
MCP ist ein offener Standard, der von Anthropic entwickelt wurde und sichere, bidirektionale Verbindungen zwischen LLMs und externen Systemen wie Elasticsearch ermöglicht. Mehr über den aktuellen Stand von MCP können Sie in diesem Artikel lesen.
Die MCP-Landschaft entwickelt sich täglich weiter, wobei Server für eine Vielzahl von Anwendungsfällen zur Verfügung stehen. In diesem Artikel zeigen wir Ihnen außerdem, wie einfach es ist, Ihren eigenen benutzerdefinierten MCP-Server zu entwickeln.
MCP-Clients
Es gibt eine lange Liste verfügbarer MCP-Clients, von denen jeder seine eigenen Eigenschaften und Einschränkungen hat. Aufgrund seiner Einfachheit und Beliebtheit verwenden wir Claude Desktop als unseren MCP-Client. Er dient als Chat-Schnittstelle, auf der Nutzer Fragen in natürlicher Sprache stellen können, und ruft automatisch die von unserem MCP-Server bereitgestellten Tools auf, um Dokumente zu durchsuchen und Zusammenfassungen zu erstellen.
Erstellen eines Elasticsearch MCP-Servers
Mit dem TypeScript SDK können wir einfach einen Server erstellen, der versteht, wie er unsere Elasticsearch-Daten basierend auf einer Nutzereingabe abfragt.
In diesem Artikel werden die folgenden Schritte zur Integration des Elasticsearch MCP-Servers mit dem Claude Desktop-Client beschrieben:
MCP-Server für Elasticsearch konfigurieren
Zunächst initialisieren wir eine Node-Anwendung:
npm init -yDadurch wird eine package.json-Datei erstellt, wodurch wir damit beginnen können, die notwendigen Abhängigkeiten für diese Anwendung zu installieren.
npm install @elastic/elasticsearch @modelcontextprotocol/sdk openai zod && npm install --save-dev ts-node @types/node typescript@elastic/elasticsearch verschafft Ihnen Zugriff auf die Node.js-Bibliothek von Elasticsearch.
@modelcontextprotocol/SDK stellt die Kerntools bereit, um einen MCP-Server zu erstellen und zu verwalten, Tools zu registrieren und die Kommunikation mit MCP-Clients zu übernehmen.
OpenAI ermöglicht die Interaktion mit OpenAI-Modellen, um Zusammenfassungen oder Antworten in natürlicher Sprache zu generieren.
ZOD sorgt dafür, strukturierte Schemata für Eingangs- und Ausgangsdaten in jedem Tool zu definieren und zu validieren.
ts-nodeWährend der Entwicklung werden @types/node und typescript verwendet, um den Code zu schreiben und die Skripte zu kompilieren.
Datensatz einrichten
Um die Daten bereitzustellen, die Claude Desktop über unseren MCP-Server abfragen kann, verwenden wir einen simulierten internen Wissensdatenbank-Datensatz. So sieht ein Dokument aus diesem Datensatz aus:
{
"id": 5,
"title": "Logging Standards for Microservices",
"content": "Consistent logging across microservices helps with debugging and tracing. Use structured JSON logs and include request IDs and timestamps. Avoid logging sensitive information. Centralize logs in Elasticsearch or a similar system. Configure log rotation to prevent storage issues and ensure logs are searchable for at least 30 days.",
"tags": ["logging", "microservices", "standards"]
}Für die Aufnahme der Daten haben wir ein Skript vorbereitet, das einen Index in Elasticsearch erstellt und den Datensatz darin lädt. Sie finden es hier.
MCP-Server
Erstellen Sie eine Datei mit dem Namen index.ts und fügen Sie den folgenden Code hinzu, um die Abhängigkeiten zu importieren und Umgebungsvariablen zu verarbeiten:
// index.ts
import { z } from "zod";
import { Client } from "@elastic/elasticsearch";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import OpenAI from "openai";
const ELASTICSEARCH_ENDPOINT =
process.env.ELASTICSEARCH_ENDPOINT ?? "http://localhost:9200";
const ELASTICSEARCH_API_KEY = process.env.ELASTICSEARCH_API_KEY ?? "";
const OPENAI_API_KEY = process.env.OPENAI_API_KEY ?? "";
const INDEX = "documents";Außerdem initialisieren wir die Clients, um Elasticsearch- und OpenAI-Aufrufe zu bewältigen:
const openai = new OpenAI({
apiKey: OPENAI_API_KEY,
});
const _client = new Client({
node: ELASTICSEARCH_ENDPOINT,
auth: {
apiKey: ELASTICSEARCH_API_KEY,
},
});Um unsere Implementierung robuster zu machen und einen strukturierten Eingang und Ausgang zu gewährleisten, definieren wir Schemata mit zod. Dadurch können wir Daten zur Laufzeit validieren, Fehler frühzeitig abfangen und die Tool-Reaktionen einfacher programmatisch verarbeiten.
const DocumentSchema = z.object({
id: z.number(),
title: z.string(),
content: z.string(),
tags: z.array(z.string()),
});
const SearchResultSchema = z.object({
id: z.number(),
title: z.string(),
content: z.string(),
tags: z.array(z.string()),
score: z.number(),
});
type Document = z.infer<typeof DocumentSchema>;
type SearchResult = z.infer<typeof SearchResultSchema>;Erfahren Sie hier mehr über strukturierte Ausgänge.
Nun initialisieren wir den MCP-Server:
const server = new McpServer({
name: "Elasticsearch RAG MCP",
description:
"A RAG server using Elasticsearch. Provides tools for document search, result summarization, and source citation.",
version: "1.0.0",
});Definition der MCP-Tools
Wenn alles konfiguriert ist, können wir mit dem Schreiben der Tools beginnen, die von unserem MCP-Server bereitgestellt werden. Dieser Server stellt zwei Tools bereit:
search_docs: Sucht nach Dokumenten in Elasticsearch mittels Volltextsuche.summarize_and_cite: Fasst Informationen aus zuvor abgerufenen Dokumenten zusammen und synthetisiert sie, um eine Nutzerfrage zu beantworten. Dieses Tool fügt außerdem Zitate hinzu, die auf die Quelldokumente verweisen.
Zusammen bilden diese Tools einen einfachen Workflow zum Abrufen und Zusammenfassen, bei dem ein Tool relevante Dokumente abruft und das andere diese Dokumente verwendet, um eine zusammengefasste, zitierte Reaktion zu generieren.
Reaktionsformat des Tools
Jedes Tool kann beliebige Eingangsparameter akzeptieren, muss aber mit folgender Struktur antworten:
Inhalt: Dies ist die Reaktion des Tools im unstrukturierten Format. Dieses Feld wird in der Regel verwendet, um Text, Bilder, Audio, Links oder Einbettungen zurückzugeben. In dieser Anwendung dient es dazu, formatierten Text mit den Informationen zurückzugeben, die von den Tools generiert wurden.
structuredContent: Dies ist eine optionale Rückgabe, die verwendet wird, um die Ergebnisse der einzelnen Tools in einem strukturierten Format bereitzustellen. Dies ist für programmatische Zwecke nützlich. Zwar wird es in diesem MCP-Server nicht verwendet, es kann jedoch von Nutzen sein, wenn Sie andere Tools entwickeln oder die Ergebnisse programmatisch verarbeiten möchten.
Vor diesem Hintergrund betrachten wir nun jedes Tool im Detail.
Tool „Search_docs“
Dieses Tool führt eine Volltextsuche im Elasticsearch-Index durch, um die relevantesten Dokumente basierend auf der Nutzeranfrage abzurufen. Es hebt die wichtigsten Treffer hervor und bietet einen schnellen Überblick mit Relevanzbewertungen.
server.registerTool(
"search_docs",
{
title: "Search Documents",
description:
"Search for documents in Elasticsearch using full-text search. Returns the most relevant documents with their content, title, tags, and relevance score.",
inputSchema: {
query: z
.string()
.describe("The search query terms to find relevant documents"),
max_results: z
.number()
.optional()
.default(5)
.describe("Maximum number of results to return"),
},
outputSchema: {
results: z.array(SearchResultSchema),
total: z.number(),
},
},
async ({ query, max_results }) => {
if (!query) {
return {
content: [
{
type: "text",
text: "Query parameter is required",
},
],
isError: true,
};
}
try {
const response = await _client.search({
index: INDEX,
size: max_results,
query: {
bool: {
must: [
{
multi_match: {
query: query,
fields: ["title^2", "content", "tags"],
fuzziness: "AUTO",
},
},
],
should: [
{
match_phrase: {
title: {
query: query,
boost: 2,
},
},
},
],
},
},
highlight: {
fields: {
title: {},
content: {},
},
},
});
const results: SearchResult[] = response.hits.hits.map((hit: any) => {
const source = hit._source as Document;
return {
id: source.id,
title: source.title,
content: source.content,
tags: source.tags,
score: hit._score ?? 0,
};
});
const contentText = results
.map(
(r, i) =>
`[${i + 1}] ${r.title} (score: ${r.score.toFixed(
2,
)})\n${r.content.substring(0, 200)}...`,
)
.join("\n\n");
const totalHits =
typeof response.hits.total === "number"
? response.hits.total
: (response.hits.total?.value ?? 0);
return {
content: [
{
type: "text",
text: `Found ${results.length} relevant documents:\n\n${contentText}`,
},
],
structuredContent: {
results: results,
total: totalHits,
},
};
} catch (error: any) {
console.log("Error during search:", error);
return {
content: [
{
type: "text",
text: `Error searching documents: ${error.message}`,
},
],
isError: true,
};
}
}
);Wir konfigurieren fuzziness: “AUTO” so, dass eine variable Tippfehlertoleranz basierend auf der Länge des analysierten Tokens besteht. Wir legen außerdem title^2 fest, um die Bewertung der Dokumente zu erhöhen, bei denen die Übereinstimmung im Feld „Titel“ erfolgt.
Tool „summarize_and_cite“
Dieses Tool erstellt eine Zusammenfassung auf Basis von Dokumenten, die bei der vorherigen Suche ermittelt wurden. Es verwendet das gpt-4o-mini-Modell von OpenAI, um die relevantesten Informationen zur Beantwortung der Nutzerfragen zu synthetisieren und Antworten zu liefern, die direkt aus den Suchergebnissen abgeleitet werden. Neben der Zusammenfassung werden auch Metadaten für Zitate zu den verwendeten Quelldokumenten zurückgegeben.
server.registerTool(
"summarize_and_cite",
{
title: "Summarize and Cite",
description:
"Summarize the provided search results to answer a question and return citation metadata for the sources used.",
inputSchema: {
results: z
.array(SearchResultSchema)
.describe("Array of search results from search_docs"),
question: z.string().describe("The question to answer"),
max_length: z
.number()
.optional()
.default(500)
.describe("Maximum length of the summary in characters"),
max_docs: z
.number()
.optional()
.default(5)
.describe("Maximum number of documents to include in the context"),
},
outputSchema: {
summary: z.string(),
sources_used: z.number(),
citations: z.array(
z.object({
id: z.number(),
title: z.string(),
tags: z.array(z.string()),
relevance_score: z.number(),
})
),
},
},
async ({ results, question, max_length, max_docs }) => {
if (!results || results.length === 0 || !question) {
return {
content: [
{
type: "text",
text: "Both results and question parameters are required, and results must not be empty",
},
],
isError: true,
};
}
try {
const used = results.slice(0, max_docs);
const context = used
.map(
(r: SearchResult, i: number) =>
`[Document ${i + 1}: ${r.title}]\\n${r.content}`
)
.join("\n\n---\n\n");
// Generate summary with OpenAI
const completion = await openai.chat.completions.create({
model: "gpt-4o-mini",
messages: [
{
role: "system",
content:
"You are a helpful assistant that answers questions based on provided documents. Synthesize information from the documents to answer the user's question accurately and concisely. If the documents don't contain relevant information, say so.",
},
{
role: "user",
content: `Question: ${question}\\n\\nRelevant Documents:\\n${context}`,
},
],
max_tokens: Math.min(Math.ceil(max_length / 4), 1000),
temperature: 0.3,
});
const summaryText =
completion.choices[0]?.message?.content ?? "No summary generated.";
const citations = used.map((r: SearchResult) => ({
id: r.id,
title: r.title,
tags: r.tags,
relevance_score: r.score,
}));
const citationText = citations
.map(
(c: any, i: number) =>
`[${i + 1}] ID: ${c.id}, Title: "${c.title}", Tags: ${c.tags.join(
", ",
)}, Score: ${c.relevance_score.toFixed(2)}`,
)
.join("\n");
const combinedText = `Summary:\\n\\n${summaryText}\\n\\nSources used (${citations.length}):\\n\\n${citationText}`;
return {
content: [
{
type: "text",
text: combinedText,
},
],
structuredContent: {
summary: summaryText,
sources_used: citations.length,
citations: citations,
},
};
} catch (error: any) {
return {
content: [
{
type: "text",
text: `Error generating summary and citations: ${error.message}`,
},
],
isError: true,
};
}
}
);Zu guter Letzt starten wir den Server mithilfe von stdio. Das bedeutet, dass der MCP-Client mit unserem Server kommuniziert, indem er seine standardmäßigen Eingangs- und Ausgangsstreams liest und schreibt. stdio ist die einfachste Transportoption und funktioniert gut für lokale MCP-Server, die vom Client als Unterprozesse gestartet werden. Fügen Sie den folgenden Code am Ende der Datei hinzu:
const transport = new StdioServerTransport();
server.connect(transport);Kompilieren Sie das Projekt jetzt mit folgendem Befehl:
npx tsc index.ts --target ES2022 --module node16 --moduleResolution node16 --outDir ./dist --strict --esModuleInteropDadurch wird ein Ordner dist erstellt und darin eine Datei index.js.
Laden Sie den MCP-Server in Claude Desktop
Folgen Sie dieser Anleitung, um den MCP-Server mit Claude Desktop zu konfigurieren. In der Konfigurationsdatei von Claude müssen die folgenden Werte festgelegt werden:
{
"mcpServers": {
"elasticsearch-rag-mcp": {
"command": "node",
"args": [ "/Users/user-name/app-dir/dist/index.js"
],
"env": {
"ELASTICSEARCH_ENDPOINT": "your-endpoint-here",
"ELASTICSEARCH_API_KEY": "your-api-key-here",
"OPENAI_API_KEY": "your-openai-key-here"
}
}
}
}Der Wert args sollte auf die kompilierte Datei im Ordner dist verweisen. Außerdem müssen Sie die Umgebungsvariablen in der Konfigurationsdatei mit genau den gleichen Namen festlegen, die im Code definiert sind.
Probieren Sie es aus
Klicken Sie vor der Ausführung jedes Tools auf Search and Tools, um sicherzustellen, dass die Tools aktiviert sind. Hier können Sie außerdem alle Funktionen aktivieren oder deaktivieren:
Zum Schluss testen wir den MCP-Server über den Claude Desktop-Chat und beginnen, Fragen zu stellen:
Für die Frage „Suche nach Dokumenten zu Authentifizierungsmethoden und RBAC“ wird das search_docs-Tool ausgeführt und liefert folgende Ergebnisse:
Most Relevant Documents:
Access Control and Role Management (highest relevance) - This document covers role-based access control (RBAC) principles, including ensuring users only have necessary permissions, regular auditing of user roles, revoking inactive accounts, and implementing just-in-time access for sensitive operations.
User Authentication with OAuth 2.0 - This document explains OAuth 2.0 authentication, which enables secure delegated access without credential sharing. It covers configuring identity providers, token management with limited scope and lifetime, and secure storage of refresh tokens.
Container Security Guidelines - While primarily about container security, this document touches on access control aspects like running containers as non-root users and avoiding embedded credentials.
Incident Response Playbook - This mentions role assignment during incidents (incident commander, communications lead, etc.), which relates to access control in emergency scenarios.
Logging Standards for Microservices - This document includes guidance on avoiding logging sensitive information, which is relevant to authentication security.Die Reaktion lautet: „Großartig! Ich habe 5 relevante Dokumente über Authentifizierungsmethoden und RBAC gefunden. Folgendes wurde gefunden:“
Der Toolaufruf gibt die Quelldokumente als Teil seiner Reaktionnutzlast zurück, die später zur Erstellung von Zitaten verwendet werden.
Es ist auch möglich, mehrere Tools in einer einzigen Interaktion zu verketten. In diesem Fall analysiert Claude Desktop die Frage des Nutzers und stellt fest, dass zunächst search_docs aufgerufen werden muss, um relevante Dokumente abzurufen, und dass diese Ergebnisse anschließend an summarize_and_cite übergeben werden müssen, um die endgültige Antwort zu generieren, ohne dass dafür separate Prompts vom Nutzer erforderlich sind:
In diesem Fall haben wir für die Abfrage „Was sind die wichtigsten Empfehlungen zur Verbesserung der Authentifizierung und Zugriffssteuerung in unseren Systemen? Referenzen einbeziehen.“ folgende Ergebnisse erzielt:
Based on the documentation, here are the main recommendations to improve authentication and access control across your systems:
Key Recommendations
1. Implement Role-Based Access Control (RBAC)
Ensure users have only the permissions necessary for their job functions. This principle of least privilege minimizes security risks by limiting access to what's truly needed. [1]
2. Regular Access Audits
Conduct regular audits of user roles and promptly revoke access for inactive accounts. This helps prevent unauthorized access from dormant or compromised accounts. [1]
3. Just-in-Time (JIT) Access
Implement just-in-time access for sensitive operations, where permissions are granted only when needed and for a limited duration. This reduces the attack surface by minimizing standing privileges. [1]
4. OAuth 2.0 for Secure Authentication
Use OAuth 2.0 to enable secure delegated access without sharing user credentials. This protocol allows third-party applications to access resources on behalf of users without exposing passwords. [2]
5. Token Security and Management
Configure your identity provider to issue tokens with limited scope and lifetime
Store refresh tokens securely
Validate access tokens consistently to maintain security [2]
References
Access Control and Role Management (Tags: security, access-control)
User Authentication with OAuth 2.0 (Tags: authentication, oauth)
These recommendations work together to create a defense-in-depth approach, where multiple security layers protect your systems from unauthorized access.Wie im vorherigen Schritt können wir die Reaktion jedes Tools auf diese Frage einsehen:
Hinweis: Wenn ein Untermenü erscheint, in dem gefragt wird, ob Sie die Nutzung jedes Tools genehmigen möchten, wählen Sie Immer erlauben oder Einmal erlauben.
Fazit
MCP-Server stellen einen bedeutenden Schritt zur Standardisierung von LLM-Tools für lokale und entfernte Anwendungen dar. Die vollständige Kompatibilität ist zwar noch in Bearbeitung, wir verzeichnen jedoch große Fortschritte in diese Richtung.
In diesem Artikel haben wir gelernt, wie man einen benutzerdefinierten MCP-Server in TypeScript entwickelt, der Elasticsearch mit LLM-gestützten Anwendungen verbindet. Unser Server stellt zwei Tools bereit: search_docs zum Abrufen relevanter Dokumente mittels Abfrage-DSL und summarize_and_cite zur Erstellung von Zusammenfassungen mit Zitaten über OpenAI-Modelle und Claude Desktop als Client-Benutzeroberfläche.
Die Zukunft der Kompatibilität zwischen verschiedenen Client- und Server-Anbietern sieht vielversprechend aus. Zu den nächsten Schritten gehört die Erweiterung des Funktionsumfangs und die Erhöhung der Flexibilität Ihres Agenten. Es gibt einen praktischen Artikel dazu, wie Sie Ihre Abfragen mithilfe von Suchvorlagen für mehr Präzision und Flexibilität parametrisieren können.
