httpapi

type AddServerRequest struct {
	Name           string             `json:"name"`
	URL            string             `json:"url,omitempty"`
	Command        string             `json:"command,omitempty"`
	Args           []string           `json:"args,omitempty"`
	Env            map[string]*string `json:"env,omitempty"`
	Headers        map[string]*string `json:"headers,omitempty"`
	WorkingDir     string             `json:"working_dir,omitempty"`
	Protocol       string             `json:"protocol,omitempty"`
	Enabled        *bool              `json:"enabled,omitempty"`
	Quarantined    *bool              `json:"quarantined,omitempty"`
	ReconnectOnUse *bool              `json:"reconnect_on_use,omitempty"`
	// AutoApproveToolChanges is the per-server intent to auto-approve
	// new/changed tools past the trust baseline (MCP-2930). Tri-state *bool:
	// a nil pointer means "leave unchanged" on PATCH; a present value
	// (including false) is applied. Mirrors config.ServerConfig's *bool
	// semantics — do NOT collapse to a plain bool, or an omitted field would
	// silently reset a previously-set value.
	AutoApproveToolChanges *bool `json:"auto_approve_tool_changes,omitempty"`
	// TrustMode is the per-server trust tier (spec 086): "auto", "scan", or
	// "manual". Empty means "leave unchanged" on PATCH (and inherit the migrated
	// default on create). A non-empty value is applied to ServerConfig.TrustMode
	// and resolved by EffectiveTrustMode (an unrecognized value fails closed to
	// manual). This is the REST seam for changing the trust tier via
	// POST/PATCH /api/v1/servers.
	TrustMode string `json:"trust_mode,omitempty"`
	// InitTimeout is the per-server MCP `initialize` handshake deadline override
	// (MCP-3322 / GH #760), serialized as a duration string (e.g. "120s"). A nil
	// pointer means "leave unchanged" on PATCH; a present value is applied.
	// Mirrors config.ServerConfig.InitTimeout's *Duration tri-state.
	InitTimeout *config.Duration `json:"init_timeout,omitempty" swaggertype:"string"`
	// Isolation carries per-server Docker isolation overrides (image,
	// network_mode, extra_args, working_dir, enabled). A nil pointer
	// means "do not touch isolation config"; an empty-but-present
	// object on PATCH intentionally clears the overrides.
	Isolation *IsolationRequest `json:"isolation,omitempty"`
}

type CanonicalConfigPath struct {
	Name        string `json:"name"`        // Display name (e.g., "Claude Desktop")
	Format      string `json:"format"`      // Format identifier (e.g., "claude_desktop")
	Path        string `json:"path"`        // Full path to the config file
	Exists      bool   `json:"exists"`      // Whether the file exists
	OS          string `json:"os"`          // Operating system (darwin, windows, linux)
	Description string `json:"description"` // Brief description
}

type CanonicalConfigPathsResponse struct {
	OS    string                `json:"os"`    // Current operating system
	Paths []CanonicalConfigPath `json:"paths"` // List of canonical config paths
}

type CodeExecError struct {
	Message string `json:"message"`
	Code    string `json:"code"`
}

type CodeExecHandler struct {
	// contains filtered or unexported fields
}

type CodeExecOptions struct {
	TimeoutMS      int      `json:"timeout_ms"`
	MaxToolCalls   int      `json:"max_tool_calls"`
	AllowedServers []string `json:"allowed_servers"`
}

type CodeExecRequest struct {
	Code     string                 `json:"code"`
	Language string                 `json:"language,omitempty"` // "javascript" (default) or "typescript"
	Input    map[string]interface{} `json:"input"`
	Options  CodeExecOptions        `json:"options"`
}

type CodeExecResponse struct {
	OK        bool                   `json:"ok"`
	Result    interface{}            `json:"result,omitempty"`
	Error     *CodeExecError         `json:"error,omitempty"`
	Stats     map[string]interface{} `json:"stats,omitempty"`
	RequestID string                 `json:"request_id,omitempty"` // T016: Added for error correlation
}

type ConnectConflictResponse struct {
	Success bool                  `json:"success"` // Always false
	Data    connect.ConnectResult `json:"data"`    // The full result; its action mirrors the top-level one
	Error   string                `json:"error"`   // Human-readable message
	Action  string                `json:"action"`  // already_exists | precondition_failed
}

