mcp

package
v0.4.4 Latest Latest
Warning

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

Go to latest
Published: Oct 28, 2026 License: MIT Imports: 51 Imported by: 0

Documentation

Index

Constants

View Source
const HostedProjectionFallbackRefresh = 3 * time.Second

HostedProjectionFallbackRefresh bounds how long a projection stream waits without a change signal. Some native availability inputs (session and service state) carry no epoch, so streams still re-list at this slow cadence; epoch advances rebuild immediately.

View Source
const (
	// HostedServerName is the single stdio MCP server name injected into ACP sessions.
	HostedServerName = "compozy-hosted-tools"
)

Variables

View Source
var (
	ErrHostedDisabled          = errors.New("mcp: hosted MCP is disabled")
	ErrHostedSessionRequired   = errors.New("mcp: hosted MCP session id is required")
	ErrHostedNonceRequired     = errors.New("mcp: hosted MCP bind nonce is required")
	ErrHostedNonceInvalid      = errors.New("mcp: hosted MCP bind nonce is invalid")
	ErrHostedNonceExpired      = errors.New("mcp: hosted MCP bind nonce expired")
	ErrHostedBindRequired      = errors.New("mcp: hosted MCP bind id is required")
	ErrHostedBindNotFound      = errors.New("mcp: hosted MCP bind not found")
	ErrHostedRunRequired       = errors.New("mcp: hosted MCP active run identity is required")
	ErrHostedPeerInvalid       = errors.New("mcp: hosted MCP peer validation failed")
	ErrHostedBinaryInvalid     = errors.New("mcp: hosted MCP binary validation failed")
	ErrHostedRegistryRequired  = errors.New("mcp: hosted MCP registry is required")
	ErrHostedProjectionChanged = errors.New("mcp: hosted MCP projection changed")
)
View Source
var ErrAuthorizationRequired = errors.New("mcp: remote server requires authorization")

ErrAuthorizationRequired reports that a remote MCP server rejected the current bearer token.

View Source
var ErrPeerCredentialsUnsupported = errors.New("mcp: peer credential validation is unsupported")
View Source
var ErrWindowsPeerCredentialsUnsupported = errors.New(
	"mcp: Windows AF_UNIX peer identity requires SIO_AF_UNIX_GETPEERPID; update Windows to a build supporting this ioctl",
)

Functions

func ContextWithPeerInfo

func ContextWithPeerInfo(ctx context.Context, peer PeerInfo, err error) context.Context

ContextWithPeerInfo annotates an accepted UDS connection context.

func HostAPIProjectionCoverage

func HostAPIProjectionCoverage() []string

HostAPIProjectionCoverage reports methods missing an explicit publish or exclusion decision.

func ProjectedHostAPIMethods

func ProjectedHostAPIMethods() []string

ProjectedHostAPIMethods returns the canonical, ordered Host API subset exposed by MCP serve.

func RunHostedProxy

func RunHostedProxy(ctx context.Context, client HostedProxyClient, opts HostedProxyOptions) error

RunHostedProxy binds to the daemon and serves hosted Compozy tools over MCP stdio.

func ServeHTTP

func ServeHTTP(
	ctx context.Context,
	invoker HostAPIInvoker,
	workspace string,
	listenAddress string,
	token string,
	logger *slog.Logger,
) (err error)

ServeHTTP exposes the projected Host API over token-authenticated loopback streamable HTTP.

func ServeStdio

func ServeStdio(
	ctx context.Context,
	invoker HostAPIInvoker,
	workspace string,
	stdin io.Reader,
	stdout io.Writer,
) (err error)

ServeStdio exposes the projected Host API over MCP stdio.

Types

type CallExecutor

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

CallExecutor lists and calls configured MCP servers through official MCP SDK clients.

func NewMCPCallExecutor

func NewMCPCallExecutor(
	servers ServerResolver,
	opts ...CallExecutorOption,
) (*CallExecutor, error)

NewMCPCallExecutor constructs the daemon-owned MCP executor.

func (*CallExecutor) CallTool

func (e *CallExecutor) CallTool(
	ctx context.Context,
	source toolspkg.SourceRef,
	req toolspkg.MCPToolCallRequest,
) (result toolspkg.ToolResult, err error)

CallTool invokes one configured MCP tool.

func (*CallExecutor) ListTools

func (e *CallExecutor) ListTools(
	ctx context.Context,
	source toolspkg.SourceRef,
) ([]toolspkg.MCPToolDescriptor, error)

ListTools discovers tools from one configured MCP server.

