AI agent tools

The mcp module exposes the translation system as a set of tools an AI agent can call through the Model Context Protocol (MCP). An agent can use these tools to inspect an asset's translation state and translate it, either by directing an installed translation service or by producing the translated text itself.

Dependencies

This module depends on the core translation module and on com.brightspot.ai:ai, which provides the underlying MCP tool framework.

Installation

Add the mcp dependency to your build:

Maven

<!-- Requires Brightspot 5.0 or later. -->
<dependency>
    <groupId>com.brightspot.translation</groupId>
    <artifactId>mcp</artifactId>
    <version>2.0.0</version>
</dependency>

Gradle

// Requires Brightspot 5.0 or later.
implementation 'com.brightspot.translation:mcp:2.0.0'

Gradle (Kotlin DSL)

// Requires Brightspot 5.0 or later.
implementation("com.brightspot.translation:mcp:2.0.0")

note

This module requires Java 21 or later.

Translation tool group

The TranslationToolGroup registers the following tools, each prefixed with Translation_:

Tool	Description
Translation_listServices	Lists the external translation providers installed on the deployment.
Translation_listLocales	Lists locales available for translation, optionally scoped to a service.
Translation_inspectContent	Returns a content item's source locale, translatable fields, and existing localized variations.
Translation_getTranslatableText	Returns a content item's source text, keyed by field path, for the agent to translate itself.
Translation_translate	Translates a content item into one or more locales using an installed translation service.
Translation_applyTranslation	Writes agent-produced translations back to a content item as a new localized variation.
Translation_status	Returns the translation log entries for a source content item.

Provider path vs. agent path

An agent can translate content two ways:

• Provider path — Translation_translate hands the content to a configured translation service (for example, Amazon Translate, DeepL, or Google Translate), which performs the translation. This applies when Translation_listServices returns at least one provider.
• Agent path — Translation_getTranslatableText returns the source text, the agent translates it, and Translation_applyTranslation writes the result back as a new localized variation. This applies when no provider is installed, or whenever the agent is asked to translate the content directly.

Fields translated through the agent path are flagged as AI-generated in the content's field metadata.

Permissions

The translation tools enforce the same permissions as the CMS translation UI:

Tool	Required permission
Translation_listServices, Translation_listLocales, Translation_inspectContent, Translation_getTranslatableText, Translation_translate, Translation_applyTranslation	Translate Content
Translation_status	Translation Action - View Translation Log

See Configuring translation permissions to grant these to a role.