type ConnectRequest struct {
	ServerName string `json:"server_name,omitempty"` // Defaults to "mcpproxy"
	Force      bool   `json:"force,omitempty"`       // Overwrite existing entry
	// PreconditionToken is the opaque token from the preview this write was
	// confirmed against (Spec 091 FR-005). When present, the core rechecks it
	// at write time and responds 409 with action "precondition_failed" —
	// writing nothing — if the config or the entry MCPProxy would write has
	// drifted since; the caller then re-previews instead of retrying. Absent
	// means exactly the pre-091 behavior. A replace-classified flow sends this
	// TOGETHER with force=true: the token, not the absence of force, is the
	// overwrite safety.
	PreconditionToken string `json:"precondition_token,omitempty"`
}

type FeedbackSubmitter interface {
	SubmitFeedback(ctx context.Context, req *telemetry.FeedbackRequest) (*telemetry.FeedbackResponse, error)
}

type ImportFromPathRequest struct {
	Path        string   `json:"path"`                   // File path to import from
	Format      string   `json:"format,omitempty"`       // Optional format hint
	ServerNames []string `json:"server_names,omitempty"` // Optional: import only these servers
	// Rename maps a server name → new name. Applied after parsing so the
	// caller can disambiguate cross-source name collisions (Spec 046 v2 —
	// e.g. "mcpproxy" → "mcpproxy_claude_code"). Keys are matched against
	// either the raw source name (OriginalName) or the sanitized name shown
	// in the preview (Server.Name); these differ for names that need
	// sanitizing (e.g. "Figma Desktop" → "Figma_Desktop"). Keys not present
	// in the imported set are ignored.
	Rename map[string]string `json:"rename,omitempty"`
}

type ImportRequest struct {
	Content     string   `json:"content"`                // Raw JSON or TOML content
	Format      string   `json:"format,omitempty"`       // Optional format hint
	ServerNames []string `json:"server_names,omitempty"` // Optional: import only these servers
}

type ImportResponse struct {
	Format     string                       `json:"format"`
	FormatName string                       `json:"format_name"`
	Summary    configimport.ImportSummary   `json:"summary"`
	Imported   []ImportedServerResponse     `json:"imported"`
	Skipped    []configimport.SkippedServer `json:"skipped"`
	Failed     []configimport.FailedServer  `json:"failed"`
	Warnings   []string                     `json:"warnings"`
}

type ImportedServerResponse struct {
	Name          string   `json:"name"`
	Protocol      string   `json:"protocol"`
	URL           string   `json:"url,omitempty"`
	Command       string   `json:"command,omitempty"`
	Args          []string `json:"args,omitempty"`
	SourceFormat  string   `json:"source_format"`
	OriginalName  string   `json:"original_name"`
	FieldsSkipped []string `json:"fields_skipped,omitempty"`
	Warnings      []string `json:"warnings,omitempty"`
}

type IsolationRequest struct {
	Enabled     *bool     `json:"enabled,omitempty"`
	Image       *string   `json:"image,omitempty"`
	NetworkMode *string   `json:"network_mode,omitempty"`
	ExtraArgs   *[]string `json:"extra_args,omitempty"`
	WorkingDir  *string   `json:"working_dir,omitempty"`
}

type OnboardingMarkRequest struct {
	// Engaged marks the wizard as engaged (completed or explicitly skipped).
	// Once true, the wizard does not auto-show again.
	Engaged bool `json:"engaged"`

	// ConnectStepStatus is one of: "", "completed", "skipped". Empty
	// preserves the existing value. The stored enum is wider (Spec 080
	// FR-001): a "skipped" request for a previously untouched connect step
	// is upgraded server-side to "completed_external" when the install
	// shows positive evidence of an external connection (Spec 080 FR-002).
	// "completed_external" is NOT accepted from clients — it must never be
	// persisted without that server-verified evidence (edge case: "never
	// guess completed_external without positive evidence").
	ConnectStepStatus string `json:"connect_step_status,omitempty"`

	// ServerStepStatus is one of: "", "completed", "skipped". Empty
	// preserves the existing value.
	ServerStepStatus string `json:"server_step_status,omitempty"`

	// MarkShown records the wizard's first display time if not already set.
	MarkShown bool `json:"mark_shown,omitempty"`
}

