MCP tools for personalized phrases

Phrases supply segment-specific text in supported RightMessage-rendered content, including widget questions, forms, offers, and campaign content replacements. A reference such as {{ phrases.phr_example }} uses the plural phrases. Adding that text to arbitrary website HTML does not make RightMessage scan and render the page as a Liquid template.

MCP phrase access and fallbacks

Every operation accepts an optional string project_id and follows the shared MCP authorization and project-selection rules. An invalid ID, missing project, inaccessible project, or disabled MCP access returns an MCP error.

Reads use the draft configuration when available, otherwise the published configuration. Create, update, and delete save a draft, record a pre-change snapshot when the configuration has changed, and notify dashboard editors. They do not publish. Publication tools control the live-site boundary.

At runtime, the phrase uses a mapped segment from its linked group, or its fallback when no mapped segment matches. A null or empty-string mapped value also falls back to fallbackText; it is not an intentional blank replacement. For a multi-select group, do not assume the map's property order establishes priority.

The examples below are illustrative and were not executed. Requests show the name and arguments passed to MCP tools/call. Responses show the decoded JSON payload rather than the MCP content envelope.

list-phrases

Returns every phrase in the current configuration. There is no pagination or filtering.

The response is an array. Each phrase has id, fallbackText, nullable segmentGroupId, and map, an object keyed by segment ID. Read responses can add _name companion fields for recognized resource IDs. No phrases returns [].

{"name":"list-phrases","arguments":{"project_id":"123456789"}}

[{"id":"phr_example","fallbackText":"Welcome to WorkForge","segmentGroupId":null,"map":{}}]

This operation does not change the configuration.

get-phrase

Returns one phrase, with the same fields and name enrichment as list-phrases.

{"name":"get-phrase","arguments":{"project_id":"123456789","phrase_id":"phr_example"}}

{"id":"phr_example","fallbackText":"Welcome to WorkForge","segmentGroupId":null,"map":{}}

Missing input returns phrase_id is required. An unknown phrase returns Phrase not found: phr_example. This is a read, not a publication check.

create-phrase

Adds a phrase to the draft.

The tool accepts an open map object. Use segment-ID keys and string values, such as {"seg_example":"Text for this segment"}, not an array of conditions. Saving does not fully validate the map or prove that the supplied dimension and segment IDs exist. Read the segment group before saving.

{"name":"create-phrase","arguments":{"project_id":"123456789","fallback_text":"Welcome to WorkForge","segment_group_id":"dim_example","map":{"seg_agency":"WorkForge for your agency"}}}

{"id":"phr_example","fallbackText":"Welcome to WorkForge","segmentGroupId":"dim_example","map":{"seg_agency":"WorkForge for your agency"}}

The response uses stored camelCase keys, not the request's snake_case keys. It does not include the read tools' name enrichment. Validation failures return Validation error: ...; other failures return Operation failed: ....

update-phrase

Changes supplied phrase fields. Omitted fields stay unchanged. Map entries merge by segment ID rather than replacing the complete map.

At least one editable field must be supplied. Top-level null values are treated as omitted, so segment_group_id: null does not clear the dimension.

The tool description advertises null for removing a map entry. The save path merges that key with a null value rather than deleting the key; the runtime then uses fallback text for that value. An empty map: {} does not clear existing entries either. Do not assume either request removes keys from a subsequent read.

{"name":"update-phrase","arguments":{"project_id":"123456789","phrase_id":"phr_example","map":{"seg_agency":"Plan your agency work with WorkForge"}}}

{"id":"phr_example","fallbackText":"Welcome to WorkForge","segmentGroupId":"dim_example","map":{"seg_agency":"Plan your agency work with WorkForge"}}

Updating can overwrite existing text. It is a destructive, idempotent draft operation. Missing input returns phrase_id is required. Empty updates return No fields provided to update. A missing phrase returns Operation failed: Phrase not found: ....

delete-phrase

Removes one phrase from the draft. It does not rewrite text fields that reference the phrase's ID.

{"name":"delete-phrase","arguments":{"project_id":"123456789","phrase_id":"phr_example"}}

{"deleted":true,"phrase_id":"phr_example"}

This is destructive. References and the intended replacement need review before publication. Missing input returns phrase_id is required. An unknown phrase returns Operation failed: Phrase not found: .... Configuration validation can also reject the save. The published site remains unchanged until publication.