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.

4

Is it true that it is integrated in some ai tools already, like Cursor? How do I even find out if a tool uses MCP servers?

5

@marcushellberg Should the MCP Server still work? Claud is getting an error

image
image1450×580 33.3 KB

6

It should still work. Let me take a look at what’s going on. Thanks for reporting!

Edit: looks like fly.io has decided to scale the server down to 0 and not spin it up again when a request comes in. Helpful :man_facepalming:

7

But it saves energy…

8

Indeed…

It should now be up and running, but the results aren’t yet as good as I’d like as it’s using a quite plain RAG implementation. I should find time to improve that.

9

Hello world!

I have made some significant updates to the Vaadin Documentation services:

Improved search accuracy:

  • Improved chunking
  • Hybrid semantic + keyword retrieval with reranking

New tools:

  • Fetch a full documentation page (useful for agents to get more context around a snippet)
  • Get latest Vaadin version
  • Vaadin primer document tool that gives agents up-to-date information about Vaadin in the hopes of keeping agents from writing code for older Vaadin versions.

Breaking change in the REST API: the query parameter was renamed question.

Please give it a try with the latest version

{
    "mcpServers": {
        "vaadin": {
            "command": "npx",
            "args": [
                "-y",
                "vaadin-docs-mcp-server@0.7.2"
            ]
        }
    }
}
1 Like
10

Super cool! Thank you very much

11

If you use Claude Code:

claude mcp add vaadin -- npx -y vaadin-docs-mcp-server@0.7.2

2 Likes
12

Thanks! The primer doc is an experiment to see if it could help LLMs better grasp modern Vaadin development vs rely on random Vaadin 8-14 stuff it has found online. It seems to have a positive impact, but the actual file content needs some curation - right now it’s quickly put together with an LLM from our docs with minor edits. Not sure how prescriptive it should be either. Interested to hear your experiences trying it.

1 Like
13

I get this problem when adding your MCP server to Claude Code: Anthropic API Validation Error: Invalid Tool Input Schema with OneOf/AllOf · Issue #4753 · anthropics/claude-code · GitHub

14

Sounds like you’re a perfect candidate for testing the new HTTP transport ;)

claude mcp add --transport http VaadinMCP https://vaadin-mcp.fly.dev/mcp
2 Likes
15

Works! Thank you. This is the much better option IMO

16

Yes. It was what I originally wanted but back then anything besides the stdio transport was mostly just a vague idea. Going forward, I’m only focusing on the HTTP one. It’s also much more convenient to hook up to Java apps as you don’t need a node process just to proxy calls to a REST server.

17

I’ll go ahead and create an MCP server for jOOQ.
Thanks for the inspiration

18

Great idea!

If their docs are in simpler markdown format (doesn’t require pre-processing like ours), it’s likely that using Context7 will already give you most of the benefits Context7 - Up-to-date documentation for LLMs and AI code editors

19

The jOOQ documentation is not on GitHub.
Contex7 doesn’t help here

1 Like
20

The jOOQ MCP server is live :partying_face:

If you use Claude Code, you can add it with this command:

claude mcp add --transport sse jOOQ https://jooq-mcp.fly.dev/sse

If you can’t use SSE transport directly, you can use it with mcp remote:

{
  "mcpServers":
  {
    "jOOQ": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://jooq-mcp.fly.dev/sse",
        "--transport sse-only"
      ]
    }
  }
1 Like