type OnboardingStateResponse struct {
	// HasConnectedClient is true if at least one supported AI client currently
	// has mcpproxy registered in its config.
	HasConnectedClient bool `json:"has_connected_client"`

	// HasConfiguredServer is true if at least one upstream MCP server is
	// configured (regardless of current connection health).
	HasConfiguredServer bool `json:"has_configured_server"`

	// ConnectedClientCount is the number of supported clients currently
	// pointing at mcpproxy.
	ConnectedClientCount int `json:"connected_client_count"`

	// ConnectedClientIDs are the identifiers of supported clients currently
	// pointing at mcpproxy. Drawn exclusively from the fixed adapter table —
	// user-entered values never appear here.
	ConnectedClientIDs []string `json:"connected_client_ids"`

	// ConfiguredServerCount is the number of upstream MCP servers configured
	// in mcpproxy (counts both enabled and disabled).
	ConfiguredServerCount int `json:"configured_server_count"`

	// State is the persisted wizard engagement record. Engaged is true once
	// the wizard was shown and the user completed or skipped it.
	State storage.OnboardingState `json:"state"`

	// ShouldShowWizard is the derived flag the frontend uses to decide
	// whether to auto-show. True when not engaged and IncompleteTabCount > 0
	// (Spec 046 v2 — semantics widened to also count the Verify tab).
	ShouldShowWizard bool `json:"should_show_wizard"`

	// FirstMCPClientEver is true once any MCP client has successfully completed
	// an `initialize` round-trip with this mcpproxy. Sourced from the Spec 044
	// activation bucket. Drives the Verify tab's "green check" state.
	FirstMCPClientEver bool `json:"first_mcp_client_ever"`

	// MCPClientsSeenEver is the capped list of recognized client names that
	// have ever called this mcpproxy. Names come from the MCP `initialize`
	// payload's `clientInfo.name` field, sanitized. Surfaces on the Verify tab
	// so the user can see whether their real IDE — not a test client — has
	// connected.
	MCPClientsSeenEver []string `json:"mcp_clients_seen_ever"`

	// IncompleteTabCount is the number of wizard tabs whose state is incomplete.
	// Drives the sidebar Setup entry's badge. Formula:
	//   +1 if HasConnectedClient == false
	//   +1 if HasConfiguredServer == false
	//   +1 if FirstMCPClientEver == false
	IncompleteTabCount int `json:"incomplete_tab_count"`
}

type ProfileSummary struct {
	Name      string   `json:"name"`
	Servers   []string `json:"servers"`
	ToolCount int      `json:"tool_count"`
}

type RegistryGetter func() *telemetry.CounterRegistry

type SecurityController interface {
	ListScanners(ctx context.Context) ([]*scanner.ScannerPlugin, error)
	InstallScanner(ctx context.Context, id string) error
	RemoveScanner(ctx context.Context, id string) error
	ConfigureScanner(ctx context.Context, id string, env map[string]string, dockerImage string) error
	GetScannerStatus(ctx context.Context, id string) (*scanner.ScannerPlugin, error)

	StartScan(ctx context.Context, serverName string, dryRun bool, scannerIDs []string, sourceDir string) (*scanner.ScanJob, error)
	GetScanStatus(ctx context.Context, serverName string) (*scanner.ScanJob, error)
	GetScanStatusByPass(ctx context.Context, serverName string, pass int) (*scanner.ScanJob, error)
	GetScanReport(ctx context.Context, serverName string) (*scanner.AggregatedReport, error)
	CancelScan(ctx context.Context, serverName string) error

	ApproveServer(ctx context.Context, serverName string, force bool, approvedBy string) error
	RejectServer(ctx context.Context, serverName string) error
	CheckIntegrity(ctx context.Context, serverName string) (*scanner.IntegrityCheckResult, error)

	GetSecurityOverview(ctx context.Context) (*scanner.SecurityOverview, error)
	GetScanSummary(ctx context.Context, serverName string) *scanner.ScanSummary

	// DeepScanEnabled reports whether the opt-in deep-scan layer
	// (security.deep_scan.enabled, Spec 077 US3) is currently on. Used to warn
	// when a Docker-based scanner is enabled while the layer that would run it
	// is off (audit FIX 3b).
	DeepScanEnabled() bool

	// Batch scan operations
	ScanAll(ctx context.Context, servers []scanner.ServerStatus, scannerIDs []string) (*scanner.QueueProgress, error)
	GetQueueProgress() *scanner.QueueProgress
	CancelAllScans() error
	IsQueueRunning() bool

	// Scan history
	ListScanHistory(ctx context.Context) ([]scanner.ScanJobSummary, error)
	GetScanReportByJobID(ctx context.Context, jobID string) (*scanner.AggregatedReport, error)
}

type Server struct {
	// contains filtered or unexported fields
}

