Documentation
¶
Overview ¶
Package mcpserver is ReputeCast's Model Context Protocol server (main spec 5.13, A5 §5.13). AI agents connect over streamable HTTP at /mcp with their own token (rc_agent_…). Every tool checks the agent's permissions through internal/authz, exactly like a member or API key, and every call lands in the audit log with the agent as actor. Anything that would send mail needs a person to confirm it in ReputeCast.
Index ¶
- Constants
- Variables
- func CapabilitiesIn(l i18n.Lang) []string
- func Register(h huma.API, s *Service)
- type AccessibilityReader
- type CampaignRef
- type DigestReader
- type DigestRef
- type GrowReader
- type GrowthReader
- type MCPAgentRow
- type MCPCapabilityCell
- type MCPOverview
- type MCPSettingsInput
- type MCPToolInfo
- type PagesReader
- type PaidMembersReader
- type PlacementReader
- type PlacementRef
- type PollReader
- type ProductsReader
- type PushDrafts
- type RecommendationsReader
- type ReportReader
- type RevenueReader
- type Service
- type Settings
- type SmsAgent
- type SmsCampaignRef
- type SponsorProposer
- type WebsitePosts
- type WhatsAppDrafts
Constants ¶
const Path = "/mcp"
Path is where the MCP endpoint is mounted.
Variables ¶
var Capabilities = CapabilitiesIn(i18n.Default)
Capabilities are the columns of the agents matrix, in English.
var Tools = []MCPToolInfo{ {"list_campaigns", "List campaigns with status, audience and headline results.", string(authz.CampaignsView), false}, {"get_campaign_report", "A campaign's report as the app shows it: human, privacy-protected and scanner opens apart, the measurable open rate, complaints where reported, results by mailbox and sending provider, links, the A/B decision and growth.", string(authz.ReportsView), false}, {"share_campaign_report", "Make a read-only link to a campaign's report that expires (30 days by default), choosing whether it shows the cost, warm-up and the email.", string(authz.ReportsShare), true}, {"get_send_readiness", "The latest Send Readiness verdict and checks of a campaign.", string(authz.CampaignsView), false}, {"create_campaign_draft", "Create a draft campaign from MJML.", string(authz.CampaignsEdit), true}, {"update_campaign_content", "Change the subject, preheader or MJML of a draft, or of one of its language versions.", string(authz.CampaignsEdit), true}, {"schedule_campaign", "Propose a send time. A team member confirms it in ReputeCast.", string(authz.CampaignsSend), true}, {"pause_campaign", "Pause a running send.", string(authz.CampaignsPause), true}, {"resume_campaign", "Resume a paused send.", string(authz.CampaignsSend), true}, {"get_campaign_live_stats", "Live counters and routes of a running send.", string(authz.CampaignsView), false}, {"search_contacts", "Find contacts by email or name.", string(authz.SubscribersView), false}, {"create_segment", "Create a segment from condition-builder JSON.", string(authz.SegmentsEdit), true}, {"add_to_suppression", "Suppress an address so nothing is sent to it again.", string(authz.SubscribersEdit), true}, {"get_provider_health", "Status, bounce and complaint rates and quota of each sending provider.", string(authz.ProvidersView), false}, {"get_routing", "Routing rules per stream with weights and fallbacks.", string(authz.ProvidersView), false}, {"update_routing", "Change the weights of a stream's default route.", string(authz.ProvidersManage), true}, {"list_automations", "Automations with their status.", string(authz.AutomationsView), false}, {"get_deliverability", "Domain authentication, blocklists and Postmaster reputation.", string(authz.DeliverabilityView), false}, {"send_test_email", "Send a test of a campaign to a member of the workspace.", string(authz.CampaignsEdit), true}, {"get_campaign_languages", "A campaign's language versions: each one's status (up to date, outdated, draft, missing) and who gets it.", string(authz.CampaignsView), false}, {"get_accessibility_issues", "Accessibility issues of a campaign in every language: what is serious, where it is and how to fix it.", string(authz.CampaignsView), false}, {"list_transactional_templates", "Transactional templates with their category, live version and numbers.", string(authz.TransactionalView), false}, {"render_transactional_template", "Render a transactional template with test data or given data. Nothing is sent or stored.", string(authz.TransactionalView), false}, {"search_transactional_messages", "Search the transactional message log by status, template or recipient, without message content.", string(authz.TransactionalView), false}, {"get_growth_sources", "Joins, departures, quality and cohort retention per growth source over a period (totals only, no addresses).", string(authz.SubscribersView), false}, {"list_digests", "Recurring digests with their status, schedule, next issue and owner. Agents can't turn a digest on.", string(authz.CampaignsView), false}, {"get_digest_issues", "A digest's issues: sent, skipped, held and waiting, each with its posts and results. Agents can't release or skip an issue.", string(authz.CampaignsView), false}, {"get_poll_results", "Results of a campaign's polls or of a survey: answers by answer, NPS, by tier and language. Aggregate only.", string(authz.ReportsView), false}, {"list_placement_tests", "Placement tests people ran: the email, the providers and where the copies landed.", string(authz.DeliverabilityView), false}, {"get_placement_test", "One placement test: each copy's folder, time to arrive and SPF, DKIM and DMARC, with the guidance.", string(authz.DeliverabilityView), false}, {"get_referral_results", "A referral program's results: visits, signups, confirmations, counted referrals, channels, top referrers and rewards.", string(authz.GrowView), false}, {"list_referrers", "Referrers with their counted, in-hold and held referrals and the milestones they reached (no addresses).", string(authz.GrowView), false}, {"list_held_referrals", "Referrals held for review, grouped by referrer, with the signals and addresses masked to their network.", string(authz.GrowView), false}, {"propose_referral_decision", "Propose counting or not counting a referrer's held referrals. A person with grow:review decides in ReputeCast.", string(authz.GrowView), true}, {"list_recommendations", "The newsletters you recommend and the partners that recommend you, with their numbers. Agents can't change them or touch partner links.", string(authz.GrowView), false}, }
Tools is the catalogue, in the order shown on the MCP settings screen.
Functions ¶
func CapabilitiesIn ¶
CapabilitiesIn are the columns of the agents matrix in a language.
Types ¶
type AccessibilityReader ¶
type AccessibilityReader interface {
CampaignReport(ctx context.Context, ws *store.Workspace, id uuid.UUID) (accessibility.AccessibilityReport, error)
}
AccessibilityReader returns a campaign's accessibility issues (X06).
type CampaignRef ¶
type CampaignRef struct {
Campaign string `json:"campaign" jsonschema:"the campaign's name (exact) or id"`
}
CampaignRef names a campaign by name or id.
type DigestReader ¶
type DigestReader interface {
List(ctx context.Context, ws *store.Workspace) (digests.DigestList, error)
Issues(ctx context.Context, ws *store.Workspace, id uuid.UUID) (digests.DigestIssues, error)
}
DigestReader lists recurring digests and their issues (X10).
type DigestRef ¶
type DigestRef struct {
Digest string `json:"digest" jsonschema:"the digest's name (exact) or id"`
}
DigestRef names a digest by name or id.
type GrowReader ¶
type GrowReader interface {
Programs(ctx context.Context, ws *store.Workspace) (referrals.ReferralProgramList, error)
Results(ctx context.Context, ws *store.Workspace, programID uuid.UUID, period, grouping string) (referrals.ReferralResults, error)
Referrers(ctx context.Context, ws *store.Workspace, programID uuid.UUID, p referrals.ReferrerParams) (referrals.ReferralReferrerList, error)
Review(ctx context.Context, ws *store.Workspace, programID uuid.UUID, signal string, link *uuid.UUID) (referrals.ReferralReviewQueue, error)
}
GrowReader reads Grow › Referrals (internal/referrals).
type GrowthReader ¶
type GrowthReader interface {
Page(ctx context.Context, ws *store.Workspace, in growth.GrowthQuery) (growth.GrowthPage, error)
}
GrowthReader returns Audience › Growth (internal/growth).
type MCPAgentRow ¶
type MCPAgentRow struct {
ID string `json:"id"`
Name string `json:"name"`
Masked string `json:"masked"`
CreatedBy string `json:"createdBy"`
Permissions []string `json:"permissions"`
Cells []MCPCapabilityCell `json:"cells"`
Status string `json:"status" enum:"active,expired"`
}
MCPAgentRow is one agent in the matrix.
type MCPCapabilityCell ¶
type MCPCapabilityCell struct {
Capability string `json:"capability"`
Level string `json:"level" enum:"allow,approve,partial,deny"`
Label string `json:"label" example:"Pause only · never start"`
}
MCPCapabilityCell is one cell of the matrix.
func Cells ¶
func Cells(perms authz.Set) []MCPCapabilityCell
Cells derives what an agent can do from its permission keys, in English.
type MCPOverview ¶
type MCPOverview struct {
Enabled bool `json:"enabled"`
Endpoint string `json:"endpoint"`
Transport string `json:"transport" enum:"streamable_http"`
RateLimitPerMinute int `json:"rateLimitPerMinute"`
ApprovalExpiryHours int `json:"approvalExpiryHours"`
Capabilities []string `json:"capabilities"`
Agents []MCPAgentRow `json:"agents"`
Tools []MCPToolInfo `json:"tools"`
Resources []string `json:"resources"`
Prompts []string `json:"prompts"`
CanManage bool `json:"canManage"`
}
MCPOverview is the MCP server settings screen.
type MCPSettingsInput ¶
type MCPSettingsInput struct {
Enabled bool `json:"enabled"`
RateLimitPerMinute int `json:"rateLimitPerMinute" minimum:"1" maximum:"6000"`
ApprovalExpiryHours int `json:"approvalExpiryHours" minimum:"1" maximum:"168"`
}
MCPSettingsInput changes the MCP options.
type MCPToolInfo ¶
type MCPToolInfo struct {
Name string `json:"name"`
Description string `json:"description"`
Permission string `json:"permission"`
// Writes is true for tools that change something.
Writes bool `json:"writes"`
}
MCPToolInfo describes a tool for the settings screen and the docs.
type PagesReader ¶
type PagesReader interface {
Overview(ctx context.Context, ws *store.Workspace, p *authz.Principal, period string) (pages.PagesOverview, error)
Detail(ctx context.Context, ws *store.Workspace, p *authz.Principal, id uuid.UUID) (pages.PageDetail, error)
}
PagesReader lists and reads pages (internal/pages).
type PaidMembersReader ¶
type PaidMembersReader interface {
PaidMemberCounts(ctx context.Context, ws *store.Workspace) (earn.PaidMemberSummary, error)
}
PaidMembersReader counts paid members (internal/earn).
type PlacementReader ¶
type PlacementReader interface {
Tests(ctx context.Context, ws *store.Workspace) (placement.PlacementTestList, error)
Test(ctx context.Context, ws *store.Workspace, id uuid.UUID) (placement.PlacementTestDetail, error)
}
PlacementReader reads the workspace's placement tests (X14). Agents can read results; running tests and managing seed mailboxes stay with people (placement:run and placement:manage can't be granted to agents).
type PlacementRef ¶
type PlacementRef struct {
Test string `json:"test" jsonschema:"The test's id, or its name (Weekly Digest #142 · SES vs Postal)"`
}
PlacementRef names a placement test by id or name.
type PollReader ¶
type PollReader interface {
CampaignPolls(ctx context.Context, ws *store.Workspace, p *authz.Principal, campaignID uuid.UUID) (polls.PollResultsList, error)
Surveys(ctx context.Context, ws *store.Workspace) (polls.SurveyList, error)
SurveyResultsOf(ctx context.Context, ws *store.Workspace, id uuid.UUID) (polls.SurveyResults, error)
}
PollReader reads poll and survey results (design expansion, X11).
type ProductsReader ¶
type ProductsReader interface {
Overview(ctx context.Context, ws *store.Workspace, period string) (products.ProductsOverview, error)
Detail(ctx context.Context, ws *store.Workspace, id uuid.UUID) (products.ProductDetail, error)
}
ProductsReader lists and reads products (internal/products).
type PushDrafts ¶
type PushDrafts interface {
CreateCampaign(ctx context.Context, ws *store.Workspace, p *authz.Principal, in push.PushCampaignCreate) (push.PushCampaign, error)
CampaignReport(ctx context.Context, ws *store.Workspace, id uuid.UUID, canSend bool) (push.PushReport, error)
}
PushDrafts drafts push campaigns and reads their reports (internal/push).
type RecommendationsReader ¶
type RecommendationsReader interface {
View(ctx context.Context, ws *store.Workspace) (recommendations.RecommendationsView, error)
}
RecommendationsReader reads Grow › Recommendations.
type ReportReader ¶
type ReportReader interface {
Report(ctx context.Context, ws *store.Workspace, id uuid.UUID) (reports.CampaignReport, error)
}
ReportReader reads campaign reports and makes read-only links to them (internal/reports).
type RevenueReader ¶
type RevenueReader interface {
Overview(ctx context.Context, ws *store.Workspace, p *authz.Principal, in revenue.OverviewQuery) (revenue.RevenueOverview, error)
}
RevenueReader reads Earn › Overview (internal/revenue).
type Service ¶
type Service struct {
Pool *pgxpool.Pool
Q *store.Queries
Audit *audit.Logger
Sending sending.Starter
Mail mailer.Sender
Campaigns *campaigns.Service
// Languages handles campaigns' language versions; nil leaves them out.
Languages *languages.Service
// Accessibility reads campaigns' accessibility issues (nil: unavailable).
Accessibility AccessibilityReader
// PaidMembers counts paid members (internal/earn; nil: unavailable).
PaidMembers PaidMembersReader
// Transactional lists templates, renders previews and reads the log
// for agents (they never send).
Transactional *transactional.Service
// Growth reads Audience › Growth (nil: unavailable).
Growth GrowthReader
// Digests reads recurring digests and their issues (nil: unavailable).
Digests DigestReader
// Placement reads placement tests (nil: unavailable).
Placement PlacementReader
// Sms reads texting and drafts text campaigns (nil: unavailable).
Sms SmsAgent
PublicURL func(context.Context) string
Now func() time.Time
// Polls reads poll and survey results (nil: unavailable).
Polls PollReader
// Website lists, reads and drafts posts (nil: unavailable).
Website WebsitePosts
// Pages and Products list and read landing pages and digital products
// (nil: unavailable).
Pages PagesReader
Products ProductsReader
// Revenue reads Earn › Overview and Sponsors takes proposed bookings
// (X17; nil: unavailable).
Revenue RevenueReader
Sponsors SponsorProposer
// Reports reads campaign reports as the API does and makes read-only
// links (nil: the report from the counters only, no links).
Reports ReportReader
// Grow and Recommendations read Grow's referrals and recommendations
// (nil: unavailable).
Grow GrowReader
Recommendations RecommendationsReader
// Push and WhatsApp draft campaigns and read their reports (X22; nil:
// unavailable). Agents never send them.
Push PushDrafts
WhatsApp WhatsAppDrafts
// contains filtered or unexported fields
}
func (*Service) Handler ¶
Handler serves the MCP endpoint: bearer-token check, a per-agent rate limit, then the streamable HTTP transport.
func (*Service) Overview ¶
func (s *Service) Overview(ctx context.Context, ws *store.Workspace, p *authz.Principal) (MCPOverview, error)
Overview returns the MCP settings of the workspace.
func (*Service) UpdateSettings ¶
func (s *Service) UpdateSettings(ctx context.Context, ws *store.Workspace, in MCPSettingsInput) (MCPOverview, error)
UpdateSettings saves the MCP options.
type Settings ¶
type Settings struct {
Enabled bool `json:"enabled"`
RateLimitPerMinute int `json:"rate_limit_per_minute"`
ApprovalExpiryHours int `json:"approval_expiry_hours"`
}
Settings are the per-workspace MCP options.
func ParseSettings ¶
func ParseSettings(raw json.RawMessage) Settings
ParseSettings reads workspaces.mcp_settings with defaults.
type SmsAgent ¶
type SmsAgent interface {
AgentOverview(ctx context.Context, ws *store.Workspace, p *authz.Principal) (map[string]any, error)
AgentReport(ctx context.Context, ws *store.Workspace, p *authz.Principal, ref string) (map[string]any, string, string, error)
AgentDraft(ctx context.Context, ws *store.Workspace, p *authz.Principal, name, body string, lists []string) (map[string]any, error)
}
SmsAgent is what agents can do with texts (X21, internal/texting): read the SMS providers' overview and a text campaign's report, and draft a text campaign. Sending stays with people: it needs sms:send in Review & send.
type SmsCampaignRef ¶
type SmsCampaignRef struct {
Campaign string `json:"campaign" jsonschema:"The text campaign's id, or its name (Summit: 8 days to go)"`
}
SmsCampaignRef names a text campaign by id or name.
type SponsorProposer ¶
type SponsorProposer interface {
Propose(ctx context.Context, ws *store.Workspace, p *authz.Principal, in sponsors.ProposeInput) (sponsors.SponsorIssueDetail, error)
}
SponsorProposer records an agent's proposed booking (internal/sponsors).
type WebsitePosts ¶
type WebsitePosts interface {
Posts(ctx context.Context, ws *store.Workspace, p *authz.Principal, f website.WebsitePostFilter) (website.WebsitePostList, error)
Post(ctx context.Context, ws *store.Workspace, p *authz.Principal, id uuid.UUID) (website.WebsitePost, error)
CreatePost(ctx context.Context, ws *store.Workspace, p *authz.Principal, in website.WebsitePostCreate) (website.WebsitePost, error)
FindPost(ctx context.Context, ws *store.Workspace, ref string) (uuid.UUID, error)
}
WebsitePosts reads and drafts posts (internal/website).
type WhatsAppDrafts ¶
type WhatsAppDrafts interface {
CreateCampaign(ctx context.Context, ws *store.Workspace, p *authz.Principal, in whatsapp.WhatsAppCampaignCreate) (whatsapp.WhatsAppCampaign, error)
CampaignReport(ctx context.Context, ws *store.Workspace, id uuid.UUID) (whatsapp.WhatsAppReport, error)
Templates(ctx context.Context, ws *store.Workspace) ([]whatsapp.WhatsAppTemplate, error)
}
WhatsAppDrafts drafts WhatsApp campaigns and reads their reports and costs (internal/whatsapp).