Package io.meeds.gamification.mcp

Class GamificationMcpTool

java.lang.Object

io.meeds.gamification.mcp.GamificationMcpTool

All Implemented Interfaces:

io.meeds.mcp.server.plugin.McpToolPlugin

@Service
@Profile("mcp-server")
public class GamificationMcpTool
extends Object
implements io.meeds.mcp.server.plugin.McpToolPlugin

MCP tools exposing the Meeds Gamification add-on to the AI agent (EVA). The product's UI vocabulary is used: a campaign is a gamification program and a quest is a gamification action/rule inside a campaign. Every method acts as the current user, so program ownership, rewarding-admin rights and rule visibility are enforced by the underlying services.

Field Summary

Fields inherited from interface io.meeds.mcp.server.plugin.McpToolPlugin

DEFAULT_LIMIT, DEFAULT_OFFSET

Constructor Summary

Constructors

Constructor	Description
GamificationMcpTool(ProgramService programService, RuleService ruleService, RealizationService realizationService, AnnouncementService announcementService, BadgeService badgeService, org.exoplatform.social.core.manager.IdentityManager identityManager)

Method Summary

Modifier and Type	Method	Description
AnnouncementModel	announceQuest(Long questId, String comment)	Announces (as the current user) that they completed a manual quest (a challenge), so it can be reviewed and rewarded.
String	cancelQuestAnnouncement(Long announcementId)	Cancels (deletes) a quest announcement previously made by the current user.
QuestAvailabilityModel	checkQuestAvailability(Long questId)	Checks whether the current user can complete/announce a given quest right now, and explains why not.
CampaignModel	createCampaign(String title, String description, Long spaceId, Long budget, Boolean open, String visibility)	Creates a new campaign (gamification program).
QuestModel	createQuest(Long campaignId, String title, String description, Integer score, String type, String startDate, String endDate, String recurrence)	Creates a new quest (gamification action/rule) inside a campaign.
String	deleteQuest(Long questId)	Deletes a quest (gamification action/rule).
CampaignModel	getCampaign(Long campaignId)	Returns a single campaign (gamification program) by its id.
List<LeaderboardEntryModel>	getGamificationLeaderboard(Long campaignId, Long spaceId, String period, String identityType, Integer limit)	Returns the gamification leaderboard (top earners), optionally scoped to a campaign and/or a space, for a given period.
List<CampaignModel>	getMyCampaigns(Integer limit, Integer offset)	Lists the campaigns the current user is a member of or owns (as opposed to list_campaigns which lists every campaign visible to the user).
ScoreModel	getMyGamificationScore(Long campaignId)	Returns the current user's gamification score: the overall total, the overall leaderboard rank and the score per campaign.
PointsTotalModel	getMyPointsTotal(String fromDate, String toDate, Long campaignId)	Returns the total gamification points the current user earned within a date range, optionally scoped to a single campaign.
List<ScoreBreakdownEntryModel>	getMyScoreBreakdown(String period)	Breaks down the current user's points by campaign for a period (WEEK/MONTH/QUARTER/ALL).
QuestModel	getQuest(Long questId)	Returns a single quest (gamification action/rule) by its id.
List<BadgeModel>	listCampaignBadges(Long campaignId)	Lists the badges (levels) of a campaign and the score needed to reach each.
List<CampaignModel>	listCampaigns(String term, Long spaceId, Integer limit, Integer offset)	Lists the campaigns (gamification programs) visible to the current user, optionally filtered by a search term and/or a space.
List<CampaignModel>	listJoinableCampaigns(Integer limit, Integer offset)	Lists the open (public) campaigns the current user can join and participate in.
List<AnnouncementModel>	listMyAnnouncements(Long questId, Integer limit, Integer offset)	Lists the current user's own quest announcements (challenges they announced), most recent first.
List<RealizationModel>	listMyRealizations(String fromDate, String toDate, Long campaignId, String status, Integer limit, Integer offset)	Lists the current user's own realizations (gamification achievements), optionally filtered by date range, campaign and/or status.
List<QuestModel>	listQuests(Long campaignId, String type, String status, Integer limit, Integer offset)	Lists the quests (gamification actions/rules) of a campaign, or across all accessible campaigns when no campaign id is given.
QuestModel	updateQuest(Long questId, String title, String description, Integer score, String startDate, String endDate, Boolean enabled, String recurrence)	Updates an existing quest (gamification action/rule).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface io.meeds.mcp.server.plugin.McpToolPlugin

