proxy

package
v0.0.4 Latest Latest
Warning

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

 Go to latest Published: Mar 12, 2026 License: Apache-2.0 Imports: 22 Imported by: 0

Documentation

Index

Constants

View Source 
const NamespaceSeparator = "___"

NamespaceSeparator is used to create tool names in an aggregated proxy server.

Variables

This section is empty.

Functions

func ApplyResult added in v0.0.3 

func ApplyResult(processorConfig *config.ProcessorConfig, result *processor.DataContext, callCtx CallContext) error

ApplyResult takes the result from the processor and processes it in order for each configured part of the ProcessorConfig.

func GetInput added in v0.0.3 

func GetInput(processorConfig *config.ProcessorConfig, callCtx CallContext) *processor.DataContext

GetInput uses the provided ProcessorConfig and CallContext to create the input map for the processor.

func RegisterEndpoint added in v0.0.3 

func RegisterEndpoint(endpoint string, proxy *MCPProxy, mux *http.ServeMux, options *mcp.StreamableHTTPOptions)

RegisterEndpoint registers a ServerProvider with the HTTP mux.

func WithCallContext added in v0.0.3 

func WithCallContext(ctx context.Context, cc CallContext) context.Context

WithCallContext attaches a CallContext to a context.Context.

Types

type CallContext added in v0.0.3 

type CallContext interface {
	// Lifecycle
	SendRequest(ctx context.Context) error // Execute the downstream call

	HasResult() bool // Returns true if a result is available

	GetResult() *mcp.CallToolResult         // Returns the CallToolResult, can be nil if request was not sent yet OR resulted in error
	GetOriginalResult() *mcp.CallToolResult // Returns the initial CallToolResult first set, can be nil if request was not sent yet OR resulted in error
	SetResult(*mcp.CallToolResult)          // Sets the result for this call context

	GetEventInfo() *common.MCPEvent // Returns the attached MCPEvent
	SetEventInfo(*common.MCPEvent)  // Sets the provided MCPEvent

	// Original request (immutable deep clone - for auditing/comparison)
	GetOriginalServerName() string            // Returns name of the original server
	GetOriginalRequest() *mcp.CallToolRequest // Returns original CallToolRequest
	GetOriginalToolName() string              // Returns original tool name

	// Current request (mutable - handlers modify this)
	GetServerName() string            // Returns current server name
	SetServerName(string)             // Sets current server name, can be used for re-routing
	GetRequest() *mcp.CallToolRequest // Returns current CallToolRequest
	GetToolName() string              // Returns current tool name

	// Status and error handling
	GetStatus() int   // Returns current status code (0 = not set, 200 = ok, 4xx/5xx = error)
	SetStatus(int)    // Sets status code
	GetError() string // Returns error message if status >= 400
	SetError(string)  // Sets error message

	// Session and request identification
	GetRequestID() string // Returns unique request ID
	GetSessionID() string // Returns session ID

	// Direction (processors need to know request vs response phase)
	GetDirection() common.McpEventDirection
	SetDirection(common.McpEventDirection)

	GetMessageType() common.McpMessageType
	SetMessageType(common.McpMessageType)

	// Routing context (reuses common.RoutingContext)
	GetRoutingContext() *common.RoutingLog

	// Handler access
	GetHandler(part string) (CallContextHandler, bool) // Returns handler for given part (payload, meta, routing, etc.)
	SetHandler(part string, h CallContextHandler)      // Sets the provided context handler
	GetLogHandler() LogHandler                         // Returns the log handler for this context
	SetLogHandler(l LogHandler)                        // sets the provided log handler
}

CallContext represents a single request/response cycle. Implementations know how to send themselves and manage their own state.

func NewToolCallContext added in v0.0.3 

func NewToolCallContext(
	ctx context.Context,
	proxy *MCPProxy,
	upstreamSession *UpstreamSession,
	serverName string,
	req *mcp.CallToolRequest,
) (CallContext, error)

NewToolCallContext creates a new ToolCallContext. Returns CallContext interface to allow implementation swapping.

type CallContextHandler added in v0.0.3 

type CallContextHandler interface {
	// AttachPart extracts this handler's part from CallContext for processor input
	AttachPart(callCtx CallContext, input *processor.DataContext)

	// Apply updates CallContext based on processor output for this part
	Apply(callCtx CallContext, output *processor.DataContext) error
}

