core

package
v0.2.46 Latest Latest
Warning

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

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

README

core

MCP protocol types and tool-handler APIs.

This package defines the shared types used by both server/ and client/. It has no dependencies on either — only stdlib and encoding/json.

What belongs here

  • JSON-RPC types: Request, Response, Error
  • MCP domain types: ToolDef, ResourceDef, PromptDef, Content, Claims
  • Tool-handler APIs: Sample(), Elicit(), EmitLog(), EmitProgress(), NotifyResourcesChanged()
  • UI metadata types: UIMetadata, UICSPConfig, UIVisibility, AppMIMEType, ToolMeta, ResourceContentMeta
  • Extension types: Extension, ExtensionProvider, RefValidator, ClientExtensionCap, UIExtensionID
  • Context helpers: ClientSupportsExtension(), ClientSupportsUI()
  • Interfaces: Transport, TokenSource, AuthValidator
  • Protocol constants: ServerInfo, ClientInfo, ClientCapabilities

What does NOT belong here

  • Server implementation (Dispatcher, transports, middleware) → server/
  • Client implementation (HTTP transports, reconnection) → client/
  • Auth implementation (JWT, PRM, OAuth) → ext/auth/
  • Anything that imports server/ or client/

Documentation

Index

Constants

View Source 
const (
	// RemediationTypeURL indicates remediation via URL-mode elicitation.
	// Composes with the existing URLElicitationRequiredError (-32042).
	RemediationTypeURL = "url"

	// RemediationTypeOAuthRAR indicates the client should re-authorize with
	// RFC 9396 Rich Authorization Request authorization_details. The hint
	// carries an "authorization_details" field at the top level.
	RemediationTypeOAuthRAR = "oauth_authorization_details"
)

SEP-defined remediation hint type values.

View Source 
const (
	// ElicitModeForm is the default form-based elicitation mode.
	// The server sends a JSON schema and the client renders a form.
	ElicitModeForm = "form"

	// ElicitModeURL is the URL-based elicitation mode (SEP-1036).
	// The server directs the user to a URL for out-of-band interaction.
	// The MCP client's bearer token remains unchanged.
	ElicitModeURL = "url"
)

Elicitation mode constants (SEP-1036).

View Source 
const (
	FileInputReasonTooLarge        = "file_too_large"
	FileInputReasonTypeNotAccepted = "file_type_not_accepted"
)

File-input error reason strings. Pinned by the conformance suite as stable machine-readable identifiers — clients can branch on these without parsing the human-readable message. JS-side bridge errors (ext/ui/assets/file-picker.ts) use the same constants.

View Source 
const (
	// Standard JSON-RPC 2.0 error codes — use only for JSON-RPC protocol errors.
	ErrCodeParse          = -32700 // Invalid JSON
	ErrCodeInvalidRequest = -32600 // Not a valid JSON-RPC request
	ErrCodeMethodNotFound = -32601 // Method not found
	ErrCodeInvalidParams  = -32602 // Invalid params
	ErrCodeInternal       = -32603 // Internal JSON-RPC error (marshaling, framework bugs)

	// ErrCodeServerError is the base of the implementation-defined range (-32000 to -32099).
	// Avoid using this directly — prefer the MCP-specific codes below.
	ErrCodeServerError = -32000

	// MCP application error codes — outside the JSON-RPC reserved range.
	// These indicate application-level failures in tool, resource, or prompt handlers.
	ErrCodeToolExecutionError = -31000 // Tool handler returned an error
	ErrCodeResourceError      = -31001 // Resource handler returned an error
	ErrCodePromptError        = -31002 // Prompt handler returned an error
	ErrCodeCompletionError    = -31003 // Completion handler returned an error

	// ErrCodeURLElicitationRequired indicates that the request cannot proceed
	// until the user completes one or more URL-based elicitation flows (SEP-1036).
	// The error data contains an elicitations array with URL-mode elicitation
	// requests. Clients should present the URLs to the user and retry after
	// receiving notifications/elicitation/complete.
	//
	// This error code is also the composition point for FineGrainedAuth (UC1):
	// the authorization denial envelope is additive metadata in the same data
	// object, alongside the elicitations array.
	ErrCodeURLElicitationRequired = -32042
)

