Files
archie/internal/tools/mcp/sampling.go
T
sam 1586fef2b9 feat(mcp): answer server-initiated sampling from the chat model
MCP servers could not ask the client for a completion: the transports
routed only responses by id and dropped every server-initiated request,
so a server calling sampling/createMessage hung waiting for a reply.

Route server->client requests through the transport readers to a handler
on the client. The client answers sampling/createMessage from a
configured SamplingHandler and maps a missing handler, malformed params
and handler failure to JSON-RPC errors for that request alone -- never a
silent drop or a failed session. stdio and SSE implement the routing;
the stateless HTTP transport cannot receive the request at all and says
so in its doc.

The daemon wires the handler to its own chat runtime and active model
role, so a sample is answered by the model a chat turn uses, capped by
the request's maxTokens and the model's output ceiling, and recorded on
/status like every other model call. No model configured is a refused
request with a clear error.
2026-10-02 09:33:32 +10:00

77 lines
3.2 KiB
Go

package mcp
import (
"context"
"encoding/json"
)
// JSON-RPC 2.0 error codes used when answering a server-initiated request.
// These are spec-defined and part of the MCP wire contract: the server
// distinguishes "this client cannot do that" from "the request was
// malformed" from "the handler failed" by the code, not the message.
const (
// ErrCodeMethodNotFound is returned when this client has no idea how
// to answer the requested method, including a sampling request when no
// sampling handler is configured. It is never a silent drop.
ErrCodeMethodNotFound = -32601
// ErrCodeInvalidParams is returned when the request's params cannot be
// decoded into the method's shape.
ErrCodeInvalidParams = -32602
// ErrCodeInternal is returned when the configured handler ran but
// failed. The message carries the handler's own error text.
ErrCodeInternal = -32603
)
// SamplingContent is one content block in a sampling message. The MCP
// sampling method sends text today; the type field is carried so an
// unsupported block is rejected explicitly rather than silently emptied.
type SamplingContent struct {
Type string `json:"type"`
Text string `json:"text,omitempty"`
}
// SamplingMessage is one conversation message supplied by the MCP server.
type SamplingMessage struct {
Role string `json:"role"`
Content SamplingContent `json:"content"`
}
// SamplingRequest is the params of a sampling/createMessage request: the
// server asks this client to run a completion on its behalf.
type SamplingRequest struct {
Messages []SamplingMessage `json:"messages"`
SystemPrompt string `json:"systemPrompt,omitempty"`
MaxTokens int `json:"maxTokens,omitempty"`
Temperature *float64 `json:"temperature,omitempty"`
StopSequences []string `json:"stopSequences,omitempty"`
}
// SamplingResult is the result of a sampling/createMessage request.
type SamplingResult struct {
Model string `json:"model"`
Role string `json:"role"`
Content SamplingContent `json:"content"`
StopReason string `json:"stopReason,omitempty"`
}
// SamplingHandler answers one server-initiated sampling request from a
// configured model. It returns a Go error for a refused or failed
// completion; the client maps that to a JSON-RPC internal error so the
// server sees the failure for its own request only, never a dropped
// session.
type SamplingHandler func(ctx context.Context, req SamplingRequest) (SamplingResult, error)
// ServerRequestHandler answers one request the MCP server sent to this
// client. A non-nil *ErrorData becomes a JSON-RPC error response;
// otherwise result becomes the success response. The MCP wire contract
// permits both, and a client must never drop a request it cannot answer.
type ServerRequestHandler func(ctx context.Context, method string, params json.RawMessage) (json.RawMessage, *ErrorData)
// serverRequestRouter is implemented by transports that can receive
// server-initiated requests over their server→client channel. The
// stateless HTTP transport cannot (it has no persistent stream) and
// therefore does not implement it.
type serverRequestRouter interface {
SetServerRequestHandler(handler ServerRequestHandler)
}