Vaadin Documentation as a Service

General
1

I’ve been working on a way to make our documentation more available to AI assistants and other programmatic uses. I’m happy to present an early development preview of my Vaadin Documentation Service: GitHub - marcushellberg/vaadin-documentation-services: A complete solution for ingesting, indexing, and retrieving Vaadin documentation through semantic search.

It consists of 3 parts:

  1. An ingestion pipeline that creates vector embeddings for selected Vaadin docs
  2. A REST API for searching relevant documentation for a given question
  3. An MCP server that allows any supporting client to search relevant Vaadin documentation as part of their workflow

Usage

REST API

POST https://vaadin-docs-search.fly.dev/search
Content-Type: application/json

{
    "query": "How should I structure a Vaadin project?",
    "max_results": 3
}

MCP server config

{
    "mcpServers": {
        "vaadin": {
            "command": "npx",
            "args": [
                "-y",
                "vaadin-docs-mcp-server@latest"
            ]
        }
    }
}

I’m actively developing it, so expect breaking changes and service disruptions. That said, I’d love to hear your thoughts and feedback!

4 Likes
2

I added a new /ask endpoint to the REST server based on @Artur’s suggestion. It will internally query docs and return an AI generated answer that’s suitable for end users.

POST https://vaadin-docs-search.fly.dev/ask
Content-Type: application/json

{
    "question": "What's the Hilla route directory structure?"
}
3

You can now also add an optional "framework": "flow" | "hilla" to the /ask and /search endpoints to restrict the returned values to one framework. Omitting the value returns results for both frameworks.

The latest (0.2.0) version of the MCP server uses the framework parameter and instructs the using agent to figure out a correct value for it based on context.