Documentation
¶
Overview ¶
Package sampling provides a Client for requesting LLM analysis via MCP sampling.
The Client is a value type — its zero value is safe to use and acts as a no-op when the connected MCP client does not support sampling. This mirrors the pattern used by the progress.Tracker type.
SECURITY: All user-supplied data sent to the LLM is wrapped in unique nonce-based XML delimiters (e.g., <gitlab_data_{random}>) that cannot be predicted or injected by attacker-controlled content. This prevents XML tag injection attacks. Credential patterns are stripped from data before sending.
Index ¶
- Constants
- Variables
- func WrapConfidentialWarning(data string, confidential bool) string
- type AnalysisResult
- type Client
- type Option
- func WithIterationTimeout(d time.Duration) Option
- func WithMaxIterations(n int) Option
- func WithMaxTokens(n int) Option
- func WithModelHints(hints ...string) Option
- func WithToolChoice(choice *mcp.ToolChoice) Option
- func WithTools(tools []*mcp.Tool) Option
- func WithTotalTimeout(d time.Duration) Option
- type ServerToolExecutor
- type ToolExecutor
Constants ¶
const DefaultIterationTimeout = 2 * time.Minute
DefaultIterationTimeout is the per-iteration timeout for each LLM call plus tool execution round within AnalyzeWithTools.
const DefaultMaxIterations = 5
DefaultMaxIterations is the default maximum number of tool-calling rounds in AnalyzeWithTools before giving up.
const DefaultMaxTokens = 4096
DefaultMaxTokens is the default maximum number of tokens the LLM may produce.
const DefaultTotalTimeout = 5 * time.Minute
DefaultTotalTimeout is the cumulative timeout for the entire AnalyzeWithTools call across all iterations. This prevents unbounded execution when many iterations each complete just within their per-iteration timeout (e.g. 5 iterations x 2 min = 10 min uncapped without this).
const MaxInputLength = 100 * 1024 // 100 KB
MaxInputLength is the maximum byte length of user-supplied data sent to the LLM. Data exceeding this limit is truncated with a warning marker.
Variables ¶
var ErrMaxIterationsReached = errors.New("sampling: maximum tool-calling iterations reached")
ErrMaxIterationsReached is returned when the tool-calling loop exceeds the configured maximum number of iterations.
var ErrSamplingNotSupported = errors.New("sampling: client does not support sampling capability")
ErrSamplingNotSupported is returned when the MCP client does not advertise the sampling capability.
Functions ¶
func WrapConfidentialWarning ¶
WrapConfidentialWarning prepends a confidentiality warning if needed.
Types ¶
type AnalysisResult ¶
type AnalysisResult struct {
Content string `json:"content"`
Model string `json:"model"`
Truncated bool `json:"truncated"`
}
AnalysisResult holds the structured response from an LLM sampling request.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client sends sampling requests to the MCP client's LLM. Its zero value is an inactive client where IsSupported returns false and Analyze returns ErrSamplingNotSupported.
func FromRequest ¶
func FromRequest(req *mcp.CallToolRequest) Client
FromRequest extracts the server session from a CallToolRequest and returns a Client. If the connected MCP client does not support sampling, the returned Client is inactive (IsSupported returns false).
func (Client) Analyze ¶
func (c Client) Analyze(ctx context.Context, prompt, data string, opts ...Option) (AnalysisResult, error)
Analyze sends data to the LLM via MCP sampling and returns the analysis. The prompt describes what analysis to perform; data is the raw GitLab content.
SECURITY: data is sanitized (credentials stripped) and wrapped in XML delimiters before being sent to the LLM.
func (Client) AnalyzeWithTools ¶
func (c Client) AnalyzeWithTools(ctx context.Context, prompt, data string, executor ToolExecutor, opts ...Option) (AnalysisResult, error)
AnalyzeWithTools sends data to the LLM via MCP sampling with tool-calling support. The LLM may request tool calls during analysis; the executor handles them. The loop continues until the LLM produces a final text response or max iterations is reached.
SECURITY: data is sanitized (credentials stripped) and wrapped in XML delimiters. Only tools explicitly provided in opts (via WithTools) are available to the LLM.
func (Client) IsSupported ¶
IsSupported returns true if the MCP client supports the sampling capability.
type Option ¶
type Option func(*analyzeConfig)
Option configures an Analyze call.
func WithIterationTimeout ¶
WithIterationTimeout overrides the per-iteration timeout for each LLM + tool execution round.
func WithMaxIterations ¶
WithMaxIterations overrides the default maximum number of tool-calling rounds.
func WithMaxTokens ¶
WithMaxTokens overrides the default max token limit for the LLM response.
func WithModelHints ¶
WithModelHints provides model preference hints to the MCP client.
func WithToolChoice ¶
func WithToolChoice(choice *mcp.ToolChoice) Option
WithToolChoice controls how the LLM should use tools during AnalyzeWithTools. Mode values: "auto" (default), "required", "none".
func WithTotalTimeout ¶
WithTotalTimeout overrides the cumulative timeout for the entire AnalyzeWithTools call across all iterations.
type ServerToolExecutor ¶
type ServerToolExecutor struct {
// contains filtered or unexported fields
}
ServerToolExecutor dispatches tool calls to explicitly registered handlers, restricting execution to an allow-list of tool names.
SECURITY: Only tools whose handlers are registered can be executed. This prevents the LLM from invoking destructive or unrelated tools during sampling.
func NewServerToolExecutor ¶
func NewServerToolExecutor(session *mcp.ServerSession, handlers map[string]mcp.ToolHandler) *ServerToolExecutor
NewServerToolExecutor creates a ServerToolExecutor with the given tool handlers. The session is attached to each CallToolRequest so handlers can access it. Only the tools registered here can be called during sampling.
func (*ServerToolExecutor) ExecuteTool ¶
func (e *ServerToolExecutor) ExecuteTool(ctx context.Context, name string, args map[string]any) (*mcp.CallToolResult, error)
ExecuteTool dispatches a tool call to the registered handler. Returns an error if the tool name is not registered.
type ToolExecutor ¶
type ToolExecutor interface {
// ExecuteTool invokes the named tool with the given arguments and returns its result.
ExecuteTool(ctx context.Context, name string, args map[string]any) (*mcp.CallToolResult, error)
}
ToolExecutor dispatches tool calls requested by the LLM during sampling.
Source Files