Overview

This MCP (Model Context Protocol) server implements a hierarchical Retrieval-Augmented Generation (RAG) service specifically for Vaadin documentation. It combines semantic embeddings, keyword-aware search, and native Pinecone reranking to return concise, context-aware results that respect document structure (sections, subsections, and cross-file links). The server is designed to be used by IDE assistants and other agent-style clients via the MCP transport, enabling fast, framework-aware answers for Vaadin Flow (Java) and Hilla (React) users.

Why it’s useful: documentation queries often need more than a flat search — developers want precise sections, surrounding context, and clear navigation between parent and child sections. This server stores hierarchical metadata alongside embeddings, provides framework filters, and exposes MCP methods for both search and full-document retrieval so assistants can offer breadcrumbed navigation and follow-up exploration.

Features

Hierarchical RAG
- Maintains parent-child relationships for sections and cross-file links
- Returns contextual breadcrumbs and linkable section IDs
Enhanced hybrid search
- Combines semantic similarity with intelligent keyword extraction
- Performs native Pinecone reranking (bge-reranker-v2-m3) for improved relevance
Framework-aware filtering
- Distinguishes Vaadin Flow (Java) vs Hilla (React) content, plus shared/common pages
MCP-compatible API
- Exposes methods designed for IDE assistants (search + full-document retrieval)
- Streamable HTTP transport support for real-time assistants
Production-grade engineering
- TypeScript-first codebase, DI-friendly architecture, and tests
Query preprocessing
- Stopword-filtered keyword extraction and query expansion for better recall

Architecture (packages)

Package	Purpose
packages/core-types	Shared TypeScript interfaces (DocumentChunk, RetrievalResult, Framework)
packages/1-asciidoc-converter	Convert Vaadin AsciiDoc → Markdown with metadata and framework detection
packages/2-embedding-generator	Chunk Markdown hierarchically and generate OpenAI embeddings; populate Pinecone
packages/mcp-server	MCP server exposing search and navigation endpoints with hierarchical semantics

Installation / Configuration

Prerequisites:

Bun runtime (tested with v1.3.6)
OpenAI API key (embeddings)
Pinecone API key and index

Clone and install:

git clone https://github.com/marcushellberg/vaadin-documentation-services.git
cd vaadin-documentation-services
bun install

Environment variables (.env):

# .env
OPENAI_API_KEY=your_openai_api_key
PINECONE_API_KEY=your_pinecone_api_key
PINECONE_INDEX=your_pinecone_index
PINECONE_ENV=your_pinecone_env # if required by your Pinecone setup

One-time documentation processing:

# Convert AsciiDoc to Markdown + metadata
cd packages/1-asciidoc-converter
bun run convert

# Generate embeddings, chunk hierarchically and upsert to Pinecone
cd ../2-embedding-generator
bun run generate

Start the MCP server:

cd packages/mcp-server
bun run start

Available Resources

GitHub repository: https://github.com/marcushellberg/vaadin-documentation-services
Vector DB: Pinecone (bge-reranker-v2-m3 used for reranking)
Embeddings: OpenAI embeddings (configurable)

MCP client usage (example transport setup):

import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(new URL("https://your-mcp-server.example/"));
// Use your MCP client tooling to call methods over this transport

API (common MCP methods)

Method	Purpose	Input (typical)	Output
search_vaadin_docs	Find relevant sections for a query	{ query: string, framework?: “flow”	“hilla”
get_full_document	Retrieve full document or section with parents & children	{ documentId: string }	Full Markdown or structured document with hierarchical links

Example search request body (JSON):

{
  "query": "how to bind a Grid column in Flow",
  "framework": "flow",
  "maxResults": 5
}

Use Cases

IDE assistant contextual help: An IDE plugin calls search_vaadin_docs for the current cursor context and shows the most relevant section, plus a breadcrumb and link to the parent topic.
Documentation site search augmentation: Use the server to power a “smart search” UI that returns section-level answers and suggested broader topics.
Developer onboarding and migration: Filtered searches (Flow vs Hilla) let engineers quickly find framework-specific guidance and compare approaches across Vaadin flavors.

Practical tips

Tune chunk size and hierarchy preservation in the embedding generator to balance answer granularity vs context length.
Use framework filtering for more precise results when the user’s project framework is known.
Leverage parent/child navigation: start with narrow results, then use the returned parent links to expand context or retrieve full documents.

If you want to explore the code or contribute, see the repository above for implementation details, tests, and project plan documentation.

Vaadin RAG MCP Server for Hierarchical Documentation