getCurrentUserAclIdentity, getCurrentUserLocale, getCurrentUserLocale, getCurrentUserName, getLocale

Constructor Details

GamificationMcpTool

public GamificationMcpTool(ProgramService programService,
 RuleService ruleService,
 RealizationService realizationService,
 AnnouncementService announcementService,
 BadgeService badgeService,
 org.exoplatform.social.core.manager.IdentityManager identityManager)

Method Details

listCampaigns

public List<CampaignModel> listCampaigns(String term,
 Long spaceId,
 Integer limit,
 Integer offset)
                                  throws IllegalAccessException

Lists the campaigns (gamification programs) visible to the current user, optionally filtered by a search term and/or a space.

Throws:

IllegalAccessException

getCampaign

public CampaignModel getCampaign(Long campaignId)
                          throws IllegalAccessException,
org.exoplatform.commons.exception.ObjectNotFoundException

Returns a single campaign (gamification program) by its id.

Throws:

IllegalAccessException

org.exoplatform.commons.exception.ObjectNotFoundException

listQuests

public List<QuestModel> listQuests(Long campaignId,
 String type,
 String status,
 Integer limit,
 Integer offset)

Lists the quests (gamification actions/rules) of a campaign, or across all accessible campaigns when no campaign id is given.

getQuest

public QuestModel getQuest(Long questId)
                    throws IllegalAccessException,
org.exoplatform.commons.exception.ObjectNotFoundException

Returns a single quest (gamification action/rule) by its id.

Throws:

IllegalAccessException

org.exoplatform.commons.exception.ObjectNotFoundException

getMyGamificationScore

public ScoreModel getMyGamificationScore(Long campaignId)

Returns the current user's gamification score: the overall total, the overall leaderboard rank and the score per campaign. When a campaign id is given, the rank and score for that campaign are added.

getGamificationLeaderboard

public List<LeaderboardEntryModel> getGamificationLeaderboard(Long campaignId,
 Long spaceId,
 String period,
 String identityType,
 Integer limit)
                                                       throws IllegalAccessException

Returns the gamification leaderboard (top earners), optionally scoped to a campaign and/or a space, for a given period.

Throws:

IllegalAccessException

listMyRealizations

public List<RealizationModel> listMyRealizations(String fromDate,
 String toDate,
 Long campaignId,
 String status,
 Integer limit,
 Integer offset)
                                          throws IllegalAccessException

Lists the current user's own realizations (gamification achievements), optionally filtered by date range, campaign and/or status.

Throws:

IllegalAccessException

listMyAnnouncements

public List<AnnouncementModel> listMyAnnouncements(Long questId,
 Integer limit,
 Integer offset)
                                            throws IllegalAccessException

Lists the current user's own quest announcements (challenges they announced), most recent first. Optionally scoped to a single quest. Each entry exposes the announcement id needed by cancel_quest_announcement. This only ever returns the current user's own announcements.

Throws:

IllegalAccessException

listCampaignBadges

public List<BadgeModel> listCampaignBadges(Long campaignId)
                                    throws IllegalAccessException,
org.exoplatform.commons.exception.ObjectNotFoundException

Lists the badges (levels) of a campaign and the score needed to reach each. A badge is a milestone unlocked once the user accumulates enough campaign points; the returned level ranks the badges by that score threshold. The campaign is view-gated so a campaign the user cannot see is rejected.

Throws:

IllegalAccessException