CallContextHandler handles a specific part of the processing context. Each handler knows how to extract its part for processor input (Get) and apply processor output back to CallContext (Apply).

type CentianProxy 

type CentianProxy struct {
	Name       string
	ServerID   string // used to uniquely identify this specific object instance
	Config     *config.GlobalConfig
	Mux        *http.ServeMux
	Server     *http.Server
	Logger     *logging.Logger // Shared base logger (ONE file handle)
	Gateways   map[string]*MCPProxy
	APIKeys    *centauth.APIKeyStore
	AuthHeader string
}

CentianProxy is the main server struct.

It holds 4 critical components: - mux - used to register URL paths - server - used to serve the mux - logger - main logger for all events in the proxied endpoints - gateways - holds all gateways and proxy endpoints for easy access

Additionally it has a reference to the global config which was loaded to initialize this server.

func NewCentianProxy 

func NewCentianProxy(globalConfig *config.GlobalConfig) (*CentianProxy, error)

NewCentianProxy takes a GlobalConfig struct and returns a new CentianProxy.

func (*CentianProxy) Setup 

func (c *CentianProxy) Setup() error

Setup uses CentianServer.config to create all gateways and endpoints.

type ConnectionStatus added in v0.0.3 

type ConnectionStatus string

ConnectionStatus represents the state of a downstream connection. 

const (
	StatusPending    ConnectionStatus = "pending"
	StatusConnecting ConnectionStatus = "connecting"
	StatusConnected  ConnectionStatus = "connected"
	StatusFailed     ConnectionStatus = "failed"
)

Connection status constants for tracking downstream connection lifecycle.

type DefaultLogHandler added in v0.0.3 

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

DefaultLogHandler provides simple, default functionality for logging CallContext data.

func NewDefaultLogHandler added in v0.0.3 

func NewDefaultLogHandler(logger *logging.Logger) *DefaultLogHandler

NewDefaultLogHandler returns a new DefaultLogHandler.

func (*DefaultLogHandler) Log added in v0.0.3 

func (h *DefaultLogHandler) Log(callCtx CallContext) error

Log uses the attached logger and ToLogEntry to log the provided CallContext data.

func (*DefaultLogHandler) ToLogEntry added in v0.0.3 

func (h *DefaultLogHandler) ToLogEntry(callCtx CallContext) *common.MCPEvent

ToLogEntry transforms the provided CallContext into an MCPEvent struct.

type DefaultMetaHandler added in v0.0.3 

type DefaultMetaHandler struct{}

DefaultMetaHandler provides default behavior for providing and modifying metadata information to/by a processor.

func (*DefaultMetaHandler) Apply added in v0.0.3 

func (h *DefaultMetaHandler) Apply(callCtx CallContext, result *processor.DataContext) error

Apply uses provided result ProcessorContext to modify the CallContext.

func (*DefaultMetaHandler) AttachPart added in v0.0.3 

func (h *DefaultMetaHandler) AttachPart(callCtx CallContext, input *processor.DataContext)

AttachPart attaches MCPEvent information from CallContext on input ProcessorContext.

type DefaultPayloadHandler added in v0.0.3 

type DefaultPayloadHandler struct{}

DefaultPayloadHandler provides payload information for request and result, as well as applies modifications to those provided by a processor.

Note: DefaultPayloadHandler does a full replacement of request params and result, requiring the processors to return an exact copy of the structure. Partial replacement is not possible with this handlers.

func (*DefaultPayloadHandler) Apply added in v0.0.3 

func (h *DefaultPayloadHandler) Apply(callCtx CallContext, result *processor.DataContext) error

Apply modifies payload using result ProcessorContext.

Behavior: both result.Payload.Request.Params and result.Payload.Result will be used to modify CallContext accordingly.

func (*DefaultPayloadHandler) AttachPart added in v0.0.3 

func (h *DefaultPayloadHandler) AttachPart(callCtx CallContext, input *processor.DataContext)

AttachPart attaches Payload information from CallContext on input ProcessorContext.

type DefaultRoutingHandler added in v0.0.3 

type DefaultRoutingHandler struct{}

DefaultRoutingHandler handles routing data and modifications on CallContext.

func (*DefaultRoutingHandler) Apply added in v0.0.3 

func (h *DefaultRoutingHandler) Apply(callCtx CallContext, result *processor.DataContext) error

