flashduty

package
v0.9.13 Latest Latest
Warning

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

 Go to latest Published: Jul 8, 2026 License: MIT Imports: 14 Imported by: 0

README

Flashduty MCP Server Package

This package provides Model Context Protocol (MCP) tools for interacting with the Flashduty API, based on the official OpenAPI specification.

Architecture

The implementation follows the same patterns as the GitHub MCP Server:

  • Client (client.go): HTTP client for Flashduty API with app_key authentication
  • Server helpers (server.go): Common parameter handling and response utilities
  • Tools (tools.go): Tool set organization and registration
  • Members (members.go): Member management tools implementation

Authentication

Uses Flashduty's app_key authentication method via query parameters:

https://api.flashcat.cloud/member/list?app_key=YOUR_APP_KEY

Members Toolset

Available Tools
1. flashduty_get_member_list
  • Method: POST /member/list
  • Description: Get paginated list of members
  • Parameters:
    • p (number): Page number, starting from 1 (default: 1)
    • limit (number): Items per page (default: 20)
    • query (string): Search keyword for member name
    • role_id (number): Filter by role ID
    • orderby (string): Sort field (created_at, updated_at)
    • asc (boolean): Sort ascending (default: false)
2. flashduty_invite_member
  • Method: POST /member/invite
  • Description: Invite a new member to the account
  • Parameters:
    • email (string): Email address (required if phone not provided)
    • phone (string): Phone number (required if email not provided)
    • country_code (string): Country code (default: CN)
    • member_name (string): Member name (required when phone provided)
    • ref_id (string): Reference ID
    • role_ids (string): Comma-separated list of role IDs
3. flashduty_update_member_info
  • Method: POST /member/info/reset
  • Description: Update member information
  • Identity Parameters (exactly one required):
    • member_id (number): Member ID
    • member_name (string): Member name
    • phone (string): Member phone
    • email (string): Member email
    • ref_id (string): Reference ID
  • Update Parameters (at least one required):
    • new_phone (string): New phone number
    • new_country_code (string): New country code
    • new_email (string): New email address
    • new_member_name (string): New member name
    • new_time_zone (string): New timezone (tzdata format)
    • new_locale (string): New locale (zh-CN, en-US)
    • new_ref_id (string): New reference ID
4. flashduty_delete_member
  • Method: POST /member/delete
  • Description: Delete a member from the account
  • Parameters (exactly one required):
    • member_id (number): Member ID
    • phone (string): Member phone
    • email (string): Member email
    • ref_id (string): Reference ID

Key Implementation Details

API Differences from REST Standards
  • All operations use POST method, not GET/PUT/DELETE
  • Uses specific Flashduty API paths (/member/list, /member/invite, etc.)
  • Request body structure follows Flashduty's schema exactly
  • Authentication via query parameter app_key instead of Bearer token
Request/Response Structure
// Member list request
{
  "p": 1,
  "limit": 20,
  "query": "search term"
}

// Member invite request  
{
  "members": [
    {
      "email": "user@example.com",
      "member_name": "User Name",
      "country_code": "CN",
      "role_ids": [1, 2]
    }
  ]
}

// Member update request
{
  "member_id": 123,
  "updates": {
    "member_name": "New Name",
    "email": "new@example.com"
  }
}
Error Handling

Flashduty API returns errors in this format:

{
  "error": {
    "code": "InvalidParameter",
    "message": "Error description"
  }
}

Testing

The package includes comprehensive unit tests using mock clients:

cd pkg/flashduty
go test -v

Tests cover:

  • Tool metadata validation
  • Request parameter handling
  • API request construction
  • Response parsing
  • Error scenarios

Future Expansion

