Documentation
¶
Overview ¶
Package resource provides a type-safe fluent builder for serving MCP resources and URI-template (dynamic) resources, mirroring toolkit's style.
New(server, uri, name, description, read) builds a static resource; read is a typed func(ctx) (Content, error) — no raw SDK request/result. NewTemplate builds a templated resource whose read func also receives the concrete URI and the variables extracted from it (the SDK extracts none). Chain optional config, then register with Add:
- WithMIMEType / WithTitle / WithDescription / WithAnnotations — both.
- WithSize — static resources only.
Add panics if the URI is malformed (fails url.Parse), and NewTemplate panics on an invalid RFC 6570 template — surfacing the SDK's panics, consistent with toolkit.InputSchema.
Content envelopes (content.go) spare handlers from building []*mcp.ResourceContents by hand, filling the URI and a default MIME type: Text (text/plain), Blob (application/octet-stream), JSON[T] (application/json), and Raw as a verbatim escape hatch, with NewText / NewBlob / NewJSON constructors.
Template variables are exposed as a Vars map (not a typed struct): Get / Lookup / Has / List / Int accessors over the matched RFC 6570 values (Lookup is the comma-ok form that distinguishes absent from present-but-empty). The SDK gives no decode for templates, so a map keeps the surface minimal; a typed variant can be added later.
Sentinels (errors.go) follow the repo convention. ErrNotFound and ErrTemplateMismatch are return-side sentinels: returning either from a read func yields mcp.ResourceNotFoundError (CodeResourceNotFound) on the wire. Cross-transport errors.Is is not promised. ErrInvalidVars wraps a failed Vars.Int conversion. ErrNoContent is returned when a read func produces no content (a nil Content or an empty Raw), surfaced as a real error rather than a silent empty read.
Subscriptions (resources/updated) are not yet supported. list-changed works for free (the SDK fires it on AddResource/RemoveResources), but subscriptions need SubscribeHandler/UnsubscribeHandler set at mcp.NewServer construction, which the caller — not this package — owns.
Index ¶
Constants ¶
const ( // MIMEText is the fallback MIME type for Text content. MIMEText = "text/plain" // MIMEBlob is the fallback MIME type for Blob content. MIMEBlob = "application/octet-stream" // MIMEJSON is the MIME type JSON content always serves. MIMEJSON = "application/json" )
Default MIME types for the built-in Content shapes, exported so callers can pass them to WithMIMEType instead of repeating the literals.
Variables ¶
var ( // ErrNotFound signals a resource (or templated instance) does not exist. ErrNotFound = errors.New("resource not found") // ErrTemplateMismatch signals a read URI did not match the URI template. ErrTemplateMismatch = errors.New("uri does not match template") // ErrInvalidVars signals a template variable could not be converted. ErrInvalidVars = errors.New("invalid template variable") // ErrNoContent signals a read func produced no content — a nil Content or // an empty Raw. It is a real internal error (not not-found), so it passes // through toWireErr unchanged rather than masquerading as a missing // resource. ErrNoContent = errors.New("resource produced no content") )
Package sentinels, following the repo convention (no umbrella sentinel).
ErrNotFound and ErrTemplateMismatch are return-side sentinels: a read func returning either yields mcp.ResourceNotFoundError (CodeResourceNotFound) on the wire. Cross-transport errors.Is is not promised — the SDK serializes errors to a JSON-RPC code — same caveat as the elicit sentinels.
Functions ¶
This section is empty.
Types ¶
type Blob ¶
Blob is binary content, base64-encoded on the wire by the SDK. MIME overrides the resource's MIMEType; absent both, MIMEBlob.
type Content ¶
type Content interface {
// contains filtered or unexported methods
}
Content produces the contents of a single resource read. The uri and a fallback MIME type are supplied by the package at read time, so handlers need not repeat them.
type JSON ¶
type JSON[T any] struct { Value T }
JSON marshals Value and serves it as text with MIME MIMEJSON unconditionally — the resource's declared MIMEType (and WithMIMEType) do not apply to JSON content.
type Raw ¶
type Raw struct {
Contents []*mcp.ResourceContents
}
Raw is an escape hatch: it serves the given contents verbatim, for handlers that need multiple sub-resources or custom per-content metadata. Unlike the other shapes, Raw does not stamp the URI or fill a fallback MIME — the caller owns each block's fields. Contents must be non-empty; an empty Raw yields ErrNoContent rather than a silent empty read.
type Resource ¶
type Resource struct {
// contains filtered or unexported fields
}
Resource is a fluent registration builder, distinct from the SDK's mcp.Resource. It is a value type — builder methods return a copy.
func (Resource) Add ¶
func (r Resource) Add()
Add registers the resource on the server. It panics if the URI is malformed (fails url.Parse), surfacing the SDK's AddResource panic unchanged.
func (Resource) WithAnnotations ¶
func (r Resource) WithAnnotations(a *mcp.Annotations) Resource
WithAnnotations attaches client annotations to the resource.
func (Resource) WithDescription ¶
WithDescription overrides the description passed to New.
func (Resource) WithMIMEType ¶
WithMIMEType sets the resource's declared MIME type.
type Template ¶
type Template struct {
// contains filtered or unexported fields
}
Template is a fluent registration builder for a URI-template resource, distinct from the SDK's mcp.ResourceTemplate. It is a value type — builder methods return a copy.
func NewTemplate ¶
func NewTemplate( server *mcp.Server, uriTemplate, name, description string, read TemplateReadFunc, ) Template
NewTemplate starts a templated-resource registration. It parses uriTemplate immediately and panics if the template is invalid (RFC 6570), mirroring the SDK's AddResourceTemplate and toolkit.InputSchema panic conventions.
func (Template) Add ¶
func (t Template) Add()
Add registers the template on the server. The template was already parsed and validated by NewTemplate, so any malformed-template panic fires there, not here.
func (Template) WithAnnotations ¶
func (t Template) WithAnnotations(a *mcp.Annotations) Template
WithAnnotations attaches client annotations to the template.
func (Template) WithDescription ¶
WithDescription overrides the description passed to NewTemplate.
func (Template) WithMIMEType ¶
WithMIMEType sets the MIME type shared by resources matching the template.
type TemplateReadFunc ¶
TemplateReadFunc reads a templated resource for a concrete URI and the variables extracted from it.
type Text ¶
Text is UTF-8 textual content. MIME overrides the resource's declared MIMEType; absent both, it defaults to MIMEText.
type Vars ¶
type Vars struct {
// contains filtered or unexported fields
}
Vars holds the variables extracted from a matched URI template.
func (Vars) Get ¶
Get returns the string value of name, or "" if absent or not a string var. Get alone cannot distinguish an absent variable from a present-but-empty one — use Lookup or Has for that.
Source Files