Mcp intro (#4711)

* Add configuration guides for Vaadin MCP server integration with popular AI tools: Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, Junie, Windsurf, and others.

* Add configuration guides for Vaadin MCP server integration with popular AI tools: Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, Junie, Windsurf, and others.

* Add JetBrains IDE support for GitHub Copilot with Vaadin MCP server

* fix: add documentation for using chartoptions to set language translations (#4691)

* fix: add documentation for using chartoptions to set language translations for charts

* fix: update language according to suggestion

Co-authored-by: Rolf Smeds <[email protected]>

* fix: update language according to suggestion

Co-authored-by: Rolf Smeds <[email protected]>

---------

Co-authored-by: Rolf Smeds <[email protected]>

* Add configuration guides for Vaadin MCP server integration with popular AI tools: Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, Junie, Windsurf, and others.

* Add JetBrains IDE support for GitHub Copilot with Vaadin MCP server

* Expand AI vocabulary and refine MCP documentation.

* Add "Streamable" to accept list and fix broken formatted links in MCP documentation

* Update hyperlink in Vaadin documentation reference

* Simplify wording, fix capitalization, and standardize phrasing across MCP-related documentation.

* Refine phrasing in MCP tool guides for clarity and consistency; add SSE abbreviation.

---------

Co-authored-by: sujoykd <[email protected]>
Co-authored-by: Rolf Smeds <[email protected]>

Author: 3 people

.github/styles/Vaadin/Abbr.yml

@@ -66,6 +66,7 @@ exceptions:
   - JVM
   - JWT
   - LLM
+  - MCP
   - MDN
   - MFA
   - MIME
@@ -93,13 +94,15 @@ exceptions:
   - SPA
   - SPI
   - SQL
+  - SSE
   - SSH
   - SSL
   - SSO
   - SVG
   - TCP
   - TEST
   - TLS
+  - TOML
   - TSX
   - TXT
   - REST

.github/styles/config/vocabularies/Docs/accept.txt

@@ -1,7 +1,9 @@
 [aA]ccessors?
 [aA]ddon
 [aA]ffordance
+[aA]gentic
 allowlist
+Anthropic
 [aA]ntialias
 [aA]ppender
 [aA]utosave
@@ -25,6 +27,7 @@ bun
 [cC]acheable
 [cC]hatbot
 classpath
+Codeium
 [cC]onfig(|uration|ure|urer|urator|map)
 [cC]onformant
 [cC]ontainer-less
@@ -101,6 +104,7 @@ JServ
 jsoup
 jQuery
 JSpecify
+Junie
 JUnit
 Karaf
 Keycloak
@@ -188,6 +192,7 @@ Spring Initializr
 [sS]ubcomponents?
 [sS]uperset
 [sS]upertype
+[sS]treamable
 [sS]tylable
 [tT]ablespace(s)?
 Telepresence

articles/building-apps/mcp/index.adoc

@@ -0,0 +1,74 @@
+---
+title: MCP Server
+page-title: Model Context Protocol Server for Vaadin
+description: Learn how to integrate AI assistants with Vaadin documentation using the Model Context Protocol.
+meta-description: Search Vaadin documentation, get the full documentation, and get version information. Designed for AI agents.
+order: 70
+---
+= Model Context Protocol (MCP)
+
+The Model Context Protocol (MCP) is an open standard that enables AI assistants to securely integrate with external data sources and tools. Vaadin provides an MCP server that gives AI assistants direct access to comprehensive Vaadin documentation.
+
+== What Is MCP?
+
+Model Context Protocol allows AI development tools like Claude Code, Cursor, GitHub Copilot, and others to access structured information from external sources. This enables AI assistants to provide accurate, context-aware responses based on current Vaadin documentation.
+
+The Vaadin MCP server provides:
+
+* Semantic search across Vaadin documentation
+* Full document retrieval for complete context
+* Component version information and API references
+* Component-specific API documentation (Java, React, Web Components)
+* Component styling and theming information
+* Support for both Java and React applications
+* Current Vaadin version information
+* Vaadin development primer with best practices
+
+== Getting Started
+
+To use the Vaadin MCP server with your AI development tool, follow these steps:
+
+. Choose your AI development tool from the <<{articles}/building-apps/mcp/supported-tools/# ,supported tools list>>
+. Follow the configuration instructions for your specific tool
+. Restart your tool to load the MCP server
+. Start asking questions about Vaadin development
+
+The MCP server automatically provides your AI assistant with access to up-to-date Vaadin documentation.
+
+== Supported Tools
+
+The Vaadin MCP server is compatible with various AI development tools. Each tool has different configuration requirements and transport support.
+
+See the <<{articles}/building-apps/mcp/supported-tools/# ,MCP Setup Guide>> for detailed configuration instructions for:
+
+* <<supported-tools/claude-code# ,Claude Code>>
+* <<supported-tools/cursor# ,Cursor>>
+* <<supported-tools/windsurf# ,Windsurf>>
+* <<supported-tools/junie# ,Junie (JetBrains)>>
+* <<supported-tools/github-copilot# ,GitHub Copilot (VS Code & JetBrains IDEs)>>
+* <<supported-tools/codex# ,Codex (OpenAI)>>
+* <<supported-tools/gemini-cli# ,Gemini CLI (Google)>>
+* <<supported-tools/other-tools# ,Other MCP-compatible clients>>
+
+== Transport Types
+
+[IMPORTANT]
+====
+The Vaadin MCP server uses *HTTP transport (streamable-http)*. This is natively supported by Claude Code, Cursor, Windsurf, GitHub Copilot (VS Code and JetBrains IDEs), Codex, and Gemini CLI.
+
+For stdio-only tools like Junie, you can use https://github.com/pyroprompts/mcp-stdio-to-streamable-http-adapter[@pyroprompts/mcp-stdio-to-streamable-http-adapter] as a bridge between the two transport types.
+====
+
+== Resources
+
+=== GitHub Repository
+
+View source code, report issues, and contribute to the project.
+
+https://github.com/vaadin/vaadin-mcp
+
+=== Model Context Protocol
+
+Learn more about the Model Context Protocol standard.
+
+https://modelcontextprotocol.io

articles/building-apps/mcp/supported-tools/claude-code.adoc

@@ -0,0 +1,51 @@
+---
+title: Claude Code
+page-title: Configure Claude Code to Use Vaadin MCP Server
+description: Learn how to configure Claude Code to access Vaadin documentation through the Model Context Protocol server
+meta-description: Setup instructions for connecting Claude Code to the Vaadin MCP server. Enable your AI assistant with comprehensive Vaadin documentation access.
+order: 10
+---
+
+
+= Claude Code
+
+Claude Code is Anthropic's official CLI tool for agentic coding. It provides native support for HTTP-based MCP servers, making it straightforward to connect to the Vaadin MCP server.
+
+*Requirements:* Claude Code 0.4.0 or later
+
+== Configuration
+
+Add the following to your `~/.config/claude/claude_desktop_config.json`:
+
+[source,json]
+----
+{
+  "mcpServers": {
+    "vaadin": {
+      "url": "https://mcp.vaadin.com/docs"
+    }
+  }
+}
+----
+
+After configuration, restart Claude Code to load the MCP server.
+
+[TIP]
+====
+You can add multiple MCP servers to the configuration file. Each server should have a unique name in the `mcpServers` object.
+====
+
+== Verify the Setup
+
+After restarting Claude Code:
+
+. Start a new conversation
+. Ask a question about Vaadin development (e.g., "How to create a Button in Vaadin?")
+. Claude Code automatically uses the Vaadin MCP server to fetch relevant documentation
+
+You can verify that the MCP server is connected by checking the status indicators in Claude Code's interface.
+
+== Resources
+
+* https://docs.claude.ai/docs/build-with-claude/claude-code[Claude Code Documentation]
+* https://github.com/vaadin/vaadin-mcp[Vaadin MCP Server Repository]

articles/building-apps/mcp/supported-tools/codex.adoc

@@ -0,0 +1,76 @@
+---
+title: Codex
+page-title: Configure OpenAI Codex to Use Vaadin MCP Server
+description: Learn how to configure OpenAI Codex to access Vaadin documentation through the Model Context Protocol server
+meta-description: Setup instructions for connecting OpenAI Codex to the Vaadin MCP server. Enable AI code generation with Vaadin documentation access.
+order: 60
+---
+
+
+= Codex
+
+OpenAI Codex provides native support for HTTP-based MCP servers, making it straightforward to integrate with the Vaadin MCP server for enhanced code generation capabilities.
+
+*Requirements:* Codex CLI version 0.43 or later
+
+== Configuration
+
+Add the following to `~/.codex/config.toml`:
+
+[source,toml]
+----
+[mcp_servers.vaadin]
+url = "https://mcp.vaadin.com/docs"
+----
+
+After configuration, restart Codex to load the new MCP server.
+
+[NOTE]
+====
+If you see "missing field command" errors, upgrade Codex with:
+[source,bash]
+----
+npm install -g @openai/codex@latest
+----
+====
+
+== Configuration File Format
+
+The Codex configuration uses TOML format:
+
+* Each MCP server is defined under `[mcp_servers.name]`
+* The `url` field points to the HTTP endpoint
+* Multiple servers can be configured by adding additional sections
+
+Example with multiple servers:
+
+[source,toml]
+----
+[mcp_servers.vaadin]
+url = "https://mcp.vaadin.com/docs"
+
+[mcp_servers.other_server]
+url = "https://example.com/mcp"
+----
+
+== Verify the Setup
+
+After restarting Codex:
+
+. Start a new coding session
+. Ask Codex about Vaadin development (e.g., "Generate a Vaadin login form")
+. Codex queries the Vaadin MCP server to access relevant documentation
+. Generated code is based on current Vaadin best practices
+
+You can verify active MCP servers by running:
+
+[source,bash]
+----
+codex config list
+----
+
+== Resources
+
+* https://developers.openai.com/codex/mcp/[Codex MCP Documentation]
+* https://github.com/openai/codex[Codex GitHub Repository]
+* https://github.com/vaadin/vaadin-mcp[Vaadin MCP Server Repository]

articles/building-apps/mcp/supported-tools/cursor.adoc

@@ -0,0 +1,54 @@
+---
+title: Cursor
+page-title: Configure Cursor to Use Vaadin MCP Server
+description: Learn how to configure Cursor editor to access Vaadin documentation through the Model Context Protocol server
+meta-description: Setup instructions for connecting Cursor to the Vaadin MCP server. Enable AI-powered coding with comprehensive Vaadin documentation access.
+order: 20
+---
+
+
+= Cursor
+
+Cursor is an AI-powered code editor with native HTTP MCP support, making it easy to integrate with the Vaadin MCP server for enhanced documentation access.
+
+== Configuration
+
+. Open Cursor Settings
+. Navigate to *Features* → *Beta* → *Model Context Protocol*
+. Enable MCP support
+. Add the server configuration to `~/.cursor/mcp.json`:
+
+[source,json]
+----
+{
+  "mcpServers": {
+    "vaadin": {
+      "url": "https://mcp.vaadin.com/docs"
+    }
+  }
+}
+----
+
+After adding the configuration, restart Cursor to load the MCP server.
+
+[NOTE]
+====
+The MCP configuration file location may vary depending on your operating system:
+
+* *macOS:* `~/.cursor/mcp.json`
+* *Linux:* `~/.cursor/mcp.json`
+* *Windows:* `%USERPROFILE%\.cursor\mcp.json`
+====
+
+== Verify the Setup
+
+After restarting Cursor:
+
+. Open the AI chat panel
+. Ask a question about Vaadin development (e.g., "Show how to create a form in Vaadin")
+. Cursor automatically queries the Vaadin MCP server for relevant documentation
+
+== Resources
+
+* https://docs.cursor.com/context/model-context-protocol[Cursor MCP Documentation]
+* https://github.com/vaadin/vaadin-mcp[Vaadin MCP Server Repository]

articles/building-apps/mcp/supported-tools/gemini-cli.adoc

@@ -0,0 +1,70 @@
+---
+title: Gemini CLI
+page-title: Configure Google Gemini CLI to Use Vaadin MCP Server
+description: Learn how to configure Google Gemini CLI to access Vaadin documentation through the Model Context Protocol server
+meta-description: Setup instructions for connecting Google Gemini CLI to the Vaadin MCP server. Enable Gemini AI with comprehensive Vaadin documentation access.
+order: 70
+---
+
+
+= Gemini CLI
+
+Google Gemini CLI provides native HTTP MCP support, allowing direct integration with the Vaadin MCP server for enhanced AI-assisted development.
+
+== Configuration
+
+Add the following to `~/.gemini/settings.json`:
+
+[source,json]
+----
+{
+  "mcpServers": {
+    "vaadin": {
+      "httpUrl": "https://mcp.vaadin.com/docs"
+    }
+  }
+}
+----
+
+After configuration, restart Gemini CLI to load the MCP server.
+
+[NOTE]
+====
+Gemini CLI automatically invokes Vaadin tools when you ask questions about Vaadin development (e.g., "What is a TestBench UI unit test?").
+====
+
+== Configuration File Location
+
+The configuration file location varies by operating system:
+
+* *macOS:* `~/.gemini/settings.json`
+* *Linux:* `~/.gemini/settings.json`
+* *Windows:* `%USERPROFILE%\.gemini\settings.json`
+
+If the directory doesn't exist, create it before adding the configuration file.
+
+== Automatic Tool Invocation
+
+Gemini CLI features intelligent tool selection:
+
+* When you ask Vaadin-related questions, it automatically queries the Vaadin MCP server
+* No manual tool invocation required
+* The assistant determines when documentation lookup would be helpful
+* Responses are grounded in current Vaadin documentation
+
+== Verify the Setup
+
+After restarting Gemini CLI:
+
+. Start a new conversation
+. Ask a Vaadin-specific question (e.g., "How to implement data binding in Vaadin?")
+. Observe the tool invocation in the response
+. Gemini fetches relevant documentation from the Vaadin MCP server
+
+You can also explicitly request documentation by asking "What does the Vaadin documentation say about...?"
+
+== Resources
+
+* https://github.com/google-gemini/gemini-cli[Gemini CLI GitHub Repository]
+* https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md[Gemini CLI MCP Documentation]
+* https://github.com/vaadin/vaadin-mcp[Vaadin MCP Server Repository]