mcp

type Activator interface {
	// IsGroupAllowed reports whether a Tier 2 group may be activated.
	IsGroupAllowed(group string) bool
	// OnActivate is called when tools are dynamically registered.
	OnActivate(names []string)
}

type AuditEvent struct {
	Tool        string
	Action      string
	Outcome     string
	Reason      string
	ResourceIDs map[string]string
	Metadata    map[string]string
}

type Auditor interface {
	RecordAudit(AuditEvent) error
}

type Enforcement interface {
	// FilterTool reports whether a tool should be listed in tools/list.
	FilterTool(name string, hints ToolHints) bool
	// BeforeCall runs before the tool handler. It may:
	//   - block the call by returning a non-nil error
	//   - short-circuit with a result (e.g., dry-run preview)
	//   - return (nil, noop, nil) to proceed normally
	// The returned release function must be called when the call completes.
	//
	// schema is the tool's advertised InputSchema (may be nil) — the
	// pipeline uses it for runtime JSON-schema validation. Pipelines that
	// receive nil skip validation and behave as before.
	BeforeCall(ctx context.Context, name string, args map[string]any, hints ToolHints, schema map[string]any, lookupHandler func(string) (ToolHandler, bool)) (result any, release func(), err error)
	// AfterCall post-processes a successful tool result (e.g., truncation).
	AfterCall(result any) (any, error)
}

type ExtraHandler struct {
	Pattern string
	Handler http.Handler
}

type InitializeParams struct {
	ProtocolVersion string         `json:"protocolVersion,omitempty"`
	Capabilities    map[string]any `json:"capabilities,omitempty"`
	ClientInfo      map[string]any `json:"clientInfo,omitempty"`
	Meta            *RequestMeta   `json:"_meta,omitempty"`
}

type InlineMetricsOptions struct {
	// Enabled: when false (default), /metrics is not mounted on the main
	// HTTP listener. Set MCP_HTTP_INLINE_METRICS_ENABLED=1 to opt in.
	Enabled bool
	// AuthMode controls auth for the inline /metrics endpoint.
	// "inherit_main_bearer": require the same bearer token as /mcp (default
	//   when Enabled=true and no explicit auth mode is set).
	// "static_bearer": require a separate BearerToken below.
	// "none": unauthenticated — operator must opt in explicitly; startup warns.
	AuthMode string
	// BearerToken is used when AuthMode == "static_bearer".
	BearerToken string
	// MainBearerToken is the /mcp token reused when AuthMode == "inherit_main_bearer".
	// Populated by ServeHTTP from the top-level bearerToken argument.
	MainBearerToken string
}

type InvalidParamsError struct {
	Pointer string
	Message string
}

type MetricsServerOptions struct {
	Bind        string
	AuthMode    string
	BearerToken string
}

type Notifier interface {
	Notify(method string, params any) error
}

type ProgressToken = any

type Prompt struct {
	Name        string           `json:"name"`
	Description string           `json:"description,omitempty"`
	Arguments   []PromptArgument `json:"arguments,omitempty"`
	Messages    []PromptMessage  `json:"messages"`
}

type PromptArgument struct {
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	Required    bool   `json:"required,omitempty"`
}

type PromptMessage struct {
	Role    string            `json:"role"`
	Content PromptMessagePart `json:"content"`
}

type PromptMessagePart struct {
	Type string `json:"type"`
	Text string `json:"text,omitempty"`
}

type RPCError struct {
	Code    int            `json:"code"`
	Message string         `json:"message"`
	Data    map[string]any `json:"data,omitempty"`
}

type Request struct {
	JSONRPC string `json:"jsonrpc"`
	ID      any    `json:"id,omitempty"`
	Method  string `json:"method"`
	Params  any    `json:"params,omitempty"`
}

type RequestMeta struct {
	ProgressToken any `json:"progressToken,omitempty"`
}

type Resource struct {
	URI         string `json:"uri"`
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	MimeType    string `json:"mimeType,omitempty"`
}

type ResourceContents struct {
	URI      string `json:"uri"`
	MimeType string `json:"mimeType,omitempty"`
	Text     string `json:"text,omitempty"`
	Blob     string `json:"blob,omitempty"`
}

type ResourceProvider interface {
	ListResources(ctx context.Context) ([]Resource, error)
	ListResourceTemplates(ctx context.Context) ([]ResourceTemplate, error)
	ReadResource(ctx context.Context, uri string) ([]ResourceContents, error)
}

type ResourceTemplate struct {
	URITemplate string `json:"uriTemplate"`
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	MimeType    string `json:"mimeType,omitempty"`
}

type ResourceUpdateDelta struct {
	// Format is one of FormatNone / FormatMerge / FormatFull /
	// FormatDeleted. Empty means do not emit a delta envelope — legacy
	// payload shape {"uri": "..."} is used.
	Format string
	// Patch is the wire-format payload for FormatMerge / FormatFull. It
	// is emitted verbatim under the "patch" key. Pre-decoded (already
	// a Go value) so marshalling the notification doesn't require a
	// re-parse step.
	Patch any
}

type Response struct {
	JSONRPC string    `json:"jsonrpc"`
	ID      any       `json:"id,omitempty"`
	Method  string    `json:"method,omitempty"`
	Result  any       `json:"result,omitempty"`
	Error   *RPCError `json:"error,omitempty"`
}