func (*CallExecutor) ListToolsWithProtocol

func (e *CallExecutor) ListToolsWithProtocol(
	ctx context.Context,
	source toolspkg.SourceRef,
) (descriptors []toolspkg.MCPToolDescriptor, protocolVersion string, err error)

ListToolsWithProtocol discovers tools and returns the protocol version negotiated with the server.

func (*CallExecutor) ProjectionGeneration

func (e *CallExecutor) ProjectionGeneration(
	ctx context.Context,
	sources []toolspkg.SourceRef,
) (string, bool)

ProjectionGeneration reports the exact live tool-list cache generation for configured sources.

func (*CallExecutor) Status

func (e *CallExecutor) Status(
	ctx context.Context,
	source toolspkg.SourceRef, definitionOwner string,
) (status toolspkg.MCPAuthStatus, err error)

Status returns token-redacted auth diagnostics for registry availability.

type CallExecutorOption

type CallExecutorOption func(*CallExecutor)

CallExecutorOption configures the daemon-owned MCP executor.

func WithAuthMutationGeneration

func WithAuthMutationGeneration(generation *mcpauth.MutationGeneration) CallExecutorOption

WithAuthMutationGeneration coordinates refresh with settings-owned login and logout.

func WithDataDirCreator

func WithDataDirCreator(create func(string) error) CallExecutorOption

WithDataDirCreator injects the first-launch package data-directory boundary.

func WithHTTPClient

func WithHTTPClient(client *http.Client) CallExecutorOption

WithHTTPClient configures remote MCP HTTP calls with an explicit client.

func WithRuntimeHealthRegistry

func WithRuntimeHealthRegistry(registry *RuntimeHealthRegistry) CallExecutorOption

WithRuntimeHealthRegistry shares restart-local extension MCP health with daemon read surfaces.

func WithSecretLookup

func WithSecretLookup(lookup func(string) string) CallExecutorOption

WithSecretLookup resolves auth client secret environment-variable names.

func WithSecretResolver

func WithSecretResolver(resolver secretRefResolver) CallExecutorOption

WithSecretResolver resolves env: and vault: refs for MCP auth and stdio secret_env launch bindings.

func WithTimeout

func WithTimeout(timeout time.Duration) CallExecutorOption

WithTimeout configures the default bounded call timeout when a caller has no deadline.

func WithTokenStore

func WithTokenStore(store mcpauth.TokenStore) CallExecutorOption

WithTokenStore allows remote MCP authorization headers to be injected inside internal/mcp.

type HostAPIFacade

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

HostAPIFacade binds MCP calls to one resolved workspace before dispatching existing Host API logic.

func NewHostAPIFacade

func NewHostAPIFacade(
	handler *extensionpkg.HostAPIHandler,
	checker *extensionpkg.CapabilityChecker,
	workspaces workspacepkg.RuntimeResolver,
	sourceSessions resources.SourceSessionManager,
) *HostAPIFacade

NewHostAPIFacade constructs the daemon-side MCP projection adapter.

func (*HostAPIFacade) Close

func (f *HostAPIFacade) Close(ctx context.Context) error

Close releases every daemon-local grant and resource source retained by MCP serve clients.

func (*HostAPIFacade) CloseHostAPISession

func (f *HostAPIFacade) CloseHostAPISession(ctx context.Context, serveSessionID string) error

CloseHostAPISession releases one MCP serve client's grant and source-owned resources.

func (*HostAPIFacade) InvokeHostAPI

func (f *HostAPIFacade) InvokeHostAPI(
	ctx context.Context,
	serveSessionID string,
	workspaceRef string,
	method string,
	params json.RawMessage,
) (json.RawMessage, error)

InvokeHostAPI resolves, validates, and binds a projected request before invoking the Host API.

type HostAPIInvokeRequest

type HostAPIInvokeRequest struct {
	ServeSessionID string          `json:"serve_session_id"`
	Workspace      string          `json:"workspace"`
	Method         string          `json:"method"`
	Params         json.RawMessage `json:"params"`
}

HostAPIInvokeRequest is the daemon-internal UDS relay contract for one projected call.

type HostAPIInvokeResponse

type HostAPIInvokeResponse struct {
	Result json.RawMessage `json:"result"`
}

HostAPIInvokeResponse carries the canonical Host API result without reshaping it.

type HostAPIInvoker

type HostAPIInvoker interface {
	InvokeHostAPI(
		ctx context.Context,
		serveSessionID string,
		workspace string,
		method string,
		params json.RawMessage,
	) (json.RawMessage, error)
	CloseHostAPISession(ctx context.Context, serveSessionID string) error
}

