tools

package
v0.9.0 Latest Latest
Warning

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

 Go to latest Published: Apr 12, 2026 License: MIT Imports: 22 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var Tier2Groups = map[string]Tier2Group{}

Tier2Groups is the global registry of Tier 2 tool groups.

Functions

This section is empty.

Types

type ActivationResult added in v0.6.0 

type ActivationResult struct {
	Kind      string `json:"kind"`
	Name      string `json:"name"`
	Group     string `json:"group,omitempty"`
	ToolCount int    `json:"toolCount"`
}

type DateRange 

type DateRange struct {
	Start string `json:"start"`
	End   string `json:"end"`
}

type DaySummary 

type DaySummary struct {
	Date         string  `json:"date"`
	Entries      int     `json:"entries"`
	TotalSeconds int64   `json:"totalSeconds"`
	TotalHours   float64 `json:"totalHours"`
}

type FindAndUpdateEntryData 

type FindAndUpdateEntryData struct {
	Entry         clockify.TimeEntry `json:"entry"`
	MatchedBy     map[string]any     `json:"matchedBy"`
	UpdatedFields []string           `json:"updatedFields"`
}

type IdentityData added in v0.6.0 

type IdentityData struct {
	User        clockify.User `json:"user"`
	WorkspaceID string        `json:"workspaceId"`
}

type LogTimeData added in v0.6.0 

type LogTimeData struct {
	Entry           clockify.TimeEntry `json:"entry"`
	ResolvedProject string             `json:"resolvedProject,omitempty"`
}

type ProjectSummary 

type ProjectSummary struct {
	ProjectID    string  `json:"projectId,omitempty"`
	ProjectName  string  `json:"projectName"`
	Entries      int     `json:"entries"`
	TotalSeconds int64   `json:"totalSeconds"`
	TotalHours   float64 `json:"totalHours"`
}

type QuickReportData 

type QuickReportData struct {
	Range               DateRange            `json:"range"`
	Totals              SummaryTotals        `json:"totals"`
	TopProject          *ProjectSummary      `json:"topProject,omitempty"`
	RunningEntries      []clockify.TimeEntry `json:"runningEntries,omitempty"`
	EntriesSample       []clockify.TimeEntry `json:"entriesSample,omitempty"`
	ProjectsRepresented int                  `json:"projectsRepresented"`
}

type ResultEnvelope 

type ResultEnvelope struct {
	OK     bool           `json:"ok"`
	Action string         `json:"action"`
	Data   any            `json:"data,omitempty"`
	Meta   map[string]any `json:"meta,omitempty"`
}

type Service 

type Service struct {
	Client          *clockify.Client
	WorkspaceID     string
	DefaultTimezone *time.Location        // from CLOCKIFY_TIMEZONE; nil = system timezone
	DedupeConfig    *dedupe.Config        // optional, set during wiring
	PolicyDescribe  func() map[string]any // set during wiring; returns policy description
	ActivateGroup   func(context.Context, string) (ActivationResult, error)
	ActivateTool    func(context.Context, string) (ActivationResult, error)
	// Notifier delivers server→client notifications (progress, resource updates,
	// etc.) emitted by tool handlers. nil = drop silently.
	Notifier mcp.Notifier
	// EmitResourceUpdate publishes notifications/resources/updated for a URI
	// with an optional delta envelope. Wired from runtime.go to
	// Server.NotifyResourceUpdated so the subscription gate lives in the
	// protocol core rather than in every mutation handler. nil = drop silently
	// (tests without a Server wired).
	EmitResourceUpdate func(uri string, delta mcp.ResourceUpdateDelta)
	// SubscriptionGate reports whether any client is currently subscribed
	// to a URI. When wired (runtime.go sets it to
	// Server.HasResourceSubscription), emitResourceUpdate short-circuits
	// before the ReadResource round-trip so unsubscribed mutations don't
	// pay for a redundant fetch. nil = gate disabled; every emit pays for
	// the re-read (W3-era behaviour, preserved for tests).
	SubscriptionGate func(uri string) bool
	// ReportMaxEntries is the hard cap on the number of time entries a report
	// tool will aggregate. 0 disables the cap. Wired from CLOCKIFY_REPORT_MAX_ENTRIES.
	ReportMaxEntries int
	// contains filtered or unexported fields
}

func New 

func New(client *clockify.Client, workspaceID string) *Service

func (*Service) AddEntry added in v0.6.0 

func (s *Service) AddEntry(ctx context.Context, args map[string]any) (ResultEnvelope, error)

AddEntry creates a new time entry.

func (*Service) AddUserToGroup 

func (s *Service) AddUserToGroup(ctx context.Context, args map[string]any) (ResultEnvelope, error)