Apply uses provided result ProcessorContext to modify the CallContext. Returns an error if no request is attached to CallContext.

func (*DefaultRoutingHandler) AttachPart added in v0.0.3 

func (h *DefaultRoutingHandler) AttachPart(callCtx CallContext, input *processor.DataContext)

AttachPart attaches routing information from CallContext to input ProcessorContext.

type DownstreamConnection 

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

DownstreamConnection represents a connection to a downstream MCP server.

func NewDownstreamConnection 

func NewDownstreamConnection(name string, cfg *config.MCPServerConfig) *DownstreamConnection

NewDownstreamConnection creates an unconnected downstream wrapper.

func (*DownstreamConnection) CallTool 

func (dc *DownstreamConnection) CallTool(ctx context.Context, toolName string, args map[string]any) (*mcp.CallToolResult, error)

CallTool forwards a tool call to the downstream server.

func (*DownstreamConnection) Close 

func (dc *DownstreamConnection) Close() error

Close terminates the downstream connection.

func (*DownstreamConnection) Connect 

func (dc *DownstreamConnection) Connect(ctx context.Context, authHeaders map[string]string) error

Connect establishes connection to downstream server authHeaders: additional headers from upstream request (for passthrough auth).

func (*DownstreamConnection) ConnectedAt added in v0.0.3 

func (dc *DownstreamConnection) ConnectedAt() time.Time

ConnectedAt returns when connection was established (zero if not connected).

func (*DownstreamConnection) GetConfig added in v0.0.3 

func (dc *DownstreamConnection) GetConfig() *config.MCPServerConfig

GetConfig returns the server configuration for this connection.

func (*DownstreamConnection) GetError added in v0.0.3 

func (dc *DownstreamConnection) GetError() error

GetError returns the connection error if status is Failed (thread-safe).

func (*DownstreamConnection) GetStatus added in v0.0.3 

func (dc *DownstreamConnection) GetStatus() ConnectionStatus

GetStatus returns the current connection status (thread-safe).

func (*DownstreamConnection) IsConnected 

func (dc *DownstreamConnection) IsConnected() bool

IsConnected returns true if connection was established and not yet closed.

func (*DownstreamConnection) ServerName added in v0.0.3 

func (dc *DownstreamConnection) ServerName() string

ServerName returns the name of this downstream server.

func (*DownstreamConnection) Tools 

func (dc *DownstreamConnection) Tools() []*mcp.Tool

Tools returns the cached tools (nil if not connected).

type DownstreamConnectionInterface added in v0.0.3 

type DownstreamConnectionInterface interface {
	CallTool(ctx context.Context, toolName string, args map[string]any) (*mcp.CallToolResult, error)
	IsConnected() bool
	Tools() []*mcp.Tool
	Close() error
	GetConfig() *config.MCPServerConfig
	GetStatus() ConnectionStatus
	GetError() error
	Connect(context.Context, map[string]string) error
}

DownstreamConnectionInterface abstracts downstream MCP server connections for testability.

type DownstreamConnectionPool added in v0.0.4 

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

DownstreamConnectionPool owns the reusable downstream connection set for one pool key.

A pool key represents one proxy endpoint plus the caller identity and any forwarded auth state that affects downstream initialization. Multiple UpstreamSessions can attach to the same pool so reconnecting clients can reuse already-initialized downstream MCP sessions.

type HeaderRoundTripper 

type HeaderRoundTripper struct {
	Base    http.RoundTripper
	Headers map[string]string
}

HeaderRoundTripper is used to store.

func (HeaderRoundTripper) RoundTrip 

func (rt HeaderRoundTripper) RoundTrip(req *http.Request) (*http.Response, error)

RoundTrip adds the header from HeaderRoundTripper to the request. This is done so both configured headers as well as headers from the client are included in the request.

type LogHandler added in v0.0.3 

type LogHandler interface {
	// ToLogEntry creates a loggable representation of the current state
	ToLogEntry(callCtx CallContext) *common.MCPEvent
	Log(callCtx CallContext) error
}

LogHandler defines how CallContext is serialized for logging. Different implementations allow different log formats.

type MCPProxy 

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

MCPProxy is a unified proxy that handles both aggregated (multiple servers with namespaced tools) and single-server (pass-through) modes.