HostAPIInvoker dispatches a workspace-bound Host API call through the running daemon.

type HostAPISessionCloseRequest

type HostAPISessionCloseRequest struct {
	ServeSessionID string `json:"serve_session_id"`
}

HostAPISessionCloseRequest identifies one MCP serve client lifecycle to release.

type HostedBindRequest

type HostedBindRequest struct {
	SessionID string `json:"session_id"`
	Nonce     string `json:"bind_nonce"`
}

HostedBindRequest is sent by the stdio proxy immediately after ACP starts it.

type HostedBindResponse

type HostedBindResponse struct {
	BindID string           `json:"bind_id"`
	Scope  tools.Scope      `json:"scope"`
	Tools  []tools.ToolView `json:"tools"`
	Digest string           `json:"digest"`
}

HostedBindResponse proves a hosted proxy has bound to one launch record.

type HostedCallRequest

type HostedCallRequest struct {
	BindID        string          `json:"bind_id"`
	ToolName      string          `json:"tool_name"`
	ToolCallID    string          `json:"tool_call_id,omitempty"`
	CorrelationID string          `json:"correlation_id,omitempty"`
	Input         json.RawMessage `json:"input,omitempty"`
}

HostedCallRequest invokes one hosted MCP tool through the registry.

type HostedCallResponse

type HostedCallResponse struct {
	Result tools.ToolResult `json:"result"`
}

HostedCallResponse carries the canonical registry result envelope.

type HostedConfig

type HostedConfig struct {
	Enabled              bool
	BindNonceTTL         time.Duration
	ExpectedBinary       string
	HomePaths            compozyconfig.HomePaths
	Registry             HostedRegistry
	ProjectionGeneration HostedProjectionGeneration
	// ProjectionEpoch reports the daemon invalidation epoch that forces a stream rebuild without a generation.
	ProjectionEpoch func() uint64
	Logger          *slog.Logger
	Now             func() time.Time
	NonceReader     func([]byte) error

	// ProjectionChanges returns a channel closed by the next daemon epoch advance; streams block on it.
	ProjectionChanges func() <-chan struct{}
	// StreamRefresh is the projection stream fallback re-read interval; zero selects
	// HostedProjectionFallbackRefresh.
	StreamRefresh time.Duration
}

HostedConfig configures hosted MCP launch and bind validation.

type HostedLaunchRequest

type HostedLaunchRequest struct {
	SessionID   string
	ProfileID   string
	WorkspaceID string
	AgentName   string
}

HostedLaunchRequest describes one session-bound MCP launch.

type HostedProjectionChanges

type HostedProjectionChanges struct {
	Epoch    <-chan struct{}
	Released <-chan struct{}
}

HostedProjectionChanges carries signals closed when a bound projection may have changed. A nil channel never fires.

type HostedProjectionGeneration

type HostedProjectionGeneration func(context.Context, tools.Scope) (generation string, known bool)

HostedProjectionGeneration identifies one complete authoritative projection state. Returning known=false keeps projection reads uncached.

type HostedProjectionHandler

type HostedProjectionHandler func(HostedProjectionResponse) error

HostedProjectionHandler receives projection snapshots from the daemon stream.

type HostedProjectionResponse

type HostedProjectionResponse struct {
	Tools  []tools.ToolView `json:"tools"`
	Digest string           `json:"digest"`
}

HostedProjectionResponse is a full session-callable projection snapshot.

type HostedProxyClient

type HostedProxyClient interface {
	BindHostedMCP(ctx context.Context, req HostedBindRequest) (HostedBindResponse, error)
	HostedMCPProjection(ctx context.Context, bindID string) (HostedProjectionResponse, error)
	StreamHostedMCPProjection(
		ctx context.Context,
		bindID string,
		lastDigest string,
		handler HostedProjectionHandler,
	) error
	CallHostedMCP(ctx context.Context, req HostedCallRequest) (HostedCallResponse, error)
	ReleaseHostedMCP(ctx context.Context, req HostedReleaseRequest) error
}

HostedProxyClient is the UDS client surface consumed by the hosted stdio proxy.

type HostedProxyOptions

type HostedProxyOptions struct {
	SessionID string
	Nonce     string
	Stdin     io.Reader
	Stdout    io.Writer
	Stderr    io.Writer
	Version   string
}

HostedProxyOptions configures one `compozy tool mcp` stdio proxy process.

type HostedRegistry

type HostedRegistry func() tools.Registry