AddUserToGroup adds a user to a user group.

func (*Service) ArchiveProjects 

func (s *Service) ArchiveProjects(ctx context.Context, args map[string]any) (ResultEnvelope, error)

func (*Service) CreateClient added in v0.6.0 

func (s *Service) CreateClient(ctx context.Context, args map[string]any) (ResultEnvelope, error)

func (*Service) CreateCustomField 

func (s *Service) CreateCustomField(ctx context.Context, args map[string]any) (ResultEnvelope, error)

func (*Service) CreateHoliday 

func (s *Service) CreateHoliday(ctx context.Context, args map[string]any) (ResultEnvelope, error)

func (*Service) CreateProject added in v0.6.0 

func (s *Service) CreateProject(ctx context.Context, args map[string]any) (ResultEnvelope, error)

func (*Service) CreateProjectTemplate 

func (s *Service) CreateProjectTemplate(ctx context.Context, args map[string]any) (ResultEnvelope, error)

func (*Service) CreateTag 

func (s *Service) CreateTag(ctx context.Context, args map[string]any) (ResultEnvelope, error)

func (*Service) CreateTask added in v0.6.0 

func (s *Service) CreateTask(ctx context.Context, args map[string]any) (ResultEnvelope, error)

func (*Service) CreateUserGroup 

func (s *Service) CreateUserGroup(ctx context.Context, args map[string]any) (ResultEnvelope, error)

CreateUserGroup creates a new user group.

func (*Service) CreateUserGroupAdmin 

func (s *Service) CreateUserGroupAdmin(ctx context.Context, args map[string]any) (ResultEnvelope, error)

func (*Service) CreateWebhook 

func (s *Service) CreateWebhook(ctx context.Context, args map[string]any) (ResultEnvelope, error)

CreateWebhook creates a new webhook with URL validation.

func (*Service) CurrentUser 

func (s *Service) CurrentUser(ctx context.Context) (ResultEnvelope, error)

func (*Service) DeactivateUser 

func (s *Service) DeactivateUser(ctx context.Context, args map[string]any) (ResultEnvelope, error)

DeactivateUser deactivates a user. Supports dry-run (confirm pattern).

func (*Service) DeleteCustomField 

func (s *Service) DeleteCustomField(ctx context.Context, args map[string]any) (ResultEnvelope, error)

func (*Service) DeleteEntry 

func (s *Service) DeleteEntry(ctx context.Context, args map[string]any) (ResultEnvelope, error)

DeleteEntry deletes a time entry by ID.

func (*Service) DeleteHoliday 

func (s *Service) DeleteHoliday(ctx context.Context, args map[string]any) (ResultEnvelope, error)

func (*Service) DeleteUserGroup 

func (s *Service) DeleteUserGroup(ctx context.Context, args map[string]any) (ResultEnvelope, error)

DeleteUserGroup deletes a user group. Supports dry-run (minimal fallback).

func (*Service) DeleteUserGroupAdmin 

func (s *Service) DeleteUserGroupAdmin(ctx context.Context, args map[string]any) (ResultEnvelope, error)

func (*Service) DeleteWebhook 

func (s *Service) DeleteWebhook(ctx context.Context, args map[string]any) (ResultEnvelope, error)

DeleteWebhook deletes a webhook. Supports dry-run (preview via GET).

func (*Service) DetailedReport 

func (s *Service) DetailedReport(ctx context.Context, args map[string]any) (ResultEnvelope, error)

func (*Service) EmitProgress 

func (s *Service) EmitProgress(ctx context.Context, progress, total float64, message string)

EmitProgress publishes a notifications/progress if a progressToken was supplied with the current tools/call and the Service has a Notifier wired. No-op otherwise. total < 0 signals an indeterminate total.

func (*Service) FindAndUpdateEntry 

func (s *Service) FindAndUpdateEntry(ctx context.Context, args map[string]any) (any, error)

func (*Service) GetCustomField 

func (s *Service) GetCustomField(ctx context.Context, args map[string]any) (ResultEnvelope, error)

func (*Service) GetEntry 

func (s *Service) GetEntry(ctx context.Context, args map[string]any) (ResultEnvelope, error)

GetEntry retrieves a single time entry by ID.

func (*Service) GetProject 

func (s *Service) GetProject(ctx context.Context, projectRef string) (ResultEnvelope, error)

func (*Service) GetProjectTemplate 

func (s *Service) GetProjectTemplate(ctx context.Context, args map[string]any) (ResultEnvelope, error)

func (*Service) GetUserGroup 

func (s *Service) GetUserGroup(ctx context.Context, args map[string]any) (ResultEnvelope, error)

func (*Service) GetWebhook 