Standard JSON-RPC 2.0 error codes (https://www.jsonrpc.org/specification#error_object).

Reserved ranges: 

-32700           Parse error (invalid JSON)
-32600           Invalid Request (not a valid JSON-RPC request)
-32601           Method not found
-32602           Invalid params
-32603           Internal error
-32000 to -32099 Server error (implementation-defined)
View Source 
const AppMIMEType = "text/html;profile=mcp-app"

AppMIMEType is the MIME type for MCP App HTML resources. This profile parameter distinguishes MCP App HTML from regular HTML — hosts use it to decide whether to render in a sandboxed iframe.

View Source 
const DataURIDefaultMediaType = "text/plain;charset=US-ASCII"

DataURIDefaultMediaType is the media type assumed when a data URI omits the mediatype component (per RFC 2397 §3).

View Source 
const DataURIPrefix = "data:"

DataURIPrefix is the literal prefix that all data URIs share.

View Source 
const DefaultContentChunkMethod = "notifications/tools/content_chunk"

DefaultContentChunkMethod is the default notification method for streaming tool content. This is an mcpkit extension — not yet standardized in MCP spec. Override per-server via server.WithContentChunkMethod(method).

View Source 
const FileInputSchemaKey = "x-mcp-file"

FileInputSchemaKey is the JSON Schema extension keyword used to mark a string property as a file input (SEP-2356). Servers attach a FileInputDescriptor under this key on schema properties of {"type": "string", "format": "uri"} to signal "render a file picker here."

Clients that declare the fileInputs capability encode selected files as RFC 2397 data URIs and pass them as the property's string value.

View Source 
const MaxCompletionValues = 100

MaxCompletionValues is the MCP spec limit on the number of values in a completion response (schema maxItems: 100).

View Source 
const MetaKeyAuthorizationContextID = "io.modelcontextprotocol/authorization-context-id"

Retry meta key per SEP-2643. The client MUST echo the server-issued authorizationContextId verbatim under this key on retry.

View Source 
const PerRequestClientCapsKey = "io.modelcontextprotocol/clientCapabilities"

PerRequestClientCapsKey is the SEP-2575 _meta key under which a client may declare a per-request capability override. The value is shaped like ClientCapabilities and is merged additively on top of the session-level capabilities for the duration of one request.

View Source 
const StreamableHTTPAccept = "application/json, text/event-stream"

StreamableHTTPAccept is the Accept header value for Streamable HTTP requests. Per MCP spec: clients MUST include both application/json and text/event-stream.

View Source 
const TasksExtensionID = "io.modelcontextprotocol/tasks"

TasksExtensionID is the protocol extension identifier for SEP-2663 Tasks. Servers advertise it under capabilities.extensions in the initialize response; clients declare support under capabilities.extensions in the initialize request (or per-request via SEP-2575 _meta).

View Source 
const UIExtensionID = "io.modelcontextprotocol/ui"

UIExtensionID is the extension identifier for MCP Apps. Used in initialize handshake for both server advertisement and client capability declaration.

Variables

View Source 
var (
	ErrNotDataURI         = errors.New("not a data URI")
	ErrMalformedDataURI   = errors.New("malformed data URI")
	ErrNonBase64DataURI   = errors.New("data URI is not base64-encoded")
	ErrInvalidDataURIName = errors.New("data URI name parameter is malformed")
)

Sentinel errors returned by DecodeDataURI.

View Source 
var (
	ErrElicitationNotSupported    = errors.New("client does not support elicitation")
	ErrElicitationURLNotSupported = errors.New("client does not support URL-mode elicitation")
)

Sentinel errors for elicitation.

View Source 
var (
	ErrFileTooLarge        = errors.New("file too large")
	ErrFileTypeNotAccepted = errors.New("file type not accepted")
)

Sentinel errors for callers that just want to test category. The typed errors below carry structured fields; these constants are useful for `errors.Is` checks.

View Source 
var ErrNoRequestFunc = errors.New("server-to-client requests not available in this context")

ErrNoRequestFunc is returned when Sample() or Elicit() is called outside a session context where server-to-client requests are not available (e.g., no transport wired, or stateless mode).

View Source 
var ErrRequestStateExpired = errors.New("requestState expired")

ErrRequestStateExpired indicates the payload's expiry is in the past.

View Source 
var ErrRequestStateInvalidSignature = errors.New("requestState signature invalid")

ErrRequestStateInvalidSignature indicates the HMAC signature did not match — either tampered payload or wrong key.

View Source 
var ErrRequestStateMalformed = errors.New("requestState malformed")

ErrRequestStateMalformed indicates the encoded requestState couldn't be parsed (missing separator, bad base64, bad JSON inside the payload).

View Source 
var ErrSamplingNotSupported = errors.New("client does not support sampling")

Sentinel errors for sampling.

Functions

func AllowedRoots added in v0.1.26 

func AllowedRoots(ctx context.Context) []string

AllowedRoots returns the current enforced roots for the session, or nil if no roots enforcement is configured. The returned slice is the snapshot from the allowed-roots function — it may change on the next call if client roots update.

func ClientSupportsExtension 

func ClientSupportsExtension(ctx context.Context, extensionID string) bool

ClientSupportsExtension checks whether the connected client declared support for the given extension ID during the initialize handshake. Returns false if no session context is present or the client did not advertise the extension.

Usage in a tool handler: 

if core.ClientSupportsExtension(ctx, "io.modelcontextprotocol/ui") {
    // client can render MCP Apps
}

func ClientSupportsExtensionForRequest added in v0.2.41 

func ClientSupportsExtensionForRequest(ctx context.Context, extensionID string, requestCapsRaw json.RawMessage) bool

ClientSupportsExtensionForRequest reports whether the client supports the given extension at session level (initialize handshake) OR per-request level (SEP-2575 _meta override). Per-request opt-in is additive — it cannot revoke a session-level declaration.

requestCapsRaw is the raw JSON bytes from the SEP-2575 _meta override; the caller extracts it from a typed envelope (e.g., a json.RawMessage field tagged "io.modelcontextprotocol/clientCapabilities" inside _meta). Pass an empty slice if the request had no override.

func ClientSupportsTasks added in v0.2.41 

func ClientSupportsTasks(ctx context.Context) bool

ClientSupportsTasks checks whether the connected client declared support for the SEP-2663 Tasks extension during the initialize handshake. Equivalent to ClientSupportsExtension(ctx, TasksExtensionID).

func ClientSupportsTasksV1 added in v0.2.41 

func ClientSupportsTasksV1(ctx context.Context) bool

ClientSupportsTasksV1 reports whether the connected client declared the v1 ServerCapabilities.Tasks slot during the initialize handshake. Used by hybrid v1+v2 servers to dispatch tasks/* methods to the v1 path when the client opted into v1 (and not the io.modelcontextprotocol/tasks extension).

V2-only servers and clients can ignore this — see ClientSupportsTasks / ClientSupportsExtension(TasksExtensionID) instead.

func ClientSupportsUI 

func ClientSupportsUI(ctx context.Context) bool

ClientSupportsUI checks whether the connected client declared support for the MCP Apps extension during the initialize handshake. Tool handlers can use this to decide whether to include UI-specific content or fall back to text-only.

func CollectResponseHeaders added in v0.2.41 

func CollectResponseHeaders(ctx context.Context) map[string]string

CollectResponseHeaders returns a snapshot of the response headers staged on the current request via SetResponseHeader. HTTP transports call this after dispatch returns, before writing response headers. Returns nil when no collector was attached or no headers were staged.

func ContentChunkMethodFromContext added in v0.1.17 

func ContentChunkMethodFromContext(ctx context.Context) string

ContentChunkMethodFromContext returns the configured content chunk method, or DefaultContentChunkMethod if not set.

func ContextWithSession 

func ContextWithSession(ctx context.Context, notify NotifyFunc, request RequestFunc, logLevel *atomic.Pointer[LogLevel], clientCaps *ClientCapabilities, claims *Claims) context.Context

ContextWithSession returns a context carrying the session's notification state, request sender, client capabilities, and authenticated claims. Exported for use by the server sub-package; tool handlers should use EmitLog, Sample, Elicit, AuthClaims instead.

func DecodeDataURI added in v0.2.43 

func DecodeDataURI(uri string) (data []byte, mediaType, filename string, err error)

DecodeDataURI parses an RFC 2397 base64 data URI as produced by EncodeDataURI. Returns the decoded payload, the media type (with the default substituted when omitted), and the decoded filename from any `name=` parameter (empty when absent).

Non-base64 data URIs are rejected with ErrNonBase64DataURI; SEP-2356 requires the base64 form because payloads are binary.

func DetachForBackground added in v0.2.41 

func DetachForBackground(ctx context.Context) context.Context

DetachForBackground returns a context suitable for background goroutines. It preserves session state (notifications, claims, capabilities) but replaces transport-scoped functions with session-level equivalents.

If the server registered a detach strategy (via SetDetachStrategy), it is used. Otherwise, falls back to context.WithoutCancel (preserves values, detaches cancellation).

Use this instead of context.WithoutCancel when spawning goroutines that need to send server-to-client requests (elicitation, sampling) after the original HTTP request has returned.

func DetachFromClient added in v0.1.25 

func DetachFromClient(ctx context.Context) context.Context

DetachFromClient returns a context that preserves all session state (EmitLog, EmitSSERetry, Sample, Elicit, AuthClaims, etc.) but is NOT cancelled when the client's HTTP request context is cancelled. Use this in a tool handler that needs to continue processing after the client disconnects — e.g., long-running computations where the result is delivered via EventStore replay on reconnection.

Under the hood, this calls context.WithoutCancel (Go 1.21+), which copies all context Values but strips the parent's Done channel and any inherited deadlines/timeouts.

Important caveats:

  • Any per-tool timeout (ToolDef.Timeout, WithToolTimeout) set by the server is inherited BEFORE the handler runs. DetachFromClient strips it. If the handler needs a deadline, add one explicitly: ctx = core.DetachFromClient(ctx) ctx, cancel := context.WithTimeout(ctx, 1*time.Hour) defer cancel()

  • Session idle timeouts (WithSessionTimeout) may reap the session while the detached tool is still running if the client doesn't reconnect within the idle window. Combine with a generous WithSSEGracePeriod to keep the session alive long enough.

  • Notifications (EmitLog, EmitSSERetry) emitted after the client disconnects are buffered in the EventStore (if configured) and replayed on reconnection. Without an EventStore, they are dropped.

  • The tool's final ToolResult is still serialized as an SSE event via emitSSEEvent — if the client has disconnected but the session is alive (grace period), the event lands in the store and is replayed.

Example: 

func longRunningTool(ctx context.Context, req core.ToolRequest) (core.ToolResult, error) {
    // Hint the client to reconnect in 5 minutes
    core.EmitSSERetry(ctx, 5*time.Minute)

    // Detach: tool keeps running even if the client drops the connection
    ctx = core.DetachFromClient(ctx)

    // Long computation — ctx.Done() no longer fires on client disconnect
    result := doExpensiveWork(ctx)

    return core.TextResult(result), nil
}

func EmitContent added in v0.1.17 

func EmitContent(ctx context.Context, requestID json.RawMessage, content Content)

EmitContent sends a partial content block to the client during tool execution. Each call emits a notification via the session's notify function, delivered as an SSE event on streaming transports.

On non-streaming transports (JSON response path), the notification is silently dropped — the final ToolResult is the only response.

The tool's final ToolResult should contain the complete aggregated content. Streaming chunks are a preview for responsive UX; the final result is authoritative.

Example: 

func myTool(ctx context.Context, req core.ToolRequest) (core.ToolResult, error) {
    core.EmitContent(ctx, req.RequestID, core.Content{Type: "text", Text: "Step 1..."})
    // ... work ...
    core.EmitContent(ctx, req.RequestID, core.Content{Type: "text", Text: "Step 2..."})
    return core.TextResult("Complete"), nil
}

func EmitLog 

func EmitLog(ctx context.Context, level LogLevel, logger string, data any)

EmitLog sends a notifications/message to the connected client if the session's log level allows it. Safe to call even if no session context is present (no-op).

level is the severity of the message. logger is an optional logger name (typically the tool or subsystem name). data is the log payload (string, map, etc.).

Usage in a tool handler: 

func myHandler(ctx context.Context, req mcpkit.ToolRequest) (mcpkit.ToolResult, error) {
    mcpkit.EmitLog(ctx, mcpkit.LogInfo, "my-tool", "processing started")
    // ... do work ...
    return mcpkit.TextResult("done"), nil
}

func EmitProgress 

func EmitProgress(ctx context.Context, token any, progress, total float64, message string)

EmitProgress sends a notifications/progress to the connected client. Safe to call even if no session context is present or if token is nil (both are no-ops).

token is the ProgressToken from the ToolRequest — pass req.ProgressToken directly. progress is the current progress value, total is the expected total (0 for indeterminate). message is an optional human-readable status string.

Usage in a tool handler: 

func myHandler(ctx context.Context, req mcpkit.ToolRequest) (mcpkit.ToolResult, error) {
    mcpkit.EmitProgress(ctx, req.ProgressToken, 0, 100, "starting")
    // ... do work ...
    mcpkit.EmitProgress(ctx, req.ProgressToken, 50, 100, "halfway")
    // ... more work ...
    mcpkit.EmitProgress(ctx, req.ProgressToken, 100, 100, "done")
    return mcpkit.TextResult("complete"), nil
}

func EmitSSERetry added in v0.1.23 

func EmitSSERetry(ctx context.Context, retryAfter time.Duration) error

EmitSSERetry emits an SSE "retry:" hint to the connected client on the current session's SSE stream. The retryAfter duration is rounded down to whole milliseconds and sent to the client as the next reconnection delay.

No-op on non-SSE transports (stdio, in-process, Streamable HTTP responses that chose the JSON path over SSE). Returns nil in all cases — callers don't need to branch on transport type.

Non-positive durations are dropped (no hint emitted). The servicekit writer additionally drops zero/negative retry values to prevent "reconnect immediately" thundering herds.

Thread safety: safe to call from any goroutine spawned by the handler. Delivery is asynchronous — the function returns as soon as the message is enqueued on the SSE hub writer.

Usage in a tool handler: 

func longRunningTool(ctx context.Context, req mcpkit.ToolRequest) (mcpkit.ToolResult, error) {
    // Tell the client to back off for 30s before reconnecting if the
    // connection drops. The tool continues running regardless.
    mcpkit.EmitSSERetry(ctx, 30*time.Second)

    // ...do long work...

    return mcpkit.TextResult("done"), nil
}

func EncodeDataURI added in v0.2.43 

func EncodeDataURI(data []byte, mediaType, filename string) string

EncodeDataURI builds an RFC 2397 base64 data URI suitable for SEP-2356 file inputs. mediaType is embedded verbatim (e.g. "image/png"); pass an empty string to omit it (the consumer will assume text/plain;charset=US-ASCII per RFC 2397). filename is optional; if non-empty it is percent-encoded and emitted as a `name=` parameter.

func EncodeMRTRStatePlaintext added in v0.2.41 

func EncodeMRTRStatePlaintext(state MRTRRoundState) (string, error)

EncodeMRTRStatePlaintext returns a base64url-encoded JSON of state with no integrity guarantee — used by the dispatcher in plaintext mode when no signing key is configured. The encoded form is parseable but trivially forgeable; SEP-2322 servers without a signing key must treat it as untrusted regardless.

func FileInputArrayProperty added in v0.2.43 

func FileInputArrayProperty(desc FileInputDescriptor) map[string]any

FileInputArrayProperty builds a JSON Schema property for an array of file inputs. The returned map is shaped as `{"type": "array", "items": {"type": "string", "format": "uri", "x-mcp-file": desc}}`.

func FileInputProperty added in v0.2.43 

func FileInputProperty(desc FileInputDescriptor) map[string]any

FileInputProperty builds a JSON Schema property for a single file input. The returned map is shaped as `{"type": "string", "format": "uri", "x-mcp-file": desc}` and is suitable for embedding in a tool's inputSchema properties.

func FileMatchesAccept added in v0.2.44 

func FileMatchesAccept(mediaType, filename string, accept []string) bool

FileMatchesAccept implements the SEP-2356 accept-pattern matcher. Pattern rules — same set as the JS-side bridge matcher in ext/ui/assets/file-picker.ts so both sides agree on what passes:

  • "image/png" — exact MIME match (case-sensitive on type, as RFC 6838)
  • "image/*" — wildcard subtype match (prefix on `type/`)
  • ".pdf" — extension match against filename suffix (case-insensitive)

Empty / nil accept means anything matches.

func FileURIToPath added in v0.1.26 

func FileURIToPath(uri string) string

FileURIToPath converts a file:// URI to a local filesystem path. Returns the path portion with the "file://" prefix stripped. Returns the input unchanged if it doesn't have a file:// prefix. Used by the server dispatch layer to convert client-provided root URIs to paths for IsPathAllowed.

func GenerateSchema added in v0.2.26 

func GenerateSchema[T any]() json.RawMessage

GenerateSchema derives a JSON Schema from a Go type using the current schema generator. Panics if no generator is set.

func GetSessionID added in v0.2.41 

func GetSessionID(ctx context.Context) string

GetSessionID returns the session ID from a raw context.Context. For use in middleware that doesn't have a typed BaseContext. Returns empty string if no session context is present.

func HasFileInputs added in v0.2.43 

func HasFileInputs(ctx context.Context) bool

HasFileInputs reports whether the connected client declared the SEP-2356 fileInputs capability during the initialize handshake. Servers consult this before advertising x-mcp-file in tool inputSchemas — per spec, the keyword MUST NOT appear if the client cannot handle it.

func HasScope 

func HasScope(ctx context.Context, scope string) bool

HasScope checks if the context's authenticated claims include the given scope. Returns false if no claims are present.

func IntPtr added in v0.2.41 

func IntPtr(v int) *int

IntPtr returns a pointer to the given int. Convenience for setting TaskInfo.TTL.

func IsDataURI added in v0.2.43 

func IsDataURI(s string) bool

IsDataURI reports whether s starts with the "data:" scheme prefix. Cheap prefix check; use DecodeDataURI to actually parse.

func IsJSONRPCResponse 

func IsJSONRPCResponse(data []byte) bool

isJSONRPCResponse detects whether raw JSON is a JSON-RPC response (not a request). A response has an "id" field and either "result" or "error", but no "method" field. Used by transports to route incoming client messages that are responses to server-to-client requests (sampling/createMessage, elicitation/create).

func IsPathAllowed added in v0.1.26 

func IsPathAllowed(ctx context.Context, path string) bool

IsPathAllowed reports whether the given file path falls within at least one of the session's enforced roots. Returns true if:

  • No session context is present (bare context, no sandbox)
  • No allowed-roots function is installed (no WithAllowedRoots, no client roots)
  • The allowed-roots function returns nil (no restriction)

Returns false if the allowed-roots function returns a non-nil empty slice (explicit "nothing allowed") or the path doesn't match any root.

Path matching uses cleaned, directory-prefix semantics: "/workspace" allows "/workspace/src/main.go" but NOT "/workspace-other/y". Both the root and the path are cleaned via filepath.Clean before comparison.

func IsTemplateURI added in v0.2.4 

func IsTemplateURI(uri string) bool

IsTemplateURI reports whether uri is a valid RFC 6570 URI template with at least one variable expression.

func MCPToSlogLevel added in v0.2.28 

func MCPToSlogLevel(level LogLevel) slog.Level

MCPToSlogLevel maps an MCP LogLevel to the nearest slog.Level. 

LogDebug, LogNotice → slog.LevelDebug / slog.LevelInfo
LogInfo             → slog.LevelInfo
LogWarning          → slog.LevelWarn
LogError            → slog.LevelError
LogCritical+        → slog.LevelError + 4

func MarshalJSON added in v0.2.19 

func MarshalJSON(v any) ([]byte, error)

MarshalJSON encodes v as JSON without HTML-escaping <, >, &. Go's json.Marshal escapes these to \u003c/\u003e/\u0026 for HTML safety, but JSON-RPC payloads are not HTML contexts. This matches how Node.js and Python serialize JSON.

func MarshalNotification 

func MarshalNotification(method string, params any) (json.RawMessage, error)

MarshalNotification builds a JSON-RPC notification (no id field). Exported for use by the server transport sub-package.

func Notify 

func Notify(ctx context.Context, method string, params any) bool

Notify sends an arbitrary server-to-client JSON-RPC notification. Returns false if no notification sender is available in the context. This is the low-level API; prefer EmitLog for logging notifications.

func NotifyElicitationComplete added in v0.2.41 

func NotifyElicitationComplete(ctx context.Context, elicitationID string) bool

NotifyElicitationComplete sends a notifications/elicitation/complete notification to the client (SEP-1036). Call this after the user completes the out-of-band URL-mode elicitation flow so the client knows it can retry the original request.

func NotifyResourceUpdated added in v0.1.28 

func NotifyResourceUpdated(ctx context.Context, uri string)

NotifyResourceUpdated sends a notifications/resources/updated to all sessions subscribed to the given resource URI. This is the handler-facing wrapper around Server.NotifyResourceUpdated — it routes through the subscription registry to fan out across sessions, not just the caller's session.

No-op if subscriptions are not enabled or no session context is present. Uses the existing MCP spec subscription mechanism (exact URI match); no wildcard or pattern extensions.

Usage in a tool handler: 

func updateWidget(ctx context.Context, req core.ToolRequest) (core.ToolResult, error) {
    db.UpdateWidget(args.ID, args.Name)
    core.NotifyResourceUpdated(ctx, "widgets/" + args.ID)
    return core.TextResult("updated"), nil
}

func NotifyResourcesChanged 

func NotifyResourcesChanged(ctx context.Context)

NotifyResourcesChanged sends a notifications/resources/list_changed notification to the connected client, signaling that the set of available resources has changed. MCP App tool handlers should call this after mutating state that affects the UI resource, so clients know to re-fetch resources/list.

Note: this notifies the CURRENT session only (via sc.notify). For targeted fan-out to all sessions subscribed to a specific resource URI, use NotifyResourceUpdated(ctx, uri) instead.

Safe to call even if no session context is present (no-op).

func ParseWWWAuthenticate 

func ParseWWWAuthenticate(header string) (resourceMetadata string, scopes []string, err error)

ParseWWWAuthenticate extracts the resource_metadata URL and scopes from a WWW-Authenticate: Bearer header value. Used by MCP clients to discover the PRM endpoint after receiving a 401, and to parse required scopes from a 403 insufficient_scope response.

Per MCP spec (2025-11-25): clients MUST use resource_metadata from WWW-Authenticate when present.

func ReplaceSessionNotifyFunc added in v0.2.41 

func ReplaceSessionNotifyFunc(ctx context.Context, fn NotifyFunc) context.Context

ReplaceSessionNotifyFunc returns a new context with the session's notifyFunc replaced. Used by detach strategies to swap the dead POST-scoped notifyFunc with a live session-level one.

No-op if the context has no session.

func ReplaceSessionRequestFunc added in v0.2.41 

func ReplaceSessionRequestFunc(ctx context.Context, fn RequestFunc) context.Context

ReplaceSessionRequestFunc returns a new context with the session's requestFunc replaced. Used by detach strategies to swap the dead POST-scoped requestFunc with a live session-level one.

No-op if the context has no session.

func SetAllowedRoots added in v0.1.26 

func SetAllowedRoots(ctx context.Context, fn func() []string) context.Context

SetAllowedRoots installs an allowed-roots supplier on the session stored in ctx. Exported for the server dispatch layer to wire in the computed root set during session setup. Must be called AFTER ContextWithSession.

func SetDetachStrategy added in v0.2.41 

func SetDetachStrategy(ctx context.Context, strategy DetachStrategy) context.Context

SetDetachStrategy registers a background detach strategy on the context. Called by the server's dispatch layer to provide transport-aware detachment.

func SetNotifyResourceUpdated added in v0.1.28 

func SetNotifyResourceUpdated(ctx context.Context, fn func(uri string)) context.Context

SetNotifyResourceUpdated installs the resource-updated fan-out function on the session context. Exported for the server dispatch layer to wire the subscription registry's notify method. Must be called AFTER ContextWithSession.

func SetResponseHeader added in v0.2.41 

func SetResponseHeader(ctx context.Context, key, value string)

SetResponseHeader stages an HTTP response header that the transport applies before writing the response body. Used by middleware and handlers that need to surface protocol metadata at the HTTP layer (e.g., the v2 task middleware emits Mcp-Name: <taskId> per SEP-2243). Silent no-op when the request was not wrapped with WithResponseHeaderCollector (e.g., non-HTTP transports).

func SetSSERetryHint added in v0.1.23 

func SetSSERetryHint(ctx context.Context, fn func(ms int)) context.Context

SetSSERetryHint installs a retry-hint emitter on the session stored in ctx. Exported for the server transport layer to wire in an SSE-capable emitter during session setup. Non-SSE transports omit this call and EmitSSERetry becomes a silent no-op for handlers running under that transport.

Must be called AFTER ContextWithSession has populated the session context. Returns ctx unchanged if no session context is present (in which case the setter has nothing to attach to).

Idempotent: calling twice overwrites the previous emitter. Intended to be called exactly once per session during transport setup.

func SetSchemaGenerator added in v0.2.26 

func SetSchemaGenerator(sg SchemaGenerator)

SetSchemaGenerator replaces the default schema generator used by TypedTool and TextTool. Call this once at program startup before registering tools. 

core.SetSchemaGenerator(myCustomGen)

func SetSessionID added in v0.2.41 

func SetSessionID(ctx context.Context, id string)

SetSessionID sets the transport-assigned session ID on the session context. Called by the server dispatch layer after session creation. No-op if no session context is present.

func SignMRTRState added in v0.2.41 

func SignMRTRState(key []byte, state MRTRRoundState, ttl time.Duration) (string, error)

SignMRTRState produces an HMAC-SHA256-signed requestState token wrapping state. ttl bounds the token's validity. Same wire format as SignRequestState ("<base64url-sig>.<base64url-payload>") so the same helpers in transports/middleware that already strip / re-add the prefix work uniformly. Panics if key is empty — callers should fall back to the plaintext encoder when no signing key is configured.

func SignRequestState added in v0.2.41 

func SignRequestState(key []byte, taskID string, ttl time.Duration) string

SignRequestState produces an HMAC-SHA256-signed requestState token for the given taskID, valid for ttl. The encoded form is opaque to clients and round-trippable via VerifyRequestState. Panics if key is empty — callers MUST check before invoking (see v2TaskRuntime.makeRequestState which falls back to plaintext when the key is unset).

func StripFileInputKeywords added in v0.2.44 

func StripFileInputKeywords(schema any) any

StripFileInputKeywords returns a deep-copy of the given JSON Schema (typed as `any` because ToolDef.InputSchema and ElicitationRequest's requestedSchema both accept arbitrary shapes) with every occurrence of the `x-mcp-file` keyword removed. Properties remain — only the keyword is stripped, so a tool advertising `{type: "string", format: "uri", x-mcp-file: ...}` becomes `{type: "string", format: "uri"}` for clients that did not declare the SEP-2356 fileInputs capability.

Per spec interpretation locked by panyam/mcpconformance `pending` (`src/scenarios/server/file-inputs/`): keep the property visible (so legacy clients can still call the tool with a text-input fallback) instead of hiding the whole tool. The strip walks recursively into `properties` and array `items` so both single and array-of-files shapes are handled.

The input is not mutated. Schemas in shapes other than `map[string]any` (typed structs, json.RawMessage) pass through unchanged — they wouldn't have an `x-mcp-file` keyword at the expected path anyway.

func URITemplateVars added in v0.2.4 

func URITemplateVars(uri string) []string

URITemplateVars parses uri as an RFC 6570 URI template and returns the variable names it contains. Returns nil when uri is not a valid template or contains no variables (i.e. is a concrete URI).

func ValidateFileInput added in v0.2.44 

func ValidateFileInput(uri string, desc *FileInputDescriptor) error

ValidateFileInput decodes a data URI argument and verifies it against a server-declared FileInputDescriptor.

  • Returns nil on success, or when desc is nil (no constraint).
  • Returns *FileTooLargeError when MaxSize is set and exceeded.
  • Returns *FileTypeNotAcceptedError when Accept is set and unmet.
  • Returns the underlying decoder error when uri is malformed.

The returned typed errors carry structured fields that the dispatcher packs into the JSON-RPC `data` object — see the conformance suite for the frozen wire shape.

func VerifyRequestState added in v0.2.41 

func VerifyRequestState(key []byte, state string) (taskID string, err error)

VerifyRequestState checks an incoming requestState token against the signing key and current time. Returns the embedded taskID on success. Errors:

  • ErrRequestStateMalformed: structural parse failures (split, base64, JSON)
  • ErrRequestStateInvalidSignature: signature mismatch (tampered or wrong key)
  • ErrRequestStateExpired: payload exp is in the past

Uses hmac.Equal for constant-time signature comparison.

func WithContentChunkMethod added in v0.1.17 

func WithContentChunkMethod(ctx context.Context, method string) context.Context

WithContentChunkMethod returns a context with a custom notification method for streaming content chunks. Used by the server to plumb the configured method name through to EmitContent calls in tool handlers.

func WithResponseHeaderCollector added in v0.2.41 

func WithResponseHeaderCollector(ctx context.Context) context.Context

WithResponseHeaderCollector attaches a fresh per-request HTTP response header collector to ctx. Transports call this on the inbound request context BEFORE dispatching so middleware/handlers can stage headers via SetResponseHeader, and the transport reads them via CollectResponseHeaders before writing the response. Non-HTTP transports skip this and the staging functions become silent no-ops.

Types

type AuthError 

type AuthError struct {
	Code            int
	Message         string
	WWWAuthenticate string // optional WWW-Authenticate header value
}

AuthError is returned when authentication fails.

func (*AuthError) Error 

func (e *AuthError) Error() string

type AuthValidator 

type AuthValidator interface {
	Validate(r *http.Request) error
}

AuthValidator validates an HTTP request and returns claims on success.

type AuthorizationDenial added in v0.2.41 

type AuthorizationDenial struct {
	// Reason classifies the denial. The SEP currently defines a single value:
	// "insufficient_authorization". Additional values may be defined in future SEPs.
	Reason string `json:"reason"`

	// AuthorizationContextID is an optional correlation handle. When provided,
	// the client MUST echo it on retry in _meta under MetaKeyAuthorizationContextID.
	// Per spec, servers MUST NOT reject a retry solely because the handle is
	// absent or cannot be resolved.
	AuthorizationContextID string `json:"authorizationContextId,omitempty"`

	// CredentialDisposition signals the lifecycle relationship between a
	// newly-issued credential and existing credentials.
	//   - "replacement" (default): new credential supersedes existing
	//   - "additional": new credential coexists with existing (UC3)
	CredentialDisposition string `json:"credentialDisposition,omitempty"`

	// RemediationHints are optional MCP-level hints that complement the
	// transport's authorization challenge. Each hint has a type that
	// determines its additional members (which appear at the top level of
	// the hint object, NOT nested under a `data` field).
	RemediationHints []RemediationHint `json:"remediationHints,omitempty"`
}

AuthorizationDenial is the structured authorization denial envelope returned in JSON-RPC error data. It classifies the failure and optionally carries remediation hints.

EXPERIMENTAL: subject to rename/removal as SEP-2643 evolves.

type BaseContext added in v0.2.0 

type BaseContext struct {
	context.Context
	// contains filtered or unexported fields
}

BaseContext provides typed access to session capabilities shared by all MCP handler types (tools, resources, prompts, completions). It embeds context.Context so stdlib functions (Done(), Deadline(), WithTimeout) work transparently.

All methods are safe to call even when the underlying capability is unavailable (e.g., EmitLog on a transport without logging is a no-op).

func FromContext added in v0.2.0 

func FromContext(ctx context.Context) BaseContext

FromContext returns a BaseContext for the given context.Context. This is the bridge for code using the free-function API — existing free functions like EmitLog(ctx, ...) delegate to FromContext(ctx).EmitLog(...).

Always returns a usable BaseContext (never nil). Methods become no-ops when no session state is present.

func (BaseContext) AllowedRoots added in v0.2.0 

func (bc BaseContext) AllowedRoots() []string

AllowedRoots returns the current enforced roots for the session.

func (BaseContext) AuthClaims added in v0.2.0 

func (bc BaseContext) AuthClaims() *Claims

AuthClaims returns the authenticated identity, or nil if unavailable.

func (BaseContext) ClientSupportsExtension added in v0.2.0 

func (bc BaseContext) ClientSupportsExtension(extensionID string) bool

ClientSupportsExtension checks whether the client declared support for the given extension ID during initialize.

func (BaseContext) ClientSupportsUI added in v0.2.0 

func (bc BaseContext) ClientSupportsUI() bool

ClientSupportsUI checks whether the client declared MCP Apps support.

func (BaseContext) DetachFromClient added in v0.2.0 

func (bc BaseContext) DetachFromClient() BaseContext

DetachFromClient returns a BaseContext that preserves session state but is NOT cancelled when the client disconnects. See core.DetachFromClient.

func (BaseContext) Elicit added in v0.2.0 

func (bc BaseContext) Elicit(req ElicitationRequest) (ElicitationResult, error)

Elicit sends an elicitation/create request to the connected client.

SEP-2356: if the client did not declare the `fileInputs` capability, the `x-mcp-file` keyword is stripped from `req.RequestedSchema` before the request goes on the wire (spec mandate for cap-less clients — matches the `tools/list` strip on the server-side dispatch path).

func (BaseContext) EmitLog added in v0.2.0 

func (bc BaseContext) EmitLog(level LogLevel, logger string, data any)

EmitLog sends a log notification at the given severity level.

func (BaseContext) EmitSSERetry added in v0.2.0 

func (bc BaseContext) EmitSSERetry(retryAfter time.Duration) error

EmitSSERetry emits an SSE "retry:" hint to the connected client.

func (BaseContext) HasScope added in v0.2.0 

func (bc BaseContext) HasScope(scope string) bool

HasScope checks if the authenticated claims include the given scope.

func (BaseContext) IsPathAllowed added in v0.2.0 

func (bc BaseContext) IsPathAllowed(path string) bool

IsPathAllowed reports whether the given file path falls within the session's enforced roots.

func (BaseContext) Notify added in v0.2.0 

func (bc BaseContext) Notify(method string, params any) bool

Notify sends an arbitrary server-to-client JSON-RPC notification. Returns false if no notification sender is available.

func (BaseContext) NotifyResourceUpdated added in v0.2.0 

func (bc BaseContext) NotifyResourceUpdated(uri string)

NotifyResourceUpdated sends a notifications/resources/updated to all sessions subscribed to the given URI.

func (BaseContext) NotifyResourcesChanged added in v0.2.0 

func (bc BaseContext) NotifyResourcesChanged()

NotifyResourcesChanged sends a notifications/resources/list_changed to the current session.

func (BaseContext) Sample added in v0.2.0 

func (bc BaseContext) Sample(req CreateMessageRequest) (CreateMessageResult, error)

Sample sends a sampling/createMessage request to the connected client.

func (BaseContext) SessionID added in v0.2.41 

func (bc BaseContext) SessionID() string

SessionID returns the transport-assigned session ID for this request. Empty for stateless or stdio transports.

type CancelTaskResult added in v0.2.41 

type CancelTaskResult struct {
	// ResultType is the SEP-2322 polymorphic-dispatch discriminator. Always
	// "complete" for the tasks/cancel ack (defaulted by MarshalJSON when empty).
	ResultType ResultType `json:"resultType"`
}

CancelTaskResult is the (essentially empty) ack returned by tasks/cancel. Per SEP-2663, cancellation does not return task state — the client should issue tasks/get if it wants to observe the resulting "cancelled" status. Like UpdateTaskResult, the wire payload carries only the SEP-2322 resultType discriminator.

func (CancelTaskResult) MarshalJSON added in v0.2.41 

func (c CancelTaskResult) MarshalJSON() ([]byte, error)

MarshalJSON defaults ResultType to ResultTypeComplete so the zero value (CancelTaskResult{}) emits the spec-compliant wire shape automatically.

type CancelTaskResultV1 added in v0.2.41 

type CancelTaskResultV1 struct {
	TaskInfo
}

CancelTaskResultV1 is the v1 response to tasks/cancel. Per spec 2025-11-25: flat Result & Task intersection — same shape as GetTaskResultV1. (V2 returns an empty ack per SEP-2663.)

type CancelledTask added in v0.2.41 

type CancelledTask = DetailedTask

SEP-2663 narrowed aliases — convenient names for callers that have already branched on status. The wire shape is identical to DetailedTask; the alias just communicates which fields the caller expects to be populated.

type Claims 

type Claims struct {
	// Subject is the authenticated principal (user ID or client ID).
	Subject string `json:"sub"`

	// Issuer identifies the authorization server that issued the token.
	Issuer string `json:"iss"`

	// Audience lists the intended recipients of the token (RFC 8707).
	Audience []string `json:"aud"`

	// Scopes lists the granted scopes.
	Scopes []string `json:"scope"`

	// Extra holds additional claims not covered by the standard fields.
	Extra map[string]any `json:"extra,omitempty"`
}

Claims holds the authenticated identity extracted from a validated request. Populated by AuthValidators that also implement ClaimsProvider.

func AuthClaims 

func AuthClaims(ctx context.Context) *Claims

AuthClaims returns the authenticated identity from the context, or nil if no auth was configured or the validator does not provide claims.

Usage in a tool handler: 

func myHandler(ctx context.Context, req mcpkit.ToolRequest) (mcpkit.ToolResult, error) {
    claims := mcpkit.AuthClaims(ctx)
    if claims != nil {
        log.Printf("called by %s", claims.Subject)
    }
    // ...
}

type ClaimsProvider 

type ClaimsProvider interface {
	Claims(r *http.Request) *Claims
}

ClaimsProvider is an optional interface for AuthValidators that can extract identity claims from a validated request. Called only after Validate succeeds.

Validators that only perform pass/fail checks (like bearerTokenValidator) do not need to implement this interface.

type ClientCapabilities 

type ClientCapabilities struct {
	Sampling    *struct{}       `json:"sampling,omitempty"`
	Roots       *RootsCap       `json:"roots,omitempty"`
	Elicitation *ElicitationCap `json:"elicitation,omitempty"`
	Tasks       *ClientTasksCap `json:"tasks,omitempty"`
	// FileInputs advertises SEP-2356 support: the client can render
	// x-mcp-file schema properties as file pickers and encode the
	// chosen files as RFC 2397 data URIs. Currently a marker — the
	// SEP does not define sub-fields yet.
	FileInputs *struct{} `json:"fileInputs,omitempty"`

	// Extensions maps extension IDs to the client's capability declaration
	// for that extension. Sent during initialize to advertise extension support.
	Extensions map[string]ClientExtensionCap `json:"extensions,omitempty"`
}

ClientCapabilities describes features the client supports.

func PerRequestClientCaps added in v0.2.41 

func PerRequestClientCaps(raw json.RawMessage) *ClientCapabilities

PerRequestClientCaps decodes the SEP-2575 per-request client-capabilities override from raw JSON bytes (typically the value of _meta[PerRequestClientCapsKey] in the calling middleware's typed envelope). Returns nil if the bytes are empty or malformed — the caller falls back to session-level caps.

type ClientExtensionCap 

type ClientExtensionCap struct {
	// MIMETypes lists content types the client supports for this extension.
	MIMETypes []string `json:"mimeTypes,omitempty"`
}

ClientExtensionCap describes a client's support for a specific extension. The contents are extension-specific; MCP Apps uses MIMETypes to declare which app content types the client can render.

type ClientInfo 

type ClientInfo struct {
	Name    string `json:"name"`
	Version string `json:"version"`
}

ClientInfo identifies an MCP client from the initialize request.

type ClientTasksCap added in v0.2.41 

type ClientTasksCap struct {
	List     *TasksCapMethod   `json:"list,omitempty"`
	Cancel   *TasksCapMethod   `json:"cancel,omitempty"`
	Requests *TasksCapRequests `json:"requests,omitempty"`
}

ClientTasksCap declares client support for tasks in ClientCapabilities. Mirrors TasksCap structure.

type CompletedTask added in v0.2.41 

type CompletedTask = DetailedTask

SEP-2663 narrowed aliases — convenient names for callers that have already branched on status. The wire shape is identical to DetailedTask; the alias just communicates which fields the caller expects to be populated.

type CompletionArgument 

type CompletionArgument struct {
	// Name is the argument name being completed.
	Name string `json:"name"`

	// Value is the partial input the user has typed so far.
	Value string `json:"value"`
}

CompletionArgument describes the argument being completed and the partial input so far.

type CompletionCompleteResult 

type CompletionCompleteResult struct {
	Completion CompletionResult `json:"completion"`
}

CompletionCompleteResult is the typed result for completion/complete responses.

type CompletionHandler 

type CompletionHandler func(ctx PromptContext, ref CompletionRef, arg CompletionArgument) (CompletionResult, error)

CompletionHandler provides autocompletion suggestions for a specific reference. ref identifies the prompt or resource being completed, arg contains the argument name and partial value. Return matching suggestions.

type CompletionRef 

type CompletionRef struct {
	// Type is "ref/prompt" for prompt argument completion or "ref/resource" for resource URI completion.
	Type string `json:"type"`

	// Name is the prompt name (when Type is "ref/prompt").
	Name string `json:"name,omitempty"`

	// URI is the resource URI template (when Type is "ref/resource").
	URI string `json:"uri,omitempty"`
}

CompletionRef identifies what is being completed — a prompt argument or resource URI.

type CompletionResult 

type CompletionResult struct {
	// Values is the list of completion suggestions.
	Values []string `json:"values"`

	// Total is the total number of available completions (may be larger than len(Values)).
	Total int `json:"total,omitempty"`

	// HasMore indicates there are additional completions beyond what was returned.
	HasMore bool `json:"hasMore"`
}

CompletionResult is the server's response with completion suggestions.

type Content 

type Content struct {
	Type     string           `json:"type"`
	Text     string           `json:"text,omitempty"`
	MimeType string           `json:"mimeType,omitempty"`
	Data     string           `json:"data,omitempty"`
	Resource *ResourceContent `json:"resource,omitempty"`
}

Content is a single content item in a tool result. Supports text, image, audio, and embedded resource types per MCP spec.

func (*Content) UnmarshalJSON added in v0.1.21 

func (c *Content) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes a Content, tolerating an array-form `resource` field from peers that confuse EmbeddedResource (single) with ReadResourceResult (array). The first array element wins. See #81 for cardinality rationale.

type ContentChunk added in v0.1.17 

type ContentChunk struct {
	// RequestID links the chunk to the original tools/call request.
	RequestID json.RawMessage `json:"requestId"`

	// Content is the partial content block.
	Content Content `json:"content"`
}

ContentChunk is the notification payload for a streaming content block. Sent during tool execution to deliver partial results incrementally.

type CreateMessageRequest 

type CreateMessageRequest struct {
	Messages         []SamplingMessage `json:"messages"`
	SystemPrompt     string            `json:"systemPrompt,omitempty"`
	IncludeContext   string            `json:"includeContext,omitempty"` // "none", "thisServer", "allServers"
	Temperature      *float64          `json:"temperature,omitempty"`
	MaxTokens        int               `json:"maxTokens"`
	ModelPreferences *ModelPreferences `json:"modelPreferences,omitempty"`
	StopSequences    []string          `json:"stopSequences,omitempty"`
	Metadata         map[string]any    `json:"metadata,omitempty"`
	Meta             *SamplingMeta     `json:"_meta,omitempty"`
}

CreateMessageRequest is the params for a sampling/createMessage server-to-client request. The server sends this to ask the client to perform LLM inference.

type CreateMessageResult 

type CreateMessageResult struct {
	Model      string  `json:"model"`
	StopReason string  `json:"stopReason,omitempty"`
	Role       string  `json:"role"`
	Content    Content `json:"content"`
}

CreateMessageResult is the client's response to a sampling/createMessage request.

func Sample 

func Sample(ctx context.Context, req CreateMessageRequest) (CreateMessageResult, error)

Sample sends a sampling/createMessage request to the connected client and blocks until the client responds with an LLM inference result.

Returns ErrNoRequestFunc if called outside a session context (e.g., no transport). Returns ErrSamplingNotSupported if the client did not declare sampling capability. Returns context.DeadlineExceeded if the context expires before the client responds.

Usage in a tool handler: 

func myHandler(ctx context.Context, req mcpkit.ToolRequest) (mcpkit.ToolResult, error) {
    result, err := mcpkit.Sample(ctx, mcpkit.CreateMessageRequest{
        Messages:  []mcpkit.SamplingMessage{{Role: "user", Content: mcpkit.Content{Type: "text", Text: "summarize this"}}},
        MaxTokens: 1000,
    })
    if err != nil {
        return mcpkit.ErrorResult(err.Error()), nil
    }
    return mcpkit.TextResult(result.Content.Text), nil
}

func (*CreateMessageResult) UnmarshalJSON added in v0.1.21 

func (r *CreateMessageResult) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes a CreateMessageResult, tolerating an array-form `content` field (first element wins) from peers that emit the array shape. See #81.

type CreateTaskResult added in v0.2.41 

type CreateTaskResult struct {
	ResultType ResultType `json:"resultType"`
	TaskInfoV2
}

CreateTaskResult is returned by tools/call when the server elects to handle the call as an async task. Per SEP-2663 it is `Result & Task` — a flat intersection where the discriminator and the task fields share one object (taskId / status / ttlMs / ... at the top level alongside resultType).

Per SEP-2663, this envelope MUST NOT carry result, error, inputRequests, or requestState — those belong on tasks/get's DetailedTask response.

Wire shape (flat — no `task` wrapper): 

{"resultType": "task", "taskId": "...", "status": "working",
 "createdAt": "...", "lastUpdatedAt": "...", "ttlMs": 60000,
 "pollIntervalMs": 1000}

TaskInfoV2 is embedded so encoding/json promotes its fields to the parent (same trick DetailedTask uses); no custom MarshalJSON is needed.

type CreateTaskResultV1 added in v0.2.41 

type CreateTaskResultV1 struct {
	Task TaskInfo `json:"task"`
}

CreateTaskResultV1 is returned by tools/call when a v1 task is created instead of the immediate tool result. Per spec 2025-11-25: nested under "task" key. (V1 wire format; v2 uses CreateTaskResult with resultType.)

type DetachStrategy added in v0.2.41 

type DetachStrategy func(ctx context.Context) context.Context

DetachStrategy is a function that creates a background-safe context from a request-scoped context. The server registers a strategy that replaces transport-scoped functions (like requestFunc) with session-level equivalents that remain valid after the original HTTP request completes.

type DetailedTask added in v0.2.41 

type DetailedTask struct {
	// ResultType is the SEP-2322 polymorphic-dispatch discriminator. For
	// tasks/get responses it is always "complete" — the JSON-RPC request
	// itself completes with this response, even when the underlying task
	// is still running. (The task lifecycle is on the Status field.)
	// MarshalJSON defaults this to ResultTypeComplete when empty so
	// existing struct literals don't have to set it.
	ResultType ResultType `json:"resultType"`

	TaskInfoV2

	// Result is inlined when Status == TaskCompleted. Includes the original
	// ToolResult (with isError flag for tool-side errors).
	Result *ToolResult `json:"result,omitempty"`

	// Error is inlined when Status == TaskFailed. Mirrors the JSON-RPC error
	// shape and represents protocol-level failures only.
	Error *TaskError `json:"error,omitempty"`

	// InputRequests is populated when Status == TaskInputRequired and lists
	// the MRTR input requests the client must satisfy via tasks/update. // SEP-2322
	InputRequests InputRequests `json:"inputRequests,omitempty"`

	// RequestState is the opaque session-continuation token. // SEP-2322
	RequestState string `json:"requestState,omitempty"`
}

DetailedTask is the SEP-2663 discriminated union returned by tasks/get. The Status field discriminates which optional fields are populated:

  • working → no inlined payload
  • input_required → InputRequests populated
  • completed → Result populated
  • failed → Error populated
  • cancelled → no inlined payload

RequestState is opaque session-continuation state for stateless deployments; servers MAY include it on any status, clients MUST echo it back on the next tasks/get / tasks/update / tasks/cancel for the same task. // SEP-2322

func (DetailedTask) MarshalJSON added in v0.2.41 

func (d DetailedTask) MarshalJSON() ([]byte, error)

MarshalJSON defaults ResultType to ResultTypeComplete when empty so every tasks/get response carries the SEP-2322 polymorphic discriminator without every call site having to set it. The task lifecycle stays on Status.

type DisplayMode added in v0.1.29 

type DisplayMode string

DisplayMode represents an iframe display mode for MCP Apps. 

const (
	// DisplayModeInline renders the app inline within the host UI.
	DisplayModeInline DisplayMode = "inline"

	// DisplayModeFullscreen renders the app in a fullscreen overlay.
	DisplayModeFullscreen DisplayMode = "fullscreen"

	// DisplayModePIP renders the app in a picture-in-picture window.
	DisplayModePIP DisplayMode = "pip"
)

type ElicitationCap added in v0.2.41 

type ElicitationCap struct {
	Form *ElicitationFormCap `json:"form,omitempty"`
	URL  *ElicitationURLCap  `json:"url,omitempty"`
}

ElicitationCap describes client support for elicitation modes. Per SEP-1036: Form is the default mode (JSON schema → form). URL mode enables out-of-band interactions where the user visits a URL.

type ElicitationCompleteParams added in v0.2.41 

type ElicitationCompleteParams struct {
	ElicitationID string `json:"elicitationId"`
}

ElicitationCompleteParams is the params for the notifications/elicitation/complete notification (SEP-1036). The server sends this after the user completes an out-of-band URL-mode elicitation flow. The client uses elicitationId to correlate with the original elicitation request and may retry the denied operation.

type ElicitationFormCap added in v0.2.41 

type ElicitationFormCap struct{}

ElicitationFormCap is a marker for form-mode elicitation support. Currently empty; future specs may add fields (e.g., schema constraints).

type ElicitationMeta added in v0.1.29 

type ElicitationMeta struct {
	// UI contains MCP Apps presentation metadata.
	// When set, the host can render a UI resource during input collection
	// instead of falling back to the default schema-driven form.
	UI *UIMetadata `json:"ui,omitempty"`

	// RelatedTask identifies the task this request is associated with.
	// Set automatically by TaskContext.TaskElicit() so the client can
	// correlate side-channel requests with the originating task.
	RelatedTask *RelatedTaskMeta `json:"io.modelcontextprotocol/related-task,omitempty"`
}

ElicitationMeta holds protocol-level metadata for an elicitation request. Serialized as "_meta" in the elicitation/create params.

type ElicitationRequest 

type ElicitationRequest struct {
	Message         string           `json:"message"`
	RequestedSchema json.RawMessage  `json:"requestedSchema,omitempty"`
	Mode            string           `json:"mode,omitempty"`          // "form" (default) or "url"
	URL             string           `json:"url,omitempty"`           // Required for url mode
	ElicitationID   string           `json:"elicitationId,omitempty"` // Required for url mode; correlates with completion notification
	Meta            *ElicitationMeta `json:"_meta,omitempty"`
}

ElicitationRequest is the params for an elicitation/create server-to-client request. The server sends this to ask the client to collect structured user input.

For form mode (default): Message + RequestedSchema are used. For URL mode (SEP-1036): Message + URL + ElicitationID are used; RequestedSchema must NOT be set.

type ElicitationResult 

type ElicitationResult struct {
	Action  string         `json:"action"` // "accept", "decline", or "cancel"
	Content map[string]any `json:"content,omitempty"`
}

ElicitationResult is the client's response to an elicitation/create request.

func Elicit 

func Elicit(ctx context.Context, req ElicitationRequest) (ElicitationResult, error)

Elicit sends a form-mode elicitation/create request to the connected client and blocks until the client responds with user input.

Returns ErrNoRequestFunc if called outside a session context (e.g., no transport). Returns ErrElicitationNotSupported if the client did not declare elicitation capability. Returns context.DeadlineExceeded if the context expires before the client responds.

Usage in a tool handler: 

func myHandler(ctx context.Context, req mcpkit.ToolRequest) (mcpkit.ToolResult, error) {
    result, err := mcpkit.Elicit(ctx, mcpkit.ElicitationRequest{
        Message: "Which database should I connect to?",
        RequestedSchema: json.RawMessage(`{
            "type": "object",
            "properties": {"database": {"type": "string", "enum": ["prod", "staging", "dev"]}}
        }`),
    })
    if err != nil {
        return mcpkit.ErrorResult(err.Error()), nil
    }
    if result.Action != "accept" {
        return mcpkit.TextResult("User declined"), nil
    }
    return mcpkit.TextResult(fmt.Sprintf("Selected: %v", result.Content["database"])), nil
}

func ElicitURL added in v0.2.41 

func ElicitURL(ctx context.Context, req ElicitationRequest) (ElicitationResult, error)

ElicitURL sends a URL-mode elicitation/create request to the connected client (SEP-1036). The client presents the URL to the user for out-of-band interaction. The client's bearer token remains unchanged.

Returns ErrElicitationURLNotSupported if the client did not declare URL-mode elicitation capability.

After calling this, the server should send notifications/elicitation/complete (via NotifyElicitationComplete) when the out-of-band flow is done.

type ElicitationURLCap added in v0.2.41 

type ElicitationURLCap struct{}

ElicitationURLCap is a marker for URL-mode elicitation support (SEP-1036). Currently empty; future specs may add fields (e.g., allowed domains).

type Error 

type Error struct {
	Code    int    `json:"code"`
	Message string `json:"message"`
	Data    any    `json:"data,omitempty"`
}

Error is a JSON-RPC 2.0 error object.

type Extension 

type Extension struct {
	// ID is the extension identifier (e.g., "io.mcpkit/auth").
	ID string `json:"id"`

	// SpecVersion is the version of the spec this extension implements.
	SpecVersion string `json:"specVersion"`

	// Stability indicates the maturity of this extension.
	Stability Stability `json:"stability"`

	// Config holds extension-specific configuration, if any.
	Config map[string]any `json:"config,omitempty"`
}

Extension describes a protocol extension with maturity metadata. Extensions are advertised in the initialize response under capabilities.extensions.

type ExtensionCapability 

type ExtensionCapability struct {
	SpecVersion string `json:"specVersion"`
	Stability   string `json:"stability"`
}

ExtensionCapability describes a server extension's metadata in the initialize response capabilities.

type ExtensionProvider 

type ExtensionProvider interface {
	Extension() Extension
}

ExtensionProvider is implemented by sub-modules to declare their extension. This is how mcpkit/auth registers itself without the core module knowing about auth.

type FailedTask added in v0.2.41 

type FailedTask = DetailedTask

SEP-2663 narrowed aliases — convenient names for callers that have already branched on status. The wire shape is identical to DetailedTask; the alias just communicates which fields the caller expects to be populated.

type FileInputDescriptor added in v0.2.43 

type FileInputDescriptor struct {
	// Accept is the list of accepted MIME patterns or file extensions.
	// Each entry is one of:
	//   - exact MIME type:    "image/png"
	//   - wildcard subtype:   "image/*"
	//   - file extension:     ".pdf"  (matched against known MIME types)
	//
	// Empty Accept means any type is allowed.
	Accept []string `json:"accept,omitempty"`

	// MaxSize is the maximum size in bytes of the decoded file payload.
	// nil means no server-declared limit (the client may still impose its own).
	MaxSize *int `json:"maxSize,omitempty"`
}

FileInputDescriptor is the value of the x-mcp-file schema extension keyword (SEP-2356). It tells the client which file types the server will accept and the maximum decoded size in bytes.

Both fields are optional. An empty descriptor (`{}`) means "any file, any size" — the server still has to validate the payload at the transport boundary.

func ExtractFileInputDescriptor added in v0.2.43 

func ExtractFileInputDescriptor(schemaProp map[string]any) *FileInputDescriptor

ExtractFileInputDescriptor pulls the x-mcp-file descriptor from a JSON Schema property, or nil if the keyword is absent.

The descriptor may have been built by FileInputProperty (Go map of FileInputDescriptor) or unmarshalled from JSON (map[string]any with "accept" / "maxSize" fields) — both shapes are handled.

type FileTooLargeData added in v0.2.44 

type FileTooLargeData struct {
	Reason     string `json:"reason"` // always "file_too_large"
	Field      string `json:"field,omitempty"`
	ActualSize int    `json:"actualSize"`
	MaxSize    int    `json:"maxSize"`
}

FileTooLargeData is the wire-shape of FileTooLargeError. Frozen by the conformance suite: `{reason, actualSize, maxSize}`.

type FileTooLargeError added in v0.2.44 

type FileTooLargeError struct {
	// Field is the JSON-Schema property path of the offending arg (e.g.
	// "image" or "documents[0]"). Optional — empty when the validator
	// doesn't have path context.
	Field      string
	ActualSize int
	MaxSize    int
}

FileTooLargeError reports that a decoded payload exceeds the descriptor's MaxSize. The dispatcher serializes Data() as the JSON-RPC `error.data` object on the wire.

func (*FileTooLargeError) Data added in v0.2.44 

func (e *FileTooLargeError) Data() FileTooLargeData

Data returns the structured wire payload for this error.

func (*FileTooLargeError) Error added in v0.2.44 

func (e *FileTooLargeError) Error() string

func (*FileTooLargeError) Unwrap added in v0.2.44 

func (e *FileTooLargeError) Unwrap() error

Unwrap lets errors.Is(err, ErrFileTooLarge) succeed.

type FileTypeNotAcceptedData added in v0.2.44 

type FileTypeNotAcceptedData struct {
	Reason    string   `json:"reason"` // always "file_type_not_accepted"
	Field     string   `json:"field,omitempty"`
	MediaType string   `json:"mediaType"`
	Filename  string   `json:"filename,omitempty"`
	Accept    []string `json:"accept"`
}

FileTypeNotAcceptedData is the wire-shape of FileTypeNotAcceptedError. Frozen by the conformance suite: `{reason, mediaType, accept}`.

type FileTypeNotAcceptedError added in v0.2.44 

type FileTypeNotAcceptedError struct {
	Field     string
	MediaType string
	Filename  string
	Accept    []string
}

FileTypeNotAcceptedError reports that a decoded payload's media type or filename does not match any pattern in the descriptor's Accept list.

func (*FileTypeNotAcceptedError) Data added in v0.2.44 

func (e *FileTypeNotAcceptedError) Data() FileTypeNotAcceptedData

Data returns the structured wire payload for this error.

func (*FileTypeNotAcceptedError) Error added in v0.2.44 

func (e *FileTypeNotAcceptedError) Error() string

func (*FileTypeNotAcceptedError) Unwrap added in v0.2.44 

func (e *FileTypeNotAcceptedError) Unwrap() error

Unwrap lets errors.Is(err, ErrFileTypeNotAccepted) succeed.

type GetTaskResult added in v0.2.41 

type GetTaskResult = DetailedTask

GetTaskResult is the response shape for tasks/get. Identical to DetailedTask.

type GetTaskResultV1 added in v0.2.41 

type GetTaskResultV1 struct {
	TaskInfo
}

GetTaskResultV1 is the v1 response to tasks/get. Per spec 2025-11-25: flat Result & Task intersection — task fields at the root level, no "task" wrapper. (V2 returns DetailedTask with inlined result/error/inputRequests.)

type InitializeResult 

type InitializeResult struct {
	ProtocolVersion string             `json:"protocolVersion"`
	Capabilities    ServerCapabilities `json:"capabilities"`
	ServerInfo      ServerInfo         `json:"serverInfo"`
}

InitializeResult is the typed result for the initialize response.

type InputRequest added in v0.2.41 

type InputRequest struct {
	Method string          `json:"method"`
	Params json.RawMessage `json:"params,omitempty"`
}

InputRequest is a single MRTR input request enqueued by a server during tool execution: a method (e.g., "elicitation/create", "sampling/createMessage") plus opaque params encoded per that method's request schema. // SEP-2322

type InputRequests added in v0.2.41 

type InputRequests = map[string]InputRequest

InputRequests is the wire-format map from request key to InputRequest. Keys are server-chosen identifiers (e.g., "elicit-1") that the client echoes verbatim in the matching InputResponses entry. // SEP-2322

type InputRequiredResult added in v0.2.46 

type InputRequiredResult struct {
	// ResultType is always "input_required". Defaulted by MarshalJSON when
	// empty so server handlers can build the struct without thinking about
	// it.
	ResultType ResultType `json:"resultType"`

	// InputRequests is the map of server-chosen request keys → InputRequest
	// describing what the server needs from the client. Keys are echoed back
	// verbatim by the client in the matching InputResponses entry.
	InputRequests InputRequests `json:"inputRequests,omitempty"`

	// RequestState is the opaque session-continuation token. SEP-2322 says
	// servers MUST treat any echoed value as attacker-controlled; the helper
	// API in dispatch HMAC-signs it when a key is configured.
	RequestState string `json:"requestState,omitempty"`
}

InputRequiredResult is the SEP-2322 wire envelope returned by tools/call (and other request methods, in principle) when the server needs additional input from the client before it can produce a final result. Clients retry the same request with `inputResponses` (and the echoed `requestState`) until the server returns a complete result, a CreateTaskResult, or an error.

Renamed from IncompleteResult in SEP-2322 commit de6d76fb (merged 2026-05-06) per dsp-ant request. The wire `resultType` value flipped from "incomplete" to "input_required" at the same time. SEP-2663 had not yet adopted the rename as of 2026-05-07 PM, but Caitie committed to a coherent Draft Spec + Schema at the 5/15 RC (issue comment 4384052694), so the alignment direction is "input_required" both places.

Wire-format note: the `resultType` discriminator is camelCase like every other MCP wire field — Luca confirmed camelCase is the SEP-2322 spec standard. (The upstream conformance suite briefly used snake_case but that's being corrected on their side.)

func (InputRequiredResult) MarshalJSON added in v0.2.46 

func (r InputRequiredResult) MarshalJSON() ([]byte, error)

MarshalJSON defaults ResultType to ResultTypeInputRequired so handlers that build an InputRequiredResult{} literal don't have to set the discriminator.

type InputRequiredTask added in v0.2.41 

type InputRequiredTask = DetailedTask

SEP-2663 narrowed aliases — convenient names for callers that have already branched on status. The wire shape is identical to DetailedTask; the alias just communicates which fields the caller expects to be populated.

type InputResponses added in v0.2.41 

type InputResponses = map[string]json.RawMessage

InputResponses is the wire-format map from request key to opaque response payload. Keys MUST match those previously returned in InputRequests. The payload shape is defined by the original request method. // SEP-2322

type ListTasksResultV1 added in v0.2.41 

type ListTasksResultV1 struct {
	Tasks      []TaskInfo `json:"tasks"`
	NextCursor string     `json:"nextCursor,omitempty"`
}

ListTasksResultV1 is the v1 response to tasks/list with cursor pagination. (Removed in v2 — tasks/list is no longer part of the protocol.)

type LogLevel 

type LogLevel int

LogLevel represents MCP log severity levels (syslog-based, ascending severity). Used with logging/setLevel to control the minimum level of log notifications sent to the client, and with EmitLog to specify the severity of a message. 

const (
	LogDebug     LogLevel = iota // debug: detailed debugging information
	LogInfo                      // info: general informational messages
	LogNotice                    // notice: normal but significant events
	LogWarning                   // warning: warning conditions
	LogError                     // error: error conditions
	LogCritical                  // critical: critical conditions
	LogAlert                     // alert: action must be taken immediately
	LogEmergency                 // emergency: system is unusable
)

func ParseLogLevel 

func ParseLogLevel(s string) (LogLevel, bool)

ParseLogLevel converts a string to a LogLevel. Returns the level and true on success, or (LogDebug, false) for unknown strings.

func SlogToMCPLevel added in v0.2.28 

func SlogToMCPLevel(level slog.Level) LogLevel

SlogToMCPLevel maps a slog.Level to an MCP LogLevel. 

slog.LevelDebug  (-4) → LogDebug
slog.LevelInfo   (0)  → LogInfo
slog.LevelWarn   (4)  → LogWarning
slog.LevelError  (8)  → LogError
> slog.LevelError      → LogCritical

func (LogLevel) String 

func (l LogLevel) String() string

String returns the MCP wire name for the log level.

type LogMessage 

type LogMessage struct {
	Level  string `json:"level"`
	Logger string `json:"logger,omitempty"`
	Data   any    `json:"data"`
}

LogMessage is the params payload for a notifications/message notification.

type LoggingTransport added in v0.2.27 

type LoggingTransport struct {
	// Inner is the wrapped transport.
	Inner Transport

	// Logger receives log output. If nil, log.Default() is used.
	Logger *log.Logger

	// LogBodies controls whether full JSON-RPC message bodies are included
	// in log output. When false (default), only method names and direction
	// are logged — suitable for production. When true, full request/response
	// JSON is logged — useful for debugging but verbose.
	LogBodies bool
}

LoggingTransport is a Transport decorator that logs every JSON-RPC message flowing through the transport. Use it for wire-level debugging, conformance testing, and audit logging.

Wraps any Transport — zero cost when not used. Complements server middleware (which operates at the method level, post-deserialization) by providing raw message visibility before parsing.

Example: 

inner := server.NewInProcessTransport(srv)
logged := &core.LoggingTransport{Inner: inner, Logger: log.Default()}
c := client.NewClient("", info, client.WithTransport(logged))

func (*LoggingTransport) Call added in v0.2.27 

func (t *LoggingTransport) Call(ctx context.Context, req *Request) (*Response, error)

Call delegates to the inner transport and logs the request, response, and latency.

func (*LoggingTransport) Close added in v0.2.27 

func (t *LoggingTransport) Close() error

Close delegates to the inner transport and logs the close.

func (*LoggingTransport) Connect added in v0.2.27 

func (t *LoggingTransport) Connect(ctx context.Context) error

Connect delegates to the inner transport and logs the result.

func (*LoggingTransport) Notify added in v0.2.27 

func (t *LoggingTransport) Notify(ctx context.Context, req *Request) error

Notify delegates to the inner transport and logs the notification.

func (*LoggingTransport) SessionID added in v0.2.27 

func (t *LoggingTransport) SessionID() string

SessionID delegates to the inner transport.

type MCPLogHandler added in v0.2.28 

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

MCPLogHandler implements slog.Handler, routing structured log records through MCP's notifications/message protocol to the connected client.

The handler respects the per-session logging/setLevel — records below the client's requested level are dropped silently. slog levels are mapped to MCP LogLevel: Debug→debug, Info→info, Warn→warning, Error→error, >Error→critical.

Create via NewMCPLogHandler inside a tool/resource/prompt handler: 

func myTool(ctx core.ToolContext, req core.ToolRequest) (core.ToolResult, error) {
    logger := slog.New(core.NewMCPLogHandler(ctx, nil))
    logger.Info("processing", "key", "value")  // → notifications/message
    ...
}

func NewMCPLogHandler added in v0.2.28 

func NewMCPLogHandler(ctx context.Context, opts *MCPLogHandlerOptions) *MCPLogHandler

NewMCPLogHandler creates an slog.Handler that sends log records as MCP notifications/message to the connected client. The ctx must carry an MCP session (as set by the dispatch layer in tool/resource/prompt handlers).

If ctx has no session (e.g., called outside a handler), the handler is a safe no-op — Enabled() returns false for all levels.

func (*MCPLogHandler) Enabled added in v0.2.28 

func (h *MCPLogHandler) Enabled(_ context.Context, level slog.Level) bool

Enabled reports whether the handler handles records at the given level. Returns false when: the slog level filter rejects it, the session has no logging enabled (client never called logging/setLevel), or the MCP session level threshold is above the mapped MCP level.

func (*MCPLogHandler) Handle added in v0.2.28 

func (h *MCPLogHandler) Handle(_ context.Context, record slog.Record) error

Handle sends the slog record as an MCP notifications/message.

func (*MCPLogHandler) WithAttrs added in v0.2.28 

func (h *MCPLogHandler) WithAttrs(attrs []slog.Attr) slog.Handler

WithAttrs returns a new handler with the given attributes pre-set.

func (*MCPLogHandler) WithGroup added in v0.2.28 

func (h *MCPLogHandler) WithGroup(name string) slog.Handler

WithGroup returns a new handler that nests subsequent attributes under the given group name.

type MCPLogHandlerOptions added in v0.2.28 

type MCPLogHandlerOptions struct {
	// Logger is the MCP logger name sent in the "logger" field of
	// notifications/message. Defaults to "" (empty).
	Logger string

	// Level sets the minimum slog level. Records below this are dropped
	// before the MCP session level check. If nil, only the session's
	// logging/setLevel threshold applies.
	Level slog.Leveler
}

MCPLogHandlerOptions configures NewMCPLogHandler.

type MRTRRoundState added in v0.2.41 

type MRTRRoundState struct {
	Tool     string                     `json:"tool"`
	Answered map[string]json.RawMessage `json:"answered,omitempty"`
	Exp      int64                      `json:"exp"`
}

MRTRRoundState is the payload encoded inside an SEP-2322 ephemeral requestState token across multi-round flows. The dispatcher uses it to carry accumulated InputResponses from previous rounds back to the handler — the wire protocol only ships the current round's responses, so without this carry-over a stateless handler couldn't see history.

Tool is the tool name the token was issued for; replays against a different tool fail with ErrRequestStateInvalidSignature. Answered is the merged inputResponses map (raw, opaque per-key payloads). Exp is the unix-seconds expiry, mirroring the requestStatePayload semantics.

func DecodeMRTRStatePlaintext added in v0.2.41 

func DecodeMRTRStatePlaintext(token string) (MRTRRoundState, error)

DecodeMRTRStatePlaintext parses a token produced by EncodeMRTRStatePlaintext. Returns ErrRequestStateMalformed for unparseable tokens and ErrRequestStateExpired when the embedded exp is in the past. No signature check (plaintext mode has none).

func VerifyMRTRState added in v0.2.41 

func VerifyMRTRState(key []byte, token string) (MRTRRoundState, error)

VerifyMRTRState validates an incoming MRTR requestState token against the signing key + current time and returns the embedded round state. Errors:

  • ErrRequestStateMalformed: structural parse failures (split, base64, JSON)
  • ErrRequestStateInvalidSignature: signature mismatch (tampered or wrong key)
  • ErrRequestStateExpired: payload exp is in the past

Uses hmac.Equal for constant-time signature comparison.

type MethodContext added in v0.2.34 

type MethodContext struct {
	BaseContext
}

MethodContext is the context passed to custom JSON-RPC method handlers registered via server.HandleMethod or server.WithMethodHandler. It embeds BaseContext with no additional methods — custom methods get the same session capabilities as other handlers (EmitLog, Sample, Elicit, etc.).

func NewMethodContext added in v0.2.34 

func NewMethodContext(ctx context.Context) MethodContext

NewMethodContext constructs a MethodContext from a standard context.Context.

func (MethodContext) DetachFromClient added in v0.2.34 

func (mc MethodContext) DetachFromClient() MethodContext

DetachFromClient returns a MethodContext that preserves session state but is NOT cancelled when the client disconnects.

type ModelHint 

type ModelHint struct {
	Name string `json:"name,omitempty"`
}

ModelHint provides hints about which model the server prefers for sampling.

type ModelPreferences 

type ModelPreferences struct {
	Hints                []ModelHint `json:"hints,omitempty"`
	CostPriority         *float64    `json:"costPriority,omitempty"`
	SpeedPriority        *float64    `json:"speedPriority,omitempty"`
	IntelligencePriority *float64    `json:"intelligencePriority,omitempty"`
}

ModelPreferences describes the server's preferences for model selection when the client performs LLM sampling.

type NotificationHandler 

type NotificationHandler func(method string, params []byte)

NotificationHandler receives server-to-client notifications (logging, progress, resource updates). Used by tests to verify notification delivery.

type NotifyFunc 

type NotifyFunc func(method string, params any)

NotifyFunc sends a server-to-client JSON-RPC notification. method is the notification method (e.g., "notifications/message"). params will be JSON-marshaled as the notification's params field. This type is reusable for all server→client notifications (logging, progress, etc.).

type PingResult 

type PingResult struct{}

PingResult is the typed result for ping responses. Currently empty per spec, but typed to allow future extension.

type ProgressNotification 

type ProgressNotification struct {
	// ProgressToken is the token from the request's _meta.progressToken field.
	// It links this notification to the original request.
	ProgressToken any `json:"progressToken"`

	// Progress is the current progress value (e.g., bytes processed, items completed).
	Progress float64 `json:"progress"`

	// Total is the expected total value. Zero means indeterminate progress.
	Total float64 `json:"total,omitempty"`

	// Message is an optional human-readable status message.
	Message string `json:"message,omitempty"`
}

ProgressNotification is the params payload for a notifications/progress notification. Servers send this during long-running operations to report progress to the client. The ProgressToken must match the token from the client's original request _meta.

type PromptArgument 

type PromptArgument struct {
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	Required    bool   `json:"required,omitempty"`

	// Schema is an optional JSON Schema describing the expected value shape
	// for this argument. Mirrors ToolDef.InputSchema: typically a
	// map[string]any with "type", "enum", "minimum", etc. Arbitrary JSON
	// Schema keywords ($ref, $defs, additionalProperties, ...) are preserved
	// as-is through registration, serialization, and client deserialization.
	//
	// Enforced server-side: when set, the dispatcher validates incoming
	// argument values against the schema before invoking the handler and
	// returns -32602 Invalid Params with a structured errors list on
	// failure (#184). Arguments without a Schema bypass validation.
	// Use server.WithSchemaValidation(false) to opt out of call-time
	// validation if you prefer to validate in the handler.
	Schema any `json:"schema,omitempty"`
}

PromptArgument describes a single argument to a prompt.

type PromptContext added in v0.2.0 

type PromptContext struct {
	BaseContext
}

PromptContext is the context passed to PromptHandler and CompletionHandler functions. It embeds BaseContext with no additional methods.

func NewPromptContext added in v0.2.0 

func NewPromptContext(ctx context.Context) PromptContext

NewPromptContext constructs a PromptContext from a standard context.Context.

func (PromptContext) DetachFromClient added in v0.2.0 

func (pc PromptContext) DetachFromClient() PromptContext

DetachFromClient returns a PromptContext that preserves session state but is NOT cancelled when the client disconnects.

type PromptDef 

type PromptDef struct {
	// Name is the prompt identifier used in prompts/get.
	Name string `json:"name"`

	// Title is an optional display title.
	Title string `json:"title,omitempty"`

	// Description explains what this prompt does.
	Description string `json:"description,omitempty"`

	// Arguments defines the parameters this prompt accepts.
	Arguments []PromptArgument `json:"arguments,omitempty"`

	// Annotations holds optional metadata for this prompt.
	Annotations map[string]any `json:"annotations,omitempty"`

	// Timeout is a per-prompt execution timeout. Not serialized to clients.
	Timeout time.Duration `json:"-"`
}

PromptDef describes a prompt exposed via MCP.

type PromptHandler 

type PromptHandler func(ctx PromptContext, req PromptRequest) (PromptResult, error)

PromptHandler generates prompt messages, optionally using arguments.

type PromptMessage 

type PromptMessage struct {
	Role    string  `json:"role"`
	Content Content `json:"content"` // reuses Content from tool.go
}

PromptMessage is a single message in a prompt result.

func (*PromptMessage) UnmarshalJSON added in v0.1.21 

func (m *PromptMessage) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes a PromptMessage, tolerating an array-form `content` field from peers that emit the array shape by mistake. First element wins. See #81.

type PromptRequest 

type PromptRequest struct {
	Name      string
	Arguments map[string]any
}

PromptRequest is the validated input passed to a PromptHandler.

Arguments holds the decoded JSON values from the prompts/get request, keyed by argument name. Values retain their JSON types after decode: strings stay as string, numbers become float64, booleans stay bool, objects become map[string]any, arrays become []any. Handlers type-assert as needed. This shape mirrors how tool handlers receive ToolRequest.Arguments (raw JSON), but pre-decoded for ergonomic access — a prompt argument count is tiny, so eager decode is fine. See #87.

type PromptResult 

type PromptResult struct {
	Description string          `json:"description,omitempty"`
	Messages    []PromptMessage `json:"messages"`
}

PromptResult is the response from a prompt handler.

type PromptsCap 

type PromptsCap struct {
	ListChanged bool `json:"listChanged,omitempty"`
}

PromptsCap describes the server's prompts capability.

type PromptsListResult 

type PromptsListResult struct {
	Prompts    []PromptDef `json:"prompts"`
	NextCursor string      `json:"nextCursor,omitempty"`

	// TTL is the SEP-2549 cache freshness hint in seconds. See
	// ToolsListResult.TTL for full semantics — same three-state pointer
	// shape (nil = no guidance, &0 = do not cache, &N>0 = N seconds fresh).
	TTL *int `json:"ttl,omitempty"`
}

PromptsListResult is the typed result for prompts/list responses.

type RefValidator 

type RefValidator interface {
	ValidateRefs(tools []ToolDef, resourceURIs []string, templateURIs []string) []string
}

RefValidator is an optional interface that ExtensionProviders can implement to validate tool-to-resource references at server startup. The server calls ValidateRefs for each extension that implements this interface, passing all registered tools and the URIs of registered resources and templates. Returns a list of human-readable warning messages (empty if all refs resolve).

type RelatedTaskMeta added in v0.2.41 

type RelatedTaskMeta struct {
	TaskID string `json:"taskId"`
}

RelatedTaskMeta identifies a task associated with a result. Per MCP spec, tasks/result responses MUST include this in _meta["io.modelcontextprotocol/related-task"].

type RemediationHint added in v0.2.41 

type RemediationHint struct {
	// Type identifies the remediation mechanism. SEP-defined values:
	// "url", "oauth_authorization_details".
	Type string

	// Extra carries type-specific members. These are flattened to the
	// top level of the hint object on marshal (per SEP wire format).
	Extra map[string]any
}

RemediationHint is a single remediation suggestion within an authorization denial. Per SEP-2643, each hint has a `type` field plus zero or more type-specific members at the **top level** of the object (not nested).

To match the SEP wire format, this type uses custom JSON marshaling that flattens Extra fields onto the top level alongside `type`.

Example wire format for the oauth_authorization_details hint: 

{
  "type": "oauth_authorization_details",
  "authorization_details": [ ... ]
}

EXPERIMENTAL: subject to rename/removal as SEP-2643 evolves.

func OAuthAuthorizationDetailsHint added in v0.2.41 

func OAuthAuthorizationDetailsHint(authorizationDetails any) RemediationHint

OAuthAuthorizationDetailsHint creates a SEP-2643 remediation hint of type "oauth_authorization_details" carrying an RFC 9396 authorization_details array. Used for UC2 example 2 (RAR) and UC3 (additional credential).

func URLHint added in v0.2.41 

func URLHint() RemediationHint

URLHint creates a SEP-2643 remediation hint of type "url". Used for UC1 (URL-based approval composed with URLElicitationRequiredError).

func (RemediationHint) MarshalJSON added in v0.2.41 

func (h RemediationHint) MarshalJSON() ([]byte, error)

MarshalJSON flattens Extra at the top level of the JSON object, alongside the "type" field, per SEP-2643.

func (*RemediationHint) UnmarshalJSON added in v0.2.41 

func (h *RemediationHint) UnmarshalJSON(b []byte) error

UnmarshalJSON splits the "type" field from the other top-level members, reversing the flattening done by MarshalJSON.

type Request 

type Request struct {
	JSONRPC string          `json:"jsonrpc"`
	ID      json.RawMessage `json:"id"`
	Method  string          `json:"method"`
	Params  json.RawMessage `json:"params,omitempty"`
}

Request is a JSON-RPC 2.0 request envelope.

func (*Request) IsNotification 

func (r *Request) IsNotification() bool

IsNotification returns true if this request has no ID (JSON-RPC notification).

type RequestFunc 

type RequestFunc func(ctx context.Context, method string, params any) (json.RawMessage, error)

RequestFunc sends a server-to-client JSON-RPC request and blocks until the client sends a response. method is the JSON-RPC method (e.g., "sampling/createMessage"). params will be JSON-marshaled as the request's params field. Returns the raw JSON result on success, or an error on timeout, transport failure, or JSON-RPC error from the client.

type ResourceContent 

type ResourceContent struct {
	URI      string `json:"uri"`
	MimeType string `json:"mimeType,omitempty"`
	Text     string `json:"text,omitempty"`
	Blob     string `json:"blob,omitempty"`
}

ResourceContent is an embedded resource reference in a tool result.

type ResourceContentMeta 

type ResourceContentMeta struct {
	// UI contains MCP Apps presentation metadata.
	UI *UIMetadata `json:"ui,omitempty"`
}

ResourceContentMeta holds per-content metadata in resources/read responses. Takes precedence over the resource-level metadata from resources/list.

type ResourceContext added in v0.2.0 

type ResourceContext struct {
	BaseContext
}

ResourceContext is the context passed to ResourceHandler and TemplateHandler functions. It embeds BaseContext with no additional methods — resources don't support progress or content streaming.

func NewResourceContext added in v0.2.0 

func NewResourceContext(ctx context.Context) ResourceContext

NewResourceContext constructs a ResourceContext from a standard context.Context.

func (ResourceContext) DetachFromClient added in v0.2.0 

func (rc ResourceContext) DetachFromClient() ResourceContext

DetachFromClient returns a ResourceContext that preserves session state but is NOT cancelled when the client disconnects.

type ResourceDef 

type ResourceDef struct {
	// URI uniquely identifies this resource.
	URI string `json:"uri"`

	// Name is a human-readable short name.
	Name string `json:"name"`

	// Title is an optional display title.
	Title string `json:"title,omitempty"`

	// Description explains what this resource provides.
	Description string `json:"description,omitempty"`

	// MimeType is the MIME type of the resource content.
	MimeType string `json:"mimeType,omitempty"`

	// Annotations holds optional metadata for this resource.
	Annotations map[string]any `json:"annotations,omitempty"`

	// Timeout is a per-resource execution timeout. Not serialized to clients.
	Timeout time.Duration `json:"-"`
}

ResourceDef describes a resource exposed via MCP.

type ResourceHandler 

type ResourceHandler func(ctx ResourceContext, req ResourceRequest) (ResourceResult, error)

ResourceHandler reads a resource by URI.

type ResourceReadContent 

type ResourceReadContent struct {
	URI      string `json:"uri"`
	MimeType string `json:"mimeType,omitempty"`
	Text     string `json:"text,omitempty"`
	Blob     string `json:"blob,omitempty"`

	// Meta holds per-content metadata (e.g., UI overrides).
	// Takes precedence over the resource-level _meta from resources/list.
	Meta *ResourceContentMeta `json:"_meta,omitempty"`
}

ResourceReadContent is a single content item returned by resources/read. Either Text or Blob is set, not both.

type ResourceRequest 

type ResourceRequest struct {
	URI string
}

ResourceRequest is the validated input passed to a ResourceHandler.

type ResourceResult 

type ResourceResult struct {
	Contents []ResourceReadContent `json:"contents"`
}

ResourceResult is the response from a resource handler.

func (*ResourceResult) UnmarshalJSON added in v0.1.21 

func (r *ResourceResult) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes a ResourceResult, tolerating a single-object `contents` form from peers that emit a bare object instead of the spec-canonical array. Single objects are wrapped into a 1-element slice. See #81.

type ResourceTemplate 

type ResourceTemplate struct {
	// URITemplate is an RFC 6570 URI template (e.g., "file:///{path}").
	// This serves as the unique identifier for the template in the registry —
	// registering a template with the same URI template string overwrites the
	// previous registration.
	URITemplate string `json:"uriTemplate"`

	// Name is a human-readable short name.
	Name string `json:"name"`

	// Title is an optional display title.
	Title string `json:"title,omitempty"`

	// Description explains what this template provides.
	Description string `json:"description,omitempty"`

	// MimeType is the default MIME type for resources matching this template.
	MimeType string `json:"mimeType,omitempty"`

	// Annotations holds optional metadata for this template.
	Annotations map[string]any `json:"annotations,omitempty"`

	// Timeout is a per-template execution timeout. Not serialized to clients.
	Timeout time.Duration `json:"-"`
}

ResourceTemplate describes a parameterized resource URI template.

type ResourceTemplatesListResult 

type ResourceTemplatesListResult struct {
	ResourceTemplates []ResourceTemplate `json:"resourceTemplates"`
	NextCursor        string             `json:"nextCursor,omitempty"`

	// TTL is the SEP-2549 cache freshness hint in seconds. See
	// ToolsListResult.TTL for full semantics — same three-state pointer
	// shape (nil = no guidance, &0 = do not cache, &N>0 = N seconds fresh).
	TTL *int `json:"ttl,omitempty"`
}

ResourceTemplatesListResult is the typed result for resources/templates/list responses.

type ResourceUpdatedNotification 

type ResourceUpdatedNotification struct {
	URI string `json:"uri"`
}

ResourceUpdatedNotification is the params payload for notifications/resources/updated. Sent by the server to subscribed clients when a resource's content has changed.

type ResourcesCap 

type ResourcesCap struct {
	Subscribe   bool `json:"subscribe,omitempty"`
	ListChanged bool `json:"listChanged,omitempty"`
}

ResourcesCap describes the server's resources capability.

type ResourcesListResult 

type ResourcesListResult struct {
	Resources  []ResourceDef `json:"resources"`
	NextCursor string        `json:"nextCursor,omitempty"`

	// TTL is the SEP-2549 cache freshness hint in seconds. See
	// ToolsListResult.TTL for full semantics — same three-state pointer
	// shape (nil = no guidance, &0 = do not cache, &N>0 = N seconds fresh).
	TTL *int `json:"ttl,omitempty"`
}

ResourcesListResult is the typed result for resources/list responses.

type Response 

type Response struct {
	JSONRPC string          `json:"jsonrpc"`
	ID      json.RawMessage `json:"id"`
	Result  any             `json:"result,omitempty"`
	Error   *Error          `json:"error,omitempty"`
}

Response is a JSON-RPC 2.0 response.

func NewAuthorizationDenialError added in v0.2.41 

func NewAuthorizationDenialError(id []byte, code int, message string, denial AuthorizationDenial) *Response

NewAuthorizationDenialError creates a JSON-RPC error response with an authorization denial envelope in the error data. The error code should be chosen based on the use case:

  • UC1 (URL approval): use ErrCodeURLElicitationRequired (-32042)
  • UC2/UC3 (credential change): use the tool execution error code

The denial is composed into the error data alongside any other fields (e.g., elicitations for UC1).

EXPERIMENTAL: subject to change as the FineGrainedAuth SEP evolves.

func NewErrorResponse 

func NewErrorResponse(id json.RawMessage, code int, message string) *Response

NewErrorResponse creates an error response for the given request ID.

func NewErrorResponseWithData 

func NewErrorResponseWithData(id json.RawMessage, code int, message string, data any) *Response

NewErrorResponseWithData creates an error response with additional structured data. Used for protocol errors that carry machine-readable context (e.g., supported versions).

func NewResponse 

func NewResponse(id json.RawMessage, result any) *Response

NewResponse creates a success response for the given request ID. Result is stored as-is and serialized once when the transport sends it.

func NewURLElicitationRequiredError added in v0.2.41 

func NewURLElicitationRequiredError(id json.RawMessage, message string, data URLElicitationRequiredErrorData) *Response

NewURLElicitationRequiredError creates a -32042 error response indicating that URL-based elicitation flows must be completed before retrying.

func (*Response) ResultAs added in v0.2.20 

func (r *Response) ResultAs(v any) error

ResultAs unmarshals the response result into v. Use this when you need to inspect the result after it has been through JSON round-trip (e.g., in tests or client code). Handles both typed results (any) and pre-serialized json.RawMessage.

type ResultType added in v0.2.41 

type ResultType string

ResultType is the discriminator on a tools/call response.

"task" indicates a task-based response (CreateTaskResult). The "complete" and "input_required" values come from MRTR (Multi-Round Tool Result, SEP-2322) and signal whether a tool result is final or expects further input rounds. The "input_required" variant was renamed from "incomplete" in SEP-2322 commit de6d76fb, merged 2026-05-06. 

const (
	ResultTypeTask          ResultType = "task"
	ResultTypeComplete      ResultType = "complete"       // SEP-2322
	ResultTypeInputRequired ResultType = "input_required" // SEP-2322
)

type Root added in v0.1.18 

type Root struct {
	// URI is the root's location (e.g., "file:///home/user/project").
	URI string `json:"uri"`

	// Name is an optional human-readable label for this root.
	Name string `json:"name,omitempty"`
}

Root represents a filesystem root provided by the client. Roots inform the server about available directories for tool execution.

type RootsCap 

type RootsCap struct {
	ListChanged bool `json:"listChanged,omitempty"`
}

RootsCap describes the client's roots capability.

type RootsListResult added in v0.1.18 

type RootsListResult struct {
	Roots []Root `json:"roots"`
}

RootsListResult is the response to a roots/list server-to-client request.

type SamplingMessage 

type SamplingMessage struct {
	Role    string  `json:"role"`
	Content Content `json:"content"`
}

SamplingMessage is a single message in a sampling/createMessage request.

func (*SamplingMessage) UnmarshalJSON added in v0.1.21 

func (m *SamplingMessage) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes a SamplingMessage, tolerating an array-form `content` field (first element wins). The spec currently specifies single-content for SamplingMessage; widening to multi-part is tracked by #141 and will reuse this hook by switching to decodeContentSlice. See #81.

type SamplingMeta added in v0.1.29 

type SamplingMeta struct {
	// UI contains MCP Apps presentation metadata.
	// When set, the host can associate the sampling request with a UI resource.
	UI *UIMetadata `json:"ui,omitempty"`

	// RelatedTask identifies the task this request is associated with.
	// Set automatically by TaskContext.TaskSample() so the client can
	// correlate side-channel requests with the originating task.
	RelatedTask *RelatedTaskMeta `json:"io.modelcontextprotocol/related-task,omitempty"`
}

SamplingMeta holds protocol-level metadata for a sampling request. Serialized as "_meta" in the sampling/createMessage params.

type SchemaGenerator added in v0.2.26 

type SchemaGenerator func(v any) json.RawMessage

SchemaGenerator converts a Go value (typically a pointer to a struct) into a JSON Schema representation. The value is used only for type reflection — its fields are not read.

Implementations should return a JSON-encoded schema suitable for ToolDef.InputSchema / OutputSchema (type: "object" with properties, required, etc.).

Example usage: 

schema := sg(new(MyInput))  // reflects on MyInput struct tags

type ScopeAwareTokenSource 

type ScopeAwareTokenSource interface {
	TokenSource
	// TokenForScopes invalidates the cached token and triggers a new
	// authorization flow with the given scopes merged into the existing set.
	TokenForScopes(scopes []string) (string, error)
}

ScopeAwareTokenSource extends TokenSource with scope step-up capability. When the server returns 403 with required scopes in the WWW-Authenticate header, the client transport calls TokenForScopes to re-authenticate with broader permissions.

Implementations that support interactive re-auth (like OAuthTokenSource) should implement this interface. Static tokens and implementations that cannot acquire new scopes need not implement it — the transport will return a ClientAuthError instead of retrying.

type ServerCapabilities 

type ServerCapabilities struct {
	Tools       *ToolsCap                      `json:"tools,omitempty"`
	Resources   *ResourcesCap                  `json:"resources,omitempty"`
	Prompts     *PromptsCap                    `json:"prompts,omitempty"`
	Tasks       *TasksCap                      `json:"tasks,omitempty"`
	Logging     *struct{}                      `json:"logging,omitempty"`
	Completions *struct{}                      `json:"completions,omitempty"`
	Extensions  map[string]ExtensionCapability `json:"extensions,omitempty"`
}

ServerCapabilities describes the features the server supports, returned in the initialize response.

type ServerInfo 

type ServerInfo struct {
	Name         string `json:"name"`
	Version      string `json:"version"`
	Title        string `json:"title,omitempty"`
	Description  string `json:"description,omitempty"`
	Instructions string `json:"instructions,omitempty"`
	WebsiteURL   string `json:"websiteUrl,omitempty"`
}

ServerInfo identifies an MCP server in the initialize response.

type ServerRequestHandler 

type ServerRequestHandler func(ctx context.Context, req *Request) *Response

ServerRequestHandler handles server-to-client JSON-RPC requests (sampling, elicitation). The client registers this on the transport so the server can send requests during tool execution and receive responses.

type Stability 

type Stability string

Stability represents the maturity level of an extension. 

const (
	// Experimental indicates the extension is in development and may change.
	Experimental Stability = "experimental"
	// Stable indicates the extension is production-ready.
	Stable Stability = "stable"
	// Deprecated indicates the extension will be removed in a future version.
	Deprecated Stability = "deprecated"
)

type TaskError added in v0.2.41 

type TaskError struct {
	Code    int    `json:"code"`
	Message string `json:"message"`
	Data    any    `json:"data,omitempty"`
}

TaskError is the error shape for protocol-level failures (status: failed). Mirrors the JSON-RPC error object shape.

type TaskInfo added in v0.2.41 

type TaskInfo struct {
	TaskID        string     `json:"taskId"`
	ParentTaskID  string     `json:"parentTaskId,omitempty"` // set for sub-tasks spawned by TaskContext.SpawnTool
	Status        TaskStatus `json:"status"`
	StatusMessage string     `json:"statusMessage,omitempty"`
	CreatedAt     string     `json:"createdAt"`
	LastUpdatedAt string     `json:"lastUpdatedAt"`
	TTL           *int       `json:"ttl"`                    // milliseconds; null = unlimited
	PollInterval  int        `json:"pollInterval,omitempty"` // milliseconds
}

TaskInfo is the wire-format task object returned by tasks/* methods. TTL is required but nullable per spec: *int with null = unlimited.

type TaskInfoV2 added in v0.2.41 

type TaskInfoV2 struct {
	TaskID         string     `json:"taskId"`
	Status         TaskStatus `json:"status"`
	StatusMessage  string     `json:"statusMessage,omitempty"`
	CreatedAt      string     `json:"createdAt"`
	LastUpdatedAt  string     `json:"lastUpdatedAt"`
	TTLMs          *int       `json:"ttlMs"`                    // required+nullable, null = unlimited
	PollIntervalMs *int       `json:"pollIntervalMs,omitempty"` // optional
}

TaskInfoV2 is the v2 wire shape for task metadata. Differences from (v1) TaskInfo:

  • ttl renamed to ttlMs. Units in the field name. Integer milliseconds.
  • pollInterval renamed to pollIntervalMs. Integer milliseconds.
  • parentTaskId removed. SEP-2663 does not expose task parentage.

The TaskStore already uses milliseconds internally, so the v2 wire surface is a pass-through (no unit conversion at the boundary). Per SEP-2663 the server MAY change ttlMs over the lifetime of a task (e.g. reset on each tasks/get to extend liveness while a client is observing it).

type TaskStatus added in v0.2.41 

type TaskStatus string

TaskStatus is the lifecycle state of an MCP task. 

const (
	// TaskWorking means the task is actively executing.
	TaskWorking TaskStatus = "working"

	// TaskInputRequired means the task is paused, awaiting client input
	// (e.g., via elicitation or sampling).
	TaskInputRequired TaskStatus = "input_required"

	// TaskCompleted means the task succeeded (terminal).
	TaskCompleted TaskStatus = "completed"

	// TaskFailed means the task errored (terminal).
	TaskFailed TaskStatus = "failed"

	// TaskCancelled means the task was cancelled by the client (terminal).
	TaskCancelled TaskStatus = "cancelled"
)

func (TaskStatus) IsTerminal added in v0.2.41 

func (s TaskStatus) IsTerminal() bool

IsTerminal reports whether the status is a terminal state.

type TaskSupport added in v0.2.41 

type TaskSupport string

TaskSupport declares how a tool interacts with the tasks capability. Set on ToolDef.Execution.TaskSupport. 

const (
	// TaskSupportRequired means clients SHOULD invoke as a task; servers
	// MUST return an error if clients ignore the requirement.
	TaskSupportRequired TaskSupport = "required"

	// TaskSupportOptional means clients may choose either synchronous
	// or task-based invocation.
	TaskSupportOptional TaskSupport = "optional"

	// TaskSupportForbidden means clients must NOT invoke as a task.
	TaskSupportForbidden TaskSupport = "forbidden"
)

type TasksCap added in v0.2.41 

type TasksCap struct {
	List     *TasksCapMethod   `json:"list,omitempty"`
	Cancel   *TasksCapMethod   `json:"cancel,omitempty"`
	Requests *TasksCapRequests `json:"requests,omitempty"`
}

TasksCap declares server support for the tasks capability in ServerCapabilities. Per spec: nested structure with list, cancel, requests.

type TasksCapElicitationMethods added in v0.2.41 

type TasksCapElicitationMethods struct {
	Create *TasksCapMethod `json:"create,omitempty"`
}

TasksCapElicitationMethods declares which elicitation methods support task augmentation.

type TasksCapMethod added in v0.2.41 

type TasksCapMethod struct{}

TasksCapMethod is an empty struct used as a marker in capability negotiation.

type TasksCapRequests added in v0.2.41 

type TasksCapRequests struct {
	Tools       *TasksCapToolsMethods       `json:"tools,omitempty"`
	Sampling    *TasksCapSamplingMethods    `json:"sampling,omitempty"`
	Elicitation *TasksCapElicitationMethods `json:"elicitation,omitempty"`
}

TasksCapRequests declares which request types support task-augmented responses.

type TasksCapSamplingMethods added in v0.2.41 

type TasksCapSamplingMethods struct {
	CreateMessage *TasksCapMethod `json:"createMessage,omitempty"`
}

TasksCapSamplingMethods declares which sampling methods support task augmentation.

type TasksCapToolsMethods added in v0.2.41 

type TasksCapToolsMethods struct {
	Call *TasksCapMethod `json:"call,omitempty"`
}

TasksCapToolsMethods declares which tool methods support task augmentation.

type TemplateHandler 

type TemplateHandler func(ctx ResourceContext, uri string, params map[string]string) (ResourceResult, error)

TemplateHandler reads a resource matched by a URI template. The uri parameter is the full resolved URI, params contains the extracted template variables.

type TokenSource 

type TokenSource interface {
	// Token returns a valid access token, refreshing if necessary.
	Token() (string, error)
}

TokenSource provides access tokens for the MCP client. Simple implementations return a static token; OAuth implementations handle the full flow including discovery, browser auth, and refresh.

type ToolContext added in v0.2.0 

type ToolContext struct {
	BaseContext
	// contains filtered or unexported fields
}

ToolContext is the context passed to ToolHandler functions. It embeds BaseContext and adds tool-specific methods (EmitProgress, EmitContent).

func NewToolContext added in v0.2.0 

func NewToolContext(ctx context.Context) ToolContext

NewToolContext constructs a ToolContext from a standard context.Context. Called by the dispatch layer before invoking tool handlers.

func NewToolContextWithMRTR added in v0.2.41 

func NewToolContextWithMRTR(ctx context.Context, progressToken any, inputResponses InputResponses, requestState string) ToolContext

NewToolContextWithMRTR constructs a ToolContext for an SEP-2322 MRTR retry: progress token plus the inputResponses/requestState the client echoed back. Called by the tools/call dispatch layer after parsing the request envelope; handlers read the values via ctx.InputResponse / ctx.InputResponses / ctx.RequestState.

func NewToolContextWithProgress added in v0.2.26 

func NewToolContextWithProgress(ctx context.Context, progressToken any) ToolContext

NewToolContextWithProgress constructs a ToolContext with a stored progress token. The dispatch layer passes the token from _meta.progressToken so that handlers can call ctx.Progress() without threading the token manually.

func (ToolContext) DetachFromClient added in v0.2.0 

func (tc ToolContext) DetachFromClient() ToolContext

DetachFromClient returns a ToolContext that preserves session state but is NOT cancelled when the client disconnects.

func (ToolContext) EmitContent added in v0.2.0 

func (tc ToolContext) EmitContent(requestID json.RawMessage, content Content)

EmitContent sends a partial content block to the client during tool execution. On non-streaming transports, the notification is silently dropped.

func (ToolContext) EmitProgress added in v0.2.0 

func (tc ToolContext) EmitProgress(token any, progress, total float64, message string)

EmitProgress sends a notifications/progress to the connected client. No-op if token is nil. Prefer ctx.Progress() when the token is stored in the context (TypedTool handlers, or dispatch with NewToolContextWithProgress).

func (ToolContext) HasInputResponses added in v0.2.41 

func (tc ToolContext) HasInputResponses() bool

HasInputResponses reports whether the client echoed any inputResponses back. Equivalent to len(ctx.InputResponses()) > 0; provided for readable branching in handlers ("if ctx.HasInputResponses() { ... }").

func (ToolContext) InputResponse added in v0.2.41 

func (tc ToolContext) InputResponse(key string) json.RawMessage

InputResponse returns the raw response payload for a specific request key from the inputResponses map, or nil if the key is missing. The payload shape matches the method declared in the original InputRequest (ElicitResult, CreateMessageResult, ListRootsResult, ...) — callers json.Unmarshal it into the matching typed struct.

func (ToolContext) InputResponses added in v0.2.41 

func (tc ToolContext) InputResponses() InputResponses

InputResponses returns the SEP-2322 inputResponses map the client echoed back into this tools/call. Nil on the first call (no prior InputRequiredResult) or when the client did not include the field.

Handlers branch on this to detect retries: nil = first call, ask for input; non-nil = client has answered, build the final result.

func (ToolContext) Progress added in v0.2.26 

func (tc ToolContext) Progress(progress, total float64, message string)

Progress sends a notifications/progress using the stored progress token from _meta.progressToken. No-op if the client didn't request progress. This is the preferred method in TypedTool handlers where the token is automatically captured from the request.

func (ToolContext) ProgressToken added in v0.2.26 

func (tc ToolContext) ProgressToken() any

ProgressToken returns the stored progress token, or nil if not set.

func (ToolContext) RequestInput added in v0.2.41 

func (tc ToolContext) RequestInput(reqs InputRequests) (ToolResult, error)

RequestInput is the SEP-2322 ephemeral retry primitive. Handlers return the value as their ToolResult to signal "I need more input from the client before I can produce a final result"; the dispatch layer reshapes the response on the wire as an InputRequiredResult and mints a fresh requestState for the next round.

Usage in a tool handler: 

func myTool(ctx core.ToolContext, req core.ToolRequest) (core.ToolResult, error) {
    if !ctx.HasInputResponses() {
        return ctx.RequestInput(core.InputRequests{
            "user_name": {
                Method: "elicitation/create",
                Params: rawElicitationParams,
            },
        })
    }
    // Decode ctx.InputResponse("user_name") and build the final result.
}

The error return is always nil — the helper exists so the call site reads as a single return statement matching the ToolHandler signature.

func (ToolContext) RequestState added in v0.2.41 

func (tc ToolContext) RequestState() string

RequestState returns the SEP-2322 requestState token the client echoed back. Empty on the first call. The token has already been verified by the dispatch layer (HMAC-checked when a signing key is configured), so handlers can trust its presence as proof the round-trip is intact — the embedded payload itself is opaque to handlers.

type ToolDef 

type ToolDef struct {
	// Name is the tool identifier used in tools/call.
	Name string `json:"name"`

	// Description is a human-readable summary of what the tool does.
	Description string `json:"description"`

	// InputSchema is the JSON Schema for the tool's arguments.
	// Typically a map[string]any with "type": "object", "properties": {...}, "required": [...].
	// Arbitrary JSON Schema fields (e.g. "$schema", "$defs", "$ref",
	// "additionalProperties") are preserved as-is through registration,
	// serialization, and client-side deserialization.
	InputSchema any `json:"inputSchema"`

	// OutputSchema is an optional JSON Schema for the tool's structuredContent output.
	// When present, the tool SHOULD return StructuredContent matching this schema.
	// Per MCP spec: enables clients to validate and process tool output programmatically.
	OutputSchema any `json:"outputSchema,omitempty"`

	// Execution holds task-related execution metadata.
	// Per MCP spec: declares whether this tool supports async task execution.
	Execution *ToolExecution `json:"execution,omitempty"`

	// Annotations holds optional metadata for this tool.
	// Convention: {"experimental": true} marks experimental tools.
	Annotations map[string]any `json:"annotations,omitempty"`

	// Meta holds protocol-level metadata (e.g., UI presentation hints).
	// Serialized as "_meta" in the tools/list response.
	Meta *ToolMeta `json:"_meta,omitempty"`

	// Timeout is a per-tool execution timeout. If set, overrides the
	// server-wide WithToolTimeout for this tool. Not serialized to clients.
	Timeout time.Duration `json:"-"`

	// RequiredScopes are OAuth scopes the caller's access token must include
	// to invoke this tool. Enforced by ext/auth's scope middleware
	// (auth.NewToolScopeMiddleware), which returns HTTP 403 + WWW-Authenticate
	// when scopes are missing — per SEP-2643 (FineGrainedAuth UC2).
	//
	// Not serialized to clients (it's enforcement metadata, not API contract).
	// Empty/nil means no per-tool scope check; the tool is callable by any
	// authenticated client (subject to global server.WithRequiredScopes).
	RequiredScopes []string `json:"-"`
}

ToolDef describes a tool exposed via MCP.

type ToolExecution added in v0.2.41 

type ToolExecution struct {
	TaskSupport TaskSupport `json:"taskSupport"`
}

ToolExecution describes task-related execution metadata on a tool definition. Per MCP spec: declared at the tool level, not in annotations (because it implies binding guarantees about behavior, not hints).

type ToolHandler 

type ToolHandler func(ctx ToolContext, req ToolRequest) (ToolResult, error)

ToolHandler is the function signature for tool implementations. The ToolContext provides typed access to session capabilities (EmitLog, EmitProgress, EmitContent, Sample, Elicit, etc.) with IDE discoverability.

type ToolMeta 

type ToolMeta struct {
	// UI contains MCP Apps presentation metadata.
	UI *UIMetadata `json:"ui,omitempty"`
}

ToolMeta holds protocol-level metadata for a tool definition. Serialized as "_meta" in the tools/list response.

type ToolRequest 

type ToolRequest struct {
	// Name of the tool being called.
	Name string

	// Arguments is the raw JSON arguments from the tools/call params.
	Arguments json.RawMessage

	// RequestID is the JSON-RPC request ID.
	RequestID json.RawMessage

	// ProgressToken is the token from the request's _meta.progressToken field.
	// Nil if the client did not request progress reporting. Pass this to
	// EmitProgress to send notifications/progress notifications.
	ProgressToken any

	// InputResponses is the SEP-2322 ephemeral MRTR retry payload — the
	// client echoes the inputResponses map back into the SAME tools/call
	// request that previously returned an InputRequiredResult. Keys MUST match
	// those the server returned in the matching InputRequests; values are
	// opaque per-method response payloads (ElicitResult, CreateMessageResult,
	// ListRootsResult, ...). Nil on the first call.
	//
	// Handlers usually access this through ToolContext.InputResponses() /
	// ToolContext.InputResponse(key); the raw field is here so middleware
	// and conformance tests can inspect the wire payload directly.
	InputResponses InputResponses

	// RequestState is the opaque session-continuation token the client
	// echoed back from a previous InputRequiredResult. The dispatch layer
	// verifies it (HMAC when a key is configured) before invoking the
	// handler. Empty on the first call.
	RequestState string
}

ToolRequest is the validated input passed to a ToolHandler.

func (*ToolRequest) Bind 

func (r *ToolRequest) Bind(v any) error

Bind unmarshals the tool arguments into the provided struct.

type ToolResult 

type ToolResult struct {
	// ResultType is the SEP-2322 polymorphic-dispatch discriminator. For
	// sync tools/call responses the wire value is "complete" (defaulted by
	// MarshalJSON when this field is empty). Task-creating responses use
	// ResultTypeTask on CreateTaskResult; multi-round results use
	// ResultTypeInputRequired on InputRequiredResult instead.
	ResultType ResultType `json:"resultType"`

	// Content is the list of content items to return.
	Content []Content `json:"content"`

	// IsError indicates the tool execution failed (but the JSON-RPC call itself succeeded).
	IsError bool `json:"isError,omitempty"`

	// StructuredContent holds optional structured data for the tool result.
	// When the tool has an OutputSchema, this field carries typed data matching
	// that schema. On error (IsError=true), it can carry structured error details.
	// Per MCP spec: "If outputSchema is present, structuredContent SHOULD be included."
	StructuredContent any `json:"structuredContent,omitempty"`

	// Meta holds optional result metadata (e.g., pagination cursor).
	Meta *ToolResultMeta `json:"_meta,omitempty"`

	// IsInputRequired is the in-process sentinel signalling that the handler
	// is returning an MRTR InputRequiredResult rather than a final tool result.
	// Set by ctx.RequestInput; the dispatch layer detects it, mints / refreshes
	// the requestState, and reshapes the wire payload as InputRequiredResult.
	// Never serialized — this field is in-process plumbing only.
	//
	// Renamed from IsIncomplete in lockstep with the SEP-2322 wire-variant
	// rename (commit de6d76fb merged 2026-05-06).
	IsInputRequired bool `json:"-"`

	// InputRequests is the SEP-2322 inputRequests map staged by ctx.RequestInput
	// when IsInputRequired is true. Dispatch reads it to build the
	// InputRequiredResult envelope. Nil for normal complete results. Never
	// serialized through ToolResult — dispatch reshapes the response into
	// InputRequiredResult.
	InputRequests InputRequests `json:"-"`
}

ToolResult is the response from a tool handler.

func ErrorResult 

func ErrorResult(text string) ToolResult

ErrorResult creates a ToolResult marked as an error with the given message.

func StructuredError 

func StructuredError(text string, data any) ToolResult

StructuredError creates a ToolResult marked as an error with both text and structured error data. Use this to return machine-readable error details alongside a human-readable error message.

func StructuredResult 

func StructuredResult(text string, data any) ToolResult

StructuredResult creates a ToolResult with both text content and structured data. Use this when the tool has an OutputSchema — structuredContent carries typed data matching the schema, while content provides a human-readable summary.

func TextResult 

func TextResult(text string) ToolResult

TextResult creates a ToolResult with a single text content item.

func (ToolResult) MarshalJSON added in v0.2.41 

func (r ToolResult) MarshalJSON() ([]byte, error)

MarshalJSON ensures every ToolResult on the wire carries a ResultType. Empty defaults to ResultTypeComplete so existing callers and struct literals don't have to set the field explicitly. SEP-2322 requires this discriminator on every non-task tools/call response so clients can dispatch sync vs task vs multi-round without inspecting payload shape.

func (*ToolResult) UnmarshalJSON added in v0.1.21 

func (r *ToolResult) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes a ToolResult, tolerating a single-object `content` form from peers that haven't caught up to the array-form spec. Single objects are wrapped into a 1-element slice. See #81.

type ToolResultMeta added in v0.1.18 

type ToolResultMeta struct {
	// NextCursor is a pagination cursor for fetching the next page.
	// Empty when there are no more pages.
	NextCursor string `json:"nextCursor,omitempty"`

	// RelatedTask identifies a task associated with this result.
	// Per MCP spec: set by tasks/result responses.
	RelatedTask *RelatedTaskMeta `json:"io.modelcontextprotocol/related-task,omitempty"`
}

ToolResultMeta carries optional metadata on a tool result.

type ToolsCap 

type ToolsCap struct {
	ListChanged bool `json:"listChanged,omitempty"`
}

ToolsCap describes the server's tools capability.

type ToolsListResult 

type ToolsListResult struct {
	Tools      []ToolDef `json:"tools"`
	NextCursor string    `json:"nextCursor,omitempty"`

	// TTL is the SEP-2549 cache freshness hint in SECONDS that the client
	// MAY use to cache the tools list before re-fetching. Semantics mirror
	// HTTP Cache-Control: max-age:
	//
	//   - nil (omitted on the wire) — no server guidance; client falls back
	//     to notifications/list_changed or its own heuristics.
	//   - &0 ("ttl": 0 on the wire) — explicit "do not cache"; client SHOULD
	//     re-fetch every time the list is needed.
	//   - >0 — the list is fresh for this many seconds; the client SHOULD NOT
	//     re-fetch before the TTL expires unless it receives list_changed.
	//
	// Pointer semantics matter: omitempty omits nil but keeps a pointer to 0,
	// so the spec's three states (absent / 0 / positive) round-trip correctly.
	TTL *int `json:"ttl,omitempty"`
}

ToolsListResult is the typed result for tools/list responses.

type Transport 

type Transport interface {
	// Connect establishes the transport (e.g., SSE handshake, session creation).
	Connect(ctx context.Context) error

	// Call sends a JSON-RPC request and returns the response.
	Call(ctx context.Context, req *Request) (*Response, error)

	// Notify sends a JSON-RPC notification (no response expected).
	Notify(ctx context.Context, req *Request) error

	// Close shuts down the transport.
	Close() error

	// SessionID returns the transport's session identifier (empty if none).
	SessionID() string
}

Transport is the minimal interface for client-server communication. Both HTTP transports and the in-process transport satisfy this interface. The client package consumes it; the server package provides implementations.

type TypedToolOption added in v0.2.26 

type TypedToolOption func(*typedToolConfig)

TypedToolOption configures optional fields on a TypedTool.

func WithToolAnnotations added in v0.2.26 

func WithToolAnnotations(a map[string]any) TypedToolOption

WithToolAnnotations sets the Annotations field on the generated ToolDef.

func WithToolMeta added in v0.2.26 

func WithToolMeta(m *ToolMeta) TypedToolOption

WithToolMeta sets the Meta field on the generated ToolDef.

func WithToolRequiredScopes added in v0.2.41 

func WithToolRequiredScopes(scopes ...string) TypedToolOption

WithToolRequiredScopes sets the RequiredScopes field on the generated ToolDef. When auth.NewToolScopeMiddleware is registered on the server, calls to this tool from clients without all of the named scopes are rejected at the transport layer with HTTP 403 + WWW-Authenticate per RFC 6750.

func WithTypedToolTimeout added in v0.2.26 

func WithTypedToolTimeout(d time.Duration) TypedToolOption

WithTypedToolTimeout sets a per-tool execution timeout on the generated ToolDef.

type TypedToolResult added in v0.2.26 

type TypedToolResult struct {
	ToolDef
	Handler ToolHandler
}

TypedToolResult holds the generated ToolDef and wrapped ToolHandler produced by TypedTool or TextTool. Use this to pass typed tool registrations to any registration API (server.Register, ext/ui.RegisterAppTool, etc.).

func TextTool added in v0.2.26 

func TextTool[In any](name, desc string,
	handler func(ctx ToolContext, input In) (string, error),
	opts ...TypedToolOption,
) TypedToolResult

TextTool creates a ToolDef and ToolHandler with auto-derived InputSchema where the handler returns a string. This is sugar for TypedTool[In, string].

Example: 

r := core.TextTool[GreetInput]("greet", "Say hello",
    func(ctx core.ToolContext, input GreetInput) (string, error) {
        return "Hello, " + input.Name, nil
    },
)

func TypedTool added in v0.2.26 

func TypedTool[In, Out any](name, desc string,
	handler func(ctx ToolContext, input In) (Out, error),
	opts ...TypedToolOption,
) TypedToolResult

TypedTool creates a ToolDef and ToolHandler with InputSchema (and optionally OutputSchema) auto-derived from Go struct types via the current SchemaGenerator. The handler receives typed input — no manual Bind() needed.

The Out type parameter controls output behavior:

  • string: handler returns text, wrapped via TextResult. No OutputSchema.
  • ToolResult: handler returns a ToolResult directly. No OutputSchema.
  • any struct: handler returns typed data. OutputSchema auto-derived from Out. Result uses StructuredResult with JSON text fallback.

Example (text output — use TextTool for convenience): 

r := core.TypedTool[SearchInput, string]("search", "Search books",
    func(ctx core.ToolContext, input SearchInput) (string, error) {
        return fmt.Sprintf("found %d books", len(results)), nil
    },
)

Example (structured output): 

r := core.TypedTool[SearchInput, SearchOutput]("search", "Search books",
    func(ctx core.ToolContext, input SearchInput) (SearchOutput, error) {
        return SearchOutput{Results: results, Total: len(results)}, nil
    },
)

type UICSPConfig 

type UICSPConfig struct {
	// ConnectDomains → CSP connect-src (fetch, XHR, WebSocket targets).
	ConnectDomains []string `json:"connectDomains,omitempty"`

	// ResourceDomains → CSP script-src, style-src, img-src, font-src, media-src.
	ResourceDomains []string `json:"resourceDomains,omitempty"`

	// FrameDomains → CSP frame-src (nested iframes).
	FrameDomains []string `json:"frameDomains,omitempty"`

	// BaseUriDomains → CSP base-uri.
	BaseUriDomains []string `json:"baseUriDomains,omitempty"`
}

UICSPConfig declares external domains for Content-Security-Policy construction. Hosts use these declarations when sandboxing MCP App iframes.

type UIMetadata 

type UIMetadata struct {
	// ResourceUri points to a ui:// resource containing the HTML to render.
	// Required for tools that want inline UI rendering.
	ResourceUri string `json:"resourceUri,omitempty"`

	// Visibility controls who can see/call this tool.
	// Default (nil): host applies its own default (typically ["model", "app"]).
	Visibility []UIVisibility `json:"visibility,omitempty"`

	// CSP declares external domains the app needs to load resources from.
	// Hosts construct Content-Security-Policy from these declarations.
	CSP *UICSPConfig `json:"csp,omitempty"`

	// Permissions lists browser capabilities the app requests
	// (e.g., "camera", "microphone", "geolocation", "clipboardWrite").
	Permissions []string `json:"permissions,omitempty"`

	// PrefersBorder hints whether the host should draw a visible border.
	// nil = host decides, true = border, false = no border.
	PrefersBorder *bool `json:"prefersBorder,omitempty"`

	// Domain requests a dedicated sandbox origin for the app.
	// Format is host-dependent (e.g., "myapp" → myapp.claudemcpcontent.com).
	Domain string `json:"domain,omitempty"`

	// SupportedDisplayModes declares which display modes this app can render in.
	// Nil means the host decides. Hosts use this to offer mode switching UI.
	SupportedDisplayModes []DisplayMode `json:"supportedDisplayModes,omitempty"`
}

UIMetadata describes UI presentation metadata for tools and resources. Serialized as the "_meta.ui" object in tools/list and resources/read responses. Part of the MCP Apps extension (io.modelcontextprotocol/ui).

type UIVisibility 

type UIVisibility string

UIVisibility controls tool access scope in the MCP Apps extension. 

const (
	// UIVisibilityModel means the tool appears in tools/list for the LLM.
	UIVisibilityModel UIVisibility = "model"

	// UIVisibilityApp means the tool is callable by apps from the same server.
	UIVisibilityApp UIVisibility = "app"
)

type URLElicitationRequiredErrorData added in v0.2.41 

type URLElicitationRequiredErrorData struct {
	Elicitations []ElicitationRequest `json:"elicitations"`
	Extra        map[string]any       `json:"-"`
}

URLElicitationRequiredErrorData is the structured data for a -32042 error. The Elicitations field carries URL-mode elicitation requests. Extra holds additional metadata (e.g., authorization denial context from FineGrainedAuth UC1). Extra keys are flattened into the top-level JSON object.

func (URLElicitationRequiredErrorData) MarshalJSON added in v0.2.41 

func (d URLElicitationRequiredErrorData) MarshalJSON() ([]byte, error)

MarshalJSON flattens Extra keys into the top-level alongside elicitations.

type UpdateTaskRequest added in v0.2.41 

type UpdateTaskRequest struct {
	TaskID         string         `json:"taskId"`
	InputResponses InputResponses `json:"inputResponses,omitempty"`
	RequestState   string         `json:"requestState,omitempty"` // SEP-2322
}

UpdateTaskRequest is the params payload for tasks/update — the MRTR-driven resume path. The client supplies InputResponses keyed by the same ids returned in DetailedTask.InputRequests, optionally echoing RequestState. // SEP-2663

type UpdateTaskResult added in v0.2.41 

type UpdateTaskResult struct {
	// ResultType is the SEP-2322 polymorphic-dispatch discriminator. Always
	// "complete" for the tasks/update ack (defaulted by MarshalJSON when empty).
	ResultType ResultType `json:"resultType"`
}

UpdateTaskResult is the (essentially empty) ack returned by tasks/update. Servers resume task execution asynchronously; clients learn the outcome via the next tasks/get. The wire payload carries only the SEP-2322 resultType discriminator so polymorphic dispatch on tools/call vs tasks/update vs tasks/get is uniform across the protocol. // SEP-2663

func (UpdateTaskResult) MarshalJSON added in v0.2.41 

func (u UpdateTaskResult) MarshalJSON() ([]byte, error)

MarshalJSON defaults ResultType to ResultTypeComplete so callers using the zero value (UpdateTaskResult{}) emit the spec-compliant wire shape without thinking about it.

type WorkingTask added in v0.2.41 

type WorkingTask = DetailedTask

SEP-2663 narrowed aliases — convenient names for callers that have already branched on status. The wire shape is identical to DetailedTask; the alias just communicates which fields the caller expects to be populated.

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.