mcpmanager

package
v0.2.3 Latest Latest
Warning

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

 Go to latest Published: Jul 13, 2026 License: MIT Imports: 24 Imported by: 0

Documentation

Overview

Package mcpmanager manages MCP server resources declared in agent policy.

Index

Constants

View Source 
const (
	ReadinessStopped   = "stopped"
	ReadinessStarting  = "starting"
	ReadinessReady     = "ready"
	ReadinessUnhealthy = "unhealthy"
)

Readiness states for MCP servers.

View Source 
const (
	HealthUnknown = "unknown"
	HealthHealthy = "healthy"
	HealthFailed  = "failed"
)

Health states for MCP servers.

Variables

View Source 
var ErrServerCrashed = errors.New("mcp server crashed")

ErrServerCrashed indicates a stopped MCP server has crash context.

Functions

func AuditToolCall 

func AuditToolCall(appender audit.AuditAppender, serverID, tool, agentID, runID, decision, policyRuleID, credentialID string, inputHash, outputHash string, timingMS int64)

AuditToolCall records an MCP tool call audit event. decision: "allowed" or "denied" policyRuleID: the policy rule that authorized the call (or "undeclared" if denied) credentialID: the credential used (empty if none)

func AuditToolDenied 

func AuditToolDenied(appender audit.AuditAppender, serverID, tool, agentID, runID, reason, policyRuleID string, metadata ...any)

AuditToolDenied records an MCP tool denial audit event with full metadata.

func IsHostAffecting 

func IsHostAffecting(toolName string) bool

IsHostAffecting returns true if the tool name matches a host-affecting pattern.

func MCPStatusJSON 

func MCPStatusJSON(ctx context.Context, manager *Manager, lifecycle *Lifecycle, driver runtime.RuntimeDriver) ([]byte, error)

MCPStatusJSON returns an encoded MCP status payload suitable for CLI status output.

func RedactToolOutput 

func RedactToolOutput(output any) string

RedactToolOutput sanitizes MCP tool output for safe display/audit. It:

  • Escapes control characters (prevents terminal escape injection)
  • Redacts sentinel secret patterns
  • Truncates excessively long output

Returns the redacted string.

func RedactToolOutputHash 

func RedactToolOutputHash(output any) string

RedactToolOutputHash returns a hash of the redacted output (for audit). Uses the same hashJSONValue function from router.go.

Types

type CrashContext 

type CrashContext struct {
	ServerID    string
	Transport   string
	ExitCode    int
	ExitTime    time.Time
	Error       string
	Recoverable bool
}

CrashContext is structured failure context for a crashed MCP server.

type EgressPolicy 

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

EgressPolicy enforces default-deny outbound network access for MCP servers. MCP servers are separate managed workloads; outbound HTTP requests must be gateway-mediated and policy-checked.

func NewEgressPolicy 

func NewEgressPolicy(rules []policy.EgressRule, appender audit.AuditAppender) *EgressPolicy

NewEgressPolicy creates an EgressPolicy from declared policy egress rules. Rules come from policy.EgressRule entries that reference MCP server IDs.

func (*EgressPolicy) AuditEgress 

func (ep *EgressPolicy) AuditEgress(serverID, destination, method, credentialID, policyRuleID, decision string)

AuditEgress emits an audit event for an egress decision (allowed or denied).

func (*EgressPolicy) CheckEgress 

func (ep *EgressPolicy) CheckEgress(ctx context.Context, serverID, destination, method string) (bool, string, string, error)

CheckEgress validates whether an MCP server may make an outbound request to the given destination with the given method.

type HTTPDoer 

type HTTPDoer interface {
	Do(req *http.Request) (*http.Response, error)
}

HTTPDoer is an interface for making HTTP requests. http.Client satisfies this interface.

type HostAffectingCapability 

type HostAffectingCapability string

HostAffectingCapability classifies tools that can affect the host system. 

const (
	// CapabilityNone means the tool has no host-affecting capability.
	CapabilityNone HostAffectingCapability = "none"
	// CapabilityHostAffecting means the tool can control the host
	// (browser, shell, filesystem, AppleScript, desktop automation).
	CapabilityHostAffecting HostAffectingCapability = "host_affecting"
)

func ClassifyTool 

func ClassifyTool(toolName string) HostAffectingCapability

ClassifyTool returns the host-affecting capability for a tool name. A tool is host-affecting if its name contains any of the hostAffectingToolPatterns substrings (case-insensitive).

type Lifecycle 

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

Lifecycle manages the start/stop/readiness of declared MCP servers. Stdio servers run as child processes; HTTP servers run as Docker sidecar containers. No host networking is used for MCP sidecars.

func NewLifecycle 

func NewLifecycle(manager *Manager, driver runtime.RuntimeDriver, netID string) *Lifecycle

NewLifecycle creates a Lifecycle bound to the given Manager. driver may be nil if only stdio MCP servers will be used. netID is the Docker network ID for MCP sidecars (must NOT be host network).

func (*Lifecycle) CheckReadiness 

func (lc *Lifecycle) CheckReadiness(ctx context.Context, serverID string, timeout time.Duration) error

CheckReadiness polls the MCP server until it is ready or timeout.

func (*Lifecycle) CrashContext 