func (s *Service) GetWebhook(ctx context.Context, args map[string]any) (ResultEnvelope, error)

GetWebhook retrieves a single webhook by ID.

func (*Service) GetWorkspace 

func (s *Service) GetWorkspace(ctx context.Context) (ResultEnvelope, error)

func (*Service) ListClients added in v0.6.0 

func (s *Service) ListClients(ctx context.Context, args map[string]any) (ResultEnvelope, error)

func (*Service) ListCustomFields 

func (s *Service) ListCustomFields(ctx context.Context, args map[string]any) (ResultEnvelope, error)

func (*Service) ListEntries 

func (s *Service) ListEntries(ctx context.Context, args map[string]any) (ResultEnvelope, error)

ListEntries returns recent time entries with optional filtering by date range, project, and pagination.

func (*Service) ListHolidays 

func (s *Service) ListHolidays(ctx context.Context) (ResultEnvelope, error)

func (*Service) ListProjectTemplates 

func (s *Service) ListProjectTemplates(ctx context.Context) (ResultEnvelope, error)

func (*Service) ListProjects added in v0.6.0 

func (s *Service) ListProjects(ctx context.Context, args map[string]any) (ResultEnvelope, error)

func (*Service) ListResourceTemplates 

func (s *Service) ListResourceTemplates(_ context.Context) ([]mcp.ResourceTemplate, error)

ListResourceTemplates returns the five parametric URI templates clients can dereference by substituting concrete IDs.

func (*Service) ListResources 

func (s *Service) ListResources(ctx context.Context) ([]mcp.Resource, error)

ListResources returns a small, immediately-navigable set of concrete resources pinned to the Service's current workspace. Parametric resources (per-id entry, project, weekly report) live in ListResourceTemplates.

func (*Service) ListTags 

func (s *Service) ListTags(ctx context.Context, args map[string]any) (ResultEnvelope, error)

func (*Service) ListTasks added in v0.6.0 

func (s *Service) ListTasks(ctx context.Context, args map[string]any) (ResultEnvelope, error)

func (*Service) ListUserGroups 

func (s *Service) ListUserGroups(ctx context.Context, args map[string]any) (ResultEnvelope, error)

ListUserGroups returns user groups for the workspace.

func (*Service) ListUserGroupsAdmin 

func (s *Service) ListUserGroupsAdmin(ctx context.Context) (ResultEnvelope, error)

func (*Service) ListUsers 

func (s *Service) ListUsers(ctx context.Context, args map[string]any) (ResultEnvelope, error)

func (*Service) ListWebhookEvents 

func (s *Service) ListWebhookEvents(ctx context.Context, _ map[string]any) (ResultEnvelope, error)

ListWebhookEvents returns the available webhook event types.

func (*Service) ListWebhooks 

func (s *Service) ListWebhooks(ctx context.Context, args map[string]any) (ResultEnvelope, error)

ListWebhooks returns webhooks for the workspace.

func (*Service) ListWorkspaces added in v0.6.0 

func (s *Service) ListWorkspaces(ctx context.Context) (ResultEnvelope, error)

func (*Service) LogTime added in v0.6.0 

func (s *Service) LogTime(ctx context.Context, args map[string]any) (any, error)

func (*Service) PolicyInfo added in v0.6.0 

func (s *Service) PolicyInfo(ctx context.Context) (ResultEnvelope, error)

func (*Service) QuickReport 

func (s *Service) QuickReport(ctx context.Context, args map[string]any) (ResultEnvelope, error)

func (*Service) ReadResource 

func (s *Service) ReadResource(ctx context.Context, uri string) ([]mcp.ResourceContents, error)

ReadResource parses a clockify:// URI and fetches the underlying entity from Clockify, returning it as a single JSON-encoded ResourceContents entry. Unknown or malformed URIs return a -32602-equivalent error.

func (*Service) Registry added in v0.6.0 

func (s *Service) Registry() []mcp.ToolDescriptor

func (*Service) RemoveUserFromGroup 

func (s *Service) RemoveUserFromGroup(ctx context.Context, args map[string]any) (ResultEnvelope, error)

RemoveUserFromGroup removes a user from a user group. Supports dry-run (minimal fallback).

func (*Service) ResolveDebug added in v0.6.0 

func (s *Service) ResolveDebug(ctx context.Context, args map[string]any) (ResultEnvelope, error)

func (*Service) ResolveWorkspaceID 

func (s *Service) ResolveWorkspaceID(ctx context.Context) (string, error)

func (*Service) SearchTools added in v0.6.0 

func (s *Service) SearchTools(ctx context.Context, args map[string]any) (ResultEnvelope, error)

func (*Service) SetCustomFieldValue 

