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)
	// OnDeactivate is called when dynamically registered tools are removed.
	OnDeactivate(names []string)
}

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

type AuditPhase = 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 HTTPAdmissionLimits struct {
	PerIPPerMinute        int
	PerPrincipalPerMinute int
	SSEPerSession         int
}

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 PanicResponseSink func(Response)

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 RiskClass uint32

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
	// DefaultProtocolVersion is used only when initialize omits
	// params.protocolVersion. Empty or unsupported values fall back to
	// SupportedProtocolVersions[0]; explicit supported client requests still win.
	DefaultProtocolVersion string
	ReadyChecker           func(ctx context.Context) error // optional upstream health check for /ready
	// ExposeAuthErrors controls whether HTTP transports return detailed
	// authenticator errors to unauthenticated clients. The default is false:
	// transports return a generic OAuth error_description and log details
	// server-side only.
	ExposeAuthErrors bool

	// SanitizeUpstreamErrors controls whether tool-error responses to MCP
	// clients omit upstream Clockify response bodies. The default is false
	// (verbose, useful for local development); hosted profiles
	// (shared-service, prod-postgres) set it to true so a 4xx from
	// Clockify can't leak per-tenant info across tenant boundaries.
	// The full APIError is always logged server-side regardless.
	SanitizeUpstreamErrors bool

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

	// BehindHTTPSProxy lets the baseline-header middleware emit
	// Strict-Transport-Security on plaintext responses because a
	// trusted upstream proxy is terminating TLS for us. Without TLS
	// in front of the listener and without this flag, HSTS is skipped
	// to avoid making honest http:// URLs unreachable on misconfigured
	// dev installs. Wired from MCP_BEHIND_HTTPS_PROXY=1.
	BehindHTTPSProxy bool

	// HTTPAdmissionLimits configures process-local app-layer admission
	// guards for legacy HTTP. Streamable HTTP receives the same values
	// through StreamableHTTPOptions.
	HTTPAdmissionLimits HTTPAdmissionLimits

	// 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 tool call.
	//
	//   "best_effort" (default): log the error and increment the failure metric;
	//   do not fail the tool call.
	//
	//   "fail_closed": fail before mutation when the intent record cannot be
	//   persisted; post-mutation outcome failures stay log/metric-only for
	//   backwards compatibility.
	//
	//   "fail_closed_strict": same pre-mutation intent guard, plus post-mutation
	//   outcome failures are returned to the client so the missing durable
	//   outcome row is visible on the MCP wire.
	//
	//   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
	// ExposeAuthErrors controls whether unauthenticated clients receive
	// detailed authenticator failure reasons. Default false returns a
	// generic OAuth error_description and logs details server-side only.
	ExposeAuthErrors bool
	// SanitizeUpstreamErrors controls whether tool errors returned to
	// MCP clients omit upstream Clockify response bodies. Default false
	// (verbose, useful for local development); hosted profiles flip it
	// on so upstream payloads cannot cross tenant boundaries.
	SanitizeUpstreamErrors 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
	// POSTWriteTimeout bounds writes for request/response POST /mcp calls.
	// The http.Server keeps WriteTimeout=0 so long-lived SSE streams are not
	// severed; this per-request deadline keeps stalled POST clients from
	// pinning a handler indefinitely. Zero uses
	// defaultStreamablePOSTWriteTimeout.
	POSTWriteTimeout time.Duration
	// 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
	// TLSConfig, when non-nil, wraps the bound listener with tls.NewListener
	// so the streamable HTTP transport terminates TLS in-process. Required
	// when the operator selects MCP_AUTH_MODE=mtls on streamable_http —
	// without TLS, the mTLS authenticator has no VerifiedChains to read
	// from r.TLS and every request fails with "verified mTLS client
	// certificate required". When nil, the listener serves plain HTTP
	// (the long-standing default for this transport).
	TLSConfig *tls.Config
	// BehindHTTPSProxy, when true, lets the baseline-header middleware
	// emit Strict-Transport-Security on plaintext responses because a
	// trusted upstream proxy is terminating TLS for us. Without TLS in
	// front of the listener and without this flag, HSTS is skipped to
	// avoid making honest http:// URLs unreachable on misconfigured
	// dev installs. Wired from MCP_BEHIND_HTTPS_PROXY=1.
	BehindHTTPSProxy bool
	// AdmissionLimits configures process-local HTTP admission guards for
	// POST /mcp and GET /mcp. These limits protect the application before
	// JSON-RPC dispatch; multi-replica hosted deployments still need
	// cross-replica gateway limits.
	AdmissionLimits HTTPAdmissionLimits
	// MaxSessionsPerReplica caps the number of active streamable_http
	// sessions on this replica. initialize requests beyond the cap return
	// HTTP 503 with Retry-After. 0 = unlimited (matches the legacy
	// behaviour before this knob existed). Pair with MaxSessionsPerPrincipal
	// to prevent a single tenant from starving the pool.
	MaxSessionsPerReplica int
	// MaxSessionsPerPrincipal caps active sessions per authenticated
	// (tenant_id, subject) on this replica. initialize requests beyond
	// the cap return HTTP 429 with Retry-After so a tenant-internal
	// retry loop can back off without affecting other tenants. 0 =
	// unlimited.
	MaxSessionsPerPrincipal int
	// RequireProtocolVersionHeader, when true, rejects post-initialize
	// streamable HTTP requests that omit Mcp-Protocol-Version. Default false
	// preserves compatibility with older clients while still counting missing
	// headers for operator migration visibility.
	RequireProtocolVersionHeader bool
	// DefaultProtocolVersion is the fallback initialize protocolVersion when a
	// client omits params.protocolVersion. Empty means newest supported.
	DefaultProtocolVersion string
}

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
	// RiskClass is the structured risk taxonomy; defaults are derived from
	// the boolean hints in normalizeDescriptors when this field is zero.
	// Tier-2 tools that need finer granularity than read/write/destructive
	// (billing, admin, permission_change, external_side_effect) override it
	// in internal/tools/risk_overrides.go.
	RiskClass RiskClass
	// AuditKeys lists argument keys (beyond the implicit *_id suffix scan)
	// whose values must be captured in audit events. Used for action-defining
	// fields like role, status, quantity, unit_price.
	AuditKeys []string
}

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

type ToolHints struct {
	ReadOnly    bool
	Destructive bool
	Idempotent  bool
	// AuditKeys is forwarded from ToolDescriptor.AuditKeys so the audit
	// recorder can capture action-defining argument values (role, status,
	// quantity, unit_price, …) beyond the implicit *_id suffix scan in
	// resourceIDs. Empty for tools whose argument shape is fully
	// described by *_id keys.
	AuditKeys []string
	// RiskClass is the bitmask risk taxonomy populated on every
	// ToolDescriptor by internal/tools/applyRiskMetadata. It is forwarded
	// here so Enforcement.FilterTool / BeforeCall can make policy
	// decisions on bits (RiskBilling, RiskAdmin, RiskPermissionChange,
	// RiskExternalSideEffect, RiskDestructive) rather than re-deriving
	// the class from the tool name string. This is the Q3 prerequisite
	// from docs/adr/0018-risk-class-confirmation-tokens.md — it adds
	// no behaviour today, just the surface that future
	// confirmation-token or risk-bit-aware gates will consume. Zero
	// means "no risk classification available" (legacy callers that
	// build the literal without a descriptor).
	RiskClass RiskClass
}

type UnknownToolError struct {
	Name string
}