The current implementation focuses on member management. The architecture supports easy addition of other Flashduty toolsets:

  • Teams management (/team/*)
  • Schedules management (/schedule/*)
  • Channels management (/channel/*)
  • Incidents management (/incident/*)
  • Alerts management (/alert/*)
  • Analytics (/analytics/*)

Each toolset would follow the same pattern established in the members implementation.

Documentation

Index

Constants

View Source 
const (
	SinceDescription = "Lower bound of the query window. " +
		"PREFER relative durations like \"24h\", \"7d\", \"30m\" — they are anchored " +
		"to server time and immune to your training-data cutoff. " +
		"Use absolute dates (\"2026-04-01\" or \"2026-04-01 10:00:00\") ONLY when " +
		"the user explicitly asked for a specific calendar date; double-check the " +
		"year, since picking the wrong year returns silently incorrect data. " +
		"Also accepts unix seconds (\"1712000000\") and \"now\". " +
		"Max window (until - since): 31 days. Data older than ~90 days may have been purged."

	UntilDescription = "Upper bound of the query window. Same formats as `since`, plus " +
		"future durations like \"+24h\", \"+7d\". Defaults to \"now\" when omitted. " +
		"Must be greater than `since` and within 31 days of it."
)

SinceDescription / UntilDescription are reused across query_incidents and query_changes. The wording is tuned for LLM callers that otherwise pick absolute dates from stale training data and silently query the wrong year — see the three failure modes documented at https://github.com/flashcatcloud/flashduty-mcp-server/pull/50.

View Source 
const DefaultIncidentWindow = 30 * 24 * time.Hour

DefaultIncidentWindow is the lookback query_incidents applies when the caller omits both since and until ("current open incidents" with no explicit range). Kept under MaxTimeWindow so the defaulted span never trips the backend cap.

View Source 
const LimitDescription = "Maximum number of results per page. Default 20, max 100. " +
	"When more results exist than were returned, the response carries " +
	"`truncated:true` and a `hint` field with concrete next steps."

LimitDescription is the canonical description for the `limit` parameter on list-shaped tools. Mentioning `truncated`/`total` up front primes the LLM to inspect them before assuming it has the full result.

View Source 
const MaxTimeWindow = 31 * 24 * time.Hour

MaxTimeWindow is the backend's hard cap on (until-since) for incident/alert/change queries. Exceeding it produces a 400 from the API; we mirror the cap client-side so the LLM gets a guided error before the round-trip.

View Source 
const PageDescription = "1-based page number for paging through results beyond `limit`. " +
	"Default 1. When the response is `truncated`, request `page:2` (then 3, …) to fetch the rest."

PageDescription is the canonical description for the `page` parameter on list-shaped tools. Pairs with `limit`: page N returns results [(N-1)*limit, N*limit). Advertised alongside the `truncated`/`hint` fields so the LLM knows how to reach results beyond the first page.

Variables

View Source 
var DefaultTools = []string{"incidents", "alerts", "changes", "status_page", "users", "channels", "fields", "templates"}

DefaultTools is the default list of enabled Flashduty toolsets

Functions

func AckIncident 

func AckIncident(getClient GetFlashdutyClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc)

AckIncident creates a tool to acknowledge incidents

func CloseIncident added in v0.4.0 

func CloseIncident(getClient GetFlashdutyClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc)

CloseIncident creates a tool to close incidents

func CreateChangeTimeline added in v0.4.0 

func CreateChangeTimeline(getClient GetFlashdutyClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc)

CreateChangeTimeline creates a tool to add timeline entry to status change

func CreateIncident 

func CreateIncident(getClient GetFlashdutyClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc)

CreateIncident creates a tool to create a new incident

func CreateStatusIncident added in v0.4.0 

func CreateStatusIncident(getClient GetFlashdutyClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc)

CreateStatusIncident creates a tool to create status page incident

func DefaultToolsetGroup 

func DefaultToolsetGroup(getClient GetFlashdutyClientFn, readOnly bool, t translations.TranslationHelperFunc) *toolsets.ToolsetGroup

DefaultToolsetGroup returns the default toolset group for Flashduty

func GetPresetTemplate added in v0.9.6 

func GetPresetTemplate(getClient GetFlashdutyClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc)

GetPresetTemplate creates a tool to fetch the preset template for a channel.

func ListSimilarIncidents added in v0.4.0 

func ListSimilarIncidents(getClient GetFlashdutyClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc)

ListSimilarIncidents creates a tool to find similar incidents

func ListStatusChanges added in v0.4.0 

func ListStatusChanges(getClient GetFlashdutyClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc)

ListStatusChanges creates a tool to list status page changes

func ListTemplateFunctions added in v0.9.6 

func ListTemplateFunctions(_ GetFlashdutyClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc)

ListTemplateFunctions creates a tool that returns the available template functions.

func ListTemplateVariables added in v0.9.6 

func ListTemplateVariables(_ GetFlashdutyClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc)

ListTemplateVariables creates a tool that returns the available template variable schema.

func MarshalResult added in v0.4.0 

func MarshalResult(v any) *mcp.CallToolResult

MarshalResult serializes the given value according to the current output format and returns it as a text result for an MCP tool response.

Values come from go-flashduty, whose Timestamp/TimestampMilli types already render absolute instants as RFC3339, so no post-processing is needed.

func OptionalInt 

func OptionalInt(r mcp.CallToolRequest, p string) (int, error)

OptionalInt is a helper function that can be used to fetch a requested parameter from the request. It does the following checks: 1. Checks if the parameter is present in the request, if not, it returns its zero-value 2. If it is present, it checks if the parameter is of the expected type and returns it

func OptionalParam 

func OptionalParam[T any](r mcp.CallToolRequest, p string) (T, error)

OptionalParam is a helper function that can be used to fetch a requested parameter from the request. It does the following checks: 1. Checks if the parameter is present in the request, if not, it returns its zero-value 2. If it is present, it checks if the parameter is of the expected type and returns it

func QueryAlertEvents added in v0.9.6 

func QueryAlertEvents(getClient GetFlashdutyClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc)

QueryAlertEvents creates a tool to query raw events of a single alert.

func QueryChanges added in v0.4.0 

func QueryChanges(getClient GetFlashdutyClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc)

QueryChanges creates a tool to query change records

func QueryChannels added in v0.4.0 

func QueryChannels(getClient GetFlashdutyClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc)

QueryChannels creates a tool to query channels

func QueryEscalationRules added in v0.4.0 

func QueryEscalationRules(getClient GetFlashdutyClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc)

QueryEscalationRules creates a tool to query escalation rules

func QueryFields added in v0.4.0 

func QueryFields(getClient GetFlashdutyClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc)

QueryFields creates a tool to query custom field definitions

func QueryIncidentAlerts added in v0.4.0 

func QueryIncidentAlerts(getClient GetFlashdutyClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc)

QueryIncidentAlerts creates a tool to query incident alerts

func QueryIncidentTimeline added in v0.4.0 

func QueryIncidentTimeline(getClient GetFlashdutyClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc)

QueryIncidentTimeline creates a tool to query incident timeline

func QueryIncidents added in v0.4.0 

func QueryIncidents(getClient GetFlashdutyClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc)

QueryIncidents creates a tool to query incidents with enriched data

func QueryMembers added in v0.4.0 

func QueryMembers(getClient GetFlashdutyClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc)

QueryMembers creates a tool to query members

func QueryStatusPages added in v0.4.0 

func QueryStatusPages(getClient GetFlashdutyClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc)

QueryStatusPages creates a tool to query status pages

func QueryTeams added in v0.4.0 

func QueryTeams(getClient GetFlashdutyClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc)

QueryTeams creates a tool to query teams

func RequiredInt 

func RequiredInt(r mcp.CallToolRequest, p string) (int, error)

RequiredInt is a helper function that can be used to fetch a requested parameter from the request. It does the following checks: 1. Checks if the parameter is present in the request. 2. Checks if the parameter is of the expected type. 3. Checks if the parameter is not empty, i.e: non-zero value

func RequiredParam 

func RequiredParam[T comparable](r mcp.CallToolRequest, p string) (T, error)

RequiredParam is a helper function that can be used to fetch a requested parameter from the request. It does the following checks: 1. Checks if the parameter is present in the request. 2. Checks if the parameter is of the expected type. 3. Checks if the parameter is not empty, i.e: non-zero value

func SetOutputFormat added in v0.4.0 

func SetOutputFormat(format OutputFormat)

SetOutputFormat sets the global output format

func ToBoolPtr 

func ToBoolPtr(b bool) *bool

ToBoolPtr converts a bool to a *bool pointer.

func UpdateIncident added in v0.4.0 

func UpdateIncident(getClient GetFlashdutyClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc)

UpdateIncident creates a tool to update an incident

func ValidateTemplate added in v0.9.6 

func ValidateTemplate(getClient GetFlashdutyClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc)

ValidateTemplate creates a tool to validate and preview a template.

func WithSince added in v0.9.6 

func WithSince(opts ...mcp.PropertyOption) mcp.ToolOption

WithSince / WithUntil are convenience wrappers that apply the canonical descriptions.

func WithUntil added in v0.9.6 

func WithUntil(opts ...mcp.PropertyOption) mcp.ToolOption

Types

type Clients added in v0.9.11 

type Clients struct {
	New *flashduty.Client
}

Clients bundles the Flashduty API clients a tool handler may need.

New is the typed go-flashduty client and backs every tool.

type GetFlashdutyClientFn 

type GetFlashdutyClientFn func(context.Context) (context.Context, *Clients, error)

GetFlashdutyClientFn returns the Flashduty clients for the current request.

type OutputFormat added in v0.4.0 

type OutputFormat string

OutputFormat defines the serialization format for tool results. 

const (
	// OutputFormatJSON uses standard JSON serialization (default)
	OutputFormatJSON OutputFormat = "json"
	// OutputFormatTOON uses Token-Oriented Object Notation for reduced token usage
	OutputFormatTOON OutputFormat = "toon"
)

func GetOutputFormat added in v0.4.0 

func GetOutputFormat() OutputFormat

GetOutputFormat returns the current global output format

func ParseOutputFormat added in v0.4.0 

func ParseOutputFormat(s string) OutputFormat

ParseOutputFormat converts a string to OutputFormat, defaulting to JSON.

func (OutputFormat) String added in v0.4.0 

func (f OutputFormat) String() string

String returns the string representation of OutputFormat.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.