type Server struct {
	Version      string
	Enforcement  Enforcement                     // nil = no filtering or enforcement
	Activator    Activator                       // nil = activation unrestricted
	ToolTimeout  time.Duration                   // per-call timeout; 0 = default 45s
	ReadyChecker func(ctx context.Context) error // optional upstream health check for /ready

	// ResourceProvider backs resources/* method handlers. nil disables the
	// resources capability (server omits it from initialize.result.capabilities).
	ResourceProvider ResourceProvider

	// MaxInFlightToolCalls bounds the number of concurrently-running
	// tools/call goroutines spawned by the stdio dispatch loop.
	// Acquired before the goroutine is created so bursty input cannot
	// amplify goroutine count. 0 = unlimited.
	MaxInFlightToolCalls int
	MaxMessageSize       int64

	// StrictHostCheck enables DNS rebinding protection on the HTTP
	// transport: the inbound Host header must match either a loopback
	// literal or one of the configured allowed-origin hostnames. Defaults
	// to off so that reverse-proxy deployments that rewrite Host are
	// unaffected; flip on (MCP_STRICT_HOST_CHECK=1) in localhost-bound
	// production deployments to get the strict guarantee.
	StrictHostCheck bool

	// ExtraHTTPHandlers carries optional handlers that the legacy HTTP
	// transport mounts on its mux before ListenAndServe. Used by the
	// -tags=pprof build in cmd/clockify-mcp/ to attach /debug/pprof/*
	// without forcing internal/mcp to depend on net/http/pprof. nil or
	// empty = no extras registered, which is the default production path.
	ExtraHTTPHandlers []ExtraHandler

	Auditor        Auditor
	AuditTenantID  string
	AuditSubject   string
	AuditSessionID string
	AuditTransport string

	// AuditDurabilityMode controls what happens when audit persistence fails
	// for a non-read-only successful tool call.
	//
	//   "best_effort" (default): log the error and increment the failure metric;
	//   do not fail the tool call. The mutation already happened; the operator
	//   is alerted but the client sees success.
	//
	//   "fail_closed": return an error to the caller so the client knows the
	//   mutation's audit trail is incomplete. The mutation still happened, but
	//   reporting success when the audit write failed is suppressed.
	//   Read-only operations are never affected regardless of this setting.
	AuditDurabilityMode string
	// contains filtered or unexported fields
}

type StreamableHTTPOptions struct {
	Version string
	Bind    string
	// Listener, if non-nil, is used in place of net.Listen("tcp", Bind).
	// Primarily for tests that need to know the bound port before the
	// server starts accepting. Bind is still consulted for the logged
	// startup address when Listener is nil.
	Listener        net.Listener
	MaxBodySize     int64
	AllowedOrigins  []string
	AllowAnyOrigin  bool
	StrictHostCheck bool
	SessionTTL      time.Duration
	ReadyChecker    func(context.Context) error
	Authenticator   authn.Authenticator
	ControlPlane    controlplane.Store
	Factory         StreamableSessionFactory
	// ProtectedResource is the unauthenticated handler for the
	// /.well-known/oauth-protected-resource metadata document. When
	// non-nil it is mounted at the canonical RFC 9728 path. nil =
	// endpoint omitted (e.g. server does not advertise OAuth 2.1
	// resource discovery).
	ProtectedResource http.Handler
	// ExtraHandlers mounts optional handlers on the streamable HTTP
	// mux before ListenAndServe — counterpart to Server.ExtraHTTPHandlers
	// for the streamable transport. Used by -tags=pprof to attach
	// /debug/pprof/* alongside /mcp. nil = no extras, default path.
	ExtraHandlers []ExtraHandler
	// IdleGraceAfterDisconnect is the maximum time a session with zero
	// active SSE subscribers may sit before the reaper evicts it early.
	// Guards against orphaned-subscriber leaks where a client drops TCP
	// mid-stream without DELETEing the session: SessionTTL alone would
	// hold the entry for up to 30 minutes. Zero uses the 5 minute default.
	IdleGraceAfterDisconnect time.Duration
}

type StreamableSessionFactory func(context.Context, authn.Principal, string) (*StreamableSessionRuntime, error)

type StreamableSessionRuntime struct {
	Server          *Server
	Close           func()
	TenantID        string
	WorkspaceID     string
	ClockifyBaseURL string
}

type Tool struct {
	Name         string         `json:"name"`
	Description  string         `json:"description"`
	InputSchema  map[string]any `json:"inputSchema,omitempty"`
	OutputSchema map[string]any `json:"outputSchema,omitempty"`
	Annotations  map[string]any `json:"annotations,omitempty"`
}

type ToolCallParams struct {
	Name      string         `json:"name"`
	Arguments map[string]any `json:"arguments,omitempty"`
	Meta      *RequestMeta   `json:"_meta,omitempty"`
}

type ToolDescriptor struct {
	Tool            Tool
	Handler         ToolHandler
	ReadOnlyHint    bool
	DestructiveHint bool
	IdempotentHint  bool
}

type ToolHandler func(context.Context, map[string]any) (any, error)

type ToolHints struct {
	ReadOnly    bool
	Destructive bool
	Idempotent  bool
}