org.exoplatform.commons.exception.ObjectNotFoundException

getMyCampaigns

public List<CampaignModel> getMyCampaigns(Integer limit,
 Integer offset)

Lists the campaigns the current user is a member of or owns (as opposed to list_campaigns which lists every campaign visible to the user). This is always scoped to the current user.

listJoinableCampaigns

public List<CampaignModel> listJoinableCampaigns(Integer limit,
 Integer offset)

Lists the open (public) campaigns the current user can join and participate in.

getMyPointsTotal

public PointsTotalModel getMyPointsTotal(String fromDate,
 String toDate,
 Long campaignId)

Returns the total gamification points the current user earned within a date range, optionally scoped to a single campaign. Always scoped to the current user. For the per-event list use list_my_realizations.

getMyScoreBreakdown

public List<ScoreBreakdownEntryModel> getMyScoreBreakdown(String period)

Breaks down the current user's points by campaign for a period (WEEK/MONTH/QUARTER/ALL). Always scoped to the current user.

checkQuestAvailability

public QuestAvailabilityModel checkQuestAvailability(Long questId)
                                              throws IllegalAccessException,
org.exoplatform.commons.exception.ObjectNotFoundException

Checks whether the current user can complete/announce a given quest right now, and explains why not. This is the pre-check for announce_quest. Always evaluated for the current user.

Throws:

IllegalAccessException

org.exoplatform.commons.exception.ObjectNotFoundException

createCampaign

public CampaignModel createCampaign(String title,
 String description,
 Long spaceId,
 Long budget,
 Boolean open,
 String visibility)
                             throws IllegalAccessException,
org.exoplatform.commons.exception.ObjectNotFoundException

Creates a new campaign (gamification program). Requires rewarding-admin rights, or space-manager rights when a space is targeted.

Throws:

IllegalAccessException

org.exoplatform.commons.exception.ObjectNotFoundException

createQuest

public QuestModel createQuest(Long campaignId,
 String title,
 String description,
 Integer score,
 String type,
 String startDate,
 String endDate,
 String recurrence)
                       throws IllegalAccessException,
org.exoplatform.commons.exception.ObjectNotFoundException

Creates a new quest (gamification action/rule) inside a campaign. Only MANUAL quests (challenges the user announces) are supported; AUTOMATIC (event-triggered) quests are rejected. Requires ownership of the campaign.

Throws:

IllegalAccessException

org.exoplatform.commons.exception.ObjectNotFoundException

updateQuest

public QuestModel updateQuest(Long questId,
 String title,
 String description,
 Integer score,
 String startDate,
 String endDate,
 Boolean enabled,
 String recurrence)
                       throws IllegalAccessException,
org.exoplatform.commons.exception.ObjectNotFoundException

Updates an existing quest (gamification action/rule). Only the provided fields are changed; the others keep their current values. Requires ownership of the campaign the quest belongs to.

Throws:

IllegalAccessException

org.exoplatform.commons.exception.ObjectNotFoundException

deleteQuest

public String deleteQuest(Long questId)
                   throws org.exoplatform.commons.exception.ObjectNotFoundException

Deletes a quest (gamification action/rule). Requires ownership of the campaign the quest belongs to.

Throws:

org.exoplatform.commons.exception.ObjectNotFoundException

announceQuest

public AnnouncementModel announceQuest(Long questId,
 String comment)
                                throws IllegalAccessException,
org.exoplatform.commons.exception.ObjectNotFoundException

Announces (as the current user) that they completed a manual quest (a challenge), so it can be reviewed and rewarded.

Throws:

IllegalAccessException

org.exoplatform.commons.exception.ObjectNotFoundException

cancelQuestAnnouncement

public String cancelQuestAnnouncement(Long announcementId)
                               throws org.exoplatform.commons.exception.ObjectNotFoundException

Cancels (deletes) a quest announcement previously made by the current user.

Throws:

org.exoplatform.commons.exception.ObjectNotFoundException