HostedRegistry resolves the daemon-owned tool registry at call time.

type HostedReleaseRequest

type HostedReleaseRequest struct {
	BindID string `json:"bind_id"`
}

HostedReleaseRequest releases one active bind record.

type HostedService

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

HostedService owns session-scoped hosted MCP launch and bind lifecycle.

func NewHostedService

func NewHostedService(cfg *HostedConfig) (*HostedService, error)

NewHostedService builds a hosted MCP lifecycle service.

func (*HostedService) ArmLaunch

func (s *HostedService) ArmLaunch(ctx context.Context, sessionID string) (err error)

ArmLaunch starts the first-bind window after the ACP provider has initialized.

func (*HostedService) Bind

func (s *HostedService) Bind(
	ctx context.Context,
	req HostedBindRequest,
	peer PeerInfo,
) (response HostedBindResponse, err error)

Bind consumes an armed launch window after validating the nonce, Unix peer and expected binary.

func (*HostedService) BindRun

func (s *HostedService) BindRun(ctx context.Context, sessionID, runID string, generation int64) error

BindRun installs the authoritative active run identity for a hosted session.

func (*HostedService) Call

Call routes a hosted MCP tool call through the registry dispatch pipeline.

func (*HostedService) CancelLaunch

func (s *HostedService) CancelLaunch(sessionID string)

CancelLaunch removes all hosted state for a failed session start.

func (*HostedService) Launch

Launch mints a session-bound hosted MCP launch record that admits at most one active bind.

func (*HostedService) Projection

func (s *HostedService) Projection(
	ctx context.Context,
	bindID string,
	peer PeerInfo,
) (HostedProjectionResponse, error)

Projection returns the current session-callable tool projection for one bind.

func (*HostedService) ProjectionChanges

func (s *HostedService) ProjectionChanges() HostedProjectionChanges

ProjectionChanges captures the current change signals. Capture them before reading a projection so a change racing that read still wakes the stream.

func (*HostedService) ReleaseBind

func (s *HostedService) ReleaseBind(bindID string)

ReleaseBind removes one active bind record. Releasing the launch's current bind also clears its established state and re-arms the nonce for one replacement proxy within bindNonceTTL.

func (*HostedService) ReleaseBindForPeer

func (s *HostedService) ReleaseBindForPeer(ctx context.Context, bindID string, peer PeerInfo) error

ReleaseBindForPeer removes a bind only after validating the requesting peer still owns it.

func (*HostedService) ReleaseRun

func (s *HostedService) ReleaseRun(sessionID, runID string, generation int64)

ReleaseRun removes a matching active run identity from a hosted session.

func (*HostedService) ReleaseSession

func (s *HostedService) ReleaseSession(sessionID string)

ReleaseSession removes all hosted state for a stopped session.

func (*HostedService) StreamProjection

func (s *HostedService) StreamProjection(
	ctx context.Context,
	bindID string,
	peer PeerInfo,
	lastDigest string,
) (HostedProjectionResponse, error)

StreamProjection omits unchanged tools and isolates changed views from the shared cache.

func (*HostedService) StreamRefreshInterval

func (s *HostedService) StreamRefreshInterval() time.Duration

StreamRefreshInterval returns the projection stream fallback re-read interval.

type InsufficientScopeError

type InsufficientScopeError struct {
	Scopes []string
}

InsufficientScopeError reports a remote OAuth challenge that requires explicit scope approval.

func (*InsufficientScopeError) Error

func (e *InsufficientScopeError) Error() string

type PeerInfo

type PeerInfo struct {
	PID            int    `json:"pid"`
	UID            int    `json:"uid"`
	GID            int    `json:"gid"`
	UserSID        string `json:"user_sid,omitempty"`
	ExecutablePath string `json:"executable_path"`
	Supported      bool   `json:"supported"`
}

PeerInfo is the UDS peer identity captured from the accepted socket.

func PeerInfoFromConn

func PeerInfoFromConn(conn net.Conn) (PeerInfo, error)

PeerInfoFromConn returns OS peer credentials and executable identity for an accepted UDS connection.

func PeerInfoFromContext

func PeerInfoFromContext(ctx context.Context) (PeerInfo, error)

PeerInfoFromContext extracts UDS peer identity from a request context.

type ProjectionEpoch

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

ProjectionEpoch is the daemon-owned monotonic invalidation source for hosted tool projections.

func NewProjectionEpoch

func NewProjectionEpoch() *ProjectionEpoch

NewProjectionEpoch creates an initialized projection epoch.

func (*ProjectionEpoch) Advance