type ServerController interface {
	IsRunning() bool
	IsReady() bool
	GetListenAddress() string
	GetUpstreamStats() map[string]interface{}
	StartServer(ctx context.Context) error
	StopServer() error
	GetStatus() interface{}
	StatusChannel() <-chan interface{}
	EventsChannel() <-chan internalRuntime.Event
	// SubscribeEvents creates a new per-client event subscription channel.
	// Each SSE client should get its own channel to avoid competing for events.
	SubscribeEvents() chan internalRuntime.Event
	// UnsubscribeEvents closes and removes the subscription channel.
	UnsubscribeEvents(chan internalRuntime.Event)

	// Server management
	GetAllServers() ([]map[string]interface{}, error)
	AddServer(ctx context.Context, serverConfig *config.ServerConfig) error // T001: Add server
	RemoveServer(ctx context.Context, serverName string) error              // T002: Remove server
	UpdateServer(ctx context.Context, serverName string, updates *config.ServerConfig) error
	EnableServer(serverName string, enabled bool) error
	GetToolApprovalStatus(serverName, toolName string) (string, error)
	RestartServer(serverName string) error
	ForceReconnectAllServers(reason string) error
	GetDockerRecoveryStatus() *storage.DockerRecoveryState
	// IsDockerAvailable reports genuine Docker daemon reachability via a real
	// probe (not the synthetic recovery-state value returned when isolation is
	// off). Used by /api/v1/docker/status — see MCP-2478.
	IsDockerAvailable() bool
	QuarantineServer(serverName string, quarantined bool) error
	GetQuarantinedServers() ([]map[string]interface{}, error)
	UnquarantineServer(serverName string) error
	GetManagementService() interface{} // Returns the management service for unified operations
	DiscoverServerTools(ctx context.Context, serverName string) error

	// Tools and search
	GetServerTools(serverName string) ([]map[string]interface{}, error)
	SearchTools(query string, limit int) ([]map[string]interface{}, error)

	// Logs
	GetServerLogs(serverName string, tail int) ([]contracts.LogEntry, error)

	// Config and OAuth
	ReloadConfiguration() error
	GetConfigPath() string
	GetLogDir() string
	TriggerOAuthLogin(serverName string) error

	// Secrets management
	GetSecretResolver() *secret.Resolver
	GetCurrentConfig() interface{}
	NotifySecretsChanged(ctx context.Context, operation, secretName string) error

	// Tool call history
	GetToolCalls(limit, offset int) ([]*contracts.ToolCallRecord, int, error)
	GetToolCallByID(id string) (*contracts.ToolCallRecord, error)
	GetServerToolCalls(serverName string, limit int) ([]*contracts.ToolCallRecord, error)
	ReplayToolCall(id string, arguments map[string]interface{}) (*contracts.ToolCallRecord, error)
	GetToolCallsBySession(sessionID string, limit, offset int) ([]*contracts.ToolCallRecord, int, error)

	// Session management. status filters on session status ("active" /
	// "closed"); an empty string means no filter.
	GetRecentSessions(limit int, status string) ([]*contracts.MCPSession, int, error)
	GetSessionByID(sessionID string) (*contracts.MCPSession, error)

	// Configuration management
	ValidateConfig(cfg *config.Config) ([]config.ValidationError, error)
	ApplyConfig(cfg *config.Config, cfgPath string) (*internalRuntime.ConfigApplyResult, error)
	GetConfig() (*config.Config, error)
	// DefaultInstructions returns the built-in default MCP instructions text
	// (independent of any user-configured custom value), so /api/v1/status can
	// surface it to the Web UI as the instructions placeholder (MCP-2176).
	DefaultInstructions() string

	// Token statistics
	GetTokenSavings() (*contracts.ServerTokenMetrics, error)

	// Tool execution
	CallTool(ctx context.Context, toolName string, arguments map[string]interface{}) (interface{}, error)

	// Registry browsing (Phase 7)
	ListRegistries() ([]interface{}, error)
	// SearchRegistryServers returns the registry's servers plus a cache
	// freshness indicator (spec 070 FR-007). A registry requiring an
	// unconfigured key surfaces as a wrapped registries.ErrRegistryKeyMissing.
	SearchRegistryServers(registryID, tag, query string, limit int) ([]interface{}, *contracts.RegistryCacheInfo, error)
	// RefreshRegistryCache drops a registry's cached server lists (FR-007).
	RefreshRegistryCache(registryID string) (int, error)
	// AddServerFromRegistryRef resolves a registry reference server-side and
	// persists it quarantined (spec 070 keystone). On failure it returns a
	// stable cross-surface error code (*contracts.RegistryAddError) alongside
	// the raw error so the handler can map code → HTTP status.
	AddServerFromRegistryRef(ctx context.Context, registryID, serverID, name string, env map[string]string, enabled *bool) (*config.ServerConfig, *contracts.RegistryAddError, error)
	// AddRegistrySourceRef adds a user-supplied generic registry source
	// (MCP-866), always tagged custom/unverified. On failure it returns a stable
	// cross-surface error code alongside the raw error.
	AddRegistrySourceRef(url, protocol, id, name string) (*config.RegistryEntry, *contracts.RegistryAddError, error)
	// RemoveRegistrySourceRef removes a user-added custom registry source
	// (MCP-1057). Built-ins are refused (registry_shadows_builtin) and an unknown
	// id yields registry_not_found. On failure it returns a stable cross-surface
	// error code alongside the raw error.
	RemoveRegistrySourceRef(id string) (*config.RegistryEntry, *contracts.RegistryAddError, error)
	// EditRegistrySourceRef updates a user-added custom registry source
	// (MCP-1072): name, url, servers-url. Built-ins are refused
	// (registry_shadows_builtin), an unknown id yields registry_not_found, and a
	// non-https url yields invalid_registry_url. On failure it returns a stable
	// cross-surface error code alongside the raw error.
	EditRegistrySourceRef(id, name, url, serversURL string) (*config.RegistryEntry, *contracts.RegistryAddError, error)

	// Version and updates
	GetVersionInfo() *updatecheck.VersionInfo
	RefreshVersionInfo() *updatecheck.VersionInfo

	// Activity logging (RFC-003)
	ListActivities(filter storage.ActivityFilter) ([]*storage.ActivityRecord, int, error)
	GetActivity(id string) (*storage.ActivityRecord, error)
	StreamActivities(filter storage.ActivityFilter) <-chan *storage.ActivityRecord
	// AggregateToolUsage rolls up tool_call activity per (server,tool) since the
	// given time. Backs the global tools page usage columns (spec 050).
	AggregateToolUsage(since time.Time) (map[string]storage.ToolUsageStat, error)
	// UsageSnapshot returns the actor-owned in-memory usage aggregate snapshot
	// (spec 069 A2). The /api/v1/activity/usage endpoint reads it without a
	// full-log scan (SC-005). May be nil before the activity service is ready.
	UsageSnapshot() *internalRuntime.UsageAggregate

	// Tool-level quarantine (Spec 032)
	ListToolApprovals(serverName string) ([]*storage.ToolApprovalRecord, error)
	ApproveTools(serverName string, toolNames []string, approvedBy string) error
	ApproveAllTools(serverName string, approvedBy string) (int, error)
	// BlockTools / BlockAllTools atomically approve+disable tools (MCP-2198):
	// all-or-nothing so a tool is never left approved+enabled.
	BlockTools(serverName string, toolNames []string, blockedBy string) (int, error)
	BlockAllTools(serverName string, blockedBy string) (int, error)
	GetToolApproval(serverName, toolName string) (*storage.ToolApprovalRecord, error)

	// Onboarding wizard (Spec 046)
	GetOnboardingState() (*storage.OnboardingState, error)
	SaveOnboardingState(state *storage.OnboardingState) error

	// Activation state (Spec 044) — read-only access used by the v2
	// onboarding wizard's Verify tab to detect whether any MCP client has
	// successfully called this mcpproxy. Returns FirstMCPClientEver and
	// MCPClientsSeenEver from the activation bucket.
	GetActivationFirstMCPClient() (firstEver bool, seen []string)
}

