mcp

package
v0.3.0-beta.5 Latest Latest
Warning

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

Go to latest
Published: Aug 5, 2026 License: MIT Imports: 45 Imported by: 0

Documentation

Index

Constants

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")
	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")

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) Status

func (e *CallExecutor) Status(
	ctx context.Context,
	source toolspkg.SourceRef,
) (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 WithHTTPClient

func WithHTTPClient(client *http.Client) CallExecutorOption

WithHTTPClient configures remote MCP HTTP calls with an explicit client.

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
	Logger         *slog.Logger
	Now            func() time.Time
	NonceReader    func([]byte) error
}

HostedConfig configures hosted MCP launch and bind validation.

type HostedLaunchRequest

type HostedLaunchRequest struct {
	SessionID   string
	WorkspaceID string
	AgentName   string
}

HostedLaunchRequest describes one session-bound MCP launch.

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) Bind

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

Bind consumes a launch nonce after validating the Unix peer and expected binary.

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, single-use hosted MCP launch record.

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) ReleaseBind

func (s *HostedService) ReleaseBind(bindID string)

ReleaseBind removes one active bind record.

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) ReleaseSession

func (s *HostedService) ReleaseSession(sessionID string)

ReleaseSession removes all hosted state for a stopped session.

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"`
	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 ResolvedServer

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

ResolvedServer binds one MCP config to its OAuth credential owner.

type ServerResolver

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

ServerResolver returns the daemon-visible MCP server selected by one source.

type ServerResolverFunc

type ServerResolverFunc func(context.Context, toolspkg.SourceRef) (ResolvedServer, error)

ServerResolverFunc adapts a function into a server resolver.

func (ServerResolverFunc) ResolveMCPServer

func (f ServerResolverFunc) ResolveMCPServer(
	ctx context.Context,
	source toolspkg.SourceRef,
) (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