func (lc *Lifecycle) CrashContext(serverID string) *CrashContext

CrashContext returns structured failure context for a crashed MCP server.

func (*Lifecycle) IsRunning 

func (lc *Lifecycle) IsRunning(serverID string) bool

IsRunning returns true if the MCP server is currently running.

func (*Lifecycle) Start 

func (lc *Lifecycle) Start(ctx context.Context, serverID, agentID, runID string) error

Start launches a declared MCP server.

func (*Lifecycle) StdioPipes 

func (lc *Lifecycle) StdioPipes(serverID string) (io.Writer, <-chan stdioLine, error)

StdioPipes returns the stdin writer and stdout reader for a running stdio MCP server.

func (*Lifecycle) Stop 

func (lc *Lifecycle) Stop(ctx context.Context, serverID string) error

Stop terminates a running MCP server.

func (*Lifecycle) StopAll 

func (lc *Lifecycle) StopAll(ctx context.Context) error

StopAll stops all running MCP servers.

type MCPSidecarInfo 

type MCPSidecarInfo struct {
	ServerID     string            `json:"server_id"`
	ContainerID  string            `json:"container_id,omitempty"`
	ImageDigest  string            `json:"image_digest,omitempty"`
	Labels       map[string]string `json:"labels"`
	Networks     []string          `json:"networks"`
	Health       string            `json:"health"`
	Readiness    string            `json:"readiness"`
	RestartCount int               `json:"restart_count"`
	MemoryBytes  int64             `json:"memory_bytes,omitempty"`
	CPUPercent   float64           `json:"cpu_percent,omitempty"`
	LastError    string            `json:"last_error,omitempty"`
}

MCPSidecarInfo contains Docker artifact metadata for an MCP sidecar.

type Manager 

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

Manager manages declared MCP server resources.

func NewManager 

func NewManager() *Manager

NewManager creates a new MCP manager.

func (*Manager) ConfirmTool 

func (m *Manager) ConfirmTool(serverID, tool string)

ConfirmTool marks a host-affecting tool as confirmed for use. This is the confirmation protocol: host-affecting tools cannot be called until confirmed.

func (*Manager) DenyToolCall 

func (m *Manager) DenyToolCall(appender audit.AuditAppender, serverID, tool, agentID, runID, policyRuleID string)

DenyToolCall records a denied tool call and emits an audit event.

func (*Manager) IsToolAllowed 

func (m *Manager) IsToolAllowed(serverID, tool string) bool

IsToolAllowed returns true if the server exists and the tool is in its allowed list. Empty allowed list denies all tools.

func (*Manager) IsToolConfirmed 

func (m *Manager) IsToolConfirmed(serverID, tool string) bool

IsToolConfirmed returns true if a host-affecting tool has been confirmed.

func (*Manager) Register 

func (m *Manager) Register(servers []policy.MCPServer, agentID, runID string)

Register registers declared MCP servers as managed resources.

func (*Manager) RequiresConfirmation 

func (m *Manager) RequiresConfirmation(serverID, tool string) bool

RequiresConfirmation returns true if a tool is host-affecting and has not yet been confirmed.

func (*Manager) Status 

func (m *Manager) Status() []Resource

Status returns all managed MCP resources.

func (*Manager) Validate 

func (m *Manager) Validate(servers []policy.MCPServer) error

Validate validates declared MCP servers.

type Resource 

type Resource struct {
	ResourceType string   `json:"resource_type"`
	AgentID      string   `json:"agent_id,omitempty"`
	RunID        string   `json:"run_id,omitempty"`
	ServerID     string   `json:"server_id"`
	Transport    string   `json:"transport"`
	AllowedTools []string `json:"allowed_tools"`
	Readiness    string   `json:"readiness"`
	Health       string   `json:"health"`
	LastError    string   `json:"last_error,omitempty"`
	PolicyDigest string   `json:"policy_digest"`
}

Resource represents a managed MCP server resource.

type Router 

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

Router forwards MCP tool calls from the agent to the appropriate local MCP server. Stdio servers receive JSON-RPC over stdin/stdout. HTTP servers receive POST requests to their declared endpoint.

func NewRouter 

func NewRouter(manager *Manager, lifecycle *Lifecycle, gateway HTTPDoer, audit audit.AuditAppender) *Router

NewRouter creates a Router bound to the given Manager and Lifecycle.

func (*Router) CallTool 

func (r *Router) CallTool(ctx context.Context, serverID, tool string, input any, agentID, runID string) (any, error)

CallTool routes an MCP tool call to the appropriate server.

type StatusReport 

type StatusReport struct {
	Resources []Resource       `json:"resources"`
	Sidecars  []MCPSidecarInfo `json:"sidecars,omitempty"`
	Generated time.Time        `json:"generated_at"`
}

StatusReport aggregates MCP resource status for operator visibility. This is the data model included in `agent status --json` and dashboard.

func GenerateStatusReport 

func GenerateStatusReport(ctx context.Context, manager *Manager, lifecycle *Lifecycle, driver runtime.RuntimeDriver) (*StatusReport, error)

GenerateStatusReport produces a StatusReport from the Manager and optionally from Docker runtime data (if driver is provided). If driver is nil, sidecar info is omitted (stdio-only deployments).

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.