Skip to content

Commit f19625e

Browse files
sigvardtsigvardt
authored
feat #182: add MCP tools for Bloomreach Recommendations feature (#194)
Register 5 new MCP tools that expose the existing BloomreachRecommendationsService to MCP clients: - bloomreach.recommendations.list - bloomreach.recommendations.view_performance - bloomreach.recommendations.prepare_create - bloomreach.recommendations.prepare_configure - bloomreach.recommendations.prepare_delete Update tool constant exports, BLOOMREACH_MCP_TOOL_NAMES array, and toolConstants test expectations (262→267 tools, 34→35 domains).
1 parent 741a5a7 commit f19625e

File tree

3 files changed

+188
-4
lines changed

3 files changed

+188
-4
lines changed

‎packages/mcp/src/__tests__/toolConstants.test.ts‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,8 @@ import { describe, it, expect } from 'vitest';
22
import { BLOOMREACH_MCP_TOOL_NAMES } from '../index.js';
33

44
describe('tool constants', () => {
5-
it('exports 262 tool name constants via BLOOMREACH_MCP_TOOL_NAMES', () => {
6-
expect(BLOOMREACH_MCP_TOOL_NAMES).toHaveLength(262);
5+
it('exports 267 tool name constants via BLOOMREACH_MCP_TOOL_NAMES', () => {
6+
expect(BLOOMREACH_MCP_TOOL_NAMES).toHaveLength(267);
77
});
88

99
it('all tool names follow bloomreach.<domain>.<action> dot-notation', () => {
@@ -46,7 +46,7 @@ describe('tool constants', () => {
4646
}
4747
});
4848

49-
it('covers all 34 expected service domains', () => {
49+
it('covers all 35 expected service domains', () => {
5050
const domains = new Set(BLOOMREACH_MCP_TOOL_NAMES.map((name) => name.split('.')[1]));
5151
const expectedDomains = [
5252
'actions',
@@ -70,6 +70,7 @@ describe('tool constants', () => {
7070
'metrics',
7171
'performance',
7272
'project_settings',
73+
'recommendations',
7374
'reports',
7475
'retentions',
7576
'scenarios',

‎packages/mcp/src/bin/bloomreach-mcp.ts‎

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6118,6 +6118,174 @@ const tools: ToolRoute[] = [
61186118
serviceClass: 'BloomreachTrackingService',
61196119
methodName: 'prepareTrackCampaign',
61206120
},
6121+
{
6122+
name: toolNames.BLOOMREACH_RECOMMENDATIONS_LIST_TOOL,
6123+
description:
6124+
'List recommendation models in the project, optionally filtered by status. Returns model metadata including name, status, algorithm, and URL. ⚠️ Not yet available — coming in a future release.',
6125+
inputSchema: {
6126+
type: 'object',
6127+
properties: {
6128+
project: {
6129+
type: 'string',
6130+
description:
6131+
'Bloomreach project identifier. Defaults to BLOOMREACH_PROJECT when omitted.',
6132+
},
6133+
status: {
6134+
type: 'string',
6135+
description:
6136+
'Filter by model status: active, inactive, training, or draft.',
6137+
},
6138+
},
6139+
required: ['project'],
6140+
additionalProperties: true,
6141+
},
6142+
serviceClass: 'BloomreachRecommendationsService',
6143+
methodName: 'listRecommendationModels',
6144+
},
6145+
{
6146+
name: toolNames.BLOOMREACH_RECOMMENDATIONS_VIEW_PERFORMANCE_TOOL,
6147+
description:
6148+
'View performance metrics of a recommendation model including impressions, clicks, CTR, conversions, revenue, and average order value. ⚠️ Not yet available — coming in a future release.',
6149+
inputSchema: {
6150+
type: 'object',
6151+
properties: {
6152+
project: {
6153+
type: 'string',
6154+
description:
6155+
'Bloomreach project identifier. Defaults to BLOOMREACH_PROJECT when omitted.',
6156+
},
6157+
modelId: {
6158+
type: 'string',
6159+
description:
6160+
'ID of the recommendation model. Use bloomreach.recommendations.list to find available IDs.',
6161+
},
6162+
},
6163+
required: ['project', 'modelId'],
6164+
additionalProperties: true,
6165+
},
6166+
serviceClass: 'BloomreachRecommendationsService',
6167+
methodName: 'viewModelPerformance',
6168+
},
6169+
{
6170+
name: toolNames.BLOOMREACH_RECOMMENDATIONS_PREPARE_CREATE_TOOL,
6171+
description:
6172+
'Create a new recommendation model. Returns a confirmToken — call bloomreach.actions.confirm to execute.',
6173+
inputSchema: {
6174+
type: 'object',
6175+
properties: {
6176+
project: {
6177+
type: 'string',
6178+
description:
6179+
'Bloomreach project identifier. Defaults to BLOOMREACH_PROJECT when omitted.',
6180+
},
6181+
name: {
6182+
type: 'string',
6183+
description: 'Display name for the recommendation model (1–200 characters).',
6184+
},
6185+
modelType: {
6186+
type: 'string',
6187+
description:
6188+
'Type of recommendation model (e.g. product_recommendations, category_recommendations).',
6189+
},
6190+
algorithm: {
6191+
type: 'string',
6192+
description:
6193+
'Recommendation algorithm: collaborative_filtering, content_based, hybrid, trending, or personalized.',
6194+
},
6195+
catalogId: {
6196+
type: 'string',
6197+
description: 'Catalog ID to use for recommendations.',
6198+
},
6199+
operatorNote: {
6200+
type: 'string',
6201+
description: 'Optional note describing the reason for this action.',
6202+
},
6203+
},
6204+
required: ['project', 'name', 'modelType'],
6205+
additionalProperties: true,
6206+
},
6207+
serviceClass: 'BloomreachRecommendationsService',
6208+
methodName: 'prepareCreateRecommendationModel',
6209+
},
6210+
{
6211+
name: toolNames.BLOOMREACH_RECOMMENDATIONS_PREPARE_CONFIGURE_TOOL,
6212+
description:
6213+
'Configure parameters of an existing recommendation model (algorithm, filters, boost rules, max items). Returns a confirmToken — call bloomreach.actions.confirm to execute.',
6214+
inputSchema: {
6215+
type: 'object',
6216+
properties: {
6217+
project: {
6218+
type: 'string',
6219+
description:
6220+
'Bloomreach project identifier. Defaults to BLOOMREACH_PROJECT when omitted.',
6221+
},
6222+
modelId: {
6223+
type: 'string',
6224+
description:
6225+
'ID of the recommendation model. Use bloomreach.recommendations.list to find available IDs.',
6226+
},
6227+
algorithm: {
6228+
type: 'string',
6229+
description:
6230+
'Recommendation algorithm: collaborative_filtering, content_based, hybrid, trending, or personalized.',
6231+
},
6232+
catalogId: {
6233+
type: 'string',
6234+
description: 'Catalog ID to use for recommendations.',
6235+
},
6236+
filters: {
6237+
type: 'array',
6238+
description:
6239+
'Filter rules to restrict recommended items. Each rule has field, operator, and value.',
6240+
},
6241+
boostRules: {
6242+
type: 'array',
6243+
description:
6244+
'Boost rules to prioritize certain items. Each rule has field and weight (0–100).',
6245+
},
6246+
maxItems: {
6247+
type: 'number',
6248+
description: 'Maximum number of items to recommend (1–100).',
6249+
},
6250+
operatorNote: {
6251+
type: 'string',
6252+
description: 'Optional note describing the reason for this action.',
6253+
},
6254+
},
6255+
required: ['project', 'modelId'],
6256+
additionalProperties: true,
6257+
},
6258+
serviceClass: 'BloomreachRecommendationsService',
6259+
methodName: 'prepareConfigureRecommendationModel',
6260+
},
6261+
{
6262+
name: toolNames.BLOOMREACH_RECOMMENDATIONS_PREPARE_DELETE_TOOL,
6263+
description:
6264+
'Delete a recommendation model. Returns a confirmToken — call bloomreach.actions.confirm to execute.',
6265+
inputSchema: {
6266+
type: 'object',
6267+
properties: {
6268+
project: {
6269+
type: 'string',
6270+
description:
6271+
'Bloomreach project identifier. Defaults to BLOOMREACH_PROJECT when omitted.',
6272+
},
6273+
modelId: {
6274+
type: 'string',
6275+
description:
6276+
'ID of the recommendation model. Use bloomreach.recommendations.list to find available IDs.',
6277+
},
6278+
operatorNote: {
6279+
type: 'string',
6280+
description: 'Optional note describing the reason for this action.',
6281+
},
6282+
},
6283+
required: ['project', 'modelId'],
6284+
additionalProperties: true,
6285+
},
6286+
serviceClass: 'BloomreachRecommendationsService',
6287+
methodName: 'prepareDeleteRecommendationModel',
6288+
},
61216289
];
61226290

61236291
const toolByName = new Map<string, ToolRoute>(tools.map((tool) => [tool.name, tool]));

‎packages/mcp/src/index.ts‎

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -360,6 +360,17 @@ export const BLOOMREACH_ACCESS_PREPARE_DELETE_API_KEY_TOOL =
360360
export const BLOOMREACH_ACTIONS_CONFIRM_TOOL = 'bloomreach.actions.confirm';
361361
export const BLOOMREACH_ACTIONS_LIST_TOOL = 'bloomreach.actions.list';
362362

363+
// --- Recommendations tools (issue #182) ---
364+
export const BLOOMREACH_RECOMMENDATIONS_LIST_TOOL = 'bloomreach.recommendations.list';
365+
export const BLOOMREACH_RECOMMENDATIONS_VIEW_PERFORMANCE_TOOL =
366+
'bloomreach.recommendations.view_performance';
367+
export const BLOOMREACH_RECOMMENDATIONS_PREPARE_CREATE_TOOL =
368+
'bloomreach.recommendations.prepare_create';
369+
export const BLOOMREACH_RECOMMENDATIONS_PREPARE_CONFIGURE_TOOL =
370+
'bloomreach.recommendations.prepare_configure';
371+
export const BLOOMREACH_RECOMMENDATIONS_PREPARE_DELETE_TOOL =
372+
'bloomreach.recommendations.prepare_delete';
373+
363374

364375
// --- Tracking tools (issue #177) ---
365376
export const BLOOMREACH_TRACKING_TRACK_EVENT_TOOL = 'bloomreach.tracking.track_event';
@@ -623,6 +634,11 @@ export const BLOOMREACH_MCP_TOOL_NAMES = [
623634
BLOOMREACH_ACCESS_LIST_API_KEYS_TOOL,
624635
BLOOMREACH_ACCESS_PREPARE_CREATE_API_KEY_TOOL,
625636
BLOOMREACH_ACCESS_PREPARE_DELETE_API_KEY_TOOL,
637+
BLOOMREACH_RECOMMENDATIONS_LIST_TOOL,
638+
BLOOMREACH_RECOMMENDATIONS_VIEW_PERFORMANCE_TOOL,
639+
BLOOMREACH_RECOMMENDATIONS_PREPARE_CREATE_TOOL,
640+
BLOOMREACH_RECOMMENDATIONS_PREPARE_CONFIGURE_TOOL,
641+
BLOOMREACH_RECOMMENDATIONS_PREPARE_DELETE_TOOL,
626642
BLOOMREACH_TRACKING_TRACK_EVENT_TOOL,
627643
BLOOMREACH_TRACKING_TRACK_BATCH_TOOL,
628644
BLOOMREACH_TRACKING_TRACK_CUSTOMER_TOOL,
@@ -633,4 +649,3 @@ export const BLOOMREACH_MCP_TOOL_NAMES = [
633649
] as const;
634650

635651
export type BloomreachMcpToolName = (typeof BLOOMREACH_MCP_TOOL_NAMES)[number];
636-

0 commit comments

Comments
 (0)