func (s *Service) SetCustomFieldValue(ctx context.Context, args map[string]any) (ResultEnvelope, error)

func (*Service) SetProjectMemberships 

func (s *Service) SetProjectMemberships(ctx context.Context, args map[string]any) (ResultEnvelope, error)

func (*Service) StartTimer 

func (s *Service) StartTimer(ctx context.Context, projectID, projectRef, description string) (ResultEnvelope, error)

func (*Service) StopTimer 

func (s *Service) StopTimer(ctx context.Context, args map[string]any) (any, error)

func (*Service) SummaryReport 

func (s *Service) SummaryReport(ctx context.Context, args map[string]any) (ResultEnvelope, error)

func (*Service) SwitchProject 

func (s *Service) SwitchProject(ctx context.Context, args map[string]any) (ResultEnvelope, error)

func (*Service) TestWebhook 

func (s *Service) TestWebhook(ctx context.Context, args map[string]any) (ResultEnvelope, error)

TestWebhook sends a test delivery to a webhook.

func (*Service) Tier2Handlers added in v0.6.0 

func (s *Service) Tier2Handlers(groupName string) ([]mcp.ToolDescriptor, bool)

Tier2Handlers returns the descriptors for a named Tier 2 group. Every returned descriptor has its Tool.OutputSchema populated with at least envelopeOpaque so MCP clients see a consistent envelope shape across all 91 lazy-loaded tools.

func (*Service) TimerStatus 

func (s *Service) TimerStatus(ctx context.Context) (ResultEnvelope, error)

func (*Service) TodayEntries added in v0.6.0 

func (s *Service) TodayEntries(ctx context.Context, args map[string]any) (ResultEnvelope, error)

TodayEntries returns time entries for the current day.

func (*Service) UpdateCustomField 

func (s *Service) UpdateCustomField(ctx context.Context, args map[string]any) (ResultEnvelope, error)

func (*Service) UpdateEntry 

func (s *Service) UpdateEntry(ctx context.Context, args map[string]any) (ResultEnvelope, error)

UpdateEntry performs a fetch-then-update of a time entry, merging caller fields over the existing values.

func (*Service) UpdateProjectEstimate 

func (s *Service) UpdateProjectEstimate(ctx context.Context, args map[string]any) (ResultEnvelope, error)

func (*Service) UpdateUserGroup 

func (s *Service) UpdateUserGroup(ctx context.Context, args map[string]any) (ResultEnvelope, error)

UpdateUserGroup updates a user group's name.

func (*Service) UpdateUserGroupAdmin 

func (s *Service) UpdateUserGroupAdmin(ctx context.Context, args map[string]any) (ResultEnvelope, error)

func (*Service) UpdateUserRole 

func (s *Service) UpdateUserRole(ctx context.Context, args map[string]any) (ResultEnvelope, error)

UpdateUserRole updates a user's workspace role.

func (*Service) UpdateWebhook 

func (s *Service) UpdateWebhook(ctx context.Context, args map[string]any) (ResultEnvelope, error)

UpdateWebhook updates an existing webhook.

func (*Service) WeeklySummary 

func (s *Service) WeeklySummary(ctx context.Context, args map[string]any) (ResultEnvelope, error)

func (*Service) WhoAmI added in v0.6.0 

func (s *Service) WhoAmI(ctx context.Context) (ResultEnvelope, error)

type SummaryData added in v0.6.0 

type SummaryData struct {
	Range     DateRange            `json:"range"`
	Totals    SummaryTotals        `json:"totals"`
	ByProject []ProjectSummary     `json:"byProject"`
	Entries   []clockify.TimeEntry `json:"entries,omitempty"`
}

type SummaryTotals 

type SummaryTotals struct {
	Entries        int     `json:"entries"`
	RunningEntries int     `json:"runningEntries"`
	TotalSeconds   int64   `json:"totalSeconds"`
	TotalHours     float64 `json:"totalHours"`
}

type Tier2Group added in v0.6.0 

type Tier2Group struct {
	Name        string
	Description string
	Keywords    []string
	Builder     func(s *Service) []mcp.ToolDescriptor
}

Tier2Group defines a lazily-activated group of related tools.

type WeeklySummaryData 

type WeeklySummaryData struct {
	Range         DateRange            `json:"range"`
	Totals        SummaryTotals        `json:"totals"`
	ByDay         []DaySummary         `json:"byDay"`
	ByProject     []ProjectSummary     `json:"byProject"`
	Entries       []clockify.TimeEntry `json:"entries,omitempty"`
	UnassignedKey string               `json:"unassignedKey,omitempty"`
}

type WorkspaceContext added in v0.6.0 

type WorkspaceContext struct {
	WorkspaceID string `json:"workspaceId"`
}

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.