Mode is controlled by the namespaceTools flag:

  • true: Aggregated mode - tools are prefixed with "serverName__"
  • false: Single mode - tools pass through with original names

func NewAggregatedProxy 

func NewAggregatedProxy(gatewayName, endpoint string, gatewayConfig *config.GatewayConfig) *MCPProxy

NewAggregatedProxy creates a proxy that aggregates multiple downstream servers. Tools from each server are namespaced as "serverName__toolName" to avoid collisions.

func NewSingleProxy 

func NewSingleProxy(serverName, endpoint string, serverConfig *config.MCPServerConfig) *MCPProxy

NewSingleProxy creates a proxy for a single downstream server. Tools pass through with their original names (no namespacing).

func (*MCPProxy) Close 

func (p *MCPProxy) Close() []error

Close terminates all sessions and their downstream connections.

func (*MCPProxy) GetServerForRequest 

func (p *MCPProxy) GetServerForRequest(r *http.Request) *mcp.Server

GetServerForRequest returns (or creates) an MCP server for the given HTTP request's session.

func (*MCPProxy) NewMcpServer 

func (p *MCPProxy) NewMcpServer() *mcp.Server

NewMcpServer returns a new *mcp.Server based on the MCPProxy name.

func (*MCPProxy) ProcessCall added in v0.0.3 

func (p *MCPProxy) ProcessCall(callCtx CallContext, direction common.McpEventDirection, msgType common.McpMessageType) error

ProcessCall handles the request phase processing using handlers. It gathers input from handlers, passes it to processors, and applies results back.

If Error is non-nil, a mandatory processor failed to process the CallContext. Otherwise, processors ran as intended. Note: this can still lead to an error response.

type ProcessingController added in v0.0.3 

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

ProcessingController is used to call the main processing loop for any MCP transport method.

func NewProcessingController added in v0.0.3 

func NewProcessingController(processorConfigs []*config.ProcessorConfig) (*ProcessingController, error)

NewProcessingController returns a new ProcessingController using the provided processor configs.

func (*ProcessingController) Process added in v0.0.3 

func (ep *ProcessingController) Process(callCtx CallContext) error

Process runs all processors on the CallContext using handlers to build input and apply results.

type ProcessingControllerInterface added in v0.0.3 

type ProcessingControllerInterface interface {
	Process(event CallContext) error
}

ProcessingControllerInterface abstracts event processing for testability.

type ToolCallContext added in v0.0.3 

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

ToolCallContext handles standard tool calls (client → downstream → client). Implements the CallContext interface.

func (*ToolCallContext) GetDirection added in v0.0.3 

func (c *ToolCallContext) GetDirection() common.McpEventDirection

GetDirection returns MCPEvent.Direction.

func (*ToolCallContext) GetError added in v0.0.3 

func (c *ToolCallContext) GetError() string

GetError returns ToolCallContext.MCPEvent.Error.

func (*ToolCallContext) GetEventInfo added in v0.0.3 

func (c *ToolCallContext) GetEventInfo() *common.MCPEvent

GetEventInfo returns the attached MCPEvent.

func (*ToolCallContext) GetHandler added in v0.0.3 

func (c *ToolCallContext) GetHandler(part string) (CallContextHandler, bool)

GetHandler returns the handler for the given part.

func (*ToolCallContext) GetLogHandler added in v0.0.3 

func (c *ToolCallContext) GetLogHandler() LogHandler

GetLogHandler returns the attached log handler.

func (*ToolCallContext) GetMessageType added in v0.0.3 

func (c *ToolCallContext) GetMessageType() common.McpMessageType

GetMessageType returns MCPEvent.MessageType.

func (*ToolCallContext) GetOriginalRequest added in v0.0.3 

func (c *ToolCallContext) GetOriginalRequest() *mcp.CallToolRequest

GetOriginalRequest returns a reference to the original CallToolRequest.

func (*ToolCallContext) GetOriginalResult added in v0.0.3 

func (c *ToolCallContext) GetOriginalResult() *mcp.CallToolResult

GetOriginalResult returns the initial, original CallToolResult.

func (*ToolCallContext) GetOriginalServerName added in v0.0.3 

func (c *ToolCallContext) GetOriginalServerName() string

GetOriginalServerName returns the initial, original server name.

func (*ToolCallContext) GetOriginalToolName added in v0.0.3 

func (c *ToolCallContext) GetOriginalToolName() string