type ServerNameLister interface {
	GetAllServers() ([]map[string]interface{}, error)
}

type SetActiveProfileRequest struct {
	Profile       *string `json:"profile,omitempty"`
	ActiveProfile *string `json:"active_profile,omitempty"`
}

type TokenStore interface {
	CreateAgentToken(token auth.AgentToken, rawToken string, hmacKey []byte) error
	ListAgentTokens() ([]auth.AgentToken, error)
	GetAgentTokenByName(name string) (*auth.AgentToken, error)
	RevokeAgentToken(name string) error
	DeleteAgentToken(name string) error
	RegenerateAgentToken(name string, newRawToken string, hmacKey []byte) (*auth.AgentToken, error)
	ValidateAgentToken(rawToken string, hmacKey []byte) (*auth.AgentToken, error)
	UpdateAgentTokenLastUsed(name string) error
}

type ToolCaller interface {
	CallTool(ctx context.Context, toolName string, arguments map[string]interface{}) (interface{}, error)
}

type UndoConnectRequest struct {
	ServerName string `json:"server_name,omitempty"` // Defaults to "mcpproxy"
	// BackupName is the bare filename (filepath.Base) of the backup returned as
	// backup_path by the preceding connect — a name, never a path. Undo resolves
	// the full path server-side by joining it with the client's own config
	// directory, so a client-supplied value can never contribute a directory
	// component (traversal is impossible by construction). Empty means the
	// connect created the file (no prior file existed), so undo removes it.
	BackupName string `json:"backup_name,omitempty"`
}