Demo: MCP dla wyszukiwarki dokumentacji (Elasticsearch)

Działający przykład tego, jak może wyglądać serwer MCP opisany w propozycji technicznej: 5 narzędzi, które dowolny agent LLM (Claude Desktop, Claude Code, własny chatbot na Claude API) może wywołać, żeby przeszukać bazę instrukcji, filmów instruktażowych, PDF-ów, DOCX-ów i zdjęć — zamiast dostawać surowy dostęp do indeksu.

Demo ma dwa tryby, ten sam kod serwera i te same narzędzia w obu:

• memory (domyślny) — 10 przykładowych dokumentów z data/documents.json, wyszukiwanie hybrydowe (BM25 + wektor) liczone w pamięci procesu Node. Zero zależności zewnętrznych, działa od razu, po npm install.

• elasticsearch — te same narzędzia, ale dane trzymane w prawdziwym Elasticsearch (docker-compose). Pokazuje ścieżkę do wdrożenia produkcyjnego.

Szybki start (tryb memory, bez Dockera)

npm install
npm run test:e2e        # uruchamia realnego klienta MCP i sprawdza wszystkie narzędzia

test/demo-client.js to nie jest test jednostkowy funkcji — to prawdziwy klient MCP, który odpala src/server.js jako osobny proces i rozmawia z nim po protokole MCP przez stdio, dokładnie tak jak zrobiłby to Claude Desktop.

Related MCP server: rag-hub-mcp

Podłączenie do Claude Desktop

1. Otwórz konfigurację Claude Desktop (Settings → Developer → Edit Config).

2. Dopisz zawartość claude_desktop_config.example.json, podmieniając ścieżkę na pełną ścieżkę do src/server.js na Twoim dysku.

3. Zrestartuj Claude Desktop.

4. Zapytaj np. "jak zresetować ekspres X200?" albo "pokaż jak wymienić filtr wody" — Claude sam wywoła search_documents, ewentualnie doprecyzuje przez list_facets, i odpowie z cytowaniem źródła (dla filmu — z konkretną minutą).

Narzędzia (tools)

Przykładowe zapytania testowe (patrz test/demo-client.js) celowo używają innych słów niż dokumenty źródłowe — np. "zacięta kartka w drukarce" trafia w dokument mówiący o "zacięciu papieru", a "jak zresetować" trafia w dokumenty mówiące o "przywracaniu ustawień fabrycznych". To demonstruje mechanizm opisany w propozycji: dopasowanie działa mimo że słowa się nie pokrywają.

Ważne zastrzeżenie co do jakości wyszukiwania w trybie memory

Wektor semantyczny w src/embeddings.js to uproszczony zamiennik demo (hashed bag-of-words + ręczna normalizacja kilkunastu synonimów domenowych), nie prawdziwy model embeddingowy. Wystarcza, żeby pokazać mechanizm hybrydowego wyszukiwania i to, że synonimy/parafrazy trafiają w wynik — ale nie ma prawdziwego rozumienia znaczenia zdań. W produkcji embed() zamienia się na wywołanie realnego modelu (self-hosted bge-m3/multilingual-e5, albo API OpenAI/Voyage/Cohere) — interfejs (embed(text) -> wektor) zostaje ten sam, zmienia się tylko ta jedna funkcja.

Tryb produkcyjny: prawdziwy Elasticsearch (lokalnie)

docker compose up -d              # startuje ES 8.15 lokalnie
npm run seed:elasticsearch        # tworzy indeks i ładuje data/documents.json
STORE_BACKEND=elasticsearch npm start

src/store/elasticsearchStore.js implementuje dokładnie ten sam kontrakt co memoryStore.js (patrz src/store/interface.js) — serwer MCP przełącza się między nimi zmienną środowiskową STORE_BACKEND, bez zmian w warstwie narzędzi (src/createMcpServer.js). To pokazuje, że warstwa MCP jest niezależna od tego, gdzie faktycznie stoją dane.

Uwaga: zapytanie hybrydowe w elasticsearchStore.js używa rank.rrf, które działa na ES 8.9–8.12. Od 8.13 zalecany jest nowszy DSL retriever — przed wdrożeniem u klienta sprawdź wersję klastra (patrz komentarz w tym pliku).

Wdrożenie na zdalny serwer (Docker, HTTP)

Do lokalnego użycia z Claude Desktop służy src/server.js (transport stdio). Do wdrożenia na serwerze, gdzie ma być dostępny przez sieć, służy src/httpServer.js — te same 5 narzędzi, transport HTTP zamiast stdio, z autoryzacją Bearer-token (MCP_API_KEY).

Pełna instrukcja krok po kroku (kopiowanie na serwer, docker-compose.prod.yml z Elasticsearch + seed + appką, reverse proxy z TLS, podłączenie zdalnego serwera MCP do klienta) jest w DEPLOY.md.

Struktura projektu

mcp-elasticsearch-demo/
  data/documents.json           przykładowe dokumenty (pdf/docx/jpg/mp4)
  src/embeddings.js              uproszczony "embedding" demo + synonimy
  src/store/interface.js         kontrakt wspólny dla obu backendów
  src/store/memoryStore.js       backend w pamięci (domyślny)
  src/store/elasticsearchStore.js backend na prawdziwym ES
  src/createMcpServer.js          rejestracja 5 narzędzi MCP (współdzielona)
  src/storeFactory.js             wybór backendu wg STORE_BACKEND
  src/server.js                   wejście stdio — lokalnie, Claude Desktop
  src/httpServer.js               wejście HTTP — zdalny serwer, patrz DEPLOY.md
  scripts/seed-elasticsearch.js   tworzy indeks + ładuje dane do ES
  docker-compose.yml              lokalny klaster ES (do dev, bez appki)
  docker-compose.prod.yml         pełny stack do wdrożenia (ES + seed + app)
  Dockerfile                      obraz dla src/httpServer.js
  .env.example                    szablon zmiennych (MCP_API_KEY, PORT)
  DEPLOY.md                       instrukcja wdrożenia na serwer
  test/demo-client.js             klient MCP do testu end-to-end
  claude_desktop_config.example.json  jak podłączyć do Claude Desktop (stdio)

Co dalej (poza zakresem tego demo)

• Prawdziwy model embeddingowy zamiast src/embeddings.js.

• Indeksowanie segmentów wideo jako osobnych dokumentów ES (trafność na poziomie minuty filmu, nie całego pliku) — patrz uwaga w elasticsearchStore.js.

• Autoryzacja / filtrowanie wyników wg uprawnień użytkownika po stronie serwera MCP, nie po stronie agenta.

• Warstwa RAG (synteza odpowiedzi z cytowaniami) jako kolejne narzędzie albo prompt MCP — patrz faza 3 w dokumencie technicznym.