GetOriginalToolName returns the initial tool name.

func (*ToolCallContext) GetRequest added in v0.0.3 

func (c *ToolCallContext) GetRequest() *mcp.CallToolRequest

GetRequest returns a reference to the current CallToolRequest - allows modifications.

func (*ToolCallContext) GetRequestID added in v0.0.3 

func (c *ToolCallContext) GetRequestID() string

GetRequestID returns the current request ID.

func (*ToolCallContext) GetResult added in v0.0.3 

func (c *ToolCallContext) GetResult() *mcp.CallToolResult

GetResult returns the CallToolResult for this CallContext.

func (*ToolCallContext) GetRoutingContext added in v0.0.3 

func (c *ToolCallContext) GetRoutingContext() *common.RoutingLog

GetRoutingContext returns the attached RoutingLog.

func (*ToolCallContext) GetServerName added in v0.0.3 

func (c *ToolCallContext) GetServerName() string

GetServerName returns the current server name from routing context.

func (*ToolCallContext) GetSessionID added in v0.0.3 

func (c *ToolCallContext) GetSessionID() string

GetSessionID returns the current session ID.

func (*ToolCallContext) GetStatus added in v0.0.3 

func (c *ToolCallContext) GetStatus() int

GetStatus returns ToolCallContext.MCPEvent.Status.

func (*ToolCallContext) GetToolName added in v0.0.3 

func (c *ToolCallContext) GetToolName() string

GetToolName returns the current tool name.

func (*ToolCallContext) HasResult added in v0.0.3 

func (c *ToolCallContext) HasResult() bool

HasResult returns true if a result is available.

func (*ToolCallContext) SendRequest added in v0.0.3 

func (c *ToolCallContext) SendRequest(ctx context.Context) error

SendRequest executes the downstream call using current request state. Note: if processors returned a status >= 400 this will NOT trigger a downstream call, instead an immediate error response will be returned.

func (*ToolCallContext) SetDirection added in v0.0.3 

func (c *ToolCallContext) SetDirection(d common.McpEventDirection)

SetDirection sets MCPEvent.Direction.

func (*ToolCallContext) SetError added in v0.0.3 

func (c *ToolCallContext) SetError(msg string)

SetError sets the ToolCallContext.MCPEvent.Error.

func (*ToolCallContext) SetEventInfo added in v0.0.3 

func (c *ToolCallContext) SetEventInfo(event *common.MCPEvent)

SetEventInfo sets the provided MCPEvent.

func (*ToolCallContext) SetHandler added in v0.0.3 

func (c *ToolCallContext) SetHandler(part string, h CallContextHandler)

SetHandler sets the provided handler for the provided part.

Automatically creates the handlers slice if its nil.

func (*ToolCallContext) SetLogHandler added in v0.0.3 

func (c *ToolCallContext) SetLogHandler(l LogHandler)

SetLogHandler sets the provided longer handler.

func (*ToolCallContext) SetMessageType added in v0.0.3 

func (c *ToolCallContext) SetMessageType(t common.McpMessageType)

SetMessageType sets MCPEvent.MessageType.

func (*ToolCallContext) SetResult added in v0.0.3 

func (c *ToolCallContext) SetResult(result *mcp.CallToolResult)

SetResult sets the CallToolResult for this CallContext.

func (*ToolCallContext) SetServerName added in v0.0.3 

func (c *ToolCallContext) SetServerName(name string)

SetServerName sets the server name in routing context.

Note: creates routing context if it doesn't exist.

func (*ToolCallContext) SetStatus added in v0.0.3 

func (c *ToolCallContext) SetStatus(status int)

SetStatus sets ToolCallContext.MCPEvent.Status.

type UpstreamSession added in v0.0.4 

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

UpstreamSession represents one MCP client session talking to this proxy endpoint.

It owns only upstream-facing state: - the upstream MCP session ID - the per-session upstream mcp.Server exposed to the SDK - the resolved request identity and forwarded auth headers captured from the client

It does not own downstream lifecycle. Instead, it points at a reusable DownstreamConnectionPool via poolKey and receives whichever downstream connections that pool currently owns.

func (*UpstreamSession) GetConnectionByName added in v0.0.4 

func (s *UpstreamSession) GetConnectionByName(serverName string) (DownstreamConnectionInterface, error)

GetConnectionByName returns a MCP connection for the given server name.

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.