Documentation
¶
Overview ¶
Package skills holds the wire types and pure rules for skills served by an upstream MCP server through the io.modelcontextprotocol/skills extension. It is a leaf: every layer may import it, and it imports no other package of this module.
Index ¶
- Constants
- Variables
- func Chunk(data []byte, offset, limit int64) (text []byte, next int64, more bool, err error)
- func ContentHash(e Entry) (string, error)
- func FrontmatterEqual(listed, parsed map[string]any) bool
- func ParseFrontmatter(skillMD []byte) (map[string]any, error)
- func ParseSkillURI(uri string) (root, path, name string, err error)
- func RelPath(root, fileURI string) (string, error)
- func ShouldContinue(ctx context.Context) bool
- func WithContinueCheck(ctx context.Context, check func() bool) context.Context
- type Entry
- type EntryError
- type FileRef
- type ListPage
- type TruncatedError
- type UnusableError
Constants ¶
const ( MaxFilesPerSkill = 512 MaxSkillBytes = 16 << 20 MaxSkillsPerServer = 200 // MaxUnlistedSkillsPerServer bounds the records kept for skills a server // no longer lists, so a server that keeps renaming its skills cannot grow // the store. Blocked records are kept beyond it. MaxUnlistedSkillsPerServer = 200 MaxListPages = 50 MaxListResponseBytes = 4 << 20 // MaxListBytes bounds all pages of one listing together. MaxListBytes = 16 << 20 MaxStoredTextPerServer = 64 << 20 MaxReadPerRefresh = 256 << 20 MaxFrontmatterBytes = 64 << 10 MaxScanBytesPerSkill = 1 << 20 MaxURIBytes = 2048 )
Bounds that keep one upstream from making mcpproxy read, store or scan without limit. They are constants, not config, so every layer agrees.
const ( BoundPages = "pages" BoundEntries = "entries" BoundResponseBytes = "response_bytes" )
The bound that cut a listing short.
const ( ReasonInvalidURI = "invalid_uri" ReasonNameMismatch = "name_mismatch" ReasonDynamic = "dynamic" ReasonTooManyFiles = "too_many_files" ReasonTooLarge = "too_large" ReasonServerBoundExceeded = "server_bound_exceeded" ReasonUnsupportedDigest = "unsupported_digest" ReasonDigestMismatch = "digest_mismatch" ReasonSizeMismatch = "size_mismatch" ReasonFrontmatterMismatch = "frontmatter_mismatch" ReasonFrontmatterInvalid = "frontmatter_invalid" ReasonReadFailed = "read_failed" ReasonStoredCopyDamaged = "stored_copy_damaged" )
Reasons a skill cannot be used. They are stored and shown, so they are a stable vocabulary.
const ExtensionKey = "io.modelcontextprotocol/skills"
ExtensionKey is the capabilities.extensions key an upstream announces to say it serves skills (SEP-2640).
Variables ¶
var ( // ErrChunkOffsetPastEnd: the offset is negative or beyond the end of the data. ErrChunkOffsetPastEnd = errors.New("offset is past the end of the file") // ErrChunkOffsetInsideRune: the offset points into the middle of a UTF-8 character. ErrChunkOffsetInsideRune = errors.New("offset is inside a UTF-8 character") )
var ErrNotServed = errors.New("skills: the server is not asked for skills")
ErrNotServed is returned by a listing that was not sent: the server does not announce skills, or it is excluded from them. It is deliberately not an empty listing. An empty listing says "this server has no skills now" and unlists what was known; a server that was not asked says nothing.
var ErrStopped = errors.New("skills: the read was stopped by its caller")
ErrStopped is returned by a multi-request read that its caller's continue check stopped. It is not a failure of the upstream.
Functions ¶
func Chunk ¶
Chunk cuts at most limit bytes of data starting at byte offset, ending on a UTF-8 character boundary, so the answer can be a few bytes shorter than limit. A limit smaller than one character still returns that whole character, so a reader always makes progress. next is the offset to ask for next (the end of the chunk) and more reports whether data remains after it.
An offset equal to len(data) is valid and returns an empty chunk. An offset beyond the end or inside a character is refused with ErrChunkOffsetPastEnd or ErrChunkOffsetInsideRune. limit must be positive; callers validate it.
func ContentHash ¶
ContentHash returns the approval binding of a skill: sk1- plus the sha256 of an unambiguous encoding of the skill URI, every file (sorted by URI) as (URI, relative path, digest, size), and the canonical frontmatter encoding. Every string is length-prefixed so two different inputs never share an encoding.
func FrontmatterEqual ¶
FrontmatterEqual compares the listed frontmatter with the one parsed from SKILL.md by value: YAML and JSON numbers compare by their exact numeric value, nested maps of either origin compare key by key. A value with no canonical form never compares equal.
func ParseFrontmatter ¶
ParseFrontmatter reads the leading "---" YAML block of a SKILL.md. The block is bounded at MaxFrontmatterBytes and must be a mapping.
func ParseSkillURI ¶
ParseSkillURI splits a skill address. The address must end in /SKILL.md; root is the address without that suffix, path is the root without scheme and "//", and name is the last segment of path.
func RelPath ¶
RelPath returns where fileURI sits inside the skill rooted at root. It rejects anything that is not strictly below root: another scheme or host, a query or fragment, an encoded separator or dot segment, an escaping "..", an absolute path, an empty segment or a control character.
func ShouldContinue ¶
ShouldContinue reports whether the read may send its next request. A context without a check always may.
func WithContinueCheck ¶
WithContinueCheck attaches a check that a multi-request read asks before every request it sends. It is how the catalog stops a listing that is still paging when skills are switched off: a context alone would need someone to watch the configuration and cancel it.
Types ¶
type Entry ¶
type Entry struct {
URI string
Frontmatter map[string]any
Files []FileRef
// Dynamic is set when the server declares resources as "dynamic": the
// file set cannot be pinned, so the skill is unusable.
Dynamic bool
}
Entry is one skill as listed by skills/list or returned by skills/get.
func DecodeEntry ¶
func DecodeEntry(raw json.RawMessage) (Entry, error)
DecodeEntry decodes one wire entry. Unknown fields are ignored.
func DecodeGetResult ¶
func DecodeGetResult(raw json.RawMessage) (Entry, error)
DecodeGetResult decodes a skills/get result.
func (Entry) Validate ¶
func (e Entry) Validate() *UnusableError
Validate applies the rules a listed skill must meet before anything is read for it. It returns nil for a usable entry.
type EntryError ¶
EntryError is a listing entry that did not decode.
type FileRef ¶
type FileRef struct {
URI string `json:"uri"`
Digest string `json:"digest"`
Size int64 `json:"size"`
}
FileRef is one file the listing promises, with the digest and size the bytes must match.
type ListPage ¶
type ListPage struct {
Entries []Entry
Errors []EntryError
NextCursor string
}
ListPage is one decoded skills/list result. A malformed entry lands in Errors and does not fail the page.
func DecodeListResult ¶
func DecodeListResult(raw json.RawMessage) (ListPage, error)
DecodeListResult decodes a skills/list result. Only an unusable envelope is an error; per-entry failures are reported in the page.
type TruncatedError ¶
TruncatedError reports that a listing stopped at a bound. It travels next to the partial result so the caller can record the listing as truncated rather than complete.
func (*TruncatedError) Error ¶
func (e *TruncatedError) Error() string
type UnusableError ¶
UnusableError says why a skill cannot be used: a machine Code from the Reason constants and a human Detail.
func VerifyFile ¶
func VerifyFile(ref FileRef, content []byte) *UnusableError
VerifyFile checks the bytes against the listing: size first, then sha256. Only sha256:<64 lower-case hex> digests are understood.
func (*UnusableError) Error ¶
func (e *UnusableError) Error() string
Directories
¶
| Path | Synopsis |
|---|---|
|
Package index is a memory-only full-text index of skills (spec 125, D12).
|
Package index is a memory-only full-text index of skills (spec 125, D12). |
|
Package skillstest is a fake upstream MCP server that serves skills over raw JSON-RPC on HTTP.
|
Package skillstest is a fake upstream MCP server that serves skills over raw JSON-RPC on HTTP. |