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.

One public method is one MCP tool and its parameter list is the tool's input schema, which is why this class is wide (Sonar S107 and S6539 are accepted here by decision, EXO-90210) and why what remains in it beyond the delegation is presentation only — ranking badges by their score threshold and turning a RealizationValidityContext into a sentence, the same job a REST EntityBuilder does. Business logic belongs to the services: the member/owned campaign union lives in ProgramService.getMyProgramIds(String, int, int), not here.

  • Constructor Details

    • GamificationMcpTool

      public GamificationMcpTool(ProgramService programService, RuleService ruleService, RealizationService realizationService, AnnouncementService announcementService, BadgeService badgeService, org.exoplatform.social.core.manager.IdentityManager identityManager, io.meeds.portal.permlink.service.PermanentLinkService permanentLinkService)
      Builds the tool plugin over the gamification services it delegates to.
      Parameters:
      programService - campaigns
      ruleService - quests
      realizationService - realizations and leaderboards
      announcementService - announcements
      badgeService - badges
      identityManager - social identities
      permanentLinkService - resolves the page address of a campaign or a quest

  • 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) throws IllegalAccessException
      Creates a new campaign (gamification program). With a space id the campaign is scoped to that space's audience and requires space-manager rights; with no space id it is a platform-wide campaign open to everyone and requires rewarding-admin rights. The visibility is computed by the service from the target space (OPEN when the space is open and not hidden, RESTRICTED otherwise) — no caller can influence it.
      Throws:
      IllegalAccessException

    • createQuest

      public QuestModel createQuest(Long campaignId, String title, String description, Integer score, String type, String startDate, String endDate, String recurrence, Boolean publish) 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. When publish is true the quest is announced in the campaign's stream, exactly as RuleRest does it with a RulePublication; when it is false (the default) the quest's activity stays hidden.
      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, IllegalAccessException
      Deletes a quest (gamification action/rule). Requires ownership of the campaign the quest belongs to.
      Throws:
      org.exoplatform.commons.exception.ObjectNotFoundException
      IllegalAccessException

    • 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, IllegalAccessException
      Cancels (deletes) a quest announcement previously made by the current user.
      Throws:
      org.exoplatform.commons.exception.ObjectNotFoundException
      IllegalAccessException