mcptool

Documentation

Overview

Package mcptool implements the private, bounded Streamable HTTP MCP client used by the runtime tool adapter.

Index

• Variables
• type Client
  • func NewClient(config Config) (*Client, error)
  • func (client *Client) Execute(ctx context.Context, descriptor Descriptor, operationID string) ([]byte, bool, error)
  • func (client *Client) Reconcile(ctx context.Context, descriptor Descriptor, operationID string) ([]byte, bool, error)
• type Config
• type CredentialSource
• type Descriptor
  • func DecodeDescriptor(raw []byte) (Descriptor, error)
• type ServerConfig
• type ToolConfig

Variables

var ErrInvalidDescriptor = errors.New("invalid MCP tool descriptor")

ErrInvalidDescriptor reports that a broker-authorized descriptor is not a canonical MCP action. It is safe for the adapter to surface as invalid input.

var ErrUnauthorizedServerTool = errors.New("MCP server or tool is not authorized")

ErrUnauthorizedServerTool reports an endpoint reference or Tool name that is absent from operator configuration. It must never trigger a network call.

var ErrUncertain = errors.New("MCP tool operation outcome is uncertain")

ErrUncertain reports that the caller cannot safely know whether an MCP operation completed. Callers must reconcile, never resubmit.

Types

type Client

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

Client is a private stateless MCP requester. A fresh protocol session per operation makes connection loss observational rather than authorization state, while every request still carries the negotiated session headers.

func NewClient

func NewClient(config Config) (*Client, error)

NewClient constructs a fail-closed Streamable HTTP MCP client.

func (*Client) Execute

func (client *Client) Execute(ctx context.Context, descriptor Descriptor, operationID string) ([]byte, bool, error)

Execute invokes the broker-authorized configured tool exactly once. A transport failure after submission is uncertain and must be reconciled.

func (*Client) Reconcile

func (client *Client) Reconcile(ctx context.Context, descriptor Descriptor, operationID string) ([]byte, bool, error)

Reconcile observes a server-declared operation-status tool. It never calls the original external-effect tool again.

type Config

type Config struct {
	Servers                    []ServerConfig
	RoundTripper               http.RoundTripper
	RequestTimeout             time.Duration
	CancelTimeout              time.Duration
	MaximumResultBytes         int64
	AllowInsecureLoopbackTests bool
}

Config constructs a bounded Streamable HTTP client. HTTP is only available for explicit loopback test fixtures; production endpoints must use HTTPS.

type CredentialSource

type CredentialSource interface {
	Authorization(context.Context) (string, error)
}

CredentialSource obtains an authorization value only while one outbound MCP request is being constructed. Its value is never retained by Client.

type Descriptor

type Descriptor struct {
	Version   string          `json:"version"`
	ServerID  string          `json:"server_id"`
	ToolName  string          `json:"tool_name"`
	Arguments json.RawMessage `json:"arguments"`
}

Descriptor is the private canonical MCP action persisted only after broker admission. It contains no endpoint URL, session, credential, or capability.

func DecodeDescriptor

func DecodeDescriptor(raw []byte) (Descriptor, error)

DecodeDescriptor parses one exact mcp.tool/v1 immutable descriptor.

type ServerConfig

type ServerConfig struct {
	ID                         string
	Endpoint                   string
	Credentials                CredentialSource
	Tools                      []ToolConfig
	ReconcileTool              string
	ReconcileOperationArgument string
}

ServerConfig declares one operator-configured MCP endpoint. The model never supplies this endpoint or its credential source.

type ToolConfig

type ToolConfig struct {
	Name                string
	InputSchemaDigest   string
	OperationIDArgument string
}

ToolConfig pins one server tool and its input schema. The operation ID is injected only into the declared argument, never chosen by a model request.