Files
Rusty Shackleford e969ebcfb0 fix(mcp): close Skills conformance gaps with directory reads and resource metadata (#905)
* feat(mcp): support Skills directory reads and metadata listing

Expose accepted skill directories and SKILL.md metadata so MCP hosts can
browse served packages without guessing manifest filenames. Reuse catalog
selection and refresh boundaries, including empty directories and stable
pagination, and normalize strict frontmatter for YAML 1.2 Core readback.

Add regressions and a pinned official conformance runner, and update the
runbook and MCP references to describe the browsing contract.

Refs #895

* fix(mcp): preserve supporting file MIME types in directory listings

Record UTF-8 classification from the same bounded bytes used for package
digests so directory metadata agrees with resource reads for extensionless
and unknown-extension text. Reuse the existing bounded reader without
adding listing-time payload reads or changing package limits.

Share pagination with skills/list, trust the SDK's typed request boundary,
and repair the pagination regression to detect stale catalog snapshots.

Refs #895

* fix(mcp): stream supporting file metadata inspection

Buffering supporting files during catalog refresh allocated with asset size.
Restore one bounded stream for digest, size and UTF-8 classification, retaining
at most three incomplete rune bytes and consuming invalid text through EOF.
Preserve the existing same-file checks, package caps and SKILL.md byte reader.

Keep real package-load benchmarks and strengthen the existing MIME fixtures
for split runes and bytes after invalid sequences. Use one first-match sed
command for the conformance URL without a truncated pipeline under pipefail.

Scoped packages, focused race tests, vet, shell syntax/shellcheck and all 45
pinned official checks pass. Allocation stays near 48 KB for 64 KiB and 8 MiB
assets; multibyte UTF-8 validation still costs CPU versus digest-only loading.

* test(mcp): consolidate directory and frontmatter coverage

Check every directory continuation URI so a duplicated middle entry cannot
hide a missing resource. Keep the existing before/after-cursor refresh cases.

Merge nested-skill acceptance fixtures in the catalog owner, preserving all
skill-count, skip-warning and directory assertions across configured and
targetless cases. Move directory capability coverage to initialization and
merge scalar, alias and rejection cases under the existing parser test.

Give cached-page benchmark skills names that match their URI directories.
Narrow tests, benchmark smoke and vet pass; duplicate-result and stale-catalog
mutations both fail, then restored source passes. Production is unchanged.
2026-11-15 00:21:35 +08:00

264 lines
7.8 KiB
Go

package utils
import (
"bytes"
"encoding/json"
"fmt"
"os"
"path/filepath"
"strings"
"gopkg.in/yaml.v3"
)
// IsRootFrontmatterLine reports whether a nonblank, noncomment line shares the
// first content line's indentation. Initialize *indent to -1 for each
// frontmatter block.
func IsRootFrontmatterLine(raw string, indent *int) bool {
trimmed := strings.TrimSpace(raw)
if trimmed == "" || trimmed[0] == '#' {
return false
}
lineIndent := len(raw) - len(strings.TrimLeft(raw, " \t"))
if *indent < 0 {
*indent = lineIndent
}
return lineIndent == *indent
}
// ParseSkillName reads the SKILL.md and extracts the top-level "name" from frontmatter.
// It reads line by line and stops at a plain top-level name line ("name", 'name' and
// name : count; top-level keys share the first key's indent). Any other form YAML
// allows (flow mapping, block scalar, alias, merge key, explicit key, ...) leaves the
// scan without a name, and then the whole block is decoded.
func ParseSkillName(skillPath string) (string, error) {
name, literal, indent := "", "", -1
path := filepath.Join(skillPath, "SKILL.md")
err := scanLenientBlock(path, func(raw []byte) bool {
line := string(raw)
trimmed := strings.TrimLeft(line, " \t")
if !IsRootFrontmatterLine(line, &indent) {
return true
}
key, value, ok := strings.Cut(trimmed, ":")
if !ok || strings.Trim(strings.TrimSpace(key), `"'`) != "name" {
return true
}
if v := strings.TrimSpace(value); v != "" && strings.ContainsRune("*|>&!", rune(v[0])) {
return false // alias, block scalar, anchor or tag: decode the whole block
}
// The line alone decodes quotes and a trailing comment. When it does not decode to
// a string (a multi-line quoted scalar, a number), the whole block is decoded, and
// the line read as is is kept for frontmatter YAML rejects.
var fm map[string]any
if yaml.Unmarshal([]byte("name:"+value), &fm) == nil {
if v, isString := fm["name"].(string); isString {
name = v
return false
}
}
literal = strings.Trim(strings.TrimSpace(value), `"'`)
return false
})
if err != nil || name != "" {
return name, err
}
raw, err := readLenientBlock(path)
if err != nil {
return "", err
}
if name, isString := decodeFrontmatter(raw)["name"].(string); isString {
return name, nil
}
return literal, nil
}
// isYAMLBlockIndicator returns true for YAML block scalar indicators (>, >-, >+, |, |-, |+).
func isYAMLBlockIndicator(s string) bool {
switch s {
case ">", ">-", ">+", "|", "|-", "|+":
return true
}
return false
}
// resolveField looks up a field in the frontmatter map.
// Priority: metadata.<field> > top-level <field>.
// Returns nil when the field is absent in both locations.
func resolveField(fm map[string]any, field string) any {
if md, ok := fm["metadata"]; ok {
if mdMap, ok := md.(map[string]any); ok {
if val, ok := mdMap[field]; ok {
return val
}
}
}
val, ok := fm[field]
if !ok {
return nil
}
return val
}
// ParseFrontmatterList reads a SKILL.md file and extracts a YAML list field from frontmatter.
// Supports both inline [a, b] and block (- a\n- b) formats.
// Returns nil when the field is absent or the file cannot be read.
func ParseFrontmatterList(filePath, field string) []string {
raw, err := readLenientBlock(filePath)
if err != nil {
return nil
}
return stringList(decodeFrontmatter(raw), field)
}
// ParseFrontmatterListFromBytes parses a YAML list field from pre-read content.
// Same as ParseFrontmatterList but avoids re-reading the file.
func ParseFrontmatterListFromBytes(content []byte, field string) []string {
raw := locateFrontmatter(content, lenientBlock).withoutLastNewline()
return stringList(decodeFrontmatter(raw), field)
}
// stringList returns the string items of a list field, resolved by resolveField.
func stringList(fm map[string]any, field string) []string {
list, _ := resolveField(fm, field).([]any)
var result []string
for _, item := range list {
if s, ok := item.(string); ok {
result = append(result, s)
}
}
return result
}
// decodeFrontmatter decodes the block a lenient reader found. It is nil when the block
// is empty or not a YAML mapping.
func decodeFrontmatter(raw []byte) map[string]any {
var fm map[string]any
if err := yaml.Unmarshal(raw, &fm); err != nil {
return nil
}
return fm
}
// ParseFrontmatterMap returns the complete YAML frontmatter of SKILL.md content.
// The Agent Skills format requires the file to begin with it, closed by a second ---.
func ParseFrontmatterMap(content []byte) (map[string]any, error) {
block := locateFrontmatter(content, strictBlock)
if !block.open {
return nil, fmt.Errorf("no frontmatter at the start")
}
if !block.closed {
return nil, fmt.Errorf("unclosed frontmatter: no closing ---")
}
if len(bytes.TrimSpace(block.raw)) == 0 {
return nil, fmt.Errorf("no frontmatter")
}
var doc yaml.Node
if err := yaml.Unmarshal(block.raw, &doc); err != nil {
return nil, fmt.Errorf("invalid frontmatter: %w", err)
}
normalizeCoreScalars(&doc)
var fm map[string]any
if err := doc.Decode(&fm); err != nil {
return nil, fmt.Errorf("invalid frontmatter: %w", err)
}
// A non-string key decodes to map[any]any, which JSON cannot carry.
if _, err := json.Marshal(fm); err != nil {
return nil, fmt.Errorf("frontmatter JSON cannot carry: %w", err)
}
return fm, nil
}
// ParseFrontmatterFields reads a SKILL.md file once and returns the values of
// multiple frontmatter fields. This avoids opening the same file repeatedly
// when multiple fields are needed (e.g. description + license).
// Note: does not resolve metadata.<field> — only reads top-level scalar fields.
// Use ParseFrontmatterMap for the complete structured frontmatter, including nested values.
func ParseFrontmatterFields(filePath string, fields []string) map[string]string {
result := make(map[string]string, len(fields))
if len(fields) == 0 {
return result
}
raw, err := readLenientBlock(filePath)
if err != nil {
return result
}
fm := decodeFrontmatter(raw)
for _, field := range fields {
val, ok := fm[field]
if !ok || val == nil {
continue
}
switch v := val.(type) {
case string:
result[field] = v
case int:
result[field] = fmt.Sprintf("%d", v)
case float64:
result[field] = fmt.Sprintf("%g", v)
case bool:
result[field] = fmt.Sprintf("%t", v)
}
}
return result
}
// ReadSkillBody reads a file and returns everything after the YAML frontmatter.
// If no frontmatter is present, the entire content is returned.
// Returns "" on read error.
func ReadSkillBody(filePath string) string {
data, err := os.ReadFile(filePath)
if err != nil {
return ""
}
block := locateFrontmatter(scanLines(data), bodyBlock)
if !block.open {
return strings.TrimSpace(string(data))
}
if !block.closed {
return ""
}
return strings.TrimSpace(string(block.body))
}
// ParseFrontmatterField reads a SKILL.md file and extracts the value of a given frontmatter field.
// It supports both inline values and YAML block scalars (>, >-, |, |-).
func ParseFrontmatterField(filePath, field string) string {
prefix := field + ":"
indent := -1
val := ""
var blockParts []string // set once val is a block scalar indicator
err := scanLenientBlock(filePath, func(raw []byte) bool {
if blockParts != nil {
// The block scalar continues while lines are indented
if len(raw) > 0 && (raw[0] == ' ' || raw[0] == '\t') {
blockParts = append(blockParts, strings.TrimSpace(string(raw)))
return true
}
return false
}
rawLine := string(raw)
line := strings.TrimSpace(rawLine)
if !IsRootFrontmatterLine(rawLine, &indent) || !strings.HasPrefix(line, prefix) {
return true
}
val = strings.TrimSpace(strings.SplitN(line, ":", 2)[1])
if isYAMLBlockIndicator(val) {
blockParts = []string{}
return true
}
return false
})
if err != nil {
return ""
}
if blockParts != nil {
return strings.Join(blockParts, " ")
}
return strings.Trim(val, `"'`)
}