mcpserver

package
v1.0.0 Latest Latest
Warning

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

Go to latest
Published: Oct 24, 2026 License: AGPL-3.0 Imports: 33 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 = []string{"Read reports and contacts", "Draft campaigns", "Edit audience", "Schedule or send", "Change routing"}

Capabilities are the columns of the agents matrix.

View Source
var Tools = []MCPToolInfo{
	{"list_campaigns", "List campaigns with status, audience and headline results.", string(authz.CampaignsView), false},
	{"get_campaign_report", "Results of a campaign by sending provider and mailbox provider.", string(authz.ReportsView), false},
	{"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.", 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},
}

Tools is the catalogue, in the order shown on the MCP settings screen.

Functions

func Register

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

Register adds the MCP server settings operations.

Types

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

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 Service

type Service struct {
	Pool      *pgxpool.Pool
	Q         *store.Queries
	Audit     *audit.Logger
	Sending   sending.Starter
	Mail      mailer.Sender
	Campaigns *campaigns.Service
	PublicURL func(context.Context) string
	Now       func() time.Time
	// 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.

Jump to

Keyboard shortcuts

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