func (e *ProjectionEpoch) Advance() uint64

Advance invalidates projections built against an earlier daemon state and wakes waiters.

func (*ProjectionEpoch) Changes

func (e *ProjectionEpoch) Changes() <-chan struct{}

Changes returns a channel closed by the next Advance. Capture it before reading projection state so an advance racing that read still wakes the waiter. A nil epoch never signals.

func (*ProjectionEpoch) Current

func (e *ProjectionEpoch) Current() uint64

Current returns the current epoch without changing it.

func (*ProjectionEpoch) Snapshot

func (e *ProjectionEpoch) Snapshot(_ context.Context, _ tools.Scope) (string, bool)

Snapshot returns the current authoritative daemon projection epoch.

type ResolvedServer

type ResolvedServer struct {
	Server    compozyconfig.MCPServer
	Target    mcpauth.Target
	HealthKey RuntimeHealthKey
}

ResolvedServer binds one MCP config to its OAuth credential owner.

type RuntimeHealthEntry

type RuntimeHealthEntry struct {
	Key      RuntimeHealthKey
	Sequence uint64
	Message  string
}

RuntimeHealthEntry is one redacted live failure.

type RuntimeHealthKey

type RuntimeHealthKey struct {
	ResourceID       string
	InstanceName     string
	WorkspaceID      string
	BundleGeneration string
	ServerName       string
}

RuntimeHealthKey identifies one extension-owned MCP server generation.

type RuntimeHealthObservation

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

RuntimeHealthObservation fences one asynchronous call-site outcome.

type RuntimeHealthRegistry

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

RuntimeHealthRegistry owns restart-local extension MCP availability state.

func NewRuntimeHealthRegistry

func NewRuntimeHealthRegistry() *RuntimeHealthRegistry

NewRuntimeHealthRegistry creates an empty restart-local registry.

func (*RuntimeHealthRegistry) Begin

Begin reserves a monotonic observation sequence before one exchange starts.

func (*RuntimeHealthRegistry) Entries

func (r *RuntimeHealthRegistry) Entries(
	instanceName string,
	workspaceID string,
	bundleGeneration string,
) []RuntimeHealthEntry

Entries returns deterministic live failures for one instance generation.

func (*RuntimeHealthRegistry) EvictInstance

func (r *RuntimeHealthRegistry) EvictInstance(instanceName string, workspaceID string)

EvictInstance clears all generations and fences in-flight observations for one instance.

func (*RuntimeHealthRegistry) Ready

Ready reports the latest completed exchange without launching or probing a server.

func (*RuntimeHealthRegistry) RecordFailure

func (r *RuntimeHealthRegistry) RecordFailure(observation RuntimeHealthObservation, err error)

RecordFailure records a redacted failure unless a newer outcome or lifecycle epoch won.

func (*RuntimeHealthRegistry) RecordSuccess

func (r *RuntimeHealthRegistry) RecordSuccess(observation RuntimeHealthObservation)

RecordSuccess clears a live failure unless a newer outcome or lifecycle epoch won.

type ServerResolver

type ServerResolver interface {
	ResolveMCPServer(ctx context.Context, source toolspkg.SourceRef, definitionOwner string) (ResolvedServer, error)
}

ServerResolver returns the daemon-visible MCP server selected by one source. definitionOwner constrains diagnostic lookups; discovered tools use their ResourceID.

type ServerResolverFunc

type ServerResolverFunc func(
	ctx context.Context,
	source toolspkg.SourceRef,
	definitionOwner string,
) (ResolvedServer, error)

ServerResolverFunc adapts a function into a server resolver.

func (ServerResolverFunc) ResolveMCPServer

func (f ServerResolverFunc) ResolveMCPServer(
	ctx context.Context,
	source toolspkg.SourceRef, definitionOwner string,
) (ResolvedServer, error)

ResolveMCPServer returns the configured MCP server selected by source.

type UnsupportedCapabilityError

type UnsupportedCapabilityError struct {
	Capability string
}

UnsupportedCapabilityError reports an MCP capability Compozy intentionally does not implement.

func (*UnsupportedCapabilityError) Error

type UnsupportedProtocolVersionError

type UnsupportedProtocolVersionError struct{ Version string }

UnsupportedProtocolVersionError reports a peer that negotiated outside Compozy's MCP contract.

func (*UnsupportedProtocolVersionError) Error

Directories

Path Synopsis
Package securehttp provides outbound HTTP clients for remote MCP and OAuth services.
Package securehttp provides outbound HTTP clients for remote MCP and OAuth services.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL