mcpserver

package
v0.1.35 Latest Latest
Warning

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

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

Documentation

Overview

Package mcpserver provides MCP (Model Context Protocol) server management functionality.

This package enables the registration, configuration, and lifecycle management of MCP servers within the muster ecosystem. It supports both static configuration through YAML files and dynamic management through API operations.

MCP Server Types

Currently supported MCP server types:

  • **Stdio**: Execute MCP servers as local processes with configurable command lines
  • **Streamable-HTTP**: Connect to external MCP servers via HTTP transport
  • **SSE**: Connect to external MCP servers via Server-Sent Events transport

Configuration Structure

MCP servers are defined using the MCPServer CRD or YAML configuration files. Each server definition includes metadata, type-specific configuration, and operational settings.

Basic configuration structure: 

apiVersion: muster.giantswarm.io/v1alpha1
kind: MCPServer
metadata:
  name: example-server
  namespace: default
spec:
  description: Example MCP server for demonstration
  toolPrefix: example
  type: stdio
  autoStart: true
  command: npx
  args:
    - "@modelcontextprotocol/server-filesystem"
    - "/workspace"
  env:
    DEBUG: "1"

For remote servers: 

spec:
  type: streamable-http
  url: "https://api.example.com/mcp"
  timeout: 30
  headers:
    Authorization: "Bearer token"

Static Configuration

MCP servers can be defined in YAML files for static configuration. These files are typically placed in the muster configuration directory and loaded at startup.

Static configuration example: 

# Stdio server example
---
apiVersion: muster.giantswarm.io/v1alpha1
kind: MCPServer
metadata:
  name: filesystem-tools
spec:
  description: File system operations
  toolPrefix: fs
  type: stdio
  autoStart: true
  command: npx
  args: ["@modelcontextprotocol/server-filesystem", "/workspace"]

# Remote server example
---
apiVersion: muster.giantswarm.io/v1alpha1
kind: MCPServer
metadata:
  name: remote-api
spec:
  description: Remote API tools
  toolPrefix: api
  type: streamable-http
  url: "https://api.example.com/mcp"
  timeout: 60
  headers:
    Authorization: "Bearer token"

Dynamic Management

MCP servers can also be created, updated, and deleted dynamically through the muster API. This enables runtime configuration changes and programmatic server management.

API operations include:

  • Create: Register new MCP server definitions
  • Update: Modify existing server configurations
  • Delete: Remove server definitions
  • List: Retrieve all configured servers
  • Get: Fetch specific server details
  • Validate: Check server configuration validity

Lifecycle Management

The package handles the complete lifecycle of MCP servers:

  • **Registration**: Adding server definitions to the system
  • **Validation**: Ensuring configuration correctness
  • **Instantiation**: Creating service instances
  • **Startup**: Initializing server processes or connections
  • **Monitoring**: Tracking server health and status
  • **Shutdown**: Graceful termination of server instances

Integration Points

This package integrates with several muster components:

  • **Aggregator**: Registers tools provided by MCP servers
  • **Service Registry**: Manages server lifecycle as services
  • **Configuration System**: Loads static server definitions
  • **API Layer**: Exposes management operations as tools
  • **Orchestrator**: Coordinates server startup and dependencies

Index

Constants

View Source 
const DefaultClientIDKey = "client-id"

DefaultClientIDKey is the default key for client ID in the secret.

View Source 
const DefaultClientSecretKey = "client-secret"

DefaultClientSecretKey is the default key for client secret in the secret.

View Source 
const DefaultStdioInitTimeout = 10 * time.Second

DefaultStdioInitTimeout is the default timeout for stdio client initialization. This covers the time needed to start the subprocess and complete the MCP handshake.

Variables

This section is empty.

Functions

This section is empty.

Types

type Adapter 

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

Adapter provides MCP server management functionality using the unified client

func NewAdapterWithClient 

func NewAdapterWithClient(musterClient client.MusterClient, namespace string) *Adapter

NewAdapterWithClient creates a new adapter with a specific client (for testing)

func (*Adapter) Close 

func (a *Adapter) Close() error

Close performs cleanup for the adapter

func (*Adapter) ExecuteTool 

func (a *Adapter) ExecuteTool(ctx context.Context, toolName string, args map[string]interface{}) (*api.CallToolResult, error)

ExecuteTool executes a tool by name

func (*Adapter) GetMCPServer 

func (a *Adapter) GetMCPServer(name string) (*api.MCPServerInfo, error)

GetMCPServer returns information about a specific MCP server

func (*Adapter) GetTools 

func (a *Adapter) GetTools() []api.ToolMetadata

GetTools returns all tools this provider offers

func (*Adapter) ListMCPServers 

func (a *Adapter) ListMCPServers() []api.MCPServerInfo

ListMCPServers returns all MCP server definitions

func (*Adapter) Register 

func (a *Adapter) Register()

Register registers the adapter with the API

type AuthInfo 

type AuthInfo struct {
	// Issuer is the OAuth issuer URL (from WWW-Authenticate realm)
	Issuer string

	// Scope is the OAuth scope required by the server
	Scope string

	// ResourceMetadataURL is the URL to fetch OAuth metadata (MCP-specific)
	ResourceMetadataURL string
}

AuthInfo contains OAuth authentication information extracted from a 401 response during MCP server initialization.

type AuthRequiredError 

type AuthRequiredError struct {
	// URL is the endpoint that returned the 401
	URL string

	// AuthInfo contains the OAuth parameters extracted from the 401 response
	AuthInfo AuthInfo

	// Err is the underlying error
	Err error
}

AuthRequiredError is returned when an MCP server requires OAuth authentication before the protocol handshake can complete. This error contains the information needed to initiate the OAuth flow.

func CheckForAuthRequiredError 

func CheckForAuthRequiredError(ctx context.Context, err error, url string) *AuthRequiredError

CheckForAuthRequiredError examines an error to determine if it's a 401 authentication required error. It uses mcp-go's typed error detection instead of string parsing:

  • transport.OAuthAuthorizationRequiredError: returned when WithHTTPOAuth is set. The error carries an OAuthHandler that can discover server metadata (issuer, scopes).
  • transport.ErrUnauthorized: returned when no OAuth handler is configured.

func (*AuthRequiredError) AuthRequired added in v0.1.18 

func (e *AuthRequiredError) AuthRequired() bool

AuthRequired is a marker method that satisfies api.authRequiredError, enabling detection via api.IsAuthRequiredError without direct imports.

func (*AuthRequiredError) Error 

func (e *AuthRequiredError) Error() string

Error implements the error interface

func (*AuthRequiredError) GetIssuer 

func (e *AuthRequiredError) GetIssuer() string

GetIssuer returns the OAuth issuer URL from the error.

func (*AuthRequiredError) GetResourceMetadataURL 

func (e *AuthRequiredError) GetResourceMetadataURL() string

GetResourceMetadataURL returns the resource metadata URL from the error.

func (*AuthRequiredError) GetScope 

func (e *AuthRequiredError) GetScope() string

GetScope returns the OAuth scope from the error.

func (*AuthRequiredError) HasValidChallenge 

func (e *AuthRequiredError) HasValidChallenge() bool

HasValidChallenge returns true if the error contains valid auth challenge information.

func (*AuthRequiredError) Unwrap 

func (e *AuthRequiredError) Unwrap() error

Unwrap returns the underlying error

type CredentialsAdapter 

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

CredentialsAdapter implements the SecretCredentialsHandler interface for loading OAuth client credentials from Kubernetes secrets.

func NewCredentialsAdapter 

func NewCredentialsAdapter(k8sClient client.Client) *CredentialsAdapter

NewCredentialsAdapter creates a new credentials adapter.

Args:

  • k8sClient: The Kubernetes client for reading secrets

Returns:

  • *CredentialsAdapter: The adapter instance

func (*CredentialsAdapter) LoadClientCredentials 

func (a *CredentialsAdapter) LoadClientCredentials(
	ctx context.Context,
	secretRef *api.ClientCredentialsSecretRef,
	defaultNamespace string,
) (*api.ClientCredentials, error)

LoadClientCredentials loads OAuth client credentials from a Kubernetes secret.

The secret should contain:

  • clientIdKey: The OAuth client ID (defaults to "client-id")
  • clientSecretKey: The OAuth client secret (defaults to "client-secret")

Args:

  • ctx: Context for Kubernetes API calls
  • secretRef: Reference to the secret containing credentials
  • defaultNamespace: Namespace to use if not specified in secretRef

Returns:

  • *api.ClientCredentials: The loaded credentials
  • error: Error if the secret cannot be found or is missing required keys

func (*CredentialsAdapter) Register 

func (a *CredentialsAdapter) Register()

Register registers the adapter with the API.

type DynamicAuthClient 

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

DynamicAuthClient implements the MCPClient interface using StreamableHTTP transport with mcp-go's built-in OAuth handler for automatic bearer token injection and typed 401 error handling.

Instead of manually injecting Authorization headers via WithHTTPHeaderFunc, this client delegates token management to mcp-go's WithHTTPOAuth transport option. The transport.TokenStore adapter bridges muster's session-scoped token management to mcp-go's OAuth handler, enabling:

  • Automatic bearer token injection on every request
  • Typed OAuthAuthorizationRequiredError on 401 (preserving error details)
  • Transparent token refresh via the TokenStore

func NewDynamicAuthClient 

func NewDynamicAuthClient(url string, tokenStore transport.TokenStore, scope string) *DynamicAuthClient

NewDynamicAuthClient creates a new StreamableHTTP-based MCP client with mcp-go's built-in OAuth handler. The TokenStore is queried on each HTTP request to get the current access token for bearer injection.

Args:

  • url: The MCP server URL
  • tokenStore: Adapter providing OAuth tokens (implements transport.TokenStore)
  • scope: The OAuth scope for this connection

Returns a new DynamicAuthClient ready for initialization.

func (*DynamicAuthClient) CallTool 

func (c *DynamicAuthClient) CallTool(ctx context.Context, name string, args map[string]interface{}) (*mcp.CallToolResult, error)

CallTool executes a specific tool and returns the result

func (*DynamicAuthClient) Close 

func (c *DynamicAuthClient) Close() error

Close cleanly shuts down the client connection

func (*DynamicAuthClient) GetPrompt 

func (c *DynamicAuthClient) GetPrompt(ctx context.Context, name string, args map[string]interface{}) (*mcp.GetPromptResult, error)

GetPrompt retrieves a specific prompt

func (*DynamicAuthClient) Initialize 

func (c *DynamicAuthClient) Initialize(ctx context.Context) error

Initialize establishes the connection and performs protocol handshake. Uses mcp-go's WithHTTPOAuth for automatic token injection and typed 401 handling.

func (*DynamicAuthClient) ListPrompts 

func (c *DynamicAuthClient) ListPrompts(ctx context.Context) ([]mcp.Prompt, error)

ListPrompts returns all available prompts from the server

func (*DynamicAuthClient) ListResources 

func (c *DynamicAuthClient) ListResources(ctx context.Context) ([]mcp.Resource, error)

ListResources returns all available resources from the server

func (*DynamicAuthClient) ListTools 

func (c *DynamicAuthClient) ListTools(ctx context.Context) ([]mcp.Tool, error)

ListTools returns all available tools from the server

func (*DynamicAuthClient) Ping 

func (c *DynamicAuthClient) Ping(ctx context.Context) error

Ping checks if the server is responsive

func (*DynamicAuthClient) ReadResource 

func (c *DynamicAuthClient) ReadResource(ctx context.Context, uri string) (*mcp.ReadResourceResult, error)

ReadResource retrieves a specific resource

type MCPClient 

type MCPClient interface {
	// Initialize establishes the connection and performs protocol handshake
	Initialize(ctx context.Context) error
	// Close cleanly shuts down the client connection
	Close() error
	// ListTools returns all available tools from the server
	ListTools(ctx context.Context) ([]mcp.Tool, error)
	// CallTool executes a specific tool and returns the result
	CallTool(ctx context.Context, name string, args map[string]interface{}) (*mcp.CallToolResult, error)
	// ListResources returns all available resources from the server
	ListResources(ctx context.Context) ([]mcp.Resource, error)
	// ReadResource retrieves a specific resource
	ReadResource(ctx context.Context, uri string) (*mcp.ReadResourceResult, error)
	// ListPrompts returns all available prompts from the server
	ListPrompts(ctx context.Context) ([]mcp.Prompt, error)
	// GetPrompt retrieves a specific prompt
	GetPrompt(ctx context.Context, name string, args map[string]interface{}) (*mcp.GetPromptResult, error)
	// Ping checks if the server is responsive
	Ping(ctx context.Context) error
}

MCPClient defines the interface for MCP client implementations. All transport types (stdio, SSE, streamable-http) implement this interface, enabling polymorphic usage and easier testing with mocks.

func NewMCPClientFromType 

func NewMCPClientFromType(serverType api.MCPServerType, config MCPClientConfig) (MCPClient, error)

NewMCPClientFromType creates the appropriate MCP client based on the server type. This factory function simplifies client creation by encapsulating the logic for choosing the correct client implementation.

Supported types:

  • "stdio": Creates a StdioClient for local subprocess communication
  • "streamable-http": Creates a StreamableHTTPClient for HTTP-based servers
  • "sse": Creates an SSEClient for Server-Sent Events communication

If config.HTTPClient is provided (e.g., for Teleport TLS authentication), it will be used instead of the default HTTP client for remote server types.

Returns an error if the server type is not recognized.

type MCPClientConfig 

type MCPClientConfig struct {
	// Command is the executable path for stdio servers
	Command string
	// Args are the command line arguments for stdio servers
	Args []string
	// Env contains environment variables for stdio servers
	Env map[string]string
	// URL is the endpoint for remote servers (streamable-http, sse)
	URL string
	// Headers are HTTP headers for remote servers
	Headers map[string]string
	// HTTPClient is a custom HTTP client to use for remote servers.
	// When set, this client is used instead of the default.
	// Used for Teleport authentication with custom TLS certificates.
	HTTPClient *http.Client
}

MCPClientConfig contains configuration for creating an MCP client. This provides a unified configuration structure for all client types.

type McpDiscreteStatusUpdate 

type McpDiscreteStatusUpdate struct {
	Name          string // The unique label of the MCP server instance
	ProcessStatus string // A string indicating the process status, e.g., "ProcessInitializing", "ProcessStarting", "ProcessRunning", "ProcessExitedWithError"
	ProcessErr    error  // The actual Go error object if the process failed or exited with an error
}

McpDiscreteStatusUpdate is used to report discrete status changes from a running MCP process. It focuses on the state, not verbose logs.

type McpUpdateFunc 

type McpUpdateFunc func(update McpDiscreteStatusUpdate)

McpUpdateFunc is a callback function type for receiving McpDiscreteStatusUpdate messages.

type MusterTokenStore added in v0.0.231 

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

MusterTokenStore is a thin context-binder that implements mcp-go's transport.TokenStore interface by binding {sessionID, issuer} context to the single backing store exposed through api.OAuthHandler.

It has no storage of its own -- all reads and writes go through api.OAuthHandler. The only local state is a cached copy of the ID token, because mcp-go's transport.Token doesn't track ID tokens.

mcp-go owns token refresh and 401 handling. This store simply returns the current token as-is and persists whatever mcp-go writes back after a successful refresh.

func NewMusterTokenStore added in v0.0.231 

func NewMusterTokenStore(sessionID, issuer string, oauthHandler api.OAuthHandler) *MusterTokenStore

NewMusterTokenStore creates a new token store that binds the given session and issuer context to the api.OAuthHandler backing store.

func (*MusterTokenStore) GetIDToken added in v0.0.231 

func (s *MusterTokenStore) GetIDToken() string

GetIDToken returns the last cached ID token. mcp-go's transport.Token doesn't track ID tokens, so we cache them from the backing store on each GetToken() call for SSO forwarding.

func (*MusterTokenStore) GetToken added in v0.0.231 

func (s *MusterTokenStore) GetToken(ctx context.Context) (*transport.Token, error)

GetToken returns the current OAuth token from the backing store. Returns transport.ErrNoToken when no token is available, which signals mcp-go to initiate the OAuth authorization flow.

Unlike the previous implementation, this does NOT call RefreshTokenIfNeeded. mcp-go decides when to refresh based on the ExpiresAt field.

func (*MusterTokenStore) SaveToken added in v0.0.231 

func (s *MusterTokenStore) SaveToken(ctx context.Context, token *transport.Token) error

SaveToken persists a refreshed token to the backing store via api.OAuthHandler.StoreToken. mcp-go calls this after a successful token refresh.

The cached IDToken is preserved because refresh responses typically don't include ID tokens.

type SSEClient 

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

SSEClient implements the MCPClient interface using SSE transport. It connects to remote MCP servers using Server-Sent Events for communication.

func NewSSEClientWithHeaders 

func NewSSEClientWithHeaders(url string, headers map[string]string) *SSEClient

NewSSEClientWithHeaders creates a new SSE-based MCP client with custom headers

func (*SSEClient) CallTool 

func (c *SSEClient) CallTool(ctx context.Context, name string, args map[string]interface{}) (*mcp.CallToolResult, error)

CallTool executes a specific tool and returns the result

func (*SSEClient) Close 

func (c *SSEClient) Close() error

Close cleanly shuts down the client connection

func (*SSEClient) GetPrompt 

func (c *SSEClient) GetPrompt(ctx context.Context, name string, args map[string]interface{}) (*mcp.GetPromptResult, error)

GetPrompt retrieves a specific prompt

func (*SSEClient) Initialize 

func (c *SSEClient) Initialize(ctx context.Context) error

Initialize establishes the connection and performs protocol handshake

func (*SSEClient) ListPrompts 

func (c *SSEClient) ListPrompts(ctx context.Context) ([]mcp.Prompt, error)

ListPrompts returns all available prompts from the server

func (*SSEClient) ListResources 

func (c *SSEClient) ListResources(ctx context.Context) ([]mcp.Resource, error)

ListResources returns all available resources from the server

func (*SSEClient) ListTools 

func (c *SSEClient) ListTools(ctx context.Context) ([]mcp.Tool, error)

ListTools returns all available tools from the server

func (*SSEClient) Ping 

func (c *SSEClient) Ping(ctx context.Context) error

Ping checks if the server is responsive

func (*SSEClient) ReadResource 

func (c *SSEClient) ReadResource(ctx context.Context, uri string) (*mcp.ReadResourceResult, error)

ReadResource retrieves a specific resource

type StdioClient 

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

StdioClient implements the MCPClient interface using stdio transport. It manages a local subprocess that communicates via stdin/stdout.

func NewStdioClientWithEnv 

func NewStdioClientWithEnv(command string, args []string, env map[string]string) *StdioClient

NewStdioClientWithEnv creates a new stdio-based MCP client with environment variables

func (*StdioClient) CallTool 

func (c *StdioClient) CallTool(ctx context.Context, name string, args map[string]interface{}) (*mcp.CallToolResult, error)

CallTool executes a specific tool and returns the result

func (*StdioClient) Close 

func (c *StdioClient) Close() error

Close cleanly shuts down the client connection

func (*StdioClient) GetPrompt 

func (c *StdioClient) GetPrompt(ctx context.Context, name string, args map[string]interface{}) (*mcp.GetPromptResult, error)

GetPrompt retrieves a specific prompt

func (*StdioClient) GetStderr 

func (c *StdioClient) GetStderr() (io.Reader, bool)

GetStderr returns a reader for the stderr output of the subprocess

func (*StdioClient) Initialize 

func (c *StdioClient) Initialize(ctx context.Context) error

Initialize establishes the connection and performs protocol handshake

func (*StdioClient) ListPrompts 

func (c *StdioClient) ListPrompts(ctx context.Context) ([]mcp.Prompt, error)

ListPrompts returns all available prompts from the server

func (*StdioClient) ListResources 

func (c *StdioClient) ListResources(ctx context.Context) ([]mcp.Resource, error)

ListResources returns all available resources from the server

func (*StdioClient) ListTools 

func (c *StdioClient) ListTools(ctx context.Context) ([]mcp.Tool, error)

ListTools returns all available tools from the server

func (*StdioClient) Ping 

func (c *StdioClient) Ping(ctx context.Context) error

Ping checks if the server is responsive

func (*StdioClient) ReadResource 

func (c *StdioClient) ReadResource(ctx context.Context, uri string) (*mcp.ReadResourceResult, error)

ReadResource retrieves a specific resource

type StreamableHTTPClient 

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

StreamableHTTPClient implements the MCPClient interface using StreamableHTTP transport. It connects to remote MCP servers using HTTP with streaming support.

func NewStreamableHTTPClientWithHTTPClient 

func NewStreamableHTTPClientWithHTTPClient(url string, headers map[string]string, httpClient *http.Client) *StreamableHTTPClient

NewStreamableHTTPClientWithHTTPClient creates a new StreamableHTTP-based MCP client with a custom HTTP client. This is useful for Teleport authentication where the HTTP client needs custom TLS certificates.

func NewStreamableHTTPClientWithHeaderFunc added in v0.1.33 

func NewStreamableHTTPClientWithHeaderFunc(url string, headerFunc transport.HTTPHeaderFunc) *StreamableHTTPClient

NewStreamableHTTPClientWithHeaderFunc creates a new StreamableHTTP-based MCP client with a dynamic header function that is called on every request. This enables token refresh by resolving the latest token at call time instead of baking in a static header.

func NewStreamableHTTPClientWithHeaderFuncAndHTTPClient added in v0.1.33 

func NewStreamableHTTPClientWithHeaderFuncAndHTTPClient(url string, headerFunc transport.HTTPHeaderFunc, httpClient *http.Client) *StreamableHTTPClient

NewStreamableHTTPClientWithHeaderFuncAndHTTPClient creates a new StreamableHTTP-based MCP client with both a dynamic header function and a custom HTTP client (e.g., for Teleport TLS).

func NewStreamableHTTPClientWithHeaders 

func NewStreamableHTTPClientWithHeaders(url string, headers map[string]string) *StreamableHTTPClient

NewStreamableHTTPClientWithHeaders creates a new StreamableHTTP-based MCP client with custom headers

func (*StreamableHTTPClient) CallTool 

func (c *StreamableHTTPClient) CallTool(ctx context.Context, name string, args map[string]interface{}) (*mcp.CallToolResult, error)

CallTool executes a specific tool and returns the result

func (*StreamableHTTPClient) Close 

func (c *StreamableHTTPClient) Close() error

Close cleanly shuts down the client connection

func (*StreamableHTTPClient) GetPrompt 

func (c *StreamableHTTPClient) GetPrompt(ctx context.Context, name string, args map[string]interface{}) (*mcp.GetPromptResult, error)

GetPrompt retrieves a specific prompt

func (*StreamableHTTPClient) Initialize 

func (c *StreamableHTTPClient) Initialize(ctx context.Context) error

Initialize establishes the connection and performs protocol handshake

func (*StreamableHTTPClient) ListPrompts 

func (c *StreamableHTTPClient) ListPrompts(ctx context.Context) ([]mcp.Prompt, error)

ListPrompts returns all available prompts from the server

func (*StreamableHTTPClient) ListResources 

func (c *StreamableHTTPClient) ListResources(ctx context.Context) ([]mcp.Resource, error)

ListResources returns all available resources from the server

func (*StreamableHTTPClient) ListTools 

func (c *StreamableHTTPClient) ListTools(ctx context.Context) ([]mcp.Tool, error)

ListTools returns all available tools from the server

func (*StreamableHTTPClient) Ping 

func (c *StreamableHTTPClient) Ping(ctx context.Context) error

Ping checks if the server is responsive

func (*StreamableHTTPClient) ReadResource 

func (c *StreamableHTTPClient) ReadResource(ctx context.Context, uri string) (*mcp.ReadResourceResult, error)

ReadResource retrieves a specific resource

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.