mcpserver

package
v1.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 30, 2026 License: AGPL-3.0 Imports: 57 Imported by: 0

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

View Source
const Path = "/mcp"

Path is where the MCP endpoint is mounted.

Variables

View Source
var Capabilities = CapabilitiesIn(i18n.Default)

Capabilities are the columns of the agents matrix, in English.

View Source
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

func CapabilitiesIn(l i18n.Lang) []string

CapabilitiesIn are the columns of the agents matrix in a language.

func Register

func Register(h huma.API, s *Service)

Register adds the MCP server settings operations.

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.

func CellsIn

func CellsIn(l i18n.Lang, perms authz.Set) []MCPCapabilityCell

CellsIn derives what an agent can do from its permission keys, its columns and labels in a language.

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)
	CreateShare(ctx context.Context, ws *store.Workspace, campaignID uuid.UUID, in reports.ShareInput) (reports.ReportShareLink, 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

func (s *Service) Handler(log *slog.Logger) http.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

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).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL