From cc7d8024119bb3da2df54d66ddb68d8466e0185c Mon Sep 17 00:00:00 2001 From: Willie Date: Tue, 6 Oct 2026 14:18:16 +0800 Subject: [PATCH 01/26] feat(mcp): serve skills over MCP with the SEP-2640 Skills extension Agents on a disposable VM, in a hosted assistant or behind an MCP gateway can reach an MCP endpoint but not the folder skills sync to, so they got tools and none of the user's skills (#428). `skillshare mcp serve` is a read-only server for the skills skillshare already manages. It declares io.modelcontextprotocol/skills and implements skills/list, skills/get and resources/read: one entry per skill, its URI from the source path, the full frontmatter, and every file with a sha256 digest and size. --target applies that target's selection, and the source is reread at most every 5 seconds so install, update, enable and disable show up without a restart; unchanged files keep their digest. stdio is the default; --http serves Streamable HTTP and needs SKILLSHARE_MCP_TOKEN off loopback. Skills the extension cannot carry are skipped with a warning instead of being published incomplete: a name that breaks the Agent Skills rules or differs from its directory, more than 512 files or 16 MiB, or a nested skill that is not served. --check lists them without serving. The naming rules moved to internal/skillpkg so sync and the server share them. Few clients support the extension yet, so the server also offers list_skills and read_skill tools. A client that declares the extension does not see them, so it never gets each skill twice. sync.SelectTargetSkills is the one place that turns discovered skills into a target's selection (enabled, include/exclude, frontmatter targets). Refs: #428 --- ai_docs/tests/mcp_serve_runbook.md | 178 +++++++++++++++++++ cmd/skillshare/completion_bash.go | 4 +- cmd/skillshare/completion_fish.go | 4 +- cmd/skillshare/completion_nushell.go | 4 +- cmd/skillshare/completion_powershell.go | 3 +- cmd/skillshare/completion_zsh.go | 4 +- cmd/skillshare/mcp.go | 4 + cmd/skillshare/mcp_serve.go | 160 +++++++++++++++++ go.mod | 12 +- go.sum | 28 ++- internal/skillpkg/skillpkg.go | 118 +++++++++++++ internal/skillserve/catalog.go | 220 ++++++++++++++++++++++++ internal/skillserve/catalog_test.go | 189 ++++++++++++++++++++ internal/skillserve/server.go | 220 ++++++++++++++++++++++++ internal/skillserve/server_test.go | 183 ++++++++++++++++++++ internal/skillserve/tools.go | 117 +++++++++++++ internal/sync/filter.go | 12 ++ internal/sync/filter_target_test.go | 15 ++ internal/sync/target_naming.go | 30 +--- internal/utils/frontmatter.go | 13 ++ skills/skillshare/SKILL.md | 4 +- skills/skillshare/references/mcp.md | 13 ++ tests/integration/completion_test.go | 10 +- tests/integration/mcp_serve_test.go | 105 +++++++++++ website/docs/reference/commands/mcp.md | 95 +++++++++- 25 files changed, 1698 insertions(+), 47 deletions(-) create mode 100644 ai_docs/tests/mcp_serve_runbook.md create mode 100644 cmd/skillshare/mcp_serve.go create mode 100644 internal/skillpkg/skillpkg.go create mode 100644 internal/skillserve/catalog.go create mode 100644 internal/skillserve/catalog_test.go create mode 100644 internal/skillserve/server.go create mode 100644 internal/skillserve/server_test.go create mode 100644 internal/skillserve/tools.go create mode 100644 tests/integration/mcp_serve_test.go diff --git a/ai_docs/tests/mcp_serve_runbook.md b/ai_docs/tests/mcp_serve_runbook.md new file mode 100644 index 000000000..927cfaa1c --- /dev/null +++ b/ai_docs/tests/mcp_serve_runbook.md @@ -0,0 +1,178 @@ +# CLI E2E Runbook: `skillshare mcp serve` + +Validates the read-only SEP-2640 skills server over stdio and Streamable HTTP. + +**Origin**: issue #428 — Agents that only reach an MCP endpoint need the skills Skillshare manages. + +## Scope + +- `server/discover` declares `resources` and the `io.modelcontextprotocol/skills` extension +- `skills/list` returns one entry per valid, enabled skill with frontmatter and a complete sha256 manifest +- A skill whose `name` differs from its directory is skipped with a stderr warning; a disabled skill is not served +- `--check` lists skipped skills and the served count without serving +- `--target` applies that target's `exclude` filter +- `resources/read` returns a listed file and rejects a URI that escapes the skill +- Over HTTP: bearer token required, a newly added skill appears without a restart +- A non-loopback `--http` address without `SKILLSHARE_MCP_TOKEN` is refused + +## Environment + +Run inside the devcontainer with a fresh ssenv HOME: + +```bash +ssenv create mcp-serve-e2e --init +ssenv enter mcp-serve-e2e -- mdproof --report json /workspace/ai_docs/tests/mcp_serve_runbook.md +``` + +Every step works from `$HOME` and points `SKILLSHARE_CONFIG` at `$HOME/mcp-serve/config.yaml`. +The server drops requests still in flight when stdin closes, so stdio steps keep stdin open +with `sleep 1`. Step 6 listens on port 47941; pick another free port if it is taken. + +## Steps + +### Step 1: Discover and list over stdio + +```bash +set -eu +cd "$HOME" +CASE="$HOME/mcp-serve" +rm -rf "$CASE" +mkdir -p "$CASE/skills" +export SKILLSHARE_CONFIG="$CASE/config.yaml" +cat > "$SKILLSHARE_CONFIG" < "$CASE/skills/$n/SKILL.md" +done +mkdir -p "$CASE/skills/pdf/references" "$CASE/skills/renamed" +echo forms > "$CASE/skills/pdf/references/FORMS.md" +printf -- '---\nname: original\ndescription: Use when testing\n---\n# Renamed\n' > "$CASE/skills/renamed/SKILL.md" +echo off > "$CASE/skills/.skillignore" +M='"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"e2e","version":"1"},"io.modelcontextprotocol/clientCapabilities":{}}' +{ printf '%s\n' "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"server/discover\",\"params\":{$M}}" "{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"skills/list\",\"params\":{$M}}"; sleep 1; } \ + | ss mcp serve -g 2>"$CASE/stderr" | jq -sc 'map({(.id|tostring): .result}) | add' +``` + +Expected: +- exit_code: 0 +- jq: .["1"].capabilities.extensions | has("io.modelcontextprotocol/skills") +- jq: .["1"].capabilities.resources == {} +- jq: [.["2"].skills[].uri] == ["skill://notes/SKILL.md", "skill://pdf/SKILL.md"] +- jq: .["2"].resultType == "complete" +- jq: (.["2"].skills[] | select(.uri == "skill://pdf/SKILL.md") | [.resources[].uri] | sort) == ["skill://pdf/SKILL.md", "skill://pdf/references/FORMS.md"] +- jq: [.["2"].skills[].resources[].digest | test("^sha256:[0-9a-f]{64}$")] | all + +### Step 2: The renamed skill is reported on stderr + +```bash +cat "$HOME/mcp-serve/stderr" +``` + +Expected: +- exit_code: 0 +- skipped renamed: SKILL.md name "original" does not match directory name "renamed" + +### Step 3: `--check` lists the skipped skill without serving + +```bash +cd "$HOME" +export SKILLSHARE_CONFIG="$HOME/mcp-serve/config.yaml" +NO_COLOR=1 ss mcp serve --check -g < /dev/null +``` + +Expected: +- exit_code: 0 +- SKILL.md name "original" does not match directory name "renamed" +- 2 skills served, 1 skipped + +### Step 4: `--target` applies the target's exclude filter + +```bash +set -eu +cd "$HOME" +export SKILLSHARE_CONFIG="$HOME/mcp-serve/config.yaml" +M='"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"e2e","version":"1"},"io.modelcontextprotocol/clientCapabilities":{}}' +{ printf '%s\n' "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"skills/list\",\"params\":{$M}}"; sleep 1; } \ + | ss mcp serve -g --target claude 2>/dev/null | jq -c .result +``` + +Expected: +- exit_code: 0 +- jq: [.skills[].uri] == ["skill://pdf/SKILL.md"] + +### Step 5: Read a listed file; reject an escaping URI + +```bash +set -eu +cd "$HOME" +export SKILLSHARE_CONFIG="$HOME/mcp-serve/config.yaml" +M='"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"e2e","version":"1"},"io.modelcontextprotocol/clientCapabilities":{}}' +{ printf '%s\n' \ + "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"resources/read\",\"params\":{$M,\"uri\":\"skill://pdf/references/FORMS.md\"}}" \ + "{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"resources/read\",\"params\":{$M,\"uri\":\"skill://pdf/%2e%2e/notes/SKILL.md\"}}"; sleep 1; } \ + | ss mcp serve -g 2>/dev/null | jq -sc 'map({(.id|tostring): .}) | add' +``` + +Expected: +- exit_code: 0 +- jq: .["1"].result.contents[0].text == "forms\n" +- jq: .["2"].error.code == -32602 + +### Step 6: HTTP needs the token and picks up a new skill without a restart + +```bash +set -eu +cd "$HOME" +CASE="$HOME/mcp-serve" +export SKILLSHARE_CONFIG="$CASE/config.yaml" +export SKILLSHARE_MCP_TOKEN=e2e-token +ss mcp serve -g --http 127.0.0.1:47941 2>/dev/null & +PID=$! +trap 'kill $PID 2>/dev/null || true' EXIT +for _ in 1 2 3 4 5 6 7 8 9 10; do curl -s -o /dev/null http://127.0.0.1:47941/ && break; sleep 0.5; done +M='"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"e2e","version":"1"},"io.modelcontextprotocol/clientCapabilities":{}}' +list() { + curl -s -X POST http://127.0.0.1:47941/ -H 'Content-Type: application/json' \ + -H 'Accept: application/json, text/event-stream' -H 'MCP-Protocol-Version: 2026-07-28' \ + -H 'Mcp-Method: skills/list' "$@" \ + -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"skills/list\",\"params\":{$M}}" +} +UNAUTH=$(list -o /dev/null -w '%{http_code}') +BEFORE=$(list -H "Authorization: Bearer $SKILLSHARE_MCP_TOKEN" | sed -n 's/^data: //p' | jq '.result.skills | length') +mkdir -p "$CASE/skills/late" +printf -- '---\nname: late\ndescription: Use when testing late\n---\n# late\n' > "$CASE/skills/late/SKILL.md" +sleep 6 +AFTER=$(list -H "Authorization: Bearer $SKILLSHARE_MCP_TOKEN" | sed -n 's/^data: //p' | jq '.result.skills | length') +jq -nc --arg u "$UNAUTH" --argjson b "$BEFORE" --argjson a "$AFTER" '{unauth: $u, before: $b, after: $a}' +``` + +Expected: +- exit_code: 0 +- jq: .unauth == "401" +- jq: .before == 2 +- jq: .after == 3 + +### Step 7: A network listener without a token is refused + +```bash +cd "$HOME" +export SKILLSHARE_CONFIG="$HOME/mcp-serve/config.yaml" +unset SKILLSHARE_MCP_TOKEN +ss mcp serve -g --http 0.0.0.0:47942 +``` + +Expected: +- exit_code: 1 +- SKILLSHARE_MCP_TOKEN + +## Pass Criteria + +- All steps marked PASS +- No `ss mcp serve` process remains after Step 6 diff --git a/cmd/skillshare/completion_bash.go b/cmd/skillshare/completion_bash.go index ad684ce57..8962acb07 100644 --- a/cmd/skillshare/completion_bash.go +++ b/cmd/skillshare/completion_bash.go @@ -38,7 +38,7 @@ _skillshare() { local unlink_flags="--help -h" local list_flags="--verbose -v --json -j --no-tui --type -t --status --sort -s --all --help -h" local sync_flags="--all --dry-run -n --force -f --json --quiet -q --help -h" - local mcp_flags="--tools-allow --tools-deny --pi-options --url --target --from --file --sync --replace --disabled --keep-files --revision --dry-run -n --json --no-tui --no-dns --live --timeout --help -h" + local mcp_flags="--tools-allow --tools-deny --pi-options --url --target --from --file --sync --replace --disabled --keep-files --revision --dry-run -n --json --no-tui --no-dns --live --timeout --http --check --help -h" local status_flags="--json --help -h" local hooks_flags="--file --from --sync --replace --keep-files --revision --dry-run -n --json --help -h" local diff_flags="--no-tui --patch --stat --json --help -h" @@ -256,7 +256,7 @@ _skillshare() { list) COMPREPLY=($(compgen -W "${list_flags} ${global_flags}" -- "${cur}")) ;; sync) COMPREPLY=($(compgen -W "${sync_flags} ${global_flags}" -- "${cur}")) ;; plugin) COMPREPLY=($(compgen -W "add discover import list inspect sync check update enable disable remove --target --from --plugin --name --source-ref --entry --revision --dry-run -n --json --no-tui --help -h ${global_flags}" -- "${cur}")) ;; - mcp) COMPREPLY=($(compgen -W "add check edit import list remove restore ${mcp_flags} ${global_flags}" -- "${cur}")) ;; + mcp) COMPREPLY=($(compgen -W "add check edit import list remove restore serve ${mcp_flags} ${global_flags}" -- "${cur}")) ;; status) COMPREPLY=($(compgen -W "${status_flags} ${global_flags}" -- "${cur}")) ;; hooks) COMPREPLY=($(compgen -W "add disable edit enable import list remove restore sync ${hooks_flags} ${global_flags}" -- "${cur}")) ;; diff) COMPREPLY=($(compgen -W "${diff_flags} ${global_flags}" -- "${cur}")) ;; diff --git a/cmd/skillshare/completion_fish.go b/cmd/skillshare/completion_fish.go index 5748c2618..196f75b2d 100644 --- a/cmd/skillshare/completion_fish.go +++ b/cmd/skillshare/completion_fish.go @@ -52,6 +52,8 @@ complete -c skillshare -n '__fish_skillshare_using_command mcp' -l pi-options -r complete -c skillshare -n '__fish_skillshare_using_command mcp' -l no-dns -d 'Skip host lookups' complete -c skillshare -n '__fish_skillshare_using_command mcp' -l live -d 'check: start or call each server' complete -c skillshare -n '__fish_skillshare_using_command mcp' -l timeout -r -d 'check --live: per-server timeout' +complete -c skillshare -n '__fish_skillshare_using_command mcp' -l http -r -d 'serve: Streamable HTTP listen address' +complete -c skillshare -n '__fish_skillshare_using_command mcp' -l check -d 'serve: list skipped skills without serving' complete -c skillshare -n '__fish_skillshare_using_command mcp' -l url -r -d 'MCP endpoint' complete -c skillshare -n '__fish_skillshare_using_command mcp' -l target -r -a 'claude codex cursor vscode opencode kilocode grok antigravity amp claude-desktop cline copilot factory gemini goose junie kiro lmstudio warp windsurf pi omp' -d 'Receiving client' complete -c skillshare -n '__fish_skillshare_using_command mcp' -l from -r -a 'claude codex cursor vscode opencode kilocode grok antigravity amp claude-desktop cline copilot factory gemini goose junie kiro lmstudio warp windsurf pi omp' -d 'Import client' @@ -65,7 +67,7 @@ complete -c skillshare -n '__fish_skillshare_using_command mcp' -l dry-run -s n complete -c skillshare -n '__fish_skillshare_using_command mcp' -l json -d 'JSON output' complete -c skillshare -n '__fish_skillshare_using_command mcp' -l no-tui -d 'Disable interactive menus' complete -c skillshare -n '__fish_skillshare_using_command mcp' -l help -s h -d 'Show help' -complete -c skillshare -n '__fish_skillshare_using_command mcp' -a 'add check edit import list remove restore' +complete -c skillshare -n '__fish_skillshare_using_command mcp' -a 'add check edit import list remove restore serve' complete -c skillshare -n __fish_skillshare_no_subcommand -a hooks -d 'Manage Agent hooks' complete -c skillshare -n '__fish_skillshare_using_command hooks' -a 'add disable edit enable import list remove restore sync' complete -c skillshare -n '__fish_skillshare_using_command hooks' -l file -r -F -d 'Entry or native file' diff --git a/cmd/skillshare/completion_nushell.go b/cmd/skillshare/completion_nushell.go index 624f03198..bb07a9257 100644 --- a/cmd/skillshare/completion_nushell.go +++ b/cmd/skillshare/completion_nushell.go @@ -50,7 +50,7 @@ def "nu-complete skillshare plugin" [] { } def "nu-complete skillshare mcp" [] { - [add check edit import list remove restore] + [add check edit import list remove restore serve] } def "nu-complete skillshare mcp-target" [] { @@ -89,6 +89,8 @@ export extern "skillshare mcp" [ --no-dns # Skip host lookups --live # check: start or call each server --timeout: string # check --live: per-server timeout, such as 10s + --http: string # serve: Streamable HTTP listen address + --check # serve: list skipped skills without serving --no-tui --project(-p) --global(-g) diff --git a/cmd/skillshare/completion_powershell.go b/cmd/skillshare/completion_powershell.go index 4f8d2c072..8deca7e78 100644 --- a/cmd/skillshare/completion_powershell.go +++ b/cmd/skillshare/completion_powershell.go @@ -54,6 +54,7 @@ $_skillshareCompleter = { @{ Name = 'list'; Desc = 'MCP list' } @{ Name = 'remove'; Desc = 'MCP remove' } @{ Name = 'restore'; Desc = 'MCP restore' } + @{ Name = 'serve'; Desc = 'MCP serve' } ) 'hooks' = @( @{ Name = 'add'; Desc = 'Hooks add' } @@ -207,7 +208,7 @@ $_skillshareCompleter = { 'enable' = '--dry-run', '-n', '--kind', '--help', '-h', '--project', '-p', '--global', '-g' 'disable' = '--dry-run', '-n', '--kind', '--help', '-h', '--project', '-p', '--global', '-g' 'analyze' = '--verbose', '-v', '--filter', '--no-tui', '--json', '--help', '-h', '--project', '-p', '--global', '-g' - 'mcp' = '--tools-allow', '--tools-deny', '--pi-options', '--target', '--from', '--url', '--file', '--sync', '--replace', '--disabled', '--keep-files', '--revision', '--dry-run', '-n', '--json', '--no-dns', '--live', '--timeout', '--no-tui', '--help', '-h', '--project', '-p', '--global', '-g' + 'mcp' = '--tools-allow', '--tools-deny', '--pi-options', '--target', '--from', '--url', '--file', '--sync', '--replace', '--disabled', '--keep-files', '--revision', '--dry-run', '-n', '--json', '--no-dns', '--live', '--timeout', '--http', '--check', '--no-tui', '--help', '-h', '--project', '-p', '--global', '-g' 'plugin' = '--target', '--from', '--plugin', '--name', '--source-ref', '--entry', '--revision', '--dry-run', '-n', '--json', '--no-tui', '--help', '-h', '--project', '-p', '--global', '-g' 'extras memory' = '--from', '--version', '--search', '--update-mode', '--json', '--help', '-h', '--project', '-p', '--global', '-g' 'extras' = '--mode', '--target', '--source', '--file', '--as', '--flatten', '--no-flatten', '--add-target', '--remove-target', '--prune', '--from', '--dry-run', '--force', '-f', '--json', '--no-tui', '--help', '-h', '--project', '-p', '--global', '-g' diff --git a/cmd/skillshare/completion_zsh.go b/cmd/skillshare/completion_zsh.go index 429031abe..dd5bc1a7a 100644 --- a/cmd/skillshare/completion_zsh.go +++ b/cmd/skillshare/completion_zsh.go @@ -96,7 +96,7 @@ _skillshare() { ;; mcp) _arguments \ - '1:command:(add check edit import list remove restore)' \ + '1:command:(add check edit import list remove restore serve)' \ '--tools-allow[Only these tools, comma-separated, * matches any characters; empty clears]:tools:' \ '--tools-deny[Never these tools, comma-separated, * matches any characters; empty clears]:tools:' \ '--pi-options[Other Pi built-in per-server fields as JSON]:json:' \ @@ -115,6 +115,8 @@ _skillshare() { '--no-dns[Skip host lookups]' \ '--live[check: start or call each server]' \ '--timeout[check --live: per-server timeout]:duration:' \ + '--http[serve: Streamable HTTP listen address]:address:' \ + '--check[serve: list skipped skills without serving]' \ '--no-tui[Disable interactive menus]' \ $global_flags \ '--help[Show help]' \ diff --git a/cmd/skillshare/mcp.go b/cmd/skillshare/mcp.go index 20ba3ac09..19239b7a2 100644 --- a/cmd/skillshare/mcp.go +++ b/cmd/skillshare/mcp.go @@ -154,6 +154,9 @@ func cmdMCP(args []string) (resultErr error) { args = append([]string{"list"}, args...) } sub, args := args[0], args[1:] + if sub == "serve" { + return cmdMCPServe(args) + } service, rest, err := mcpContext(args) if err != nil { return err @@ -387,6 +390,7 @@ func printMCPHelp() { {"check [name...]", "Verify variables, commands, hosts and sync state (--no-dns);\n--live also starts or calls each server [--timeout 10s]"}, {"remove [name]", "Select and remove a source entry; optionally sync removal,\nor stop managing it and keep its Agent entries (--keep-files)"}, {"restore [id]", "Browse backups, preview and restore Agent entries"}, + {"serve", "Serve skills read-only over MCP (SEP-2640) on stdio, or\n--http [--target ]; global unless -p;\n--check lists skipped skills without serving"}, }}, helpGroup{title: "Options", rows: []helpRow{ {"--target ", "Receiving client; repeat for several, or none to keep the\nserver in Skillshare without writing it to any Agent"}, diff --git a/cmd/skillshare/mcp_serve.go b/cmd/skillshare/mcp_serve.go new file mode 100644 index 000000000..db673fd53 --- /dev/null +++ b/cmd/skillshare/mcp_serve.go @@ -0,0 +1,160 @@ +package main + +import ( + "context" + "errors" + "fmt" + "net" + "net/http" + "os" + "os/signal" + "strings" + "syscall" + "time" + + "github.com/modelcontextprotocol/go-sdk/mcp" + + "skillshare/internal/config" + "skillshare/internal/skillserve" + "skillshare/internal/ui" +) + +const mcpServeUsage = "skillshare mcp serve [--target ] [--http | --check] [-g|-p]" + +// mcpServeTokenEnv holds the bearer token HTTP clients must send. +const mcpServeTokenEnv = "SKILLSHARE_MCP_TOKEN" + +// cmdMCPServe serves the managed skills over MCP (SEP-2640). It never writes: +// stdout carries the protocol, so diagnostics go to stderr. +func cmdMCPServe(args []string) error { + mode, rest, err := parseModeArgs(args, "--target", "--http") + if err != nil { + return err + } + var target, addr string + check := false + for i := 0; i < len(rest); i++ { + switch a := rest[i]; a { + case "--check": + check = true + case "--target", "--http": + if i+1 == len(rest) { + return fmt.Errorf("%s requires a value", a) + } + i++ + if a == "--target" { + target = rest[i] + } else { + addr = rest[i] + } + default: + return fmt.Errorf("unknown mcp serve argument %q; usage: %s", a, mcpServeUsage) + } + } + if check && addr != "" { + return fmt.Errorf("--check starts no server; drop --http") + } + + // A gateway chooses the working directory, so only -p selects project mode. + b := &skillserve.Builder{Target: target} + var targets map[string]config.TargetConfig + if mode == modeProject { + cwd, err := os.Getwd() + if err != nil { + return err + } + rt, err := loadProjectRuntime(cwd) + if err != nil { + return err + } + b.Source, b.Walk, targets = rt.sourcePath, rt.skillsWalk(), rt.targets + } else { + cfg, err := config.Load() + if err != nil { + return err + } + b.Source, b.Walk, targets = cfg.EffectiveSkillsSource(), cfg.SkillsWalk(), cfg.Targets + } + if target != "" { + tc, ok := targets[target] + if !ok { + return fmt.Errorf("unknown target %q", target) + } + sc := tc.SkillsConfig() + if !sc.IsEnabled() { + return fmt.Errorf("target %q has skills disabled", target) + } + b.Skills = &sc + } + if check { + return printMCPServeCheck(b) + } + + token := os.Getenv(mcpServeTokenEnv) + if addr != "" && token == "" && !isLoopbackAddr(addr) { + return fmt.Errorf("refusing to serve on %s without authentication: set %s, or bind a loopback address such as 127.0.0.1:8765", addr, mcpServeTokenEnv) + } + + srv, err := skillserve.NewServer(b, skillserve.Options{Version: version, Warn: os.Stderr, Refresh: 5 * time.Second}) + if err != nil { + return err + } + ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM) + defer stop() + + if addr == "" { + return srv.Run(ctx, &mcp.StdioTransport{}) + } + ln, err := net.Listen("tcp", addr) + if err != nil { + return err + } + httpSrv := &http.Server{Handler: skillserve.HTTPHandler(srv, token), ReadHeaderTimeout: 10 * time.Second} + go func() { + <-ctx.Done() + httpSrv.Close() + }() + fmt.Fprintf(os.Stderr, "Serving skills over MCP at http://%s/\n", ln.Addr()) + if err := httpSrv.Serve(ln); !errors.Is(err, http.ErrServerClosed) { + return err + } + return nil +} + +// printMCPServeCheck builds the catalog the server would serve and lists the +// skills it would skip, without starting a server. +func printMCPServeCheck(b *skillserve.Builder) error { + start := time.Now() + c, err := b.Build() + if err != nil { + return err + } + labels := make([]string, len(c.Skipped)) + for i, s := range c.Skipped { + labels[i] = s.Path + } + width := ui.RowWidth(labels...) + for _, s := range c.Skipped { + ui.Row(ui.MarkWarn, s.Path, s.Reason, width) + } + text, mark := plural(len(c.Skills), "skill")+" served", ui.MarkOK + if len(c.Skipped) > 0 { + text, mark = text+fmt.Sprintf(", %d skipped", len(c.Skipped)), ui.MarkWarn + } + ui.Done(mark, text, time.Since(start)) + return nil +} + +// isLoopbackAddr reports whether a listen address only accepts local +// connections. An empty host listens on every interface. +func isLoopbackAddr(addr string) bool { + host, _, err := net.SplitHostPort(addr) + if err != nil || host == "" { + return false + } + if strings.EqualFold(host, "localhost") { + return true + } + ip := net.ParseIP(host) + return ip != nil && ip.IsLoopback() +} diff --git a/go.mod b/go.mod index 7c5fc5999..635b4f01e 100644 --- a/go.mod +++ b/go.mod @@ -3,7 +3,6 @@ module skillshare go 1.25.5 require ( - github.com/yuin/goldmark v1.7.8 github.com/charmbracelet/bubbles v1.0.0 github.com/charmbracelet/bubbletea v1.3.10 github.com/charmbracelet/glamour v0.10.0 @@ -12,12 +11,14 @@ require ( github.com/charmbracelet/x/ansi v0.11.6 github.com/gofrs/flock v0.12.1 github.com/mattn/go-runewidth v0.0.19 + github.com/modelcontextprotocol/go-sdk v1.8.0 github.com/muesli/termenv v0.16.0 github.com/pelletier/go-toml/v2 v2.2.4 github.com/pterm/pterm v0.12.82 github.com/sergi/go-diff v1.4.0 github.com/tailscale/hujson v0.0.0-20221223112325-20486734a56a - golang.org/x/sys v0.38.0 + github.com/yuin/goldmark v1.7.8 + golang.org/x/sys v0.41.0 golang.org/x/term v0.32.0 gopkg.in/yaml.v3 v3.0.1 ) @@ -43,6 +44,7 @@ require ( github.com/dlclark/regexp2 v1.11.0 // indirect github.com/dustin/go-humanize v1.0.1 // indirect github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f // indirect + github.com/google/jsonschema-go v0.4.3 // indirect github.com/gookit/color v1.5.4 // indirect github.com/gorilla/css v1.0.1 // indirect github.com/lithammer/fuzzysearch v1.1.8 // indirect @@ -57,8 +59,14 @@ require ( github.com/rivo/uniseg v0.4.7 // indirect github.com/rogpeppe/go-internal v1.16.0 // indirect github.com/sahilm/fuzzy v0.1.1 // indirect + github.com/segmentio/asm v1.1.3 // indirect + github.com/segmentio/encoding v0.5.4 // indirect github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect + github.com/yosida95/uritemplate/v3 v3.0.2 // indirect github.com/yuin/goldmark-emoji v1.0.5 // indirect golang.org/x/net v0.33.0 // indirect + golang.org/x/oauth2 v0.35.0 // indirect + golang.org/x/sync v0.20.0 // indirect golang.org/x/text v0.26.0 // indirect + golang.org/x/time v0.15.0 // indirect ) diff --git a/go.sum b/go.sum index c2bc282bc..77b4af23b 100644 --- a/go.sum +++ b/go.sum @@ -88,8 +88,12 @@ github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f h1:Y/CXytFA4m6 github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f/go.mod h1:vw97MGsxSvLiUE2X8qFplwetxpGLQrlU1Q9AUEIzCaM= github.com/gofrs/flock v0.12.1 h1:MTLVXXHf8ekldpJk3AKicLij9MdwOWkZ+a/jHHZby9E= github.com/gofrs/flock v0.12.1/go.mod h1:9zxTsyu5xtJ9DK+1tFZyibEV7y3uwDxPPfbxeeHCoD0= -github.com/google/go-cmp v0.5.8 h1:e6P7q2lk1O+qJJb4BtCQXlK8vWEO8V1ZeuEdJNOqZyg= -github.com/google/go-cmp v0.5.8/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY= +github.com/golang-jwt/jwt/v5 v5.3.1 h1:kYf81DTWFe7t+1VvL7eS+jKFVWaUnK9cB1qbwn63YCY= +github.com/golang-jwt/jwt/v5 v5.3.1/go.mod h1:fxCRLWMO43lRc8nhHWY6LGqRcf+1gQWArsqaEUEa5bE= +github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8= +github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU= +github.com/google/jsonschema-go v0.4.3 h1:/DBOLZTfDow7pe2GmaJNhltueGTtDKICi8V8p+DQPd0= +github.com/google/jsonschema-go v0.4.3/go.mod h1:r5quNTdLOYEz95Ru18zA0ydNbBuYoo9tgaYcxEYhJVE= github.com/gookit/color v1.4.2/go.mod h1:fqRyamkC1W8uxl+lxCQxOT09l/vYfZ+QeiX3rKQHCoQ= github.com/gookit/color v1.5.0/go.mod h1:43aQb+Zerm/BWh2GnrgOQm7ffz7tvQXEKV6BFMl7wAo= github.com/gookit/color v1.5.4 h1:FZmqs7XOyGgCAxmWyPslpiok1k05wmY3SJTytgvYFs0= @@ -127,6 +131,8 @@ github.com/microcosm-cc/bluemonday v1.0.27 h1:MpEUotklkwCSLeH+Qdx1VJgNqLlpY2KXwX github.com/microcosm-cc/bluemonday v1.0.27/go.mod h1:jFi9vgW+H7c3V0lb6nR74Ib/DIB5OBs92Dimizgw2cA= github.com/mitchellh/hashstructure/v2 v2.0.2 h1:vGKWl0YJqUNxE8d+h8f6NJLcCJrgbhC4NcD46KavDd4= github.com/mitchellh/hashstructure/v2 v2.0.2/go.mod h1:MG3aRVU/N29oo/V/IhBX8GR/zz4kQkprJgF2EVszyDE= +github.com/modelcontextprotocol/go-sdk v1.8.0 h1:KIvahhYqwtbeniWVPs3TcXEA7b8jEtwfBpOTAI+Urx4= +github.com/modelcontextprotocol/go-sdk v1.8.0/go.mod h1:dL7u98E/zjJTGzEq+j30jQ8K2k1mb6LeAH4inEcSGts= github.com/muesli/ansi v0.0.0-20230316100256-276c6243b2f6 h1:ZK8zHtRHOkbHy6Mmr5D264iyp3TiX5OmNcI5cIARiQI= github.com/muesli/ansi v0.0.0-20230316100256-276c6243b2f6/go.mod h1:CJlz5H+gyd6CUWT45Oy4q24RdLyn7Md9Vj2/ldJBSIo= github.com/muesli/cancelreader v0.2.2 h1:3I4Kt4BQjOR54NavqnDogx/MIoWBFa0StPA8ELUXHmA= @@ -156,6 +162,10 @@ github.com/rogpeppe/go-internal v1.16.0 h1:O9DK+vNMDVGLr2BeZqmpLeMjiMNkuXfcqntWb github.com/rogpeppe/go-internal v1.16.0/go.mod h1:DrUVZyrJU+txYW5/1kwtXQSMFio52ZOxX7yM1VHvnxs= github.com/sahilm/fuzzy v0.1.1 h1:ceu5RHF8DGgoi+/dR5PsECjCDH1BE3Fnmpo7aVXOdRA= github.com/sahilm/fuzzy v0.1.1/go.mod h1:VFvziUEIMCrT6A6tw2RFIXPXXmzXbOsSHF0DOI8ZK9Y= +github.com/segmentio/asm v1.1.3 h1:WM03sfUOENvvKexOLp+pCqgb/WDjsi7EK8gIsICtzhc= +github.com/segmentio/asm v1.1.3/go.mod h1:Ld3L4ZXGNcSLRg4JBsZ3//1+f/TjYl0Mzen/DQy1EJg= +github.com/segmentio/encoding v0.5.4 h1:OW1VRern8Nw6ITAtwSZ7Idrl3MXCFwXHPgqESYfvNt0= +github.com/segmentio/encoding v0.5.4/go.mod h1:HS1ZKa3kSN32ZHVZ7ZLPLXWvOVIiZtyJnO1gPH1sKt0= github.com/sergi/go-diff v1.2.0/go.mod h1:STckp+ISIX8hZLjrqAeVduY0gWCT9IjLuqbuNXdaHfM= github.com/sergi/go-diff v1.4.0 h1:n/SP9D5ad1fORl+llWyN+D6qoUETXNZARKjyY2/KVCw= github.com/sergi/go-diff v1.4.0/go.mod h1:A0bzQcvG0E7Rwjx0REVgAGH58e96+X0MeOfepqsbeW4= @@ -170,6 +180,8 @@ github.com/tailscale/hujson v0.0.0-20221223112325-20486734a56a/go.mod h1:DFSS3NA github.com/xo/terminfo v0.0.0-20210125001918-ca9a967f8778/go.mod h1:2MuV+tbUrU1zIOPMxZ5EncGwgmMJsa+9ucAQZXxsObs= github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e h1:JVG44RsyaB9T2KIHavMF/ppJZNG9ZpyihvCd0w101no= github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e/go.mod h1:RbqR21r5mrJuqunuUZ/Dhy/avygyECGrLceyNeo4LiM= +github.com/yosida95/uritemplate/v3 v3.0.2 h1:Ed3Oyj9yrmi9087+NczuL5BwkIc4wvTb5zIM+UJPGz4= +github.com/yosida95/uritemplate/v3 v3.0.2/go.mod h1:ILOh0sOhIJR3+L/8afwt/kE++YT040gmv5BQTMR2HP4= github.com/yuin/goldmark v1.4.13/go.mod h1:6yULJ656Px+3vBD8DxQVa3kxgyrAnzto9xy5taEt/CY= github.com/yuin/goldmark v1.7.1/go.mod h1:uzxRWxtg69N339t3louHJ7+O03ezfj6PlliRlaOzY1E= github.com/yuin/goldmark v1.7.8 h1:iERMLn0/QJeHFhxSt3p6PeN9mGnvIKSpG9YYorDMnic= @@ -188,9 +200,13 @@ golang.org/x/net v0.0.0-20220722155237-a158d28d115b/go.mod h1:XRhObCWvk6IyKnWLug golang.org/x/net v0.6.0/go.mod h1:2Tu9+aMcznHK/AK1HMvgo6xiTLG5rD5rZLDS+rp2Bjs= golang.org/x/net v0.33.0 h1:74SYHlV8BIgHIFC/LrYkOGIwL19eTYXQ5wc6TBuO36I= golang.org/x/net v0.33.0/go.mod h1:HXLR5J+9DxmrqMwG9qjGCxZ+zKXxBru04zlTvWlWuN4= +golang.org/x/oauth2 v0.35.0 h1:Mv2mzuHuZuY2+bkyWXIHMfhNdJAdwW3FuWeCPYN5GVQ= +golang.org/x/oauth2 v0.35.0/go.mod h1:lzm5WQJQwKZ3nwavOZ3IS5Aulzxi68dUSgRHujetwEA= golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM= golang.org/x/sync v0.0.0-20220722155255-886fb9371eb4/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM= golang.org/x/sync v0.1.0/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM= +golang.org/x/sync v0.20.0 h1:e0PTpb7pjO8GAtTs2dQ6jYa5BWYlMuX047Dco/pItO4= +golang.org/x/sync v0.20.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0= golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY= golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= golang.org/x/sys v0.0.0-20210124154548-22da62e12c0c/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= @@ -204,8 +220,8 @@ golang.org/x/sys v0.0.0-20220722155257-8c9f86f7a55f/go.mod h1:oPkhp1MJrh7nUepCBc golang.org/x/sys v0.1.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= golang.org/x/sys v0.5.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= -golang.org/x/sys v0.38.0 h1:3yZWxaJjBmCWXqhN1qh02AkOnCQ1poK6oF+a7xWL6Gc= -golang.org/x/sys v0.38.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks= +golang.org/x/sys v0.41.0 h1:Ivj+2Cp/ylzLiEU89QhWblYnOE9zerudt9Ftecq2C6k= +golang.org/x/sys v0.41.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks= golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo= golang.org/x/term v0.0.0-20210220032956-6a3ed077a48d/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo= golang.org/x/term v0.0.0-20210615171337-6886f2dfbf5b/go.mod h1:jbD1KX2456YbFQfuXm/mYQcufACuNUgVhRMnK/tPxf8= @@ -220,10 +236,14 @@ golang.org/x/text v0.7.0/go.mod h1:mrYo+phRRbMaCq/xk9113O4dZlRixOauAjOtrjsXDZ8= golang.org/x/text v0.9.0/go.mod h1:e1OnstbJyHTd6l/uOt8jFFHp6TRDWZR/bV3emEE/zU8= golang.org/x/text v0.26.0 h1:P42AVeLghgTYr4+xUnTRKDMqpar+PtX7KWuNQL21L8M= golang.org/x/text v0.26.0/go.mod h1:QK15LZJUUQVJxhz7wXgxSy/CJaTFjd0G+YLonydOVQA= +golang.org/x/time v0.15.0 h1:bbrp8t3bGUeFOx08pvsMYRTCVSMk89u4tKbNOZbp88U= +golang.org/x/time v0.15.0/go.mod h1:Y4YMaQmXwGQZoFaVFk4YpCt4FLQMYKZe9oeV/f4MSno= golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ= golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo= golang.org/x/tools v0.1.12/go.mod h1:hNGJHUnrk76NpqgfD5Aqm5Crs+Hm0VOH/i9J2+nxYbc= golang.org/x/tools v0.6.0/go.mod h1:Xwgl3UAJ/d3gWutnCtw505GrjyAbvKui8lOU390QaIU= +golang.org/x/tools v0.42.0 h1:uNgphsn75Tdz5Ji2q36v/nsFSfR/9BRFvqhGBaJGd5k= +golang.org/x/tools v0.42.0/go.mod h1:Ma6lCIwGZvHK6XtgbswSoWroEkhugApmsXyrUmBhfr0= golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0= gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= diff --git a/internal/skillpkg/skillpkg.go b/internal/skillpkg/skillpkg.go new file mode 100644 index 000000000..22a390d08 --- /dev/null +++ b/internal/skillpkg/skillpkg.go @@ -0,0 +1,118 @@ +// Package skillpkg reads one skill directory as an Agent Skills package: its +// full frontmatter and every regular file, within the SEP-2640 limits. It has +// no configuration dependencies, so sync can share its naming rules. +package skillpkg + +import ( + "fmt" + "os" + "path/filepath" + "strings" + "time" + + "skillshare/internal/sourcewalk" + "skillshare/internal/utils" +) + +// Per-skill limits from SEP-2640. +const ( + MaxFiles = 512 + MaxBytes = 16 << 20 +) + +// File is one regular file of a package. +type File struct { + Path string // absolute + Rel string // slash-separated, relative to the package directory + Size int64 + ModTime time.Time +} + +// Package is a valid skill directory. +type Package struct { + Dir string // resolved + Frontmatter map[string]any + Files []File +} + +// Load reads the skill in dir. The error says why the directory is not a +// valid package. .git directories are left out; links are neither listed nor read. +func Load(dir string) (*Package, error) { + dirName := filepath.Base(filepath.Clean(dir)) // a followed link's name, not its target's + dir = utils.ResolveSymlink(dir) + content, err := os.ReadFile(filepath.Join(dir, "SKILL.md")) + if err != nil { + return nil, err + } + fm, err := utils.ParseFrontmatterMap(content) + if err != nil { + return nil, fmt.Errorf("SKILL.md has %w", err) + } + name, _ := fm["name"].(string) + if reason := ValidateName(name, dirName); reason != "" { + return nil, fmt.Errorf("%s", reason) + } + if desc, _ := fm["description"].(string); strings.TrimSpace(desc) == "" { + return nil, fmt.Errorf("SKILL.md is missing a description") + } + + p := &Package{Dir: dir, Frontmatter: fm} + var total int64 + err = sourcewalk.Walk(dir, sourcewalk.Options{}, func(path string, info os.FileInfo, err error) error { + if err != nil { + return err + } + if info.IsDir() { + if info.Name() == ".git" { + return filepath.SkipDir + } + return nil + } + if !info.Mode().IsRegular() { + return nil + } + if len(p.Files) == MaxFiles { + return fmt.Errorf("has more than %d files", MaxFiles) + } + if total += info.Size(); total > MaxBytes { + return fmt.Errorf("is larger than 16 MiB") + } + rel, err := filepath.Rel(dir, path) + if err != nil { + return err + } + p.Files = append(p.Files, File{Path: path, Rel: filepath.ToSlash(rel), Size: info.Size(), ModTime: info.ModTime()}) + return nil + }) + if err != nil { + return nil, err + } + return p, nil +} + +// ValidateName returns why a SKILL.md name breaks the Agent Skills naming rules +// (including name == directory name), or "" when it follows them. +func ValidateName(name, dirName string) string { + if name == "" { + return "SKILL.md is missing a name" + } + if len(name) > 64 { + return fmt.Sprintf("SKILL.md name %q is longer than 64 characters", name) + } + if strings.HasPrefix(name, "-") || strings.HasSuffix(name, "-") { + return fmt.Sprintf("SKILL.md name %q cannot start or end with '-'", name) + } + if strings.Contains(name, "--") { + return fmt.Sprintf("SKILL.md name %q cannot contain consecutive hyphens", name) + } + for _, r := range name { + if (r >= 'a' && r <= 'z') || (r >= '0' && r <= '9') || r == '-' { + continue + } + return fmt.Sprintf("SKILL.md name %q must use only lowercase letters, numbers, and hyphens", name) + } + if name != dirName { + return fmt.Sprintf("SKILL.md name %q does not match directory name %q", name, dirName) + } + return "" +} diff --git a/internal/skillserve/catalog.go b/internal/skillserve/catalog.go new file mode 100644 index 000000000..7b80c237d --- /dev/null +++ b/internal/skillserve/catalog.go @@ -0,0 +1,220 @@ +// Package skillserve publishes the skills source as an MCP Skills extension +// (SEP-2640) catalog: one entry per valid skill with its full frontmatter and a +// complete file manifest, and contained reads of the listed files. +package skillserve + +import ( + "errors" + "fmt" + "io" + "net/url" + "os" + "slices" + "strings" + "time" + + "skillshare/internal/config" + "skillshare/internal/skillpkg" + "skillshare/internal/sourcewalk" + ssync "skillshare/internal/sync" + "skillshare/internal/utils" +) + +// extensionID is the SEP-2640 capability key. +const extensionID = "io.modelcontextprotocol/skills" + +var errNotFound = errors.New("not found") + +// File is one manifest entry of a skill. +type File struct { + URI string `json:"uri"` + Digest string `json:"digest"` + Size int64 `json:"size"` +} + +// Skill is one skills/list entry. +type Skill struct { + URI string `json:"uri"` + Frontmatter map[string]any `json:"frontmatter"` + Resources []File `json:"resources"` +} + +// servedFile locates a manifest file: the resolved skill directory and the +// slash path inside it. +type servedFile struct{ dir, rel string } + +// Skip is a skill left out of the catalog, by source path. +type Skip struct { + Path, Reason string +} + +func (s Skip) String() string { return fmt.Sprintf("skipped %s: %s", s.Path, s.Reason) } + +// Catalog is one snapshot of the served skills, ordered by source path. +type Catalog struct { + Skills []*Skill + Skipped []Skip + bySkill map[string]*Skill + byFile map[string]servedFile +} + +// Builder builds catalogs from the skills source. It keeps the digests of the +// last build so unchanged files are not hashed again. +type Builder struct { + Source string + Walk sourcewalk.Options + // Target names the target whose Skills selection applies. With Skills nil, + // every enabled skill is served. + Target string + Skills *config.ResourceTargetConfig + + digests map[string]digest +} + +type digest struct { + size int64 + mtime time.Time + sum string +} + +// Build discovers the source and returns the skills to serve. Skills that are +// invalid, over the limits, or contain an unserved nested skill are skipped +// with a warning. +func (b *Builder) Build() (*Catalog, error) { + all, err := ssync.DiscoverSourceSkillsAll(b.Source, b.Walk) + if err != nil { + return nil, err + } + var selected []ssync.DiscoveredSkill + if b.Skills != nil { + if selected, err = ssync.SelectTargetSkills(all, b.Target, *b.Skills); err != nil { + return nil, err + } + } else { + selected = slices.DeleteFunc(slices.Clone(all), func(s ssync.DiscoveredSkill) bool { return s.Disabled }) + } + served := make(map[string]bool, len(selected)) + for _, s := range selected { + served[s.RelPath] = true + } + var unserved []string + for _, s := range all { + if !served[s.RelPath] { + unserved = append(unserved, s.RelPath) + } + } + slices.SortFunc(selected, func(x, y ssync.DiscoveredSkill) int { return strings.Compare(x.RelPath, y.RelPath) }) + + c := &Catalog{bySkill: map[string]*Skill{}, byFile: map[string]servedFile{}} + next := map[string]digest{} + for _, s := range selected { + skill, reason := b.load(s, unserved, c.byFile, next) + if reason != "" { + c.Skipped = append(c.Skipped, Skip{Path: s.RelPath, Reason: reason}) + continue + } + c.Skills = append(c.Skills, skill) + c.bySkill[skill.URI] = skill + } + b.digests = next + return c, nil +} + +// load builds one entry and registers its files in byFile, or returns why the +// skill is skipped. +func (b *Builder) load(s ssync.DiscoveredSkill, unserved []string, byFile map[string]servedFile, next map[string]digest) (*Skill, string) { + for _, o := range unserved { + if strings.HasPrefix(o, s.RelPath+"/") { + return nil, fmt.Sprintf("contains %s, which is not served", o) + } + } + p, err := skillpkg.Load(s.SourcePath) + if err != nil { + return nil, err.Error() + } + base := "skill://" + escapePath(s.RelPath) + skill := &Skill{URI: base + "/SKILL.md", Frontmatter: p.Frontmatter} + files := make(map[string]servedFile, len(p.Files)) + for _, f := range p.Files { + sum, err := b.digest(f, next) + if err != nil { + return nil, err.Error() + } + uri := base + "/" + escapePath(f.Rel) + files[uri] = servedFile{dir: p.Dir, rel: f.Rel} + skill.Resources = append(skill.Resources, File{URI: uri, Digest: sum, Size: f.Size}) + } + for uri, f := range files { + byFile[uri] = f + } + return skill, "" +} + +// ponytail: size+mtime keys the digest cache, so a same-size edit within the +// filesystem's mtime granularity keeps the old digest until the next change. +func (b *Builder) digest(f skillpkg.File, next map[string]digest) (string, error) { + if d, ok := b.digests[f.Path]; ok && d.size == f.Size && d.mtime.Equal(f.ModTime) { + next[f.Path] = d + return d.sum, nil + } + sum, err := utils.FileHashFormatted(f.Path) + if err != nil { + return "", err + } + next[f.Path] = digest{size: f.Size, mtime: f.ModTime, sum: sum} + return sum, nil +} + +// Skill returns the served skill whose SKILL.md URI is uri. +func (c *Catalog) Skill(uri string) (*Skill, bool) { + key, ok := canonical(uri) + skill := c.bySkill[key] + return skill, ok && skill != nil +} + +// Read returns the content of a listed file. Only manifest files are served, +// and the read is confined to the skill directory. +func (c *Catalog) Read(uri string) ([]byte, error) { + key, ok := canonical(uri) + sf, listed := c.byFile[key] + if !ok || !listed { + return nil, errNotFound + } + root, err := os.OpenRoot(sf.dir) + if err != nil { + return nil, err + } + defer root.Close() + f, err := root.Open(sf.rel) + if err != nil { + return nil, err + } + defer f.Close() + return io.ReadAll(io.LimitReader(f, skillpkg.MaxBytes)) +} + +func escapePath(p string) string { + segs := strings.Split(p, "/") + for i, s := range segs { + segs[i] = url.PathEscape(s) + } + return strings.Join(segs, "/") +} + +// canonical decodes a skill:// URI and re-encodes it the way the catalog +// builds URIs. Empty, dot, and separator-bearing segments are rejected. +func canonical(uri string) (string, bool) { + rest, ok := strings.CutPrefix(uri, "skill://") + if !ok { + return "", false + } + segs := strings.Split(rest, "/") + for i, s := range segs { + d, err := url.PathUnescape(s) + if err != nil || d == "" || d == "." || d == ".." || strings.ContainsAny(d, "/\\\x00") { + return "", false + } + segs[i] = url.PathEscape(d) + } + return "skill://" + strings.Join(segs, "/"), true +} diff --git a/internal/skillserve/catalog_test.go b/internal/skillserve/catalog_test.go new file mode 100644 index 000000000..37e8f971f --- /dev/null +++ b/internal/skillserve/catalog_test.go @@ -0,0 +1,189 @@ +package skillserve + +import ( + "crypto/sha256" + "encoding/hex" + "fmt" + "os" + "path/filepath" + "strings" + "testing" + + "skillshare/internal/config" + "skillshare/internal/skillpkg" +) + +func writeFile(t *testing.T, path, content string) { + t.Helper() + if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(path, []byte(content), 0o644); err != nil { + t.Fatal(err) + } +} + +func skillMD(name string) string { + return "---\nname: " + name + "\ndescription: Use when testing " + name + "\nmetadata:\n tags: [a, b]\n---\n# " + name + "\n" +} + +func find(c *Catalog, uri string) *Skill { + for _, s := range c.Skills { + if s.URI == uri { + return s + } + } + return nil +} + +func hasWarning(c *Catalog, substr string) bool { + for _, w := range c.Skipped { + if strings.Contains(w.String(), substr) { + return true + } + } + return false +} + +func TestBuild_PublishesFrontmatterAndCompleteManifest(t *testing.T) { + src := t.TempDir() + writeFile(t, filepath.Join(src, "_team/tools/pdf/SKILL.md"), skillMD("pdf")) + writeFile(t, filepath.Join(src, "_team/tools/pdf/references/FORMS.md"), "forms") + writeFile(t, filepath.Join(src, "_team/tools/pdf/.git/HEAD"), "ref") + + c, err := (&Builder{Source: src}).Build() + if err != nil { + t.Fatal(err) + } + s := find(c, "skill://_team/tools/pdf/SKILL.md") + if s == nil { + t.Fatalf("skill not published; skills=%v warnings=%v", c.Skills, c.Skipped) + } + if s.Frontmatter["name"] != "pdf" || s.Frontmatter["metadata"] == nil { + t.Errorf("frontmatter = %v, want full frontmatter", s.Frontmatter) + } + sum := sha256.Sum256([]byte("forms")) + want := map[string]File{ + "skill://_team/tools/pdf/SKILL.md": {Size: int64(len(skillMD("pdf")))}, + "skill://_team/tools/pdf/references/FORMS.md": {Size: 5, Digest: "sha256:" + hex.EncodeToString(sum[:])}, + } + if len(s.Resources) != len(want) { + t.Fatalf("resources = %+v, want SKILL.md and FORMS.md only", s.Resources) + } + for _, f := range s.Resources { + w, ok := want[f.URI] + if !ok || f.Size != w.Size || (w.Digest != "" && f.Digest != w.Digest) { + t.Errorf("unexpected resource %+v", f) + } + } +} + +func TestBuild_SkipsSkillWhoseNameDiffersFromDirectory(t *testing.T) { + src := t.TempDir() + writeFile(t, filepath.Join(src, "renamed/SKILL.md"), skillMD("original")) + + c, err := (&Builder{Source: src}).Build() + if err != nil { + t.Fatal(err) + } + if len(c.Skills) != 0 || !hasWarning(c, `does not match directory name "renamed"`) { + t.Errorf("skills=%v warnings=%v, want renamed skipped with a warning", c.Skills, c.Skipped) + } +} + +func TestBuild_AppliesTargetSelectionAndDisabledState(t *testing.T) { + src := t.TempDir() + for _, n := range []string{"keep", "drop", "off"} { + writeFile(t, filepath.Join(src, n, "SKILL.md"), skillMD(n)) + } + writeFile(t, filepath.Join(src, ".skillignore"), "off\n") + + c, err := (&Builder{Source: src, Target: "claude", Skills: &config.ResourceTargetConfig{Exclude: []string{"drop"}}}).Build() + if err != nil { + t.Fatal(err) + } + if len(c.Skills) != 1 || c.Skills[0].URI != "skill://keep/SKILL.md" { + t.Errorf("skills = %v, want only keep", c.Skills) + } +} + +func TestBuild_SkipsParentOfExcludedNestedSkill(t *testing.T) { + src := t.TempDir() + writeFile(t, filepath.Join(src, "suite/SKILL.md"), skillMD("suite")) + writeFile(t, filepath.Join(src, "suite/child/SKILL.md"), skillMD("child")) + + c, err := (&Builder{Source: src, Target: "claude", Skills: &config.ResourceTargetConfig{Exclude: []string{"suite__child"}}}).Build() + if err != nil { + t.Fatal(err) + } + if len(c.Skills) != 0 || !hasWarning(c, "suite/child") { + t.Errorf("skills=%v warnings=%v, want suite skipped because of excluded child", c.Skills, c.Skipped) + } +} + +func TestBuild_SkipsSkillOverFileLimit(t *testing.T) { + src := t.TempDir() + writeFile(t, filepath.Join(src, "big/SKILL.md"), skillMD("big")) + for i := range skillpkg.MaxFiles { + writeFile(t, filepath.Join(src, "big/refs", fmt.Sprintf("f%03d", i)), "") + } + + c, err := (&Builder{Source: src}).Build() + if err != nil { + t.Fatal(err) + } + if len(c.Skills) != 0 || !hasWarning(c, "512") { + t.Errorf("skills=%d warnings=%v, want big skipped over the file limit", len(c.Skills), c.Skipped) + } +} + +func TestBuild_RefreshesDigestWhenContentChanges(t *testing.T) { + src := t.TempDir() + ref := filepath.Join(src, "doc/notes.md") + writeFile(t, filepath.Join(src, "doc/SKILL.md"), skillMD("doc")) + writeFile(t, ref, "one") + b := &Builder{Source: src} + first, err := b.Build() + if err != nil { + t.Fatal(err) + } + writeFile(t, ref, "two!") + second, err := b.Build() + if err != nil { + t.Fatal(err) + } + digest := func(c *Catalog) string { + for _, f := range c.Skills[0].Resources { + if strings.HasSuffix(f.URI, "notes.md") { + return f.Digest + } + } + return "" + } + if digest(first) == digest(second) { + t.Error("digest did not change after the file changed") + } +} + +func TestRead_ServesOnlyManifestFilesInsideTheSkill(t *testing.T) { + src := t.TempDir() + outside := filepath.Join(t.TempDir(), "secret.txt") + writeFile(t, outside, "secret") + writeFile(t, filepath.Join(src, "doc/SKILL.md"), skillMD("doc")) + if err := os.Symlink(outside, filepath.Join(src, "doc/leak.txt")); err != nil { + t.Fatal(err) + } + c, err := (&Builder{Source: src}).Build() + if err != nil { + t.Fatal(err) + } + + if data, err := c.Read("skill://doc/SKILL.md"); err != nil || string(data) != skillMD("doc") { + t.Errorf("Read SKILL.md = %q, %v", data, err) + } + for _, uri := range []string{"skill://doc/leak.txt", "skill://doc/../doc/SKILL.md", "skill://doc/%2e%2e/doc/SKILL.md"} { + if _, err := c.Read(uri); err == nil { + t.Errorf("Read(%s) succeeded, want rejection", uri) + } + } +} diff --git a/internal/skillserve/server.go b/internal/skillserve/server.go new file mode 100644 index 000000000..2366093d9 --- /dev/null +++ b/internal/skillserve/server.go @@ -0,0 +1,220 @@ +package skillserve + +import ( + "context" + "crypto/subtle" + "errors" + "fmt" + "io" + "mime" + "net/http" + "path" + "strconv" + "sync" + "time" + "unicode/utf8" + + "github.com/modelcontextprotocol/go-sdk/jsonrpc" + "github.com/modelcontextprotocol/go-sdk/mcp" +) + +// SEP-2640 methods. +const ( + methodList = "skills/list" + methodGet = "skills/get" +) + +const pageSize = 100 + +type listSkillsParams struct { + mcp.ParamsBase + Cursor string `json:"cursor,omitempty"` +} + +type listSkillsResult struct { + mcp.ResultBase + mcp.Cacheable + ResultType string `json:"resultType"` + Skills []*Skill `json:"skills"` + NextCursor string `json:"nextCursor,omitempty"` +} + +type getSkillParams struct { + mcp.ParamsBase + URI string `json:"uri"` +} + +type getSkillResult struct { + mcp.ResultBase + mcp.Cacheable + ResultType string `json:"resultType"` + Skill *Skill `json:"skill"` +} + +// Options configures NewServer. +type Options struct { + Version string + // Warn receives each skip warning when it first appears. + Warn io.Writer + // Refresh is how long a catalog is reused before the source is read again; + // it is also the ttlMs hint. Zero rebuilds on every request. + Refresh time.Duration +} + +type service struct { + b *Builder + opts Options + + mu sync.Mutex + cat *Catalog + built time.Time + warned map[string]bool +} + +// NewServer returns a read-only MCP server for the skills b selects. The first +// catalog is built here, so source errors and initial warnings surface at once. +func NewServer(b *Builder, opts Options) (*mcp.Server, error) { + if opts.Warn == nil { + opts.Warn = io.Discard + } + svc := &service{b: b, opts: opts} + if _, err := svc.catalog(); err != nil { + return nil, err + } + srv := mcp.NewServer(&mcp.Implementation{Name: "skillshare", Version: opts.Version}, &mcp.ServerOptions{ + Capabilities: &mcp.ServerCapabilities{ + Resources: &mcp.ResourceCapabilities{}, + Extensions: map[string]any{extensionID: map[string]any{}}, + }, + }) + srv.AddResourceTemplate(&mcp.ResourceTemplate{Name: "skill-file", URITemplate: "skill://{+path}"}, svc.read) + if err := mcp.AddReceivingCustomMethod(srv, methodList, svc.list); err != nil { + return nil, err + } + if err := mcp.AddReceivingCustomMethod(srv, methodGet, svc.get); err != nil { + return nil, err + } + svc.addTools(srv) + return srv, nil +} + +// HTTPHandler serves srv over Streamable HTTP. A non-empty token must be sent +// as a bearer token on every request. +func HTTPHandler(srv *mcp.Server, token string) http.Handler { + h := mcp.NewStreamableHTTPHandler(func(*http.Request) *mcp.Server { return srv }, &mcp.StreamableHTTPOptions{Stateless: true}) + if token == "" { + return h + } + want := []byte("Bearer " + token) + return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if subtle.ConstantTimeCompare([]byte(r.Header.Get("Authorization")), want) != 1 { + w.Header().Set("WWW-Authenticate", "Bearer") + http.Error(w, "unauthorized", http.StatusUnauthorized) + return + } + h.ServeHTTP(w, r) + }) +} + +func (s *service) catalog() (*Catalog, error) { + s.mu.Lock() + defer s.mu.Unlock() + if s.cat != nil && time.Since(s.built) < s.opts.Refresh { + return s.cat, nil + } + c, err := s.b.Build() + if err != nil { + return nil, err + } + seen := make(map[string]bool, len(c.Skipped)) + for _, skip := range c.Skipped { + w := skip.String() + seen[w] = true + if !s.warned[w] { + fmt.Fprintln(s.opts.Warn, "warning: "+w) + } + } + s.cat, s.built, s.warned = c, time.Now(), seen + return c, nil +} + +func (s *service) cacheable() mcp.Cacheable { + return mcp.Cacheable{TTLMs: int(s.opts.Refresh.Milliseconds()), CacheScope: "private"} +} + +func invalidParams(msg string) error { + return &jsonrpc.Error{Code: jsonrpc.CodeInvalidParams, Message: msg} +} + +func (s *service) list(_ context.Context, _ *mcp.ServerSession, p *listSkillsParams) (*listSkillsResult, error) { + c, err := s.catalog() + if err != nil { + return nil, err + } + start := 0 + if p != nil && p.Cursor != "" { + n, err := strconv.Atoi(p.Cursor) + if err != nil || n < 0 || n > len(c.Skills) { + return nil, invalidParams("invalid cursor") + } + start = n + } + end := min(start+pageSize, len(c.Skills)) + res := &listSkillsResult{Cacheable: s.cacheable(), ResultType: "complete", Skills: c.Skills[start:end]} + if end < len(c.Skills) { + res.NextCursor = strconv.Itoa(end) + } + return res, nil +} + +func (s *service) get(_ context.Context, _ *mcp.ServerSession, p *getSkillParams) (*getSkillResult, error) { + c, err := s.catalog() + if err != nil { + return nil, err + } + if p == nil { + return nil, invalidParams("missing uri") + } + skill, ok := c.Skill(p.URI) + if !ok { + return nil, invalidParams("skill not found: " + p.URI) + } + return &getSkillResult{Cacheable: s.cacheable(), ResultType: "complete", Skill: skill}, nil +} + +func (s *service) read(_ context.Context, req *mcp.ReadResourceRequest) (*mcp.ReadResourceResult, error) { + c, err := s.catalog() + if err != nil { + return nil, err + } + uri := req.Params.URI + data, err := c.Read(uri) + if errors.Is(err, errNotFound) { + return nil, mcp.ResourceNotFoundError(uri) + } + if err != nil { + return nil, err + } + text := utf8.Valid(data) + content := &mcp.ResourceContents{URI: uri, MIMEType: mimeType(uri, text)} + if text { + content.Text = string(data) + } else { + content.Blob = data + } + return &mcp.ReadResourceResult{Cacheable: s.cacheable(), Contents: []*mcp.ResourceContents{content}}, nil +} + +func mimeType(uri string, text bool) string { + ext := path.Ext(uri) + if ext == ".md" { + return "text/markdown" + } + if t := mime.TypeByExtension(ext); t != "" { + return t + } + if text { + return "text/plain" + } + return "application/octet-stream" +} diff --git a/internal/skillserve/server_test.go b/internal/skillserve/server_test.go new file mode 100644 index 000000000..3d536276b --- /dev/null +++ b/internal/skillserve/server_test.go @@ -0,0 +1,183 @@ +package skillserve + +import ( + "context" + "errors" + "fmt" + "io" + "net/http" + "net/http/httptest" + "path/filepath" + "strings" + "testing" + + "github.com/modelcontextprotocol/go-sdk/jsonrpc" + "github.com/modelcontextprotocol/go-sdk/mcp" +) + +func connect(t *testing.T, src string) *mcp.ClientSession { + t.Helper() + return connectWith(t, src, nil) +} + +func connectWith(t *testing.T, src string, opts *mcp.ClientOptions) *mcp.ClientSession { + t.Helper() + ctx := context.Background() + srv, err := NewServer(&Builder{Source: src}, Options{Version: "test", Warn: io.Discard}) + if err != nil { + t.Fatal(err) + } + ct, st := mcp.NewInMemoryTransports() + ss, err := srv.Connect(ctx, st, nil) + if err != nil { + t.Fatal(err) + } + t.Cleanup(func() { ss.Close() }) + client := mcp.NewClient(&mcp.Implementation{Name: "test-client", Version: "v1"}, opts) + if err := mcp.AddSendingCustomMethod[*listSkillsParams, *listSkillsResult](client, methodList); err != nil { + t.Fatal(err) + } + if err := mcp.AddSendingCustomMethod[*getSkillParams, *getSkillResult](client, methodGet); err != nil { + t.Fatal(err) + } + cs, err := client.Connect(ctx, ct, nil) + if err != nil { + t.Fatal(err) + } + t.Cleanup(func() { cs.Close() }) + return cs +} + +func listSkills(t *testing.T, cs *mcp.ClientSession, cursor string) *listSkillsResult { + t.Helper() + res, err := mcp.CallCustomMethod[*listSkillsParams, *listSkillsResult](context.Background(), cs, methodList, &listSkillsParams{Cursor: cursor}) + if err != nil { + t.Fatal(err) + } + return res +} + +func TestServer_DeclaresSkillsExtension(t *testing.T) { + cs := connect(t, t.TempDir()) + caps := cs.InitializeResult().Capabilities + if _, ok := caps.Extensions[extensionID]; !ok || caps.Resources == nil { + t.Errorf("capabilities = %+v, want resources and %s", caps, extensionID) + } +} + +func TestServer_ListPaginatesWholeEntries(t *testing.T) { + src := t.TempDir() + for i := range pageSize + 1 { + name := fmt.Sprintf("s%03d", i) + writeFile(t, filepath.Join(src, name, "SKILL.md"), skillMD(name)) + } + cs := connect(t, src) + + first := listSkills(t, cs, "") + if len(first.Skills) != pageSize || first.NextCursor == "" || first.ResultType != "complete" || first.CacheScope == "" { + t.Fatalf("first page: %d skills, cursor %q, resultType %q, cacheScope %q", len(first.Skills), first.NextCursor, first.ResultType, first.CacheScope) + } + second := listSkills(t, cs, first.NextCursor) + if len(second.Skills) != 1 || second.NextCursor != "" { + t.Errorf("second page: %d skills, cursor %q, want the last skill and no cursor", len(second.Skills), second.NextCursor) + } +} + +func TestServer_GetUnknownSkillIsInvalidParams(t *testing.T) { + cs := connect(t, t.TempDir()) + _, err := mcp.CallCustomMethod[*getSkillParams, *getSkillResult](context.Background(), cs, methodGet, &getSkillParams{URI: "skill://missing/SKILL.md"}) + var rpcErr *jsonrpc.Error + if !errors.As(err, &rpcErr) || rpcErr.Code != jsonrpc.CodeInvalidParams { + t.Errorf("err = %v, want -32602", err) + } +} + +func TestServer_ReadsSkillFileAsMarkdown(t *testing.T) { + src := t.TempDir() + writeFile(t, filepath.Join(src, "doc/SKILL.md"), skillMD("doc")) + cs := connect(t, src) + + res, err := cs.ReadResource(context.Background(), &mcp.ReadResourceParams{URI: "skill://doc/SKILL.md"}) + if err != nil { + t.Fatal(err) + } + if len(res.Contents) != 1 || res.Contents[0].Text != skillMD("doc") || res.Contents[0].MIMEType != "text/markdown" { + t.Errorf("contents = %+v", res.Contents) + } +} + +func TestHTTPHandler_RequiresBearerToken(t *testing.T) { + srv, err := NewServer(&Builder{Source: t.TempDir()}, Options{}) + if err != nil { + t.Fatal(err) + } + h := HTTPHandler(srv, "s3cret") + for _, auth := range []string{"", "Bearer wrong"} { + req := httptest.NewRequest(http.MethodPost, "http://127.0.0.1/", strings.NewReader(`{}`)) + req.Header.Set("Authorization", auth) + rec := httptest.NewRecorder() + h.ServeHTTP(rec, req) + if rec.Code != http.StatusUnauthorized { + t.Errorf("Authorization %q: status %d, want 401", auth, rec.Code) + } + } +} + +func TestServer_SeesNewSkillWithoutRestart(t *testing.T) { + src := t.TempDir() + cs := connect(t, src) + if got := listSkills(t, cs, ""); len(got.Skills) != 0 { + t.Fatalf("got %d skills, want 0", len(got.Skills)) + } + writeFile(t, filepath.Join(src, "late/SKILL.md"), skillMD("late")) + + res, err := mcp.CallCustomMethod[*getSkillParams, *getSkillResult](context.Background(), cs, methodGet, &getSkillParams{URI: "skill://late/SKILL.md"}) + if err != nil || res.Skill == nil || res.Skill.Frontmatter["name"] != "late" { + t.Errorf("get late = %+v, %v", res, err) + } +} + +func callTool(t *testing.T, cs *mcp.ClientSession, name string, args map[string]any) (string, bool) { + t.Helper() + res, err := cs.CallTool(context.Background(), &mcp.CallToolParams{Name: name, Arguments: args}) + if err != nil { + t.Fatal(err) + } + return res.Content[0].(*mcp.TextContent).Text, res.IsError +} + +func TestServer_ToolsListAndReadSkillsForClientsWithoutTheExtension(t *testing.T) { + src := t.TempDir() + writeFile(t, filepath.Join(src, "pdf", "SKILL.md"), skillMD("pdf")) + writeFile(t, filepath.Join(src, "pdf", "references", "guide.md"), "# Guide\n") + writeFile(t, filepath.Join(src, "review", "SKILL.md"), skillMD("review")) + cs := connect(t, src) + + if tools, err := cs.ListTools(context.Background(), nil); err != nil || len(tools.Tools) != 2 { + t.Fatalf("tools/list = %v, %v; want list_skills and read_skill", tools, err) + } + list, _ := callTool(t, cs, "list_skills", map[string]any{"query": "PDF"}) + if !strings.Contains(list, "skill://pdf/SKILL.md") || strings.Contains(list, "review") { + t.Errorf("list_skills query=PDF:\n%s", list) + } + body, _ := callTool(t, cs, "read_skill", map[string]any{"uri": "skill://pdf/SKILL.md"}) + if !strings.Contains(body, "# pdf") || !strings.Contains(body, "skill://pdf/references/guide.md") { + t.Errorf("read_skill SKILL.md should return the body and list the other files:\n%s", body) + } + if msg, isErr := callTool(t, cs, "read_skill", map[string]any{"uri": "skill://pdf/../review/SKILL.md"}); !isErr { + t.Errorf("read_skill outside the skill = %q, want a tool error", msg) + } +} + +func TestServer_HidesToolsFromClientsWithTheExtension(t *testing.T) { + caps := &mcp.ClientCapabilities{} + caps.AddExtension(extensionID, map[string]any{}) + cs := connectWith(t, t.TempDir(), &mcp.ClientOptions{Capabilities: caps}) + res, err := cs.ListTools(context.Background(), nil) + if err != nil { + t.Fatal(err) + } + if len(res.Tools) != 0 { + t.Errorf("tools = %d, want none: the client loads skills natively", len(res.Tools)) + } +} diff --git a/internal/skillserve/tools.go b/internal/skillserve/tools.go new file mode 100644 index 000000000..2b9fce820 --- /dev/null +++ b/internal/skillserve/tools.go @@ -0,0 +1,117 @@ +package skillserve + +import ( + "context" + "errors" + "fmt" + "strings" + "unicode/utf8" + + "github.com/modelcontextprotocol/go-sdk/mcp" +) + +// Tools for clients without the Skills extension, which is most of them: the +// model lists and reads skills itself. Content read this way is ordinary text, +// not a loaded skill, so the client's own skill approval does not apply. +// A client that declares the extension sees no tools and loads skills natively. + +// listLimit caps one list_skills answer so a large catalog does not flood the +// model's context; the query narrows it. +const listLimit = 200 + +type listToolInput struct { + Query string `json:"query,omitempty" jsonschema:"Only skills whose name or description contains this text, ignoring case"` +} + +type readToolInput struct { + URI string `json:"uri" jsonschema:"A skill:// URI from list_skills, or one of the files read_skill lists for a skill"` +} + +func (s *service) addTools(srv *mcp.Server) { + mcp.AddTool(srv, &mcp.Tool{ + Name: "list_skills", + Description: "List the available skills: name, when to use it, and its URI. Read a skill with read_skill before following it.", + }, s.listTool) + mcp.AddTool(srv, &mcp.Tool{ + Name: "read_skill", + Description: "Read a skill's SKILL.md, or one of its other files, by skill:// URI. Reading SKILL.md also lists the skill's other files.", + }, s.readTool) + srv.AddReceivingMiddleware(hideToolsFromNativeClients) +} + +// hideToolsFromNativeClients leaves a client that declares the Skills +// extension without the tools, so it does not see each skill twice. +func hideToolsFromNativeClients(next mcp.MethodHandler) mcp.MethodHandler { + return func(ctx context.Context, method string, req mcp.Request) (mcp.Result, error) { + res, err := next(ctx, method, req) + if r, ok := req.(*mcp.ListToolsRequest); ok && err == nil { + if caps := r.ClientCapabilities(); caps != nil { + if _, native := caps.Extensions[extensionID]; native { + res.(*mcp.ListToolsResult).Tools = []*mcp.Tool{} + } + } + } + return res, err + } +} + +func textResult(text string) *mcp.CallToolResult { + return &mcp.CallToolResult{Content: []mcp.Content{&mcp.TextContent{Text: text}}} +} + +func (s *service) listTool(_ context.Context, _ *mcp.CallToolRequest, in listToolInput) (*mcp.CallToolResult, any, error) { + c, err := s.catalog() + if err != nil { + return nil, nil, err + } + query := strings.ToLower(in.Query) + var b strings.Builder + n := 0 + for _, skill := range c.Skills { + name, _ := skill.Frontmatter["name"].(string) + desc, _ := skill.Frontmatter["description"].(string) + if query != "" && !strings.Contains(strings.ToLower(name+"\n"+desc), query) { + continue + } + if n++; n <= listLimit { + fmt.Fprintf(&b, "- %s: %s\n %s\n", name, strings.Join(strings.Fields(desc), " "), skill.URI) + } + } + switch { + case n == 0: + return textResult("No skills match."), nil, nil + case n > listLimit: + fmt.Fprintf(&b, "\n%d more skills match; pass a query to narrow the list.\n", n-listLimit) + } + return textResult(b.String()), nil, nil +} + +func (s *service) readTool(_ context.Context, _ *mcp.CallToolRequest, in readToolInput) (*mcp.CallToolResult, any, error) { + c, err := s.catalog() + if err != nil { + return nil, nil, err + } + data, err := c.Read(in.URI) + if errors.Is(err, errNotFound) { + return nil, nil, fmt.Errorf("no skill file %s; list_skills gives the skill URIs", in.URI) + } + if err != nil { + return nil, nil, err + } + if !utf8.Valid(data) { + return nil, nil, fmt.Errorf("%s is a binary file", in.URI) + } + text := string(data) + if skill, ok := c.Skill(in.URI); ok && len(skill.Resources) > 1 { + var b strings.Builder + b.WriteString(text) + b.WriteString("\n\n---\nOther files in this skill (read them with read_skill):\n") + for _, f := range skill.Resources { + if f.URI != skill.URI { + fmt.Fprintf(&b, "- %s\n", f.URI) + } + } + text = b.String() + } + return textResult(text), nil, nil +} diff --git a/internal/sync/filter.go b/internal/sync/filter.go index 4e3cce374..ab103785d 100644 --- a/internal/sync/filter.go +++ b/internal/sync/filter.go @@ -194,6 +194,18 @@ func suggestFlatNames(pattern string, skills []DiscoveredSkill) []string { return names } +// SelectTargetSkills returns the source skills a target receives: enabled +// skills that pass its include/exclude filters and whose frontmatter targets +// name it or declare none. +func SelectTargetSkills(skills []DiscoveredSkill, targetName string, sc config.ResourceTargetConfig) ([]DiscoveredSkill, error) { + enabled := slices.DeleteFunc(slices.Clone(skills), func(s DiscoveredSkill) bool { return s.Disabled }) + filtered, err := FilterSkills(enabled, sc.Include, sc.Exclude) + if err != nil { + return nil, err + } + return FilterSkillsByTarget(filtered, targetName), nil +} + // FilterSkillsByTarget removes skills whose Targets field does not include // the given target name. Skills with nil Targets (no field declared) pass // through unconditionally. diff --git a/internal/sync/filter_target_test.go b/internal/sync/filter_target_test.go index 34f6ad7db..5d473db5b 100644 --- a/internal/sync/filter_target_test.go +++ b/internal/sync/filter_target_test.go @@ -3,9 +3,24 @@ package sync import ( "testing" + "skillshare/internal/config" "skillshare/internal/resource" ) +func TestSelectTargetSkills_AppliesDisabledFiltersAndTargets(t *testing.T) { + skills := []DiscoveredSkill{ + {FlatName: "keep"}, + {FlatName: "off", Disabled: true}, + {FlatName: "dropped"}, + {FlatName: "cursor-only", Targets: []string{"cursor"}}, + } + got, err := SelectTargetSkills(skills, "claude", config.ResourceTargetConfig{Exclude: []string{"dropped"}}) + if err != nil { + t.Fatal(err) + } + assertFlatNames(t, got, []string{"keep"}) +} + func TestFilterSkillsByTarget_NilPassesThrough(t *testing.T) { skills := []DiscoveredSkill{ {FlatName: "no-targets", Targets: nil}, diff --git a/internal/sync/target_naming.go b/internal/sync/target_naming.go index 950778a36..8f4947213 100644 --- a/internal/sync/target_naming.go +++ b/internal/sync/target_naming.go @@ -7,6 +7,7 @@ import ( "strings" "skillshare/internal/config" + "skillshare/internal/skillpkg" "skillshare/internal/utils" ) @@ -54,11 +55,10 @@ func (r *TargetSkillResolution) UnmatchedIncludeWarnings() []string { // ResolveTargetSkillsForTarget applies a target's filters and target_naming // policy to discovered skills and returns the effective target-visible skills. func ResolveTargetSkillsForTarget(targetName string, sc config.ResourceTargetConfig, allSkills []DiscoveredSkill) (*TargetSkillResolution, error) { - filtered, err := FilterSkills(allSkills, sc.Include, sc.Exclude) + filtered, err := SelectTargetSkills(allSkills, targetName, sc) if err != nil { return nil, fmt.Errorf("failed to apply filters for target %s: %w", targetName, err) } - filtered = FilterSkillsByTarget(filtered, targetName) naming := config.EffectiveTargetNaming(sc.TargetNaming) result := &TargetSkillResolution{ @@ -159,29 +159,5 @@ func (r *TargetSkillResolution) LegacyFlatNames() map[string]ResolvedTargetSkill } func validateStandardTargetSkill(skill DiscoveredSkill, skillName string) string { - if skillName == "" { - return "SKILL.md is missing a name" - } - if len(skillName) > 64 { - return fmt.Sprintf("SKILL.md name %q is longer than 64 characters", skillName) - } - if strings.HasPrefix(skillName, "-") || strings.HasSuffix(skillName, "-") { - return fmt.Sprintf("SKILL.md name %q cannot start or end with '-'", skillName) - } - if strings.Contains(skillName, "--") { - return fmt.Sprintf("SKILL.md name %q cannot contain consecutive hyphens", skillName) - } - for _, r := range skillName { - if (r >= 'a' && r <= 'z') || (r >= '0' && r <= '9') || r == '-' { - continue - } - return fmt.Sprintf("SKILL.md name %q must use only lowercase letters, numbers, and hyphens", skillName) - } - - dirName := filepath.Base(filepath.Clean(skill.SourcePath)) - if skillName != dirName { - return fmt.Sprintf("SKILL.md name %q does not match directory name %q", skillName, dirName) - } - - return "" + return skillpkg.ValidateName(skillName, filepath.Base(filepath.Clean(skill.SourcePath))) } diff --git a/internal/utils/frontmatter.go b/internal/utils/frontmatter.go index 870924829..fe2584279 100644 --- a/internal/utils/frontmatter.go +++ b/internal/utils/frontmatter.go @@ -211,6 +211,19 @@ func extractFrontmatterRaw(filePath string) string { return strings.Join(lines, "\n") } +// ParseFrontmatterMap returns the complete YAML frontmatter of SKILL.md content. +func ParseFrontmatterMap(content []byte) (map[string]any, error) { + raw := extractFrontmatterRawFromBytes(content) + if raw == "" { + return nil, fmt.Errorf("no frontmatter") + } + var fm map[string]any + if err := yaml.Unmarshal([]byte(raw), &fm); err != nil { + return nil, fmt.Errorf("invalid frontmatter: %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). diff --git a/skills/skillshare/SKILL.md b/skills/skillshare/SKILL.md index 8b39521bd..40282a40f 100644 --- a/skills/skillshare/SKILL.md +++ b/skills/skillshare/SKILL.md @@ -33,8 +33,8 @@ Check `skillshare --help` if the installed version differs from these before editing MCP settings or importing native configurations. Its Agent notes cover what is specific to Claude Code, Codex, OpenCode and Pi: scopes and files, names and credentials they refuse, Pi's built-in MCP and `piOptions`, OMP's native MCP and preserved enable/disable lists, the portable `tools` policy, - upgrading Pi settings from 0.22, turning a global server off in one project, and `mcp.projects` for many folders from - one config. + upgrading Pi settings from 0.22, turning a global server off in one project, `mcp.projects` for many folders from + one config, and `mcp serve` for Agents that cannot reach the synced skill folders. - Plugins keep their native components together. Read [plugins.md](references/plugins.md) for installation, import, sync selection, updates, and native compatibility limits across Claude, Codex, Cursor, Antigravity, Pi, OMP, and OpenCode, including Pi packages from pi.dev diff --git a/skills/skillshare/references/mcp.md b/skills/skillshare/references/mcp.md index 073514faf..d4caab996 100644 --- a/skills/skillshare/references/mcp.md +++ b/skills/skillshare/references/mcp.md @@ -22,6 +22,8 @@ skillshare mcp restore BACKUP_ID --dry-run --json # Preview entry-level rest skillshare mcp restore BACKUP_ID --no-tui # Apply restoration; source stays unchanged skillshare mcp check --json # Static check: variables, commands, DNS, sync state skillshare mcp check --live --timeout 30s --json # Also start/call each server: serverInfo, protocol, tools +skillshare mcp serve [--target NAME] [--http ADDR] # Serve skills read-only over MCP (SEP-2640) +skillshare mcp serve --check [--target NAME] # List skills serve would skip, then exit ``` ## Automation rules @@ -50,6 +52,17 @@ skillshare mcp check --live --timeout 30s --json # Also start/call each serv its `env`) and POSTs to each remote one, skipping servers with a static error. A 401 is a warning with the resource metadata URL; it never signs in. Use it only for trusted servers. `--json` adds `live: {protocolVersion, serverInfo, tools, toolNames}`. +- `mcp serve` serves skills to Agents that cannot reach the synced folders (VMs, MCP + gateways): stdio by default, global unless `-p`. `--target NAME` applies that target's + filters. Skipped skills (name not matching its directory, over 512 files/16 MiB) are + listed on stderr; `--check` lists them without serving. `--http` on a non-loopback address requires `SKILLSHARE_MCP_TOKEN`. + Do not connect local Agents that already sync skills; they would see each skill twice. + Connect one with `mcp add skillshare --target CLIENT --sync -- skillshare mcp serve`, or a + remote `url` with `bearerToken: {fromEnv: SKILLSHARE_MCP_TOKEN}`. Agents with the Skills + extension load skills natively; as of October 2026 Codex, Cursor, VS Code, Goose and Pi + lack it and Claude Code's is off by default, so the server also offers `list_skills` + (`query` filters) and `read_skill` tools, hidden from clients that declare the extension. Verify the server with + `npx @modelcontextprotocol/inspector --cli skillshare mcp serve --method skills/list --verify`. - Noninteractive `import` without a name only lists candidates. Use `--replace` only when replacing is intended. - An `update` with the message `same settings, laid out one field per line` is a diff --git a/tests/integration/completion_test.go b/tests/integration/completion_test.go index bada3ba7d..f14125467 100644 --- a/tests/integration/completion_test.go +++ b/tests/integration/completion_test.go @@ -70,11 +70,11 @@ func TestCompletion_MCPCheck_AllShells(t *testing.T) { defer sb.Cleanup() for shell, subcommands := range map[string]string{ - "bash": "add check edit import list remove restore", - "zsh": "(add check edit import list remove restore)", - "fish": "-a 'add check edit import list remove restore'", - "powershell": "@{ Name = 'edit'; Desc = 'MCP edit' }", - "nushell": "[add check edit import list remove restore]", + "bash": "add check edit import list remove restore serve", + "zsh": "(add check edit import list remove restore serve)", + "fish": "-a 'add check edit import list remove restore serve'", + "powershell": "@{ Name = 'serve'; Desc = 'MCP serve' }", + "nushell": "[add check edit import list remove restore serve]", } { result := sb.RunCLI("completion", shell) result.AssertSuccess(t) diff --git a/tests/integration/mcp_serve_test.go b/tests/integration/mcp_serve_test.go new file mode 100644 index 000000000..b6ff02962 --- /dev/null +++ b/tests/integration/mcp_serve_test.go @@ -0,0 +1,105 @@ +//go:build !online + +package integration + +import ( + "bufio" + "bytes" + "fmt" + "os" + "os/exec" + "strings" + "testing" + + "skillshare/internal/testutil" +) + +const serveMeta = `"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"test","version":"1"},"io.modelcontextprotocol/clientCapabilities":{}}` + +func TestMCPServe_StdioListsValidSkills(t *testing.T) { + sb := testutil.NewSandbox(t) + defer sb.Cleanup() + sb.WriteConfig("source: " + sb.SourcePath + "\ntargets: {}\n") + sb.CreateSkill("pdf", map[string]string{"SKILL.md": "---\nname: pdf\ndescription: Use when editing PDFs\n---\n# PDF\n"}) + sb.CreateSkill("renamed", map[string]string{"SKILL.md": "---\nname: original\ndescription: Use when testing\n---\n# Renamed\n"}) + + // The server drops requests still in flight when stdin closes, so keep it + // open until both responses arrive, as a spawning gateway does. + cmd := exec.Command(sb.BinaryPath, "mcp", "serve", "-g") + cmd.Env = append(os.Environ(), "HOME="+sb.Home, "SKILLSHARE_CONFIG="+sb.ConfigPath) + var stderr bytes.Buffer + cmd.Stderr = &stderr + stdin, err := cmd.StdinPipe() + if err != nil { + t.Fatal(err) + } + stdout, err := cmd.StdoutPipe() + if err != nil { + t.Fatal(err) + } + if err := cmd.Start(); err != nil { + t.Fatal(err) + } + fmt.Fprintln(stdin, `{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{`+serveMeta+`}}`) + fmt.Fprintln(stdin, `{"jsonrpc":"2.0","id":2,"method":"skills/list","params":{`+serveMeta+`}}`) + scanner := bufio.NewScanner(stdout) + var out strings.Builder + for range 2 { + if !scanner.Scan() { + t.Fatalf("missing response: %v\nstderr: %s", scanner.Err(), stderr.String()) + } + out.WriteString(scanner.Text()) + } + stdin.Close() + if err := cmd.Wait(); err != nil { + t.Fatalf("serve exited with %v\nstderr: %s", err, stderr.String()) + } + + for _, want := range []string{`"io.modelcontextprotocol/skills"`, `"uri":"skill://pdf/SKILL.md"`} { + if !strings.Contains(out.String(), want) { + t.Errorf("responses missing %s:\n%s", want, out.String()) + } + } + if strings.Contains(out.String(), "skill://renamed") { + t.Errorf("renamed skill was served:\n%s", out.String()) + } + if want := `skipped renamed: SKILL.md name "original" does not match directory name "renamed"`; !strings.Contains(stderr.String(), want) { + t.Errorf("stderr missing %q:\n%s", want, stderr.String()) + } +} + +func TestMCPServe_CheckListsSkippedSkillsWithoutServing(t *testing.T) { + sb := testutil.NewSandbox(t) + defer sb.Cleanup() + sb.WriteConfig("source: " + sb.SourcePath + "\ntargets: {}\n") + sb.CreateSkill("pdf", map[string]string{"SKILL.md": "---\nname: pdf\ndescription: Use when editing PDFs\n---\n# PDF\n"}) + sb.CreateSkill("renamed", map[string]string{"SKILL.md": "---\nname: original\ndescription: Use when testing\n---\n# Renamed\n"}) + + r := sb.RunCLI("mcp", "serve", "--check", "-g") + + r.AssertSuccess(t) + r.AssertRowContains(t, "renamed", `SKILL.md name "original" does not match directory name "renamed"`) + r.AssertOutputContains(t, "1 skill served, 1 skipped") +} + +func TestMCPServe_RefusesUnauthenticatedNetworkListener(t *testing.T) { + sb := testutil.NewSandbox(t) + defer sb.Cleanup() + sb.WriteConfig("source: " + sb.SourcePath + "\ntargets: {}\n") + + r := sb.RunCLI("mcp", "serve", "--http", "0.0.0.0:0") + + r.AssertFailure(t) + r.AssertAnyOutputContains(t, "SKILLSHARE_MCP_TOKEN") +} + +func TestMCPServe_RejectsUnknownTarget(t *testing.T) { + sb := testutil.NewSandbox(t) + defer sb.Cleanup() + sb.WriteConfig("source: " + sb.SourcePath + "\ntargets: {}\n") + + r := sb.RunCLI("mcp", "serve", "--target", "nope") + + r.AssertFailure(t) + r.AssertAnyOutputContains(t, `unknown target "nope"`) +} diff --git a/website/docs/reference/commands/mcp.md b/website/docs/reference/commands/mcp.md index b43dc4353..058bf5095 100644 --- a/website/docs/reference/commands/mcp.md +++ b/website/docs/reference/commands/mcp.md @@ -25,6 +25,9 @@ skillshare mcp check --live --timeout 30s skillshare mcp remove docs --sync skillshare mcp remove docs --keep-files skillshare mcp restore BACKUP_ID --dry-run +skillshare mcp serve +skillshare mcp serve --target claude --http 127.0.0.1:8765 +skillshare mcp serve --check skillshare sync mcp --dry-run --json skillshare sync mcp skillshare sync --all @@ -32,7 +35,7 @@ skillshare sync --all | Option | Meaning | |---|---| -| `--target CLIENT` | Receiving client; repeat to select multiple clients. `--target none` keeps the server in Skillshare without writing it to any client. See [below](#keep-a-server-without-syncing-it) | +| `--target CLIENT` | Receiving client; repeat to select multiple clients. `--target none` keeps the server in Skillshare without writing it to any client. See [below](#keep-a-server-without-syncing-it). With `serve`, `--target NAME` names a skills target instead; see [below](#serve-skills-over-mcp) | | `--url URL` | Streamable HTTP endpoint for `add` | | `-- command args...` | Local executable and literal arguments for `add` | | `--disabled` | Project mode, with `add`: turn off a server the Agent's global config defines. See [below](#turn-off-a-global-server-in-one-project) | @@ -49,6 +52,8 @@ skillshare sync --all | `--no-dns` | With `check`: skip the host lookup of remote servers. See [below](#check-servers-before-an-agent-starts-them) | | `--live` | With `check`: also start each local server and call each remote one. See [below](#probe-servers-live) | | `--timeout DURATION` | With `check --live`: time limit for each server's probe, such as `30s`; default `10s` | +| `--http ADDR` | With `serve`: listen for Streamable HTTP on `ADDR` instead of using stdio. See [below](#serve-skills-over-mcp) | +| `--check` | With `serve`: list the skills it would skip and why, then exit without serving | | `--no-tui` | Disable interactive menus; also disabled by `tui: false`, `--json`, or non-terminal input/output | | `--revision ID` | Require a matching preview for add/import/remove or `sync mcp` | | `--global`, `-g` | Use global Skillshare configuration | @@ -765,6 +770,94 @@ and writes no files until you choose for that entry: - Replace it with the source definition: **Replace with source** in the dashboard, or `--replace` on import. +## Serve skills over MCP {#serve-skills-over-mcp} + +```bash +skillshare mcp serve # stdio, every enabled skill +skillshare mcp serve --target claude # only the skills the claude target selects +SKILLSHARE_MCP_TOKEN=change-me skillshare mcp serve --http 0.0.0.0:8765 +``` + +`mcp serve` is a read-only MCP server for an Agent that cannot reach the folder +your skills sync to, such as one on a disposable VM or behind an MCP gateway. It +implements the [Skills extension](https://modelcontextprotocol.io/seps/2640-skills-extension) +(`io.modelcontextprotocol/skills`, SEP-2640): `skills/list`, `skills/get` and +`resources/read`. Each skill is one entry whose URI follows its source path, such as +`skill://_team/tools/pdf/SKILL.md`, with its full frontmatter and every file with a +`sha256` digest and size. Agents on your own machine already receive skills through +`sync`; connecting them to `mcp serve` as well shows each skill twice. + +Most Agents do not support the Skills extension yet (see below), so the server also offers +two tools: `list_skills` lists names, descriptions and URIs (`query` narrows them; one +answer lists at most 200), and `read_skill` reads a `SKILL.md` or another file of a skill, +and for a `SKILL.md` lists the skill's other files. Any Agent that uses MCP tools can read +skills this way, including through a gateway that passes tools on. A client that declares +the Skills extension loads skills natively and is not offered the tools, so it does not +see each skill twice. Content read through a tool is ordinary text to the Agent: its own +skill approval does not apply. + +- **Selection.** Without `--target`, every enabled skill is served. `--target NAME` + applies that target's `include`/`exclude` filters and frontmatter `targets`, whatever + its sync mode; skills always come from the source. A target with skills turned off is + an error. +- **Skipped skills.** A skill is skipped, with a warning on stderr, when its `SKILL.md` + `name` breaks the Agent Skills naming rules or differs from its directory name (for + example after `install --name`), when it has no description, when it has more than 512 + files or 16 MiB, or when it contains a nested skill that is not served. + `skillshare mcp serve --check` lists those skills and their reasons, with the same + selection flags, and exits without serving. +- **Changes.** The source is read again at most every 5 seconds, so `install`, + `update`, `enable` and `disable` show up without a restart. Results carry + `ttlMs: 5000`. +- **Scope.** Global by default, wherever the server is started. `-p` serves the project + in the current directory. +- **Transport.** stdio by default, for a gateway or Agent that starts the command. + `--http ADDR` serves Streamable HTTP. A non-loopback address requires + `SKILLSHARE_MCP_TOKEN`; when it is set, every request must send + `Authorization: Bearer `. +- **Safety.** Only files in a skill's manifest can be read, and reads stay inside the + skill directory. Links and `.git` are neither listed nor served. Nothing is executed or + written. + +To connect an Agent, add the server like any other and sync it. On the machine that +runs the Agent: + +```bash +skillshare mcp add skillshare --target codex --sync -- skillshare mcp serve --target codex +``` + +In the dashboard, **Add server** → **Skillshare** builds the same command (with `-p` in +project mode) from a choice of skills; tick the Agent, save and sync. Editing that server +opens the same tab. + +For an Agent on another machine, run `mcp serve --http` where the skills are and point a +remote server at it. Keep the token in an environment variable: + +```yaml +mcp: + servers: + skillshare: + url: http://skills-host:8765/ + bearerToken: { fromEnv: SKILLSHARE_MCP_TOKEN } + targets: [codex] +``` + +Loading skills natively needs the Skills extension. As of October 2026 the common coding +Agents do not have it yet, so they use the tools: Codex, Cursor, VS Code, Goose and Pi have no support, and Claude Code includes +support that is not switched on by default. Only a few clients such as mcpc, fast-agent and +MCP Inspector do, some in part. The SEP's list of prototype hosts, such as a Codex fork, +does not mean the released Agents support it. The +[extension support matrix](https://modelcontextprotocol.io/extensions/client-matrix) lists +the current clients. + +To check the server itself, MCP Inspector 2.6.0 or later reads every skill, compares its +frontmatter and checks each file's digest: + +```bash +npx @modelcontextprotocol/inspector --cli skillshare mcp serve --method skills/list --verify +``` + + ## Safety and limitations - JSONC comments and unrelated settings are preserved. Changed owned entries From 5e02ef7ef0e82d13bae35e5ca3ef8f3545f6a993 Mon Sep 17 00:00:00 2001 From: Willie Date: Tue, 6 Oct 2026 14:18:20 +0800 Subject: [PATCH 02/26] refactor(sync): select a target's skills through SelectTargetSkills Status, doctor, diff, the dashboard's target and diff handlers and analyze each repeated FilterSkills followed by FilterSkillsByTarget, and only some dropped disabled skills first. Routing them through SelectTargetSkills keeps their answers identical to sync and mcp serve when a selection rule changes. The callers that did not drop disabled skills get discoveries without them, so their output does not change. --- cmd/skillshare/diff.go | 3 +-- cmd/skillshare/diff_project.go | 3 +-- cmd/skillshare/doctor.go | 3 +-- cmd/skillshare/status.go | 4 ++-- cmd/skillshare/status_project.go | 4 ++-- internal/server/handler_diff_stream.go | 3 +-- internal/server/handler_targets.go | 3 +-- internal/sync/analyze.go | 5 +---- 8 files changed, 10 insertions(+), 18 deletions(-) diff --git a/cmd/skillshare/diff.go b/cmd/skillshare/diff.go index 56e706e72..8cd50670c 100644 --- a/cmd/skillshare/diff.go +++ b/cmd/skillshare/diff.go @@ -420,11 +420,10 @@ func cmdDiffGlobal(targetName string, kind resourceKindFilter, opts diffRenderOp hasCopyMode := false for _, e := range entries { sc := e.target.SkillsConfig() - filtered, err := sync.FilterSkills(discovered, sc.Include, sc.Exclude) + filtered, err := sync.SelectTargetSkills(discovered, e.name, sc) if err != nil { return fmt.Errorf("target %s has invalid include/exclude config: %w", e.name, err) } - filtered = sync.FilterSkillsByTarget(filtered, e.name) fentries = append(fentries, filteredEntry{e, filtered}) totalSkills += len(filtered) if e.mode == "copy" { diff --git a/cmd/skillshare/diff_project.go b/cmd/skillshare/diff_project.go index 05835b266..841acc6d5 100644 --- a/cmd/skillshare/diff_project.go +++ b/cmd/skillshare/diff_project.go @@ -75,11 +75,10 @@ func cmdDiffProject(root, targetName string, kind resourceKindFilter, opts diffR if !sc.IsEnabled() { continue } - filtered, err := sync.FilterSkills(discovered, sc.Include, sc.Exclude) + filtered, err := sync.SelectTargetSkills(discovered, entry.Name, sc) if err != nil { return fmt.Errorf("target %s has invalid include/exclude config: %w", entry.Name, err) } - filtered = sync.FilterSkillsByTarget(filtered, entry.Name) mode := sc.Mode if mode == "" { mode = "merge" diff --git a/cmd/skillshare/doctor.go b/cmd/skillshare/doctor.go index ca54b5986..ce1c5940a 100644 --- a/cmd/skillshare/doctor.go +++ b/cmd/skillshare/doctor.go @@ -744,13 +744,12 @@ func checkSyncDrift(cfg *config.Config, result *doctorResult, discovered []sync. continue } sc := target.SkillsConfig() - filtered, err := sync.FilterSkills(discovered, sc.Include, sc.Exclude) + filtered, err := sync.SelectTargetSkills(discovered, name, sc) if err != nil { ui.Row(ui.MarkFail, name, fmt.Sprintf("invalid include/exclude config: %v", err), width) result.addError() continue } - filtered = sync.FilterSkillsByTarget(filtered, name) expectedCount := len(filtered) if expectedCount == 0 { continue diff --git a/cmd/skillshare/status.go b/cmd/skillshare/status.go index 857ef90bc..c019f862f 100644 --- a/cmd/skillshare/status.go +++ b/cmd/skillshare/status.go @@ -335,11 +335,11 @@ func printTargetsStatus(cfg *config.Config, discovered []sync.DiscoveredSkill) e // A target with skills off expects nothing, so it has no drift. expected := 0 if sc.IsEnabled() && (mode == "merge" || mode == "copy") { - filtered, err := sync.FilterSkills(discovered, sc.Include, sc.Exclude) + filtered, err := sync.SelectTargetSkills(discovered, name, sc) if err != nil { return fmt.Errorf("target %s has invalid include/exclude config: %w", name, err) } - expected = len(sync.FilterSkillsByTarget(filtered, name)) + expected = len(filtered) notSynced = max(notSynced, expected-res.syncedCount) } else if sc.IsEnabled() && (len(sc.Include) > 0 || len(sc.Exclude) > 0) { warnings = append(warnings, name+": include/exclude ignored in symlink mode") diff --git a/cmd/skillshare/status_project.go b/cmd/skillshare/status_project.go index d723c5624..3c61fd2a2 100644 --- a/cmd/skillshare/status_project.go +++ b/cmd/skillshare/status_project.go @@ -207,11 +207,11 @@ func printProjectTargetsStatus(runtime *projectRuntime, discovered []sync.Discov // A target with skills off expects nothing, so it has no drift. expected := 0 if sc.IsEnabled() && (mode == "merge" || mode == "copy") { - filtered, err := sync.FilterSkills(discovered, sc.Include, sc.Exclude) + filtered, err := sync.SelectTargetSkills(discovered, entry.Name, sc) if err != nil { return fmt.Errorf("target %s has invalid include/exclude config: %w", entry.Name, err) } - expected = len(sync.FilterSkillsByTarget(filtered, entry.Name)) + expected = len(filtered) notSynced = max(notSynced, expected-res.syncedCount) } else if sc.IsEnabled() && (len(sc.Include) > 0 || len(sc.Exclude) > 0) { warnings = append(warnings, entry.Name+": include/exclude ignored in symlink mode") diff --git a/internal/server/handler_diff_stream.go b/internal/server/handler_diff_stream.go index be4920b58..f7f9df998 100644 --- a/internal/server/handler_diff_stream.go +++ b/internal/server/handler_diff_stream.go @@ -98,11 +98,10 @@ func (s *Server) computeTargetDiff(name string, target config.TargetConfig, disc return dt } - filtered, err := ssync.FilterSkills(discovered, sc.Include, sc.Exclude) + filtered, err := ssync.SelectTargetSkills(discovered, name, sc) if err != nil { return dt } - filtered = ssync.FilterSkillsByTarget(filtered, name) resolution, err := ssync.ResolveTargetSkillsForTarget(name, config.ResourceTargetConfig{ Path: sc.Path, TargetNaming: sc.TargetNaming, diff --git a/internal/server/handler_targets.go b/internal/server/handler_targets.go index 4638c6737..7812b0146 100644 --- a/internal/server/handler_targets.go +++ b/internal/server/handler_targets.go @@ -139,12 +139,11 @@ func (s *Server) handleListTargets(w http.ResponseWriter, r *http.Request) { item.SkillsReadFrom = config.SkillsReadFrom(targets, name, projectRoot) case mode == "merge" || mode == "copy": if discoveredErr == nil { - filtered, err := ssync.FilterSkills(discovered, sc.Include, sc.Exclude) + filtered, err := ssync.SelectTargetSkills(discovered, name, sc) if err != nil { writeError(w, http.StatusBadRequest, "invalid include/exclude for target "+name+": "+err.Error()) return } - filtered = ssync.FilterSkillsByTarget(filtered, name) resolution, resErr := ssync.ResolveTargetSkillsForTarget(name, config.ResourceTargetConfig{ Path: sc.Path, TargetNaming: sc.TargetNaming, diff --git a/internal/sync/analyze.go b/internal/sync/analyze.go index 238589acd..b1c286d8f 100644 --- a/internal/sync/analyze.go +++ b/internal/sync/analyze.go @@ -3,7 +3,6 @@ package sync import ( "os" "path/filepath" - "slices" "strings" "skillshare/internal/config" @@ -33,12 +32,10 @@ func TargetSkills(name string, target config.TargetConfig, defaultMode, sourcePa return discovered, nil } - enabled := slices.DeleteFunc(slices.Clone(discovered), func(s DiscoveredSkill) bool { return s.Disabled }) - skills, err := FilterSkills(enabled, sc.Include, sc.Exclude) + skills, err := SelectTargetSkills(discovered, name, sc) if err != nil { return nil, err } - skills = FilterSkillsByTarget(skills, name) return append(skills, localTargetSkills(sc.Path, sourcePath)...), nil } From d1751f1a56d4a0e3e271739b854aa6e639edb321 Mon Sep 17 00:00:00 2001 From: Willie Date: Tue, 6 Oct 2026 14:18:26 +0800 Subject: [PATCH 03/26] feat(ui): add a Skillshare tab to Add server for mcp serve Serving skills over MCP is meant for people who do not want to type the command, so Add server gets a Skillshare tab next to the fields and the paste tabs. It asks only for a name, which skills (all enabled ones, or one skills target's selection) and the Agents, and shows the command it will run. It marks the Agents that already get skills by sync, including through another target's folder such as ~/.agents/skills, and warns when one is ticked, because that Agent would see each skill twice. Editing a server that runs skillshare mcp serve opens the same tab, in the global page and under mcp.projects. The tab is named after Skillshare rather than skills so it can hold more of what skillshare serves later. --- ui/src/components/mcp/MCPImportDialog.tsx | 7 +- ui/src/components/mcp/MCPProjectView.tsx | 11 ++- .../components/mcp/MCPServerDialog.test.tsx | 17 +++++ ui/src/components/mcp/MCPServerDialog.tsx | 74 +++++++++++++++---- ui/src/components/mcp/mcpServerDraft.test.ts | 9 ++- ui/src/components/mcp/mcpServerDraft.ts | 23 ++++++ ui/src/i18n/locales/de.json | 8 ++ ui/src/i18n/locales/en.json | 8 ++ ui/src/i18n/locales/es.json | 8 ++ ui/src/i18n/locales/fa.json | 8 ++ ui/src/i18n/locales/fr.json | 8 ++ ui/src/i18n/locales/id.json | 8 ++ ui/src/i18n/locales/ja.json | 8 ++ ui/src/i18n/locales/ko.json | 8 ++ ui/src/i18n/locales/pt-BR.json | 8 ++ ui/src/i18n/locales/zh-CN.json | 8 ++ ui/src/i18n/locales/zh-TW.json | 8 ++ ui/src/pages/MCPPage.tsx | 12 ++- .../docs/how-to/daily-tasks/sharing-mcp.md | 5 +- 19 files changed, 221 insertions(+), 25 deletions(-) diff --git a/ui/src/components/mcp/MCPImportDialog.tsx b/ui/src/components/mcp/MCPImportDialog.tsx index f95cd9c03..37b554c2a 100644 --- a/ui/src/components/mcp/MCPImportDialog.tsx +++ b/ui/src/components/mcp/MCPImportDialog.tsx @@ -17,6 +17,7 @@ import { useAppContext } from '../../context/AppContext'; import { shortenHome } from '../../lib/paths'; import { describeEndpoint, describeError, hasToolPolicy, targetLabel, parsePiOptions } from './mcpView'; import { MCPTargetOrder } from './targetOrder'; +import type { AddMode } from './mcpServerDraft'; /** Where the configuration comes from. Each entry point fixes one; the dialog never switches. */ type Source = 'target' | 'paste'; @@ -57,7 +58,7 @@ interface Props { /** Overrides the targets offered, for a project where only some Agents have a file. */ availableTargets?: readonly string[]; /** Present when this is the paste half of "add a server", so the user can swap back to the form. */ - onMode?: (mode: 'form' | 'paste') => void; + onMode?: (mode: AddMode) => void; onClose: () => void; onImported: () => void; } @@ -390,11 +391,11 @@ export default function MCPImportDialog(props: Props) {
{onMode && ( - + className="self-start" value="paste" onChange={onMode} - options={[{ value: 'form', label: t('mcp.manualTab') }, { value: 'paste', label: t('mcp.pasteTab') }]} + options={[{ value: 'form', label: t('mcp.manualTab') }, { value: 'paste', label: t('mcp.pasteTab') }, { value: 'serve', label: 'Skillshare' }]} /> )} diff --git a/ui/src/components/mcp/MCPProjectView.tsx b/ui/src/components/mcp/MCPProjectView.tsx index 9bd0501b3..a64aef515 100644 --- a/ui/src/components/mcp/MCPProjectView.tsx +++ b/ui/src/components/mcp/MCPProjectView.tsx @@ -14,6 +14,7 @@ import MCPCheckNote from './MCPCheckNote'; import MCPImportDialog from './MCPImportDialog'; import MCPRemoveDialog from './MCPRemoveDialog'; import MCPServerDialog from './MCPServerDialog'; +import { isServeCommand, type AddMode } from './mcpServerDraft'; import MCPServerList from './MCPServerList'; import MCPSyncBox, { MCPRailActions } from './MCPSyncBox'; import MCPUnmanagedNote from './MCPUnmanagedNote'; @@ -71,8 +72,10 @@ function ProjectSettings({ model, offered, pickTargets, onPickTargets, busy, sav ); } -function ProjectServerEditor({ data, model, root, offered, editing, addingOff, addMode, onMode, onClose, onSaved }: { data: MCPList; model: ProjectModel; root: string; offered: readonly string[]; editing: string; addingOff: boolean; addMode: 'form' | 'paste'; onMode: (mode: 'form' | 'paste') => void; onClose: () => void; onSaved: () => void }) { +function ProjectServerEditor({ data, model, root, offered, editing, addingOff, addMode, onMode, onClose, onSaved }: { data: MCPList; model: ProjectModel; root: string; offered: readonly string[]; editing: string; addingOff: boolean; addMode: AddMode; onMode: (mode: AddMode) => void; onClose: () => void; onSaved: () => void }) { const { servers, targets, own } = model; + const server = editing ? own[editing] : undefined; + const serve = editing === '' ? addMode === 'serve' : isServeCommand(server); return ( editing === '' && addMode === 'paste' ? ( ) : ( (null); // '' adds a new server - const [addMode, setAddMode] = useState<'form' | 'paste'>('form'); + const [addMode, setAddMode] = useState('form'); const [addingOff, setAddingOff] = useState(false); // the new entry is a switch, not a server const [removing, setRemoving] = useState(''); const [dropping, setDropping] = useState(false); diff --git a/ui/src/components/mcp/MCPServerDialog.test.tsx b/ui/src/components/mcp/MCPServerDialog.test.tsx index 2116f5517..c26e8c0a0 100644 --- a/ui/src/components/mcp/MCPServerDialog.test.tsx +++ b/ui/src/components/mcp/MCPServerDialog.test.tsx @@ -2,6 +2,7 @@ import { QueryClient, QueryClientProvider } from '@tanstack/react-query'; import { render, screen, waitFor } from '@testing-library/react'; import userEvent from '@testing-library/user-event'; import { beforeEach, describe, expect, it, vi } from 'vitest'; +import { api, type Target } from '../../api/client'; import { mcpApi } from '../../api/mcp'; import { mcpCheckApi } from '../../api/mcpCheck'; import { I18nProvider } from '../../i18n'; @@ -55,6 +56,8 @@ describe('MCP server dialog', () => { }); beforeEach(() => { vi.clearAllMocks(); localStorage.clear(); + vi.spyOn(api, 'listTargets').mockResolvedValue({ targets: [], sourceSkillCount: 0 }); + vi.spyOn(api, 'availableTargets').mockResolvedValue({ targets: [] }); HTMLElement.prototype.scrollIntoView = vi.fn(); vi.mocked(mcpApi.save).mockResolvedValue({ applied: [], backupIds: [] }); }); @@ -77,6 +80,20 @@ describe('MCP server dialog', () => { }); }); + it('serves every enabled skill from the Skillshare tab, with no command to type', async () => { + const user = userEvent.setup(); + renderDialog({ serve: true }); + expect(screen.queryByLabelText('Command')).not.toBeInTheDocument(); + await user.click(screen.getByRole('button', { name: 'Save' })); + await waitFor(() => expect(mcpApi.save).toHaveBeenCalledWith({ name: 'skillshare', server: { command: 'skillshare', args: ['mcp', 'serve'] }, replace: false })); + }); + + it('warns that an Agent already getting skills by sync would see them twice', async () => { + vi.mocked(api.listTargets).mockResolvedValue({ targets: [{ name: 'claude', skillsEnabled: true } as Target], sourceSkillCount: 1 }); + renderDialog({ serve: true }); + expect(await screen.findByText(/already get these skills by sync/)).toBeInTheDocument(); + }); + it('pins targets when the selection differs from the inherited default', async () => { const user = userEvent.setup(); renderDialog(); diff --git a/ui/src/components/mcp/MCPServerDialog.tsx b/ui/src/components/mcp/MCPServerDialog.tsx index 5db096a1e..63cef517b 100644 --- a/ui/src/components/mcp/MCPServerDialog.tsx +++ b/ui/src/components/mcp/MCPServerDialog.tsx @@ -1,6 +1,10 @@ import { useContext, useState } from 'react'; +import { useQuery } from '@tanstack/react-query'; import { Check, KeyRound, Link2, Plus, SquareTerminal, X } from 'lucide-react'; +import { api } from '../../api/client'; import { mcpApi, mcpOffTargets, type MCPMutation, type MCPServer } from '../../api/mcp'; +import { useAvailableTargetsQuery } from '../../hooks/useSharedQueries'; +import { queryKeys, staleTimes } from '../../lib/queryKeys'; import AgentIcon from '../AgentIcon'; import Button from '../Button'; import DialogShell from '../DialogShell'; @@ -13,7 +17,17 @@ import ToolPolicyFields from './ToolPolicyFields'; import MCPConfigView from './MCPConfigView'; import { cleanToolPolicy, describeError, hasToolPolicy, targetLabel } from './mcpView'; import { MCPTargetOrder } from './targetOrder'; -import { initialServerDraft, validateServerDraft, type DraftPatch, type EnvRow, type ServerDraft, type ServerValidation } from './mcpServerDraft'; +import { initialServerDraft, serveSkillsCommand, serveSkillsTarget, validateServerDraft, type AddMode, type DraftPatch, type EnvRow, type ServerDraft, type ServerValidation } from './mcpServerDraft'; + +/** For the Skillshare tab: the skills targets that can be served, and the Agents that already get skills by sync. */ +function useSkillTargets(enabled: boolean) { + const own = useQuery({ queryKey: queryKeys.targets.all, queryFn: () => api.listTargets(), staleTime: staleTimes.targets, enabled }); + const tools = useAvailableTargetsQuery({ enabled }); + const on = (own.data?.targets ?? []).filter((x) => x.skillsEnabled); + // A target syncs skills to its Agent; a tool also reads other targets' folders (universal's ~/.agents/skills). + const synced = new Set([...on.map((x) => x.agent ?? x.name), ...(tools.data?.targets ?? []).filter((x) => x.readsFrom?.length).map((x) => x.name)]); + return { names: on.map((x) => x.name), synced }; +} const valueMap = (rows: EnvRow[]) => Object.fromEntries(rows.filter((r) => r.key.trim()).map((r) => [r.key.trim(), r.fromEnv ? { fromEnv: r.value.trim() } : r.value])); @@ -68,7 +82,9 @@ interface Props { /** Adds a switch that turns off a server the Agent defines globally, not a server. */ off?: boolean; /** Present when adding, so the user can swap to pasting a snippet instead of filling the fields. */ - onMode?: (mode: 'form' | 'paste') => void; + onMode?: (mode: AddMode) => void; + /** The server is `skillshare mcp serve`: ask what to serve instead of a command. */ + serve?: boolean; onClose: () => void; onSaved: () => void; } @@ -83,6 +99,7 @@ interface ServerFormProps { order: readonly string[]; visibleTargets: Set; isProject: boolean; + serve: boolean; onMode: Props['onMode']; onSave: () => Promise; error: string; @@ -92,23 +109,27 @@ interface ServerFormProps { mutation?: MCPMutation; } -function ServerForm({ draft, validation, patch, off, saving, editing, order, visibleTargets, isProject, onMode, onSave, error, probe, mutation }: ServerFormProps) { +function ServerForm({ draft, validation, patch, off, saving, editing, order, visibleTargets, isProject, serve, onMode, onSave, error, probe, mutation }: ServerFormProps) { const t = useT(); const { name, http, targets } = draft; const { nameError } = validation; const selectedTargets = new Set(targets); + const skillTargets = useSkillTargets(serve); + const served = serveSkillsTarget(validation.words) ?? ''; + const twice = serve ? order.filter((x) => selectedTargets.has(x) && skillTargets.synced.has(x)) : []; return (
{ e.preventDefault(); void onSave(); }}> {/* Pasting a snippet only makes sense for a server, not for an off switch. */} {onMode && !off && ( - + className="self-start" - value="form" + value={serve ? 'serve' : 'form'} onChange={onMode} - options={[{ value: 'form', label: t('mcp.manualTab') }, { value: 'paste', label: t('mcp.pasteTab') }]} + options={[{ value: 'form', label: t('mcp.manualTab') }, { value: 'paste', label: t('mcp.pasteTab') }, { value: 'serve', label: 'Skillshare' }]} /> )} {off &&
{t('mcp.offHint')}
} + {serve &&

{t('mcp.serve.intro')}

}
@@ -117,7 +138,16 @@ function ServerForm({ draft, validation, patch, off, saving, editing, order, vis {nameError && {nameError}}
- {!off && ( + {serve && ( + patch({ command: serveSkillsCommand(v, isProject) })} + onChange={(v) => patch({ command: serveSkillsCommand(v, isProjectMode) })} options={[{ value: '', label: t('mcp.serve.all') }, ...[...new Set([...skillTargets.names, ...(served ? [served] : [])])].map((x) => ({ value: x, label: t('mcp.serve.like', { name: x }) }))]} disabled={saving} /> @@ -273,7 +276,8 @@ export default function MCPServerDialog({ initial, defaultTargets, existingNames const isProject = Boolean(project) || isProjectMode; const [draft, setDraft] = useState(() => { const start = initialServerDraft(server, initial?.name ?? '', defaultTargets, off); - return serve && !server ? { ...start, name: 'skillshare', command: serveSkillsCommand('', isProject) } : start; + // Only a project-mode dashboard serves with -p; a root under mcp.projects is served from the global config. + return serve && !server ? { ...start, name: 'skillshare', command: serveSkillsCommand('', isProjectMode) } : start; }); const patch: DraftPatch = (change) => setDraft((prev) => ({ ...prev, ...change })); const { http, url, tokenEnv, headers, env, targets } = draft; @@ -341,7 +345,7 @@ export default function MCPServerDialog({ initial, defaultTargets, existingNames
{/* The view takes the whole body, so a long file has room; the fields live in state and come back as they were. */} - {viewing ?
: } + {viewing ?
: } {viewing ?
: setViewing(true)} onClose={onClose} />} ); From fd4f499be768612e0dce4a3e52c82ba9bf2fb3f4 Mon Sep 17 00:00:00 2001 From: Willie Date: Tue, 6 Oct 2026 14:39:21 +0800 Subject: [PATCH 06/26] fix(mcp): keep serve digests and stdout trustworthy Size and mtime cannot prove a file is unchanged (cp -p, rsync -t), and a stale digest makes hosts that verify digests reject the file for good, so every rebuild hashes every file again; 1,000 skills rebuild in about 140 ms, at most once per refresh interval. Serve errors now go to stderr: stdout is the protocol stream, and a startup error printed there is not JSON-RPC. SKILL.md must begin with its frontmatter, as the Agent Skills format requires; a later --- block no longer passes. --- cmd/skillshare/main.go | 9 +++++-- internal/skillpkg/skillpkg.go | 10 ++++---- internal/skillserve/catalog.go | 37 +++++------------------------ internal/skillserve/catalog_test.go | 24 ++++++++++++++++++- internal/utils/frontmatter.go | 5 ++++ tests/integration/mcp_serve_test.go | 6 ++++- 6 files changed, 50 insertions(+), 41 deletions(-) diff --git a/cmd/skillshare/main.go b/cmd/skillshare/main.go index c7a5d3a62..a735c3af3 100644 --- a/cmd/skillshare/main.go +++ b/cmd/skillshare/main.go @@ -124,6 +124,8 @@ func main() { os.Exit(1) } + // mcp serve speaks the protocol on stdout, so its errors and trailers stay off it. + serving := cmd == "mcp" && len(args) > 0 && args[0] == "serve" if err := handler(args); err != nil { // jsonSilentError means JSON output was already written to stdout; // exit non-zero without adding plain-text noise. @@ -131,6 +133,10 @@ func main() { if errors.As(err, &silent) { os.Exit(1) } + if serving { + fmt.Fprintf(os.Stderr, "✗ %v\n", err) + os.Exit(1) + } fmt.Println() ui.Error("%v", err) os.Exit(1) @@ -140,8 +146,7 @@ func main() { // --format json/sarif/markdown) must produce only structured data on // stdout and nothing on stderr. Skip the trailing newline and update // check entirely so machine consumers get a clean payload. - // mcp serve speaks the protocol on stdout, so it gets neither either. - if !isStructuredOutput(args) && !(cmd == "mcp" && len(args) > 0 && args[0] == "serve") { + if !isStructuredOutput(args) && !serving { fmt.Println() // Check for updates (non-blocking, silent on errors) diff --git a/internal/skillpkg/skillpkg.go b/internal/skillpkg/skillpkg.go index 22a390d08..986a1fed8 100644 --- a/internal/skillpkg/skillpkg.go +++ b/internal/skillpkg/skillpkg.go @@ -8,7 +8,6 @@ import ( "os" "path/filepath" "strings" - "time" "skillshare/internal/sourcewalk" "skillshare/internal/utils" @@ -22,10 +21,9 @@ const ( // File is one regular file of a package. type File struct { - Path string // absolute - Rel string // slash-separated, relative to the package directory - Size int64 - ModTime time.Time + Path string // absolute + Rel string // slash-separated, relative to the package directory + Size int64 } // Package is a valid skill directory. @@ -81,7 +79,7 @@ func Load(dir string) (*Package, error) { if err != nil { return err } - p.Files = append(p.Files, File{Path: path, Rel: filepath.ToSlash(rel), Size: info.Size(), ModTime: info.ModTime()}) + p.Files = append(p.Files, File{Path: path, Rel: filepath.ToSlash(rel), Size: info.Size()}) return nil }) if err != nil { diff --git a/internal/skillserve/catalog.go b/internal/skillserve/catalog.go index c7f26abc7..3452f6cc2 100644 --- a/internal/skillserve/catalog.go +++ b/internal/skillserve/catalog.go @@ -12,7 +12,6 @@ import ( "os" "slices" "strings" - "time" "skillshare/internal/config" "skillshare/internal/skillpkg" @@ -59,8 +58,7 @@ type Catalog struct { byFile map[string]servedFile } -// Builder builds catalogs from the skills source. It keeps the digests of the -// last build so unchanged files are not hashed again. +// Builder builds catalogs from the skills source. type Builder struct { Source string Walk sourcewalk.Options @@ -68,14 +66,6 @@ type Builder struct { // every enabled skill is served. Target string Skills *config.ResourceTargetConfig - - digests map[string]digest -} - -type digest struct { - size int64 - mtime time.Time - sum string } // Build discovers the source and returns the skills to serve. Skills that are @@ -112,9 +102,8 @@ func (b *Builder) Build() (*Catalog, error) { reason string } loads := make([]loaded, len(selected)) - next := map[string]digest{} for i, s := range selected { - loads[i].skill, loads[i].files, loads[i].reason = b.load(s, next) + loads[i].skill, loads[i].files, loads[i].reason = load(s) } // Deepest first, so a nested skill skipped for any reason also skips its parents, // which would otherwise publish its files as their own. @@ -139,12 +128,13 @@ func (b *Builder) Build() (*Catalog, error) { c.bySkill[l.skill.URI] = l.skill maps.Copy(c.byFile, l.files) } - b.digests = next return c, nil } // load builds one entry and its files, or returns why the skill is skipped. -func (b *Builder) load(s ssync.DiscoveredSkill, next map[string]digest) (*Skill, map[string]servedFile, string) { +// Every build hashes every file: size and mtime cannot prove the content is +// unchanged (cp -p, rsync -t), and a stale digest makes hosts reject the file. +func load(s ssync.DiscoveredSkill) (*Skill, map[string]servedFile, string) { p, err := skillpkg.Load(s.SourcePath) if err != nil { return nil, nil, err.Error() @@ -153,7 +143,7 @@ func (b *Builder) load(s ssync.DiscoveredSkill, next map[string]digest) (*Skill, skill := &Skill{URI: base + "/SKILL.md", Frontmatter: p.Frontmatter} files := make(map[string]servedFile, len(p.Files)) for _, f := range p.Files { - sum, err := b.digest(f, next) + sum, err := utils.FileHashFormatted(f.Path) if err != nil { return nil, nil, err.Error() } @@ -164,21 +154,6 @@ func (b *Builder) load(s ssync.DiscoveredSkill, next map[string]digest) (*Skill, return skill, files, "" } -// ponytail: size+mtime keys the digest cache, so a same-size edit within the -// filesystem's mtime granularity keeps the old digest until the next change. -func (b *Builder) digest(f skillpkg.File, next map[string]digest) (string, error) { - if d, ok := b.digests[f.Path]; ok && d.size == f.Size && d.mtime.Equal(f.ModTime) { - next[f.Path] = d - return d.sum, nil - } - sum, err := utils.FileHashFormatted(f.Path) - if err != nil { - return "", err - } - next[f.Path] = digest{size: f.Size, mtime: f.ModTime, sum: sum} - return sum, nil -} - // Skill returns the served skill whose SKILL.md URI is uri. func (c *Catalog) Skill(uri string) (*Skill, bool) { key, ok := canonical(uri) diff --git a/internal/skillserve/catalog_test.go b/internal/skillserve/catalog_test.go index 5f99d748d..524354559 100644 --- a/internal/skillserve/catalog_test.go +++ b/internal/skillserve/catalog_test.go @@ -151,6 +151,20 @@ func TestBuild_SkipsSkillWhoseFrontmatterJSONCannotCarry(t *testing.T) { } } +// The Skills extension requires SKILL.md to begin with its frontmatter. +func TestBuild_SkipsSkillWhoseFrontmatterIsNotAtTheStart(t *testing.T) { + src := t.TempDir() + writeFile(t, filepath.Join(src, "late/SKILL.md"), "# intro\n"+skillMD("late")) + + c, err := (&Builder{Source: src}).Build() + if err != nil { + t.Fatal(err) + } + if len(c.Skills) != 0 || !hasWarning(c, "skipped late") { + t.Errorf("skills=%v warnings=%v, want late skipped", c.Skills, c.Skipped) + } +} + func TestBuild_SkipsSkillOverFileLimit(t *testing.T) { src := t.TempDir() writeFile(t, filepath.Join(src, "big/SKILL.md"), skillMD("big")) @@ -177,7 +191,15 @@ func TestBuild_RefreshesDigestWhenContentChanges(t *testing.T) { if err != nil { t.Fatal(err) } - writeFile(t, ref, "two!") + // Same size and modification time, as cp -p or rsync -t leave it. + info, err := os.Stat(ref) + if err != nil { + t.Fatal(err) + } + writeFile(t, ref, "two") + if err := os.Chtimes(ref, info.ModTime(), info.ModTime()); err != nil { + t.Fatal(err) + } second, err := b.Build() if err != nil { t.Fatal(err) diff --git a/internal/utils/frontmatter.go b/internal/utils/frontmatter.go index fd64093ab..74a08ef7f 100644 --- a/internal/utils/frontmatter.go +++ b/internal/utils/frontmatter.go @@ -2,6 +2,7 @@ package utils import ( "bufio" + "bytes" "encoding/json" "fmt" "os" @@ -213,7 +214,11 @@ func extractFrontmatterRaw(filePath string) string { } // ParseFrontmatterMap returns the complete YAML frontmatter of SKILL.md content. +// The Agent Skills format requires the file to begin with it. func ParseFrontmatterMap(content []byte) (map[string]any, error) { + if first, _, _ := strings.Cut(string(bytes.TrimPrefix(content, []byte("\xef\xbb\xbf"))), "\n"); strings.TrimSpace(first) != "---" { + return nil, fmt.Errorf("no frontmatter at the start") + } raw := extractFrontmatterRawFromBytes(content) if raw == "" { return nil, fmt.Errorf("no frontmatter") diff --git a/tests/integration/mcp_serve_test.go b/tests/integration/mcp_serve_test.go index b6ff02962..1553aacfd 100644 --- a/tests/integration/mcp_serve_test.go +++ b/tests/integration/mcp_serve_test.go @@ -100,6 +100,10 @@ func TestMCPServe_RejectsUnknownTarget(t *testing.T) { r := sb.RunCLI("mcp", "serve", "--target", "nope") + // stdout is the protocol stream, so the error goes to stderr alone. r.AssertFailure(t) - r.AssertAnyOutputContains(t, `unknown target "nope"`) + r.AssertErrorContains(t, `unknown target "nope"`) + if r.Stdout != "" { + t.Errorf("stdout = %q, want nothing", r.Stdout) + } } From 96593f94115e4483283fc18c595a42ebd44fa1bb Mon Sep 17 00:00:00 2001 From: Willie Date: Tue, 6 Oct 2026 14:47:41 +0800 Subject: [PATCH 07/26] fix(mcp): quote the served target and cap skill descriptions A managed project's name may hold spaces, so the Skillshare tab built `--target my app@claude`, which the save path split into two words and serve rejected as an unknown target. The command is now joined from quoted words. The Agent Skills format caps a description at 1,024 characters, and hosts validating entries reject longer ones, so serve skips such a skill with a warning instead of advertising it. The docs list every skip reason. --- internal/skillpkg/skillpkg.go | 14 ++++++++++---- internal/skillserve/catalog_test.go | 16 ++++++++++++++++ skills/skillshare/references/mcp.md | 3 ++- ui/src/components/mcp/mcpServerDraft.test.ts | 7 +++++-- ui/src/components/mcp/mcpServerDraft.ts | 2 +- website/docs/reference/commands/mcp.md | 7 ++++--- 6 files changed, 38 insertions(+), 11 deletions(-) diff --git a/internal/skillpkg/skillpkg.go b/internal/skillpkg/skillpkg.go index 986a1fed8..ead37c846 100644 --- a/internal/skillpkg/skillpkg.go +++ b/internal/skillpkg/skillpkg.go @@ -8,15 +8,17 @@ import ( "os" "path/filepath" "strings" + "unicode/utf8" "skillshare/internal/sourcewalk" "skillshare/internal/utils" ) -// Per-skill limits from SEP-2640. +// Per-skill limits from SEP-2640, and the Agent Skills description limit. const ( - MaxFiles = 512 - MaxBytes = 16 << 20 + MaxFiles = 512 + MaxBytes = 16 << 20 + MaxDescription = 1024 ) // File is one regular file of a package. @@ -50,9 +52,13 @@ func Load(dir string) (*Package, error) { if reason := ValidateName(name, dirName); reason != "" { return nil, fmt.Errorf("%s", reason) } - if desc, _ := fm["description"].(string); strings.TrimSpace(desc) == "" { + desc, _ := fm["description"].(string) + if strings.TrimSpace(desc) == "" { return nil, fmt.Errorf("SKILL.md is missing a description") } + if n := utf8.RuneCountInString(desc); n > MaxDescription { + return nil, fmt.Errorf("description has %d characters; the limit is %d", n, MaxDescription) + } p := &Package{Dir: dir, Frontmatter: fm} var total int64 diff --git a/internal/skillserve/catalog_test.go b/internal/skillserve/catalog_test.go index 524354559..7e9081d42 100644 --- a/internal/skillserve/catalog_test.go +++ b/internal/skillserve/catalog_test.go @@ -165,6 +165,22 @@ func TestBuild_SkipsSkillWhoseFrontmatterIsNotAtTheStart(t *testing.T) { } } +// The Agent Skills format caps a description at 1,024 characters, not bytes. +func TestBuild_SkipsSkillWhoseDescriptionIsTooLong(t *testing.T) { + src := t.TempDir() + skill := func(name, desc string) string { return "---\nname: " + name + "\ndescription: " + desc + "\n---\n" } + writeFile(t, filepath.Join(src, "long/SKILL.md"), skill("long", strings.Repeat("a", 1025))) + writeFile(t, filepath.Join(src, "wide/SKILL.md"), skill("wide", strings.Repeat("技", 1024))) + + c, err := (&Builder{Source: src}).Build() + if err != nil { + t.Fatal(err) + } + if len(c.Skills) != 1 || c.Skills[0].URI != "skill://wide/SKILL.md" || !hasWarning(c, "skipped long") { + t.Errorf("skills=%v warnings=%v, want long skipped and wide served", c.Skills, c.Skipped) + } +} + func TestBuild_SkipsSkillOverFileLimit(t *testing.T) { src := t.TempDir() writeFile(t, filepath.Join(src, "big/SKILL.md"), skillMD("big")) diff --git a/skills/skillshare/references/mcp.md b/skills/skillshare/references/mcp.md index d4caab996..378106d76 100644 --- a/skills/skillshare/references/mcp.md +++ b/skills/skillshare/references/mcp.md @@ -54,7 +54,8 @@ skillshare mcp serve --check [--target NAME] # List skills serve would s servers. `--json` adds `live: {protocolVersion, serverInfo, tools, toolNames}`. - `mcp serve` serves skills to Agents that cannot reach the synced folders (VMs, MCP gateways): stdio by default, global unless `-p`. `--target NAME` applies that target's - filters. Skipped skills (name not matching its directory, over 512 files/16 MiB) are + filters. Skipped skills (name not matching its directory, description missing or over 1,024 + characters, over 512 files/16 MiB) are listed on stderr; `--check` lists them without serving. `--http` on a non-loopback address requires `SKILLSHARE_MCP_TOKEN`. Do not connect local Agents that already sync skills; they would see each skill twice. Connect one with `mcp add skillshare --target CLIENT --sync -- skillshare mcp serve`, or a diff --git a/ui/src/components/mcp/mcpServerDraft.test.ts b/ui/src/components/mcp/mcpServerDraft.test.ts index aa2547b84..55be43ce9 100644 --- a/ui/src/components/mcp/mcpServerDraft.test.ts +++ b/ui/src/components/mcp/mcpServerDraft.test.ts @@ -1,5 +1,6 @@ import { describe, expect, it } from 'vitest'; import { initialServerDraft, serveSkillsCommand, serveSkillsTarget } from './mcpServerDraft'; +import { splitCommand } from './mcpView'; describe('MCP server drafts', () => { it('starts from the Pi settings of a server being edited', () => { @@ -15,8 +16,10 @@ describe('MCP server drafts', () => { }); it('reads back the skills target of a command it builds, and nothing from other commands', () => { - expect(serveSkillsTarget(serveSkillsCommand('claude', true).split(' '))).toBe('claude'); - expect(serveSkillsTarget(serveSkillsCommand('', false).split(' '))).toBe(''); + expect(serveSkillsTarget(splitCommand(serveSkillsCommand('claude', true)))).toBe('claude'); + expect(serveSkillsTarget(splitCommand(serveSkillsCommand('', false)))).toBe(''); + // A project's name may hold spaces: its target must survive as one word. + expect(serveSkillsTarget(splitCommand(serveSkillsCommand('my app@claude', false)))).toBe('my app@claude'); expect(serveSkillsTarget(['skillshare', 'mcp', 'serve', '--http', ':8765'])).toBeUndefined(); expect(serveSkillsTarget(['npx', 'skillshare', 'mcp', 'serve'])).toBeUndefined(); }); diff --git a/ui/src/components/mcp/mcpServerDraft.ts b/ui/src/components/mcp/mcpServerDraft.ts index a703939a3..5c9cc7dce 100644 --- a/ui/src/components/mcp/mcpServerDraft.ts +++ b/ui/src/components/mcp/mcpServerDraft.ts @@ -43,7 +43,7 @@ export type AddMode = 'form' | 'paste' | 'serve'; /** The command that serves skills over MCP: every enabled skill, or those of one skills target. */ export const serveSkillsCommand = (target: string, project: boolean) => - ['skillshare mcp serve', target && `--target ${target}`, project && '-p'].filter(Boolean).join(' '); + joinCommand(['skillshare', 'mcp', 'serve', ...(target ? ['--target', target] : []), ...(project ? ['-p'] : [])]); /** The skills target a `skillshare mcp serve` command serves ('' for every skill), or undefined for any other command. */ export function serveSkillsTarget(words: string[]): string | undefined { diff --git a/website/docs/reference/commands/mcp.md b/website/docs/reference/commands/mcp.md index 058bf5095..c34c4aeec 100644 --- a/website/docs/reference/commands/mcp.md +++ b/website/docs/reference/commands/mcp.md @@ -801,9 +801,10 @@ skill approval does not apply. its sync mode; skills always come from the source. A target with skills turned off is an error. - **Skipped skills.** A skill is skipped, with a warning on stderr, when its `SKILL.md` - `name` breaks the Agent Skills naming rules or differs from its directory name (for - example after `install --name`), when it has no description, when it has more than 512 - files or 16 MiB, or when it contains a nested skill that is not served. + does not begin with its frontmatter, when its `name` breaks the Agent Skills naming + rules or differs from its directory name (for example after `install --name`), when + its description is missing or over 1,024 characters, when it has more than 512 files + or 16 MiB, or when it contains a nested skill that is not served. `skillshare mcp serve --check` lists those skills and their reasons, with the same selection flags, and exits without serving. - **Changes.** The source is read again at most every 5 seconds, so `install`, From 64898e145b1c08fdd25b1e38f13c74db0ceae336 Mon Sep 17 00:00:00 2001 From: Willie Date: Tue, 6 Oct 2026 14:57:49 +0800 Subject: [PATCH 08/26] fix(mcp): keep migration notices off stdout and require closed frontmatter The first command after an upgrade reports legacy data it moved. For mcp serve that notice landed on stdout ahead of the handshake, so it now goes to stderr like serve's other messages. A SKILL.md that opens frontmatter but never closes it could still parse, so serve published a file hosts read as having no frontmatter; it is now skipped with a warning. --- cmd/skillshare/main.go | 13 ++++++++++--- internal/skillserve/catalog_test.go | 5 +++-- internal/utils/frontmatter.go | 9 +++++++-- tests/integration/mcp_serve_test.go | 21 +++++++++++++++++++++ 4 files changed, 41 insertions(+), 7 deletions(-) diff --git a/cmd/skillshare/main.go b/cmd/skillshare/main.go index a735c3af3..67ca7788f 100644 --- a/cmd/skillshare/main.go +++ b/cmd/skillshare/main.go @@ -81,7 +81,16 @@ func main() { // Migrate legacy dirs (backups/trash/logs) to XDG data/state dirs results = append(results, config.MigrateXDGDirs()...) - reportMigrationResults(results) + // mcp serve speaks the protocol on stdout, so its errors, notices and trailers stay off it. + serving := len(os.Args) > 2 && os.Args[1] == "mcp" && os.Args[2] == "serve" + if serving { + stdout := os.Stdout + os.Stdout = os.Stderr + reportMigrationResults(results) + os.Stdout = stdout + } else { + reportMigrationResults(results) + } // Set version for other packages to use versioncheck.Version = version @@ -124,8 +133,6 @@ func main() { os.Exit(1) } - // mcp serve speaks the protocol on stdout, so its errors and trailers stay off it. - serving := cmd == "mcp" && len(args) > 0 && args[0] == "serve" if err := handler(args); err != nil { // jsonSilentError means JSON output was already written to stdout; // exit non-zero without adding plain-text noise. diff --git a/internal/skillserve/catalog_test.go b/internal/skillserve/catalog_test.go index 7e9081d42..af256c979 100644 --- a/internal/skillserve/catalog_test.go +++ b/internal/skillserve/catalog_test.go @@ -155,13 +155,14 @@ func TestBuild_SkipsSkillWhoseFrontmatterJSONCannotCarry(t *testing.T) { func TestBuild_SkipsSkillWhoseFrontmatterIsNotAtTheStart(t *testing.T) { src := t.TempDir() writeFile(t, filepath.Join(src, "late/SKILL.md"), "# intro\n"+skillMD("late")) + writeFile(t, filepath.Join(src, "open/SKILL.md"), "---\nname: open\ndescription: Use when testing open\n# open\n") c, err := (&Builder{Source: src}).Build() if err != nil { t.Fatal(err) } - if len(c.Skills) != 0 || !hasWarning(c, "skipped late") { - t.Errorf("skills=%v warnings=%v, want late skipped", c.Skills, c.Skipped) + if len(c.Skills) != 0 || !hasWarning(c, "skipped late") || !hasWarning(c, "skipped open") { + t.Errorf("skills=%v warnings=%v, want late and unclosed open skipped", c.Skills, c.Skipped) } } diff --git a/internal/utils/frontmatter.go b/internal/utils/frontmatter.go index 74a08ef7f..96c00787b 100644 --- a/internal/utils/frontmatter.go +++ b/internal/utils/frontmatter.go @@ -7,6 +7,7 @@ import ( "fmt" "os" "path/filepath" + "slices" "strings" "gopkg.in/yaml.v3" @@ -214,11 +215,15 @@ func extractFrontmatterRaw(filePath string) string { } // ParseFrontmatterMap returns the complete YAML frontmatter of SKILL.md content. -// The Agent Skills format requires the file to begin with it. +// The Agent Skills format requires the file to begin with it, closed by a second ---. func ParseFrontmatterMap(content []byte) (map[string]any, error) { - if first, _, _ := strings.Cut(string(bytes.TrimPrefix(content, []byte("\xef\xbb\xbf"))), "\n"); strings.TrimSpace(first) != "---" { + lines := strings.Split(string(bytes.TrimPrefix(content, []byte("\xef\xbb\xbf"))), "\n") + if strings.TrimSpace(lines[0]) != "---" { return nil, fmt.Errorf("no frontmatter at the start") } + if !slices.ContainsFunc(lines[1:], func(l string) bool { return strings.TrimSpace(l) == "---" }) { + return nil, fmt.Errorf("unclosed frontmatter: no closing ---") + } raw := extractFrontmatterRawFromBytes(content) if raw == "" { return nil, fmt.Errorf("no frontmatter") diff --git a/tests/integration/mcp_serve_test.go b/tests/integration/mcp_serve_test.go index 1553aacfd..495152adb 100644 --- a/tests/integration/mcp_serve_test.go +++ b/tests/integration/mcp_serve_test.go @@ -8,6 +8,7 @@ import ( "fmt" "os" "os/exec" + "path/filepath" "strings" "testing" @@ -107,3 +108,23 @@ func TestMCPServe_RejectsUnknownTarget(t *testing.T) { t.Errorf("stdout = %q, want nothing", r.Stdout) } } + +func TestMCPServe_ReportsLegacyMigrationOnStderr(t *testing.T) { + sb := testutil.NewSandbox(t) + defer sb.Cleanup() + sb.WriteConfig("source: " + sb.SourcePath + "\ntargets: {}\n") + // A legacy trash folder in the config dir is moved to the data dir by the first command. + if err := os.MkdirAll(filepath.Join(sb.Home, ".config", "skillshare", "trash"), 0o755); err != nil { + t.Fatal(err) + } + if err := os.Remove(filepath.Join(sb.Home, ".local", "share", "skillshare", "trash")); err != nil { + t.Fatal(err) + } + + r := sb.RunCLI("mcp", "serve", "--target", "nope") + + r.AssertErrorContains(t, "Moved legacy data") + if r.Stdout != "" { + t.Errorf("stdout = %q, want nothing", r.Stdout) + } +} From d13e03adfc3402b2c58f1d62c47f212478514937 Mon Sep 17 00:00:00 2001 From: Willie Date: Tue, 6 Oct 2026 15:00:35 +0800 Subject: [PATCH 09/26] fix(mcp): skip skills whose compatibility exceeds the format limit The Agent Skills format caps compatibility at 500 characters, and hosts that validate entries reject longer ones, so serve skips such a skill with a warning, as it does for an overlong description. metadata is deliberately not held to the format's string values: lists there are common, tool-fallback clients read them fine, and skipping those skills would hide them from every client to satisfy a few. --- internal/skillpkg/skillpkg.go | 15 +++++++++++---- internal/skillserve/catalog_test.go | 9 +++++---- skills/skillshare/references/mcp.md | 2 +- website/docs/reference/commands/mcp.md | 3 ++- 4 files changed, 19 insertions(+), 10 deletions(-) diff --git a/internal/skillpkg/skillpkg.go b/internal/skillpkg/skillpkg.go index ead37c846..17cf2fcb9 100644 --- a/internal/skillpkg/skillpkg.go +++ b/internal/skillpkg/skillpkg.go @@ -14,11 +14,12 @@ import ( "skillshare/internal/utils" ) -// Per-skill limits from SEP-2640, and the Agent Skills description limit. +// Per-skill limits from SEP-2640, and the Agent Skills field limits in characters. const ( - MaxFiles = 512 - MaxBytes = 16 << 20 - MaxDescription = 1024 + MaxFiles = 512 + MaxBytes = 16 << 20 + MaxDescription = 1024 + MaxCompatibility = 500 ) // File is one regular file of a package. @@ -59,6 +60,12 @@ func Load(dir string) (*Package, error) { if n := utf8.RuneCountInString(desc); n > MaxDescription { return nil, fmt.Errorf("description has %d characters; the limit is %d", n, MaxDescription) } + // metadata is left unchecked: the format wants string values, but lists there are + // common and tool clients read them fine, so skipping those skills would cost more. + compat, _ := fm["compatibility"].(string) + if n := utf8.RuneCountInString(compat); n > MaxCompatibility { + return nil, fmt.Errorf("compatibility has %d characters; the limit is %d", n, MaxCompatibility) + } p := &Package{Dir: dir, Frontmatter: fm} var total int64 diff --git a/internal/skillserve/catalog_test.go b/internal/skillserve/catalog_test.go index af256c979..6e2c3da29 100644 --- a/internal/skillserve/catalog_test.go +++ b/internal/skillserve/catalog_test.go @@ -166,19 +166,20 @@ func TestBuild_SkipsSkillWhoseFrontmatterIsNotAtTheStart(t *testing.T) { } } -// The Agent Skills format caps a description at 1,024 characters, not bytes. -func TestBuild_SkipsSkillWhoseDescriptionIsTooLong(t *testing.T) { +// The Agent Skills format caps a description at 1,024 characters and compatibility at 500, not bytes. +func TestBuild_SkipsSkillWhoseDescriptionOrCompatibilityIsTooLong(t *testing.T) { src := t.TempDir() skill := func(name, desc string) string { return "---\nname: " + name + "\ndescription: " + desc + "\n---\n" } writeFile(t, filepath.Join(src, "long/SKILL.md"), skill("long", strings.Repeat("a", 1025))) writeFile(t, filepath.Join(src, "wide/SKILL.md"), skill("wide", strings.Repeat("技", 1024))) + writeFile(t, filepath.Join(src, "compat/SKILL.md"), "---\nname: compat\ndescription: Use when testing\ncompatibility: "+strings.Repeat("a", 501)+"\n---\n") c, err := (&Builder{Source: src}).Build() if err != nil { t.Fatal(err) } - if len(c.Skills) != 1 || c.Skills[0].URI != "skill://wide/SKILL.md" || !hasWarning(c, "skipped long") { - t.Errorf("skills=%v warnings=%v, want long skipped and wide served", c.Skills, c.Skipped) + if len(c.Skills) != 1 || c.Skills[0].URI != "skill://wide/SKILL.md" || !hasWarning(c, "skipped long") || !hasWarning(c, "skipped compat") { + t.Errorf("skills=%v warnings=%v, want long and compat skipped, wide served", c.Skills, c.Skipped) } } diff --git a/skills/skillshare/references/mcp.md b/skills/skillshare/references/mcp.md index 378106d76..6b36810e4 100644 --- a/skills/skillshare/references/mcp.md +++ b/skills/skillshare/references/mcp.md @@ -55,7 +55,7 @@ skillshare mcp serve --check [--target NAME] # List skills serve would s - `mcp serve` serves skills to Agents that cannot reach the synced folders (VMs, MCP gateways): stdio by default, global unless `-p`. `--target NAME` applies that target's filters. Skipped skills (name not matching its directory, description missing or over 1,024 - characters, over 512 files/16 MiB) are + characters, compatibility over 500, over 512 files/16 MiB) are listed on stderr; `--check` lists them without serving. `--http` on a non-loopback address requires `SKILLSHARE_MCP_TOKEN`. Do not connect local Agents that already sync skills; they would see each skill twice. Connect one with `mcp add skillshare --target CLIENT --sync -- skillshare mcp serve`, or a diff --git a/website/docs/reference/commands/mcp.md b/website/docs/reference/commands/mcp.md index c34c4aeec..5db28837e 100644 --- a/website/docs/reference/commands/mcp.md +++ b/website/docs/reference/commands/mcp.md @@ -803,7 +803,8 @@ skill approval does not apply. - **Skipped skills.** A skill is skipped, with a warning on stderr, when its `SKILL.md` does not begin with its frontmatter, when its `name` breaks the Agent Skills naming rules or differs from its directory name (for example after `install --name`), when - its description is missing or over 1,024 characters, when it has more than 512 files + its description is missing or over 1,024 characters or its `compatibility` over 500, + when it has more than 512 files or 16 MiB, or when it contains a nested skill that is not served. `skillshare mcp serve --check` lists those skills and their reasons, with the same selection flags, and exits without serving. From b5bad20e50f2d54316f1498ed99a45ed10a27df3 Mon Sep 17 00:00:00 2001 From: Willie Date: Tue, 6 Oct 2026 15:09:34 +0800 Subject: [PATCH 10/26] fix(mcp): serve only bytes that match the listed digest The catalog is reused for up to 5 s, so a file edited after skills/list was read live and failed the client's digest check. A read now hashes what it returns and reports the file as changed when the digest no longer matches; the next refresh lists it again. Also: a BOM-prefixed SKILL.md is parsed from the stripped bytes instead of being skipped, a non-text compatibility is rejected rather than treated as absent, and an oversized SKILL.md is skipped before it is read into memory. --- internal/skillpkg/skillpkg.go | 13 ++++++++- internal/skillserve/catalog.go | 20 ++++++++++---- internal/skillserve/catalog_test.go | 43 +++++++++++++++++++++++++++++ internal/utils/frontmatter.go | 3 +- 4 files changed, 72 insertions(+), 7 deletions(-) diff --git a/internal/skillpkg/skillpkg.go b/internal/skillpkg/skillpkg.go index 17cf2fcb9..5c0e74068 100644 --- a/internal/skillpkg/skillpkg.go +++ b/internal/skillpkg/skillpkg.go @@ -41,6 +41,14 @@ type Package struct { func Load(dir string) (*Package, error) { dirName := filepath.Base(filepath.Clean(dir)) // a followed link's name, not its target's dir = utils.ResolveSymlink(dir) + // Stat first, so an oversized SKILL.md is skipped without reading it into memory. + info, err := os.Stat(filepath.Join(dir, "SKILL.md")) + if err != nil { + return nil, err + } + if info.Size() > MaxBytes { + return nil, fmt.Errorf("SKILL.md is over %d MiB", MaxBytes>>20) + } content, err := os.ReadFile(filepath.Join(dir, "SKILL.md")) if err != nil { return nil, err @@ -62,7 +70,10 @@ func Load(dir string) (*Package, error) { } // metadata is left unchecked: the format wants string values, but lists there are // common and tool clients read them fine, so skipping those skills would cost more. - compat, _ := fm["compatibility"].(string) + compat, ok := fm["compatibility"].(string) + if _, set := fm["compatibility"]; set && !ok { + return nil, fmt.Errorf("compatibility must be text") + } if n := utf8.RuneCountInString(compat); n > MaxCompatibility { return nil, fmt.Errorf("compatibility has %d characters; the limit is %d", n, MaxCompatibility) } diff --git a/internal/skillserve/catalog.go b/internal/skillserve/catalog.go index 3452f6cc2..a469688ff 100644 --- a/internal/skillserve/catalog.go +++ b/internal/skillserve/catalog.go @@ -4,6 +4,7 @@ package skillserve import ( + "crypto/sha256" "errors" "fmt" "io" @@ -39,9 +40,9 @@ type Skill struct { Resources []File `json:"resources"` } -// servedFile locates a manifest file: the resolved skill directory and the -// slash path inside it. -type servedFile struct{ dir, rel string } +// servedFile locates a manifest file: the resolved skill directory, the +// slash path inside it, and the digest it was listed with. +type servedFile struct{ dir, rel, digest string } // Skip is a skill left out of the catalog, by source path. type Skip struct { @@ -148,7 +149,7 @@ func load(s ssync.DiscoveredSkill) (*Skill, map[string]servedFile, string) { return nil, nil, err.Error() } uri := base + "/" + escapePath(f.Rel) - files[uri] = servedFile{dir: p.Dir, rel: f.Rel} + files[uri] = servedFile{dir: p.Dir, rel: f.Rel, digest: sum} skill.Resources = append(skill.Resources, File{URI: uri, Digest: sum, Size: f.Size}) } return skill, files, "" @@ -179,7 +180,16 @@ func (c *Catalog) Read(uri string) ([]byte, error) { return nil, err } defer f.Close() - return io.ReadAll(io.LimitReader(f, skillpkg.MaxBytes)) + data, err := io.ReadAll(io.LimitReader(f, skillpkg.MaxBytes)) + if err != nil { + return nil, err + } + // A file edited since it was listed would fail the client's digest check; + // the next refresh lists it again. + if fmt.Sprintf("sha256:%x", sha256.Sum256(data)) != sf.digest { + return nil, fmt.Errorf("%s changed since it was listed; list the skills again", uri) + } + return data, nil } func escapePath(p string) string { diff --git a/internal/skillserve/catalog_test.go b/internal/skillserve/catalog_test.go index 6e2c3da29..2f33c29ab 100644 --- a/internal/skillserve/catalog_test.go +++ b/internal/skillserve/catalog_test.go @@ -258,6 +258,49 @@ func TestRead_ServesOnlyManifestFilesInsideTheSkill(t *testing.T) { } } +// Bytes that no longer match the listed digest would be rejected by a verifying client. +func TestRead_RefusesFileChangedSinceListed(t *testing.T) { + src := t.TempDir() + writeFile(t, filepath.Join(src, "doc/SKILL.md"), skillMD("doc")) + writeFile(t, filepath.Join(src, "doc/notes.md"), "one") + c, err := (&Builder{Source: src}).Build() + if err != nil { + t.Fatal(err) + } + writeFile(t, filepath.Join(src, "doc/notes.md"), "two") + + if _, err := c.Read("skill://doc/notes.md"); err == nil || !strings.Contains(err.Error(), "changed") { + t.Errorf("Read error = %v, want the file reported as changed", err) + } +} + +func TestBuild_ReadsFrontmatterAfterBOM(t *testing.T) { + src := t.TempDir() + writeFile(t, filepath.Join(src, "bom/SKILL.md"), "\ufeff"+skillMD("bom")) + + c, err := (&Builder{Source: src}).Build() + if err != nil { + t.Fatal(err) + } + if len(c.Skills) != 1 { + t.Errorf("skills=%v warnings=%v, want bom served", c.Skills, c.Skipped) + } +} + +func TestBuild_SkipsSkillWithNonStringCompatibilityOrOversizedSkillMD(t *testing.T) { + src := t.TempDir() + writeFile(t, filepath.Join(src, "list/SKILL.md"), "---\nname: list\ndescription: Use when testing\ncompatibility: [linux]\n---\n") + writeFile(t, filepath.Join(src, "huge/SKILL.md"), skillMD("huge")+strings.Repeat("x", skillpkg.MaxBytes)) + + c, err := (&Builder{Source: src}).Build() + if err != nil { + t.Fatal(err) + } + if len(c.Skills) != 0 || !hasWarning(c, "skipped list") || !hasWarning(c, "skipped huge: SKILL.md is over") { + t.Errorf("skills=%v warnings=%v, want list and huge skipped", c.Skills, c.Skipped) + } +} + func TestRead_ServesListedFileWithBackslashInName(t *testing.T) { if runtime.GOOS == "windows" { t.Skip("a backslash separates paths on Windows") diff --git a/internal/utils/frontmatter.go b/internal/utils/frontmatter.go index 96c00787b..b44d80c14 100644 --- a/internal/utils/frontmatter.go +++ b/internal/utils/frontmatter.go @@ -217,7 +217,8 @@ func extractFrontmatterRaw(filePath string) string { // 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) { - lines := strings.Split(string(bytes.TrimPrefix(content, []byte("\xef\xbb\xbf"))), "\n") + content = bytes.TrimPrefix(content, []byte("\xef\xbb\xbf")) + lines := strings.Split(string(content), "\n") if strings.TrimSpace(lines[0]) != "---" { return nil, fmt.Errorf("no frontmatter at the start") } From 78857ad6f147b2f3fd5d5e011a20474347a30190 Mon Sep 17 00:00:00 2001 From: Willie Date: Tue, 6 Oct 2026 15:16:35 +0800 Subject: [PATCH 11/26] fix(mcp): skip a linked SKILL.md and an indented opening delimiter The manifest lists no links, so a skill whose SKILL.md is a link was published without its own file and could not be read. It is now skipped with a warning. The Agent Skills reference parser requires the file to begin with --- exactly, so an indented delimiter no longer opens frontmatter. A CRLF file still parses. --- internal/skillpkg/skillpkg.go | 8 +++++-- internal/skillserve/catalog_test.go | 33 ++++++++++++++++++++++++----- internal/utils/frontmatter.go | 3 ++- 3 files changed, 36 insertions(+), 8 deletions(-) diff --git a/internal/skillpkg/skillpkg.go b/internal/skillpkg/skillpkg.go index 5c0e74068..b036e1198 100644 --- a/internal/skillpkg/skillpkg.go +++ b/internal/skillpkg/skillpkg.go @@ -41,11 +41,15 @@ type Package struct { func Load(dir string) (*Package, error) { dirName := filepath.Base(filepath.Clean(dir)) // a followed link's name, not its target's dir = utils.ResolveSymlink(dir) - // Stat first, so an oversized SKILL.md is skipped without reading it into memory. - info, err := os.Stat(filepath.Join(dir, "SKILL.md")) + // Lstat first: a linked SKILL.md would be missing from the manifest, which lists no + // links, and an oversized one is skipped without reading it into memory. + info, err := os.Lstat(filepath.Join(dir, "SKILL.md")) if err != nil { return nil, err } + if !info.Mode().IsRegular() { + return nil, fmt.Errorf("SKILL.md is not a regular file") + } if info.Size() > MaxBytes { return nil, fmt.Errorf("SKILL.md is over %d MiB", MaxBytes>>20) } diff --git a/internal/skillserve/catalog_test.go b/internal/skillserve/catalog_test.go index 2f33c29ab..5d846c171 100644 --- a/internal/skillserve/catalog_test.go +++ b/internal/skillserve/catalog_test.go @@ -156,13 +156,14 @@ func TestBuild_SkipsSkillWhoseFrontmatterIsNotAtTheStart(t *testing.T) { src := t.TempDir() writeFile(t, filepath.Join(src, "late/SKILL.md"), "# intro\n"+skillMD("late")) writeFile(t, filepath.Join(src, "open/SKILL.md"), "---\nname: open\ndescription: Use when testing open\n# open\n") + writeFile(t, filepath.Join(src, "indented/SKILL.md"), " "+skillMD("indented")) c, err := (&Builder{Source: src}).Build() if err != nil { t.Fatal(err) } - if len(c.Skills) != 0 || !hasWarning(c, "skipped late") || !hasWarning(c, "skipped open") { - t.Errorf("skills=%v warnings=%v, want late and unclosed open skipped", c.Skills, c.Skipped) + if len(c.Skills) != 0 || !hasWarning(c, "skipped late") || !hasWarning(c, "skipped open") || !hasWarning(c, "skipped indented") { + t.Errorf("skills=%v warnings=%v, want late, unclosed open and indented skipped", c.Skills, c.Skipped) } } @@ -274,16 +275,38 @@ func TestRead_RefusesFileChangedSinceListed(t *testing.T) { } } -func TestBuild_ReadsFrontmatterAfterBOM(t *testing.T) { +func TestBuild_ReadsFrontmatterAfterBOMOrWithCRLF(t *testing.T) { src := t.TempDir() writeFile(t, filepath.Join(src, "bom/SKILL.md"), "\ufeff"+skillMD("bom")) + writeFile(t, filepath.Join(src, "crlf/SKILL.md"), strings.ReplaceAll(skillMD("crlf"), "\n", "\r\n")) c, err := (&Builder{Source: src}).Build() if err != nil { t.Fatal(err) } - if len(c.Skills) != 1 { - t.Errorf("skills=%v warnings=%v, want bom served", c.Skills, c.Skipped) + if len(c.Skills) != 2 { + t.Errorf("skills=%v warnings=%v, want bom and crlf served", c.Skills, c.Skipped) + } +} + +// The walk lists no links, so a linked SKILL.md would leave the skill without its own file. +func TestBuild_SkipsSkillWhoseSkillMDIsALink(t *testing.T) { + src := t.TempDir() + target := filepath.Join(t.TempDir(), "SKILL.md") + writeFile(t, target, skillMD("linked")) + if err := os.MkdirAll(filepath.Join(src, "linked"), 0o755); err != nil { + t.Fatal(err) + } + if err := os.Symlink(target, filepath.Join(src, "linked/SKILL.md")); err != nil { + t.Skip("symlinks unavailable:", err) + } + + c, err := (&Builder{Source: src}).Build() + if err != nil { + t.Fatal(err) + } + if len(c.Skills) != 0 || !hasWarning(c, "skipped linked") { + t.Errorf("skills=%v warnings=%v, want linked skipped", c.Skills, c.Skipped) } } diff --git a/internal/utils/frontmatter.go b/internal/utils/frontmatter.go index b44d80c14..e39f51b4e 100644 --- a/internal/utils/frontmatter.go +++ b/internal/utils/frontmatter.go @@ -219,7 +219,8 @@ func extractFrontmatterRaw(filePath string) string { func ParseFrontmatterMap(content []byte) (map[string]any, error) { content = bytes.TrimPrefix(content, []byte("\xef\xbb\xbf")) lines := strings.Split(string(content), "\n") - if strings.TrimSpace(lines[0]) != "---" { + // Exactly ---: an indented delimiter does not open frontmatter. A CRLF file keeps its \r. + if strings.TrimSuffix(lines[0], "\r") != "---" { return nil, fmt.Errorf("no frontmatter at the start") } if !slices.ContainsFunc(lines[1:], func(l string) bool { return strings.TrimSpace(l) == "---" }) { From 2ac0926cce7d61da1104777fadc29185af43c2c6 Mon Sep 17 00:00:00 2001 From: Willie Date: Tue, 6 Oct 2026 15:25:33 +0800 Subject: [PATCH 12/26] fix(mcp): take a file's manifest size and digest from one read The size came from the directory walk and the digest from a later read, so a file replaced in between was listed with an old size and a new digest, which verifying clients reject. Both now come from the same read. --- internal/skillserve/catalog.go | 21 ++++++++++++++++++--- 1 file changed, 18 insertions(+), 3 deletions(-) diff --git a/internal/skillserve/catalog.go b/internal/skillserve/catalog.go index a469688ff..a74515824 100644 --- a/internal/skillserve/catalog.go +++ b/internal/skillserve/catalog.go @@ -18,7 +18,6 @@ import ( "skillshare/internal/skillpkg" "skillshare/internal/sourcewalk" ssync "skillshare/internal/sync" - "skillshare/internal/utils" ) // extensionID is the SEP-2640 capability key. @@ -144,17 +143,33 @@ func load(s ssync.DiscoveredSkill) (*Skill, map[string]servedFile, string) { skill := &Skill{URI: base + "/SKILL.md", Frontmatter: p.Frontmatter} files := make(map[string]servedFile, len(p.Files)) for _, f := range p.Files { - sum, err := utils.FileHashFormatted(f.Path) + sum, size, err := hashFile(f.Path) if err != nil { return nil, nil, err.Error() } uri := base + "/" + escapePath(f.Rel) files[uri] = servedFile{dir: p.Dir, rel: f.Rel, digest: sum} - skill.Resources = append(skill.Resources, File{URI: uri, Digest: sum, Size: f.Size}) + skill.Resources = append(skill.Resources, File{URI: uri, Digest: sum, Size: size}) } return skill, files, "" } +// hashFile returns the digest and size of one read of the file, so both describe +// the same bytes even when the file is replaced while the catalog is built. +func hashFile(path string) (string, int64, error) { + f, err := os.Open(path) + if err != nil { + return "", 0, err + } + defer f.Close() + h := sha256.New() + n, err := io.Copy(h, f) + if err != nil { + return "", 0, err + } + return fmt.Sprintf("sha256:%x", h.Sum(nil)), n, nil +} + // Skill returns the served skill whose SKILL.md URI is uri. func (c *Catalog) Skill(uri string) (*Skill, bool) { key, ok := canonical(uri) From 4f7f2d81515d9984195625578056723bd54d4875 Mon Sep 17 00:00:00 2001 From: Willie Date: Tue, 6 Oct 2026 15:32:06 +0800 Subject: [PATCH 13/26] fix(mcp): continue skills/list from a URI and cap the bytes hashed The cursor was an offset, so a catalog rebuilt between pages shifted the next page when a skill was added or removed ahead of it, repeating or dropping entries. Skills are now ordered by URI and the cursor is the last URI returned. Hashing now stops past the package's remaining size budget, so a file that grew after the walk is skipped rather than advertised over 16 MiB or hashed without bound. --- internal/skillserve/catalog.go | 18 +++++++++++++----- internal/skillserve/catalog_test.go | 9 +++++++++ internal/skillserve/server.go | 17 ++++++++++++----- internal/skillserve/server_test.go | 18 ++++++++++++++++++ 4 files changed, 52 insertions(+), 10 deletions(-) diff --git a/internal/skillserve/catalog.go b/internal/skillserve/catalog.go index a74515824..fc7eb2919 100644 --- a/internal/skillserve/catalog.go +++ b/internal/skillserve/catalog.go @@ -50,7 +50,7 @@ type Skip struct { func (s Skip) String() string { return fmt.Sprintf("skipped %s: %s", s.Path, s.Reason) } -// Catalog is one snapshot of the served skills, ordered by source path. +// Catalog is one snapshot of the served skills, ordered by URI; Skipped is in source path order. type Catalog struct { Skills []*Skill Skipped []Skip @@ -128,6 +128,8 @@ func (b *Builder) Build() (*Catalog, error) { c.bySkill[l.skill.URI] = l.skill maps.Copy(c.byFile, l.files) } + // By URI, which skills/list cursors continue from. + slices.SortFunc(c.Skills, func(x, y *Skill) int { return strings.Compare(x.URI, y.URI) }) return c, nil } @@ -142,11 +144,13 @@ func load(s ssync.DiscoveredSkill) (*Skill, map[string]servedFile, string) { base := "skill://" + escapePath(s.RelPath) skill := &Skill{URI: base + "/SKILL.md", Frontmatter: p.Frontmatter} files := make(map[string]servedFile, len(p.Files)) + left := int64(skillpkg.MaxBytes) // the walk checked sizes too, but files can grow since for _, f := range p.Files { - sum, size, err := hashFile(f.Path) + sum, size, err := hashFile(f.Path, left) if err != nil { return nil, nil, err.Error() } + left -= size uri := base + "/" + escapePath(f.Rel) files[uri] = servedFile{dir: p.Dir, rel: f.Rel, digest: sum} skill.Resources = append(skill.Resources, File{URI: uri, Digest: sum, Size: size}) @@ -155,18 +159,22 @@ func load(s ssync.DiscoveredSkill) (*Skill, map[string]servedFile, string) { } // hashFile returns the digest and size of one read of the file, so both describe -// the same bytes even when the file is replaced while the catalog is built. -func hashFile(path string) (string, int64, error) { +// the same bytes even when the file is replaced while the catalog is built. It +// stops past limit bytes, so a file that grew cannot stall the build. +func hashFile(path string, limit int64) (string, int64, error) { f, err := os.Open(path) if err != nil { return "", 0, err } defer f.Close() h := sha256.New() - n, err := io.Copy(h, f) + n, err := io.Copy(h, io.LimitReader(f, limit+1)) if err != nil { return "", 0, err } + if n > limit { + return "", 0, fmt.Errorf("is larger than %d MiB", skillpkg.MaxBytes>>20) + } return fmt.Sprintf("sha256:%x", h.Sum(nil)), n, nil } diff --git a/internal/skillserve/catalog_test.go b/internal/skillserve/catalog_test.go index 5d846c171..1b44d2c8c 100644 --- a/internal/skillserve/catalog_test.go +++ b/internal/skillserve/catalog_test.go @@ -184,6 +184,15 @@ func TestBuild_SkipsSkillWhoseDescriptionOrCompatibilityIsTooLong(t *testing.T) } } +// The size limit holds for the bytes hashed, not only the sizes the walk saw. +func TestHashFile_StopsPastTheSizeLimit(t *testing.T) { + path := filepath.Join(t.TempDir(), "big.bin") + writeFile(t, path, strings.Repeat("x", skillpkg.MaxBytes+1)) + if _, _, err := hashFile(path, skillpkg.MaxBytes); err == nil { + t.Error("hashFile succeeded past the limit, want an error") + } +} + func TestBuild_SkipsSkillOverFileLimit(t *testing.T) { src := t.TempDir() writeFile(t, filepath.Join(src, "big/SKILL.md"), skillMD("big")) diff --git a/internal/skillserve/server.go b/internal/skillserve/server.go index 2366093d9..918c411d8 100644 --- a/internal/skillserve/server.go +++ b/internal/skillserve/server.go @@ -9,7 +9,8 @@ import ( "mime" "net/http" "path" - "strconv" + "slices" + "strings" "sync" "time" "unicode/utf8" @@ -151,18 +152,24 @@ func (s *service) list(_ context.Context, _ *mcp.ServerSession, p *listSkillsPar if err != nil { return nil, err } + // The cursor is the last URI returned, not an offset: the catalog may be rebuilt + // between pages, and skills added or removed before it must not shift the next page. start := 0 if p != nil && p.Cursor != "" { - n, err := strconv.Atoi(p.Cursor) - if err != nil || n < 0 || n > len(c.Skills) { + if !strings.HasPrefix(p.Cursor, "skill://") { return nil, invalidParams("invalid cursor") } - start = n + start, _ = slices.BinarySearchFunc(c.Skills, p.Cursor, func(s *Skill, uri string) int { + if s.URI <= uri { + return -1 + } + return 1 + }) } end := min(start+pageSize, len(c.Skills)) res := &listSkillsResult{Cacheable: s.cacheable(), ResultType: "complete", Skills: c.Skills[start:end]} if end < len(c.Skills) { - res.NextCursor = strconv.Itoa(end) + res.NextCursor = c.Skills[end-1].URI } return res, nil } diff --git a/internal/skillserve/server_test.go b/internal/skillserve/server_test.go index 3d536276b..07eda4cab 100644 --- a/internal/skillserve/server_test.go +++ b/internal/skillserve/server_test.go @@ -83,6 +83,24 @@ func TestServer_ListPaginatesWholeEntries(t *testing.T) { } } +// The catalog may be rebuilt between pages; a skill added ahead of the cursor +// must not shift the next page onto entries already returned. +func TestServer_ListContinuesAfterTheLastSkillReturned(t *testing.T) { + src := t.TempDir() + for i := range pageSize + 1 { + name := fmt.Sprintf("s%03d", i) + writeFile(t, filepath.Join(src, name, "SKILL.md"), skillMD(name)) + } + cs := connect(t, src) // Refresh 0: every call rebuilds + + first := listSkills(t, cs, "") + writeFile(t, filepath.Join(src, "a000", "SKILL.md"), skillMD("a000")) + second := listSkills(t, cs, first.NextCursor) + if len(second.Skills) != 1 || second.Skills[0].URI != "skill://s100/SKILL.md" { + t.Errorf("second page = %v, want only skill://s100/SKILL.md", second.Skills) + } +} + func TestServer_GetUnknownSkillIsInvalidParams(t *testing.T) { cs := connect(t, t.TempDir()) _, err := mcp.CallCustomMethod[*getSkillParams, *getSkillResult](context.Background(), cs, methodGet, &getSkillParams{URI: "skill://missing/SKILL.md"}) From 6285e490e656431e7089ff61482e3963889184bb Mon Sep 17 00:00:00 2001 From: Willie Date: Tue, 6 Oct 2026 15:39:06 +0800 Subject: [PATCH 14/26] fix(mcp): reject an empty compatibility The Agent Skills format requires a compatibility value, when present, to hold 1 to 500 characters, so an empty one is skipped like an overlong one. --- internal/skillpkg/skillpkg.go | 4 ++-- internal/skillserve/catalog_test.go | 3 ++- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/internal/skillpkg/skillpkg.go b/internal/skillpkg/skillpkg.go index b036e1198..948e53879 100644 --- a/internal/skillpkg/skillpkg.go +++ b/internal/skillpkg/skillpkg.go @@ -75,8 +75,8 @@ func Load(dir string) (*Package, error) { // metadata is left unchecked: the format wants string values, but lists there are // common and tool clients read them fine, so skipping those skills would cost more. compat, ok := fm["compatibility"].(string) - if _, set := fm["compatibility"]; set && !ok { - return nil, fmt.Errorf("compatibility must be text") + if _, set := fm["compatibility"]; set && (!ok || compat == "") { + return nil, fmt.Errorf("compatibility must be non-empty text") } if n := utf8.RuneCountInString(compat); n > MaxCompatibility { return nil, fmt.Errorf("compatibility has %d characters; the limit is %d", n, MaxCompatibility) diff --git a/internal/skillserve/catalog_test.go b/internal/skillserve/catalog_test.go index 1b44d2c8c..e2d9e6a52 100644 --- a/internal/skillserve/catalog_test.go +++ b/internal/skillserve/catalog_test.go @@ -174,12 +174,13 @@ func TestBuild_SkipsSkillWhoseDescriptionOrCompatibilityIsTooLong(t *testing.T) writeFile(t, filepath.Join(src, "long/SKILL.md"), skill("long", strings.Repeat("a", 1025))) writeFile(t, filepath.Join(src, "wide/SKILL.md"), skill("wide", strings.Repeat("技", 1024))) writeFile(t, filepath.Join(src, "compat/SKILL.md"), "---\nname: compat\ndescription: Use when testing\ncompatibility: "+strings.Repeat("a", 501)+"\n---\n") + writeFile(t, filepath.Join(src, "blank/SKILL.md"), "---\nname: blank\ndescription: Use when testing\ncompatibility: \"\"\n---\n") c, err := (&Builder{Source: src}).Build() if err != nil { t.Fatal(err) } - if len(c.Skills) != 1 || c.Skills[0].URI != "skill://wide/SKILL.md" || !hasWarning(c, "skipped long") || !hasWarning(c, "skipped compat") { + if len(c.Skills) != 1 || c.Skills[0].URI != "skill://wide/SKILL.md" || !hasWarning(c, "skipped long") || !hasWarning(c, "skipped compat") || !hasWarning(c, "skipped blank") { t.Errorf("skills=%v warnings=%v, want long and compat skipped, wide served", c.Skills, c.Skipped) } } From 97844aa7f8724b292b1d4e21a6278d164b9374aa Mon Sep 17 00:00:00 2001 From: Willie Date: Tue, 6 Oct 2026 15:46:48 +0800 Subject: [PATCH 15/26] fix(mcp): hash SKILL.md from the bytes its frontmatter came from SKILL.md was parsed, then read again to hash, so a save in between paired old frontmatter with the new file's digest and size, and hosts that compare frontmatter against the file rejected the skill. The digest now comes from the parsed bytes; a later read of a changed file is refused until the next refresh. --- internal/skillpkg/skillpkg.go | 3 ++- internal/skillserve/catalog.go | 10 +++++++--- 2 files changed, 9 insertions(+), 4 deletions(-) diff --git a/internal/skillpkg/skillpkg.go b/internal/skillpkg/skillpkg.go index 948e53879..120492b11 100644 --- a/internal/skillpkg/skillpkg.go +++ b/internal/skillpkg/skillpkg.go @@ -33,6 +33,7 @@ type File struct { type Package struct { Dir string // resolved Frontmatter map[string]any + SkillMD []byte // the bytes Frontmatter was parsed from Files []File } @@ -82,7 +83,7 @@ func Load(dir string) (*Package, error) { return nil, fmt.Errorf("compatibility has %d characters; the limit is %d", n, MaxCompatibility) } - p := &Package{Dir: dir, Frontmatter: fm} + p := &Package{Dir: dir, Frontmatter: fm, SkillMD: content} var total int64 err = sourcewalk.Walk(dir, sourcewalk.Options{}, func(path string, info os.FileInfo, err error) error { if err != nil { diff --git a/internal/skillserve/catalog.go b/internal/skillserve/catalog.go index fc7eb2919..24b3fc585 100644 --- a/internal/skillserve/catalog.go +++ b/internal/skillserve/catalog.go @@ -146,9 +146,13 @@ func load(s ssync.DiscoveredSkill) (*Skill, map[string]servedFile, string) { files := make(map[string]servedFile, len(p.Files)) left := int64(skillpkg.MaxBytes) // the walk checked sizes too, but files can grow since for _, f := range p.Files { - sum, size, err := hashFile(f.Path, left) - if err != nil { - return nil, nil, err.Error() + // SKILL.md is hashed from the bytes its frontmatter came from, so the entry + // never pairs old frontmatter with a newer file's digest. + sum, size := fmt.Sprintf("sha256:%x", sha256.Sum256(p.SkillMD)), int64(len(p.SkillMD)) + if f.Rel != "SKILL.md" { + if sum, size, err = hashFile(f.Path, left); err != nil { + return nil, nil, err.Error() + } } left -= size uri := base + "/" + escapePath(f.Rel) From a8edbc715f45f308a90fe93d5033d6fe563dd05b Mon Sep 17 00:00:00 2001 From: Willie Date: Tue, 6 Oct 2026 15:57:02 +0800 Subject: [PATCH 16/26] fix(mcp): follow the reference validator for names and bound SKILL.md reads MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Agent Skills reference validator accepts lowercase Unicode letters and digits after NFKC normalization and counts the 64-character limit in characters, so names such as 技能-審查 or café were skipped although they are valid. ValidateName now applies the same rules. sync's target naming shares it and accepts those names too. golang.org/x/text becomes a direct dependency at the version already in the module graph. SKILL.md was size-checked and then read whole, so a file that grew in between was still read into memory; the read itself now stops past 16 MiB. --- go.mod | 2 +- internal/skillpkg/skillpkg.go | 46 +++++++++++++++++++++-------- internal/skillserve/catalog_test.go | 18 +++++++++++ 3 files changed, 52 insertions(+), 14 deletions(-) diff --git a/go.mod b/go.mod index 635b4f01e..c455a99c9 100644 --- a/go.mod +++ b/go.mod @@ -20,6 +20,7 @@ require ( github.com/yuin/goldmark v1.7.8 golang.org/x/sys v0.41.0 golang.org/x/term v0.32.0 + golang.org/x/text v0.26.0 gopkg.in/yaml.v3 v3.0.1 ) @@ -67,6 +68,5 @@ require ( golang.org/x/net v0.33.0 // indirect golang.org/x/oauth2 v0.35.0 // indirect golang.org/x/sync v0.20.0 // indirect - golang.org/x/text v0.26.0 // indirect golang.org/x/time v0.15.0 // indirect ) diff --git a/internal/skillpkg/skillpkg.go b/internal/skillpkg/skillpkg.go index 120492b11..915007918 100644 --- a/internal/skillpkg/skillpkg.go +++ b/internal/skillpkg/skillpkg.go @@ -5,11 +5,15 @@ package skillpkg import ( "fmt" + "io" "os" "path/filepath" "strings" + "unicode" "unicode/utf8" + "golang.org/x/text/unicode/norm" + "skillshare/internal/sourcewalk" "skillshare/internal/utils" ) @@ -42,8 +46,7 @@ type Package struct { func Load(dir string) (*Package, error) { dirName := filepath.Base(filepath.Clean(dir)) // a followed link's name, not its target's dir = utils.ResolveSymlink(dir) - // Lstat first: a linked SKILL.md would be missing from the manifest, which lists no - // links, and an oversized one is skipped without reading it into memory. + // A linked SKILL.md would be missing from the manifest, which lists no links. info, err := os.Lstat(filepath.Join(dir, "SKILL.md")) if err != nil { return nil, err @@ -51,10 +54,8 @@ func Load(dir string) (*Package, error) { if !info.Mode().IsRegular() { return nil, fmt.Errorf("SKILL.md is not a regular file") } - if info.Size() > MaxBytes { - return nil, fmt.Errorf("SKILL.md is over %d MiB", MaxBytes>>20) - } - content, err := os.ReadFile(filepath.Join(dir, "SKILL.md")) + // The read itself is bounded: the file can grow after the Lstat. + content, err := readAtMost(filepath.Join(dir, "SKILL.md"), MaxBytes) if err != nil { return nil, err } @@ -117,13 +118,33 @@ func Load(dir string) (*Package, error) { return p, nil } +// readAtMost reads the file, failing once it holds more than limit bytes. +func readAtMost(path string, limit int64) ([]byte, error) { + f, err := os.Open(path) + if err != nil { + return nil, err + } + defer f.Close() + data, err := io.ReadAll(io.LimitReader(f, limit+1)) + if err != nil { + return nil, err + } + if int64(len(data)) > limit { + return nil, fmt.Errorf("SKILL.md is over %d MiB", limit>>20) + } + return data, nil +} + // ValidateName returns why a SKILL.md name breaks the Agent Skills naming rules -// (including name == directory name), or "" when it follows them. +// (including name == directory name), or "" when it follows them. Like the +// reference validator, it takes lowercase Unicode letters and digits after NFKC +// normalization and counts the limit in characters. func ValidateName(name, dirName string) string { + name = norm.NFKC.String(strings.TrimSpace(name)) if name == "" { return "SKILL.md is missing a name" } - if len(name) > 64 { + if utf8.RuneCountInString(name) > 64 { return fmt.Sprintf("SKILL.md name %q is longer than 64 characters", name) } if strings.HasPrefix(name, "-") || strings.HasSuffix(name, "-") { @@ -132,13 +153,12 @@ func ValidateName(name, dirName string) string { if strings.Contains(name, "--") { return fmt.Sprintf("SKILL.md name %q cannot contain consecutive hyphens", name) } - for _, r := range name { - if (r >= 'a' && r <= 'z') || (r >= '0' && r <= '9') || r == '-' { - continue - } + if name != strings.ToLower(name) || strings.ContainsFunc(name, func(r rune) bool { + return r != '-' && !unicode.IsLetter(r) && !unicode.IsNumber(r) + }) { return fmt.Sprintf("SKILL.md name %q must use only lowercase letters, numbers, and hyphens", name) } - if name != dirName { + if name != norm.NFKC.String(dirName) { return fmt.Sprintf("SKILL.md name %q does not match directory name %q", name, dirName) } return "" diff --git a/internal/skillserve/catalog_test.go b/internal/skillserve/catalog_test.go index e2d9e6a52..263d1605e 100644 --- a/internal/skillserve/catalog_test.go +++ b/internal/skillserve/catalog_test.go @@ -194,6 +194,24 @@ func TestHashFile_StopsPastTheSizeLimit(t *testing.T) { } } +// The Agent Skills reference validator takes lowercase Unicode letters and digits, +// after NFKC normalization, and counts the 64-character limit in characters. +func TestBuild_AcceptsLowercaseUnicodeNames(t *testing.T) { + src := t.TempDir() + writeFile(t, filepath.Join(src, "技能-審查/SKILL.md"), skillMD("技能-審查")) + writeFile(t, filepath.Join(src, "café/SKILL.md"), skillMD("café")) + writeFile(t, filepath.Join(src, "Été/SKILL.md"), skillMD("Été")) + writeFile(t, filepath.Join(src, "a_b/SKILL.md"), skillMD("a_b")) + + c, err := (&Builder{Source: src}).Build() + if err != nil { + t.Fatal(err) + } + if len(c.Skills) != 2 || !hasWarning(c, "skipped Été") || !hasWarning(c, "skipped a_b") { + t.Errorf("skills=%v warnings=%v, want 技能-審查 and café served, Été and a_b skipped", c.Skills, c.Skipped) + } +} + func TestBuild_SkipsSkillOverFileLimit(t *testing.T) { src := t.TempDir() writeFile(t, filepath.Join(src, "big/SKILL.md"), skillMD("big")) From 2647e79ef9815a5206e229722ed4ba31daf80e50 Mon Sep 17 00:00:00 2001 From: Willie Date: Tue, 6 Oct 2026 16:08:44 +0800 Subject: [PATCH 17/26] feat(mcp): require HTTPS for mcp serve off loopback A non-loopback --http listener accepted a bearer token over plain HTTP, so anyone on the path could read the token and the skills. Off loopback it now also needs --tls-cert and --tls-key and serves HTTPS; loopback stays plain, so a TLS-terminating proxy in front still works. --- ai_docs/tests/mcp_serve_runbook.md | 13 ++++ cmd/skillshare/completion_bash.go | 2 +- cmd/skillshare/completion_fish.go | 2 + cmd/skillshare/completion_nushell.go | 2 + cmd/skillshare/completion_powershell.go | 2 +- cmd/skillshare/completion_zsh.go | 2 + cmd/skillshare/mcp.go | 2 +- cmd/skillshare/mcp_serve.go | 41 +++++++++---- skills/skillshare/references/mcp.md | 4 +- tests/integration/mcp_serve_test.go | 79 +++++++++++++++++++++++++ website/docs/reference/commands/mcp.md | 16 +++-- 11 files changed, 141 insertions(+), 24 deletions(-) diff --git a/ai_docs/tests/mcp_serve_runbook.md b/ai_docs/tests/mcp_serve_runbook.md index 927cfaa1c..cd01ae74a 100644 --- a/ai_docs/tests/mcp_serve_runbook.md +++ b/ai_docs/tests/mcp_serve_runbook.md @@ -14,6 +14,7 @@ Validates the read-only SEP-2640 skills server over stdio and Streamable HTTP. - `resources/read` returns a listed file and rejects a URI that escapes the skill - Over HTTP: bearer token required, a newly added skill appears without a restart - A non-loopback `--http` address without `SKILLSHARE_MCP_TOKEN` is refused +- A non-loopback `--http` address with a token but no `--tls-cert`/`--tls-key` is refused ## Environment @@ -172,6 +173,18 @@ Expected: - exit_code: 1 - SKILLSHARE_MCP_TOKEN +### Step 8: A network listener without TLS is refused + +```bash +cd "$HOME" +export SKILLSHARE_CONFIG="$HOME/mcp-serve/config.yaml" +SKILLSHARE_MCP_TOKEN=change-me ss mcp serve -g --http 0.0.0.0:47943 +``` + +Expected: +- exit_code: 1 +- --tls-cert + ## Pass Criteria - All steps marked PASS diff --git a/cmd/skillshare/completion_bash.go b/cmd/skillshare/completion_bash.go index 8962acb07..989bd7bde 100644 --- a/cmd/skillshare/completion_bash.go +++ b/cmd/skillshare/completion_bash.go @@ -38,7 +38,7 @@ _skillshare() { local unlink_flags="--help -h" local list_flags="--verbose -v --json -j --no-tui --type -t --status --sort -s --all --help -h" local sync_flags="--all --dry-run -n --force -f --json --quiet -q --help -h" - local mcp_flags="--tools-allow --tools-deny --pi-options --url --target --from --file --sync --replace --disabled --keep-files --revision --dry-run -n --json --no-tui --no-dns --live --timeout --http --check --help -h" + local mcp_flags="--tools-allow --tools-deny --pi-options --url --target --from --file --sync --replace --disabled --keep-files --revision --dry-run -n --json --no-tui --no-dns --live --timeout --http --tls-cert --tls-key --check --help -h" local status_flags="--json --help -h" local hooks_flags="--file --from --sync --replace --keep-files --revision --dry-run -n --json --help -h" local diff_flags="--no-tui --patch --stat --json --help -h" diff --git a/cmd/skillshare/completion_fish.go b/cmd/skillshare/completion_fish.go index 196f75b2d..7cdedb202 100644 --- a/cmd/skillshare/completion_fish.go +++ b/cmd/skillshare/completion_fish.go @@ -53,6 +53,8 @@ complete -c skillshare -n '__fish_skillshare_using_command mcp' -l no-dns -d 'Sk complete -c skillshare -n '__fish_skillshare_using_command mcp' -l live -d 'check: start or call each server' complete -c skillshare -n '__fish_skillshare_using_command mcp' -l timeout -r -d 'check --live: per-server timeout' complete -c skillshare -n '__fish_skillshare_using_command mcp' -l http -r -d 'serve: Streamable HTTP listen address' +complete -c skillshare -n '__fish_skillshare_using_command mcp' -l tls-cert -r -F -d 'serve --http: TLS certificate file' +complete -c skillshare -n '__fish_skillshare_using_command mcp' -l tls-key -r -F -d 'serve --http: TLS key file' complete -c skillshare -n '__fish_skillshare_using_command mcp' -l check -d 'serve: list skipped skills without serving' complete -c skillshare -n '__fish_skillshare_using_command mcp' -l url -r -d 'MCP endpoint' complete -c skillshare -n '__fish_skillshare_using_command mcp' -l target -r -a 'claude codex cursor vscode opencode kilocode grok antigravity amp claude-desktop cline copilot factory gemini goose junie kiro lmstudio warp windsurf pi omp' -d 'Receiving client' diff --git a/cmd/skillshare/completion_nushell.go b/cmd/skillshare/completion_nushell.go index bb07a9257..e0f0b4ba4 100644 --- a/cmd/skillshare/completion_nushell.go +++ b/cmd/skillshare/completion_nushell.go @@ -90,6 +90,8 @@ export extern "skillshare mcp" [ --live # check: start or call each server --timeout: string # check --live: per-server timeout, such as 10s --http: string # serve: Streamable HTTP listen address + --tls-cert: string # serve --http: TLS certificate file + --tls-key: string # serve --http: TLS key file --check # serve: list skipped skills without serving --no-tui --project(-p) diff --git a/cmd/skillshare/completion_powershell.go b/cmd/skillshare/completion_powershell.go index 8deca7e78..350ae5029 100644 --- a/cmd/skillshare/completion_powershell.go +++ b/cmd/skillshare/completion_powershell.go @@ -208,7 +208,7 @@ $_skillshareCompleter = { 'enable' = '--dry-run', '-n', '--kind', '--help', '-h', '--project', '-p', '--global', '-g' 'disable' = '--dry-run', '-n', '--kind', '--help', '-h', '--project', '-p', '--global', '-g' 'analyze' = '--verbose', '-v', '--filter', '--no-tui', '--json', '--help', '-h', '--project', '-p', '--global', '-g' - 'mcp' = '--tools-allow', '--tools-deny', '--pi-options', '--target', '--from', '--url', '--file', '--sync', '--replace', '--disabled', '--keep-files', '--revision', '--dry-run', '-n', '--json', '--no-dns', '--live', '--timeout', '--http', '--check', '--no-tui', '--help', '-h', '--project', '-p', '--global', '-g' + 'mcp' = '--tools-allow', '--tools-deny', '--pi-options', '--target', '--from', '--url', '--file', '--sync', '--replace', '--disabled', '--keep-files', '--revision', '--dry-run', '-n', '--json', '--no-dns', '--live', '--timeout', '--http', '--tls-cert', '--tls-key', '--check', '--no-tui', '--help', '-h', '--project', '-p', '--global', '-g' 'plugin' = '--target', '--from', '--plugin', '--name', '--source-ref', '--entry', '--revision', '--dry-run', '-n', '--json', '--no-tui', '--help', '-h', '--project', '-p', '--global', '-g' 'extras memory' = '--from', '--version', '--search', '--update-mode', '--json', '--help', '-h', '--project', '-p', '--global', '-g' 'extras' = '--mode', '--target', '--source', '--file', '--as', '--flatten', '--no-flatten', '--add-target', '--remove-target', '--prune', '--from', '--dry-run', '--force', '-f', '--json', '--no-tui', '--help', '-h', '--project', '-p', '--global', '-g' diff --git a/cmd/skillshare/completion_zsh.go b/cmd/skillshare/completion_zsh.go index dd5bc1a7a..2ffd10e26 100644 --- a/cmd/skillshare/completion_zsh.go +++ b/cmd/skillshare/completion_zsh.go @@ -116,6 +116,8 @@ _skillshare() { '--live[check: start or call each server]' \ '--timeout[check --live: per-server timeout]:duration:' \ '--http[serve: Streamable HTTP listen address]:address:' \ + '--tls-cert[serve --http: TLS certificate file]:file:_files' \ + '--tls-key[serve --http: TLS key file]:file:_files' \ '--check[serve: list skipped skills without serving]' \ '--no-tui[Disable interactive menus]' \ $global_flags \ diff --git a/cmd/skillshare/mcp.go b/cmd/skillshare/mcp.go index 19239b7a2..bee71c34c 100644 --- a/cmd/skillshare/mcp.go +++ b/cmd/skillshare/mcp.go @@ -390,7 +390,7 @@ func printMCPHelp() { {"check [name...]", "Verify variables, commands, hosts and sync state (--no-dns);\n--live also starts or calls each server [--timeout 10s]"}, {"remove [name]", "Select and remove a source entry; optionally sync removal,\nor stop managing it and keep its Agent entries (--keep-files)"}, {"restore [id]", "Browse backups, preview and restore Agent entries"}, - {"serve", "Serve skills read-only over MCP (SEP-2640) on stdio, or\n--http [--target ]; global unless -p;\n--check lists skipped skills without serving"}, + {"serve", "Serve skills read-only over MCP (SEP-2640) on stdio, or\n--http [--tls-cert --tls-key ] [--target ];\nglobal unless -p; --check lists skipped skills without serving"}, }}, helpGroup{title: "Options", rows: []helpRow{ {"--target ", "Receiving client; repeat for several, or none to keep the\nserver in Skillshare without writing it to any Agent"}, diff --git a/cmd/skillshare/mcp_serve.go b/cmd/skillshare/mcp_serve.go index 7ea654e52..98bd5ae46 100644 --- a/cmd/skillshare/mcp_serve.go +++ b/cmd/skillshare/mcp_serve.go @@ -19,7 +19,7 @@ import ( "skillshare/internal/ui" ) -const mcpServeUsage = "skillshare mcp serve [--target ] [--http | --check] [-g|-p]" +const mcpServeUsage = "skillshare mcp serve [--target ] [--http [--tls-cert --tls-key ] | --check] [-g|-p]" // mcpServeTokenEnv holds the bearer token HTTP clients must send. const mcpServeTokenEnv = "SKILLSHARE_MCP_TOKEN" @@ -27,33 +27,36 @@ const mcpServeTokenEnv = "SKILLSHARE_MCP_TOKEN" // cmdMCPServe serves the managed skills over MCP (SEP-2640). It never writes: // stdout carries the protocol, so diagnostics go to stderr. func cmdMCPServe(args []string) error { - mode, rest, err := parseModeArgs(args, "--target", "--http") + mode, rest, err := parseModeArgs(args, "--target", "--http", "--tls-cert", "--tls-key") if err != nil { return err } - var target, addr string + values := map[string]string{} check := false for i := 0; i < len(rest); i++ { switch a := rest[i]; a { case "--check": check = true - case "--target", "--http": + case "--target", "--http", "--tls-cert", "--tls-key": if i+1 == len(rest) { return fmt.Errorf("%s requires a value", a) } i++ - if a == "--target" { - target = rest[i] - } else { - addr = rest[i] - } + values[a] = rest[i] default: return fmt.Errorf("unknown mcp serve argument %q; usage: %s", a, mcpServeUsage) } } + target, addr, certFile, keyFile := values["--target"], values["--http"], values["--tls-cert"], values["--tls-key"] if check && addr != "" { return fmt.Errorf("--check starts no server; drop --http") } + if (certFile == "") != (keyFile == "") { + return fmt.Errorf("--tls-cert and --tls-key go together") + } + if certFile != "" && addr == "" { + return fmt.Errorf("--tls-cert and --tls-key need --http") + } // A gateway chooses the working directory, so only -p selects project mode. b := &skillserve.Builder{Target: target} @@ -90,9 +93,15 @@ func cmdMCPServe(args []string) error { return printMCPServeCheck(b) } + // Off loopback, the token must exist and must not cross the network in plain text. token := os.Getenv(mcpServeTokenEnv) - if addr != "" && token == "" && !isLoopbackAddr(addr) { - return fmt.Errorf("refusing to serve on %s without authentication: set %s, or bind a loopback address such as 127.0.0.1:8765", addr, mcpServeTokenEnv) + if addr != "" && !isLoopbackAddr(addr) { + if token == "" { + return fmt.Errorf("refusing to serve on %s without authentication: set %s, or bind a loopback address such as 127.0.0.1:8765", addr, mcpServeTokenEnv) + } + if certFile == "" { + return fmt.Errorf("refusing to send %s over plain HTTP on %s: pass --tls-cert and --tls-key, or bind a loopback address behind a TLS proxy", mcpServeTokenEnv, addr) + } } srv, err := skillserve.NewServer(b, skillserve.Options{Version: version, Warn: os.Stderr, Refresh: 5 * time.Second}) @@ -118,8 +127,14 @@ func cmdMCPServe(args []string) error { <-ctx.Done() httpSrv.Close() }() - fmt.Fprintf(os.Stderr, "Serving skills over MCP at http://%s/\n", ln.Addr()) - if err := httpSrv.Serve(ln); !errors.Is(err, http.ErrServerClosed) { + if certFile == "" { + fmt.Fprintf(os.Stderr, "Serving skills over MCP at http://%s/\n", ln.Addr()) + err = httpSrv.Serve(ln) + } else { + fmt.Fprintf(os.Stderr, "Serving skills over MCP at https://%s/\n", ln.Addr()) + err = httpSrv.ServeTLS(ln, certFile, keyFile) + } + if !errors.Is(err, http.ErrServerClosed) { return err } return nil diff --git a/skills/skillshare/references/mcp.md b/skills/skillshare/references/mcp.md index 6b36810e4..bef37acff 100644 --- a/skills/skillshare/references/mcp.md +++ b/skills/skillshare/references/mcp.md @@ -22,7 +22,7 @@ skillshare mcp restore BACKUP_ID --dry-run --json # Preview entry-level rest skillshare mcp restore BACKUP_ID --no-tui # Apply restoration; source stays unchanged skillshare mcp check --json # Static check: variables, commands, DNS, sync state skillshare mcp check --live --timeout 30s --json # Also start/call each server: serverInfo, protocol, tools -skillshare mcp serve [--target NAME] [--http ADDR] # Serve skills read-only over MCP (SEP-2640) +skillshare mcp serve [--target NAME] [--http ADDR [--tls-cert F --tls-key F]] # Serve skills read-only over MCP (SEP-2640) skillshare mcp serve --check [--target NAME] # List skills serve would skip, then exit ``` @@ -56,7 +56,7 @@ skillshare mcp serve --check [--target NAME] # List skills serve would s gateways): stdio by default, global unless `-p`. `--target NAME` applies that target's filters. Skipped skills (name not matching its directory, description missing or over 1,024 characters, compatibility over 500, over 512 files/16 MiB) are - listed on stderr; `--check` lists them without serving. `--http` on a non-loopback address requires `SKILLSHARE_MCP_TOKEN`. + listed on stderr; `--check` lists them without serving. `--http` on a non-loopback address requires `SKILLSHARE_MCP_TOKEN` and `--tls-cert`/`--tls-key` (or bind loopback behind a TLS proxy). Do not connect local Agents that already sync skills; they would see each skill twice. Connect one with `mcp add skillshare --target CLIENT --sync -- skillshare mcp serve`, or a remote `url` with `bearerToken: {fromEnv: SKILLSHARE_MCP_TOKEN}`. Agents with the Skills diff --git a/tests/integration/mcp_serve_test.go b/tests/integration/mcp_serve_test.go index 495152adb..a9e62fab2 100644 --- a/tests/integration/mcp_serve_test.go +++ b/tests/integration/mcp_serve_test.go @@ -5,12 +5,20 @@ package integration import ( "bufio" "bytes" + "crypto/ecdsa" + "crypto/elliptic" + "crypto/rand" + "crypto/x509" + "crypto/x509/pkix" + "encoding/pem" "fmt" + "math/big" "os" "os/exec" "path/filepath" "strings" "testing" + "time" "skillshare/internal/testutil" ) @@ -94,6 +102,77 @@ func TestMCPServe_RefusesUnauthenticatedNetworkListener(t *testing.T) { r.AssertAnyOutputContains(t, "SKILLSHARE_MCP_TOKEN") } +// A token sent over plain HTTP off loopback can be read by anyone on the path. +func TestMCPServe_RefusesPlainHTTPNetworkListener(t *testing.T) { + sb := testutil.NewSandbox(t) + defer sb.Cleanup() + sb.WriteConfig("source: " + sb.SourcePath + "\ntargets: {}\n") + + r := sb.RunCLIEnv(map[string]string{"SKILLSHARE_MCP_TOKEN": "secret"}, "mcp", "serve", "--http", "0.0.0.0:0") + + r.AssertFailure(t) + r.AssertAnyOutputContains(t, "--tls-cert") +} + +func TestMCPServe_RequiresBothTLSFiles(t *testing.T) { + sb := testutil.NewSandbox(t) + defer sb.Cleanup() + sb.WriteConfig("source: " + sb.SourcePath + "\ntargets: {}\n") + + r := sb.RunCLI("mcp", "serve", "--http", "127.0.0.1:0", "--tls-cert", "cert.pem") + + r.AssertFailure(t) + r.AssertAnyOutputContains(t, "--tls-cert and --tls-key go together") +} + +func TestMCPServe_ServesHTTPSOffLoopbackWithTokenAndCertificate(t *testing.T) { + sb := testutil.NewSandbox(t) + defer sb.Cleanup() + sb.WriteConfig("source: " + sb.SourcePath + "\ntargets: {}\n") + certFile, keyFile := writeSelfSignedCert(t) + + cmd := exec.Command(sb.BinaryPath, "mcp", "serve", "--http", "0.0.0.0:0", "--tls-cert", certFile, "--tls-key", keyFile) + cmd.Env = append(os.Environ(), "HOME="+sb.Home, "SKILLSHARE_CONFIG="+sb.ConfigPath, "SKILLSHARE_MCP_TOKEN=secret") + stderr, err := cmd.StderrPipe() + if err != nil { + t.Fatal(err) + } + if err := cmd.Start(); err != nil { + t.Fatal(err) + } + defer func() { _ = cmd.Process.Kill(); _ = cmd.Wait() }() + line, _ := bufio.NewReader(stderr).ReadString('\n') + if !strings.Contains(line, "https://") { + t.Errorf("first stderr line = %q, want the https:// address", line) + } +} + +func writeSelfSignedCert(t *testing.T) (string, string) { + t.Helper() + key, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader) + if err != nil { + t.Fatal(err) + } + tmpl := &x509.Certificate{SerialNumber: big.NewInt(1), Subject: pkix.Name{CommonName: "test"}, NotBefore: time.Now(), NotAfter: time.Now().Add(time.Hour)} + der, err := x509.CreateCertificate(rand.Reader, tmpl, tmpl, &key.PublicKey, key) + if err != nil { + t.Fatal(err) + } + keyDER, err := x509.MarshalECPrivateKey(key) + if err != nil { + t.Fatal(err) + } + dir := t.TempDir() + certFile, keyFile := filepath.Join(dir, "cert.pem"), filepath.Join(dir, "key.pem") + if err := os.WriteFile(certFile, pem.EncodeToMemory(&pem.Block{Type: "CERTIFICATE", Bytes: der}), 0o600); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(keyFile, pem.EncodeToMemory(&pem.Block{Type: "EC PRIVATE KEY", Bytes: keyDER}), 0o600); err != nil { + t.Fatal(err) + } + return certFile, keyFile +} + func TestMCPServe_RejectsUnknownTarget(t *testing.T) { sb := testutil.NewSandbox(t) defer sb.Cleanup() diff --git a/website/docs/reference/commands/mcp.md b/website/docs/reference/commands/mcp.md index 5db28837e..dbd1a0ae6 100644 --- a/website/docs/reference/commands/mcp.md +++ b/website/docs/reference/commands/mcp.md @@ -53,6 +53,7 @@ skillshare sync --all | `--live` | With `check`: also start each local server and call each remote one. See [below](#probe-servers-live) | | `--timeout DURATION` | With `check --live`: time limit for each server's probe, such as `30s`; default `10s` | | `--http ADDR` | With `serve`: listen for Streamable HTTP on `ADDR` instead of using stdio. See [below](#serve-skills-over-mcp) | +| `--tls-cert FILE`, `--tls-key FILE` | With `serve --http`: serve HTTPS with this PEM certificate and key; required off loopback | | `--check` | With `serve`: list the skills it would skip and why, then exit without serving | | `--no-tui` | Disable interactive menus; also disabled by `tui: false`, `--json`, or non-terminal input/output | | `--revision ID` | Require a matching preview for add/import/remove or `sync mcp` | @@ -775,7 +776,8 @@ and writes no files until you choose for that entry: ```bash skillshare mcp serve # stdio, every enabled skill skillshare mcp serve --target claude # only the skills the claude target selects -SKILLSHARE_MCP_TOKEN=change-me skillshare mcp serve --http 0.0.0.0:8765 +SKILLSHARE_MCP_TOKEN=change-me skillshare mcp serve --http 0.0.0.0:8765 \ + --tls-cert cert.pem --tls-key key.pem # HTTPS for other machines ``` `mcp serve` is a read-only MCP server for an Agent that cannot reach the folder @@ -815,8 +817,10 @@ skill approval does not apply. in the current directory. - **Transport.** stdio by default, for a gateway or Agent that starts the command. `--http ADDR` serves Streamable HTTP. A non-loopback address requires - `SKILLSHARE_MCP_TOKEN`; when it is set, every request must send - `Authorization: Bearer `. + `SKILLSHARE_MCP_TOKEN` and HTTPS through `--tls-cert` and `--tls-key`, so the token + never crosses the network in plain text; when the token is set, every request must + send `Authorization: Bearer `. To use a TLS proxy instead, bind a loopback + address such as `127.0.0.1:8765` and let the proxy terminate TLS. - **Safety.** Only files in a skill's manifest can be read, and reads stay inside the skill directory. Links and `.git` are neither listed nor served. Nothing is executed or written. @@ -832,14 +836,14 @@ In the dashboard, **Add server** → **Skillshare** builds the same command (wit project mode) from a choice of skills; tick the Agent, save and sync. Editing that server opens the same tab. -For an Agent on another machine, run `mcp serve --http` where the skills are and point a -remote server at it. Keep the token in an environment variable: +For an Agent on another machine, run `mcp serve --http` with a certificate where the +skills are and point a remote server at it. Keep the token in an environment variable: ```yaml mcp: servers: skillshare: - url: http://skills-host:8765/ + url: https://skills-host:8765/ bearerToken: { fromEnv: SKILLSHARE_MCP_TOKEN } targets: [codex] ``` From 7980c08a2d2d92c8d86bb763d5a827f8fab094a4 Mon Sep 17 00:00:00 2001 From: Willie Date: Tue, 6 Oct 2026 16:16:25 +0800 Subject: [PATCH 18/26] refactor(mcp): read each skill file once in skillpkg.Load The review fixes left the per-file size and digest split across two packages: a stat-based budget in the walk, a second bounded read in the catalog, a SKILL.md special case hashed once per file, and the digest format written out three times. skillpkg.Load now reads every file once within one package budget and records its digest and size, so the catalog only maps them, and skillpkg.Digest is the one digest format. Also: Build settles skills in one deepest-first loop, the skills/list cursor uses sort.Search, ParseFrontmatterMap splits the file once, mcp serve names each value flag once, and the migration report is not called twice in main. --- cmd/skillshare/main.go | 10 ++-- cmd/skillshare/mcp_serve.go | 28 ++++++----- internal/skillpkg/skillpkg.go | 66 +++++++++++++++++------- internal/skillserve/catalog.go | 78 +++++++---------------------- internal/skillserve/catalog_test.go | 20 +++++--- internal/skillserve/server.go | 9 +--- internal/utils/frontmatter.go | 7 +-- 7 files changed, 104 insertions(+), 114 deletions(-) diff --git a/cmd/skillshare/main.go b/cmd/skillshare/main.go index 67ca7788f..868beb909 100644 --- a/cmd/skillshare/main.go +++ b/cmd/skillshare/main.go @@ -83,14 +83,12 @@ func main() { results = append(results, config.MigrateXDGDirs()...) // mcp serve speaks the protocol on stdout, so its errors, notices and trailers stay off it. serving := len(os.Args) > 2 && os.Args[1] == "mcp" && os.Args[2] == "serve" + stdout := os.Stdout if serving { - stdout := os.Stdout - os.Stdout = os.Stderr - reportMigrationResults(results) - os.Stdout = stdout - } else { - reportMigrationResults(results) + os.Stdout = os.Stderr // ui writes through fmt.Printf } + reportMigrationResults(results) + os.Stdout = stdout // Set version for other packages to use versioncheck.Version = version diff --git a/cmd/skillshare/mcp_serve.go b/cmd/skillshare/mcp_serve.go index 98bd5ae46..429236a55 100644 --- a/cmd/skillshare/mcp_serve.go +++ b/cmd/skillshare/mcp_serve.go @@ -4,10 +4,12 @@ import ( "context" "errors" "fmt" + "maps" "net" "net/http" "os" "os/signal" + "slices" "strings" "syscall" "time" @@ -27,27 +29,29 @@ const mcpServeTokenEnv = "SKILLSHARE_MCP_TOKEN" // cmdMCPServe serves the managed skills over MCP (SEP-2640). It never writes: // stdout carries the protocol, so diagnostics go to stderr. func cmdMCPServe(args []string) error { - mode, rest, err := parseModeArgs(args, "--target", "--http", "--tls-cert", "--tls-key") + var target, addr, certFile, keyFile string + valueFlags := map[string]*string{"--target": &target, "--http": &addr, "--tls-cert": &certFile, "--tls-key": &keyFile} + mode, rest, err := parseModeArgs(args, slices.Collect(maps.Keys(valueFlags))...) if err != nil { return err } - values := map[string]string{} check := false for i := 0; i < len(rest); i++ { - switch a := rest[i]; a { - case "--check": + a := rest[i] + if a == "--check" { check = true - case "--target", "--http", "--tls-cert", "--tls-key": - if i+1 == len(rest) { - return fmt.Errorf("%s requires a value", a) - } - i++ - values[a] = rest[i] - default: + continue + } + v, ok := valueFlags[a] + if !ok { return fmt.Errorf("unknown mcp serve argument %q; usage: %s", a, mcpServeUsage) } + if i+1 == len(rest) { + return fmt.Errorf("%s requires a value", a) + } + i++ + *v = rest[i] } - target, addr, certFile, keyFile := values["--target"], values["--http"], values["--tls-cert"], values["--tls-key"] if check && addr != "" { return fmt.Errorf("--check starts no server; drop --http") } diff --git a/internal/skillpkg/skillpkg.go b/internal/skillpkg/skillpkg.go index 915007918..107e72d89 100644 --- a/internal/skillpkg/skillpkg.go +++ b/internal/skillpkg/skillpkg.go @@ -4,6 +4,7 @@ package skillpkg import ( + "crypto/sha256" "fmt" "io" "os" @@ -26,36 +27,40 @@ const ( MaxCompatibility = 500 ) -// File is one regular file of a package. +// File is one regular file of a package. Digest and Size come from one read, so +// they describe the same bytes even when the file changes while it is loaded. type File struct { - Path string // absolute - Rel string // slash-separated, relative to the package directory - Size int64 + Path string // absolute + Rel string // slash-separated, relative to the package directory + Digest string // sha256: + Size int64 } -// Package is a valid skill directory. +// Package is a valid skill directory. Its SKILL.md entry is the read the +// frontmatter was parsed from. type Package struct { Dir string // resolved Frontmatter map[string]any - SkillMD []byte // the bytes Frontmatter was parsed from Files []File } +var errTooLarge = fmt.Errorf("is larger than %d MiB", MaxBytes>>20) + // Load reads the skill in dir. The error says why the directory is not a // valid package. .git directories are left out; links are neither listed nor read. func Load(dir string) (*Package, error) { dirName := filepath.Base(filepath.Clean(dir)) // a followed link's name, not its target's dir = utils.ResolveSymlink(dir) // A linked SKILL.md would be missing from the manifest, which lists no links. - info, err := os.Lstat(filepath.Join(dir, "SKILL.md")) + skillPath := filepath.Join(dir, "SKILL.md") + info, err := os.Lstat(skillPath) if err != nil { return nil, err } if !info.Mode().IsRegular() { return nil, fmt.Errorf("SKILL.md is not a regular file") } - // The read itself is bounded: the file can grow after the Lstat. - content, err := readAtMost(filepath.Join(dir, "SKILL.md"), MaxBytes) + content, err := readAtMost(skillPath, MaxBytes) if err != nil { return nil, err } @@ -84,8 +89,10 @@ func Load(dir string) (*Package, error) { return nil, fmt.Errorf("compatibility has %d characters; the limit is %d", n, MaxCompatibility) } - p := &Package{Dir: dir, Frontmatter: fm, SkillMD: content} - var total int64 + p := &Package{Dir: dir, Frontmatter: fm, Files: []File{{Path: skillPath, Rel: "SKILL.md", Digest: Digest(content), Size: int64(len(content))}}} + // Every read is bounded by what is left of the package budget, so a file that + // grows while it is read cannot push the package past the limit. + left := MaxBytes - int64(len(content)) err = sourcewalk.Walk(dir, sourcewalk.Options{}, func(path string, info os.FileInfo, err error) error { if err != nil { return err @@ -99,17 +106,19 @@ func Load(dir string) (*Package, error) { if !info.Mode().IsRegular() { return nil } + rel, err := filepath.Rel(dir, path) + if err != nil || rel == "SKILL.md" { // SKILL.md is listed from the read above + return err + } if len(p.Files) == MaxFiles { return fmt.Errorf("has more than %d files", MaxFiles) } - if total += info.Size(); total > MaxBytes { - return fmt.Errorf("is larger than 16 MiB") - } - rel, err := filepath.Rel(dir, path) + sum, n, err := hashAtMost(path, left) if err != nil { return err } - p.Files = append(p.Files, File{Path: path, Rel: filepath.ToSlash(rel), Size: info.Size()}) + left -= n + p.Files = append(p.Files, File{Path: path, Rel: filepath.ToSlash(rel), Digest: sum, Size: n}) return nil }) if err != nil { @@ -118,7 +127,10 @@ func Load(dir string) (*Package, error) { return p, nil } -// readAtMost reads the file, failing once it holds more than limit bytes. +// Digest is the manifest digest of b. +func Digest(b []byte) string { return fmt.Sprintf("sha256:%x", sha256.Sum256(b)) } + +// readAtMost reads the file, failing past limit bytes. func readAtMost(path string, limit int64) ([]byte, error) { f, err := os.Open(path) if err != nil { @@ -130,11 +142,29 @@ func readAtMost(path string, limit int64) ([]byte, error) { return nil, err } if int64(len(data)) > limit { - return nil, fmt.Errorf("SKILL.md is over %d MiB", limit>>20) + return nil, errTooLarge } return data, nil } +// hashAtMost streams the file into its digest and size, failing past limit bytes. +func hashAtMost(path string, limit int64) (string, int64, error) { + f, err := os.Open(path) + if err != nil { + return "", 0, err + } + defer f.Close() + h := sha256.New() + n, err := io.Copy(h, io.LimitReader(f, limit+1)) + if err != nil { + return "", 0, err + } + if n > limit { + return "", 0, errTooLarge + } + return fmt.Sprintf("sha256:%x", h.Sum(nil)), n, nil +} + // ValidateName returns why a SKILL.md name breaks the Agent Skills naming rules // (including name == directory name), or "" when it follows them. Like the // reference validator, it takes lowercase Unicode letters and digits after NFKC diff --git a/internal/skillserve/catalog.go b/internal/skillserve/catalog.go index 24b3fc585..c1db7e524 100644 --- a/internal/skillserve/catalog.go +++ b/internal/skillserve/catalog.go @@ -4,7 +4,6 @@ package skillserve import ( - "crypto/sha256" "errors" "fmt" "io" @@ -96,45 +95,32 @@ func (b *Builder) Build() (*Catalog, error) { } slices.SortFunc(selected, func(x, y ssync.DiscoveredSkill) int { return strings.Compare(x.RelPath, y.RelPath) }) - type loaded struct { - skill *Skill - files map[string]servedFile - reason string - } - loads := make([]loaded, len(selected)) - for i, s := range selected { - loads[i].skill, loads[i].files, loads[i].reason = load(s) - } // Deepest first, so a nested skill skipped for any reason also skips its parents, // which would otherwise publish its files as their own. - for i := len(loads) - 1; i >= 0; i-- { - for _, o := range unserved { - if loads[i].reason == "" && strings.HasPrefix(o, selected[i].RelPath+"/") { - loads[i].reason = fmt.Sprintf("contains %s, which is not served", o) - } - } - if loads[i].reason != "" { - unserved = append(unserved, selected[i].RelPath) - } - } - c := &Catalog{bySkill: map[string]*Skill{}, byFile: map[string]servedFile{}} - for i, l := range loads { - if l.reason != "" { - c.Skipped = append(c.Skipped, Skip{Path: selected[i].RelPath, Reason: l.reason}) + for i := len(selected) - 1; i >= 0; i-- { + s := selected[i] + skill, files, reason := load(s) + if j := slices.IndexFunc(unserved, func(o string) bool { return strings.HasPrefix(o, s.RelPath+"/") }); reason == "" && j >= 0 { + reason = fmt.Sprintf("contains %s, which is not served", unserved[j]) + } + if reason != "" { + c.Skipped = append(c.Skipped, Skip{Path: s.RelPath, Reason: reason}) + unserved = append(unserved, s.RelPath) continue } - c.Skills = append(c.Skills, l.skill) - c.bySkill[l.skill.URI] = l.skill - maps.Copy(c.byFile, l.files) + c.Skills = append(c.Skills, skill) + c.bySkill[skill.URI] = skill + maps.Copy(c.byFile, files) } + slices.Reverse(c.Skipped) // By URI, which skills/list cursors continue from. slices.SortFunc(c.Skills, func(x, y *Skill) int { return strings.Compare(x.URI, y.URI) }) return c, nil } // load builds one entry and its files, or returns why the skill is skipped. -// Every build hashes every file: size and mtime cannot prove the content is +// Every build reads every file again: size and mtime cannot prove the content is // unchanged (cp -p, rsync -t), and a stale digest makes hosts reject the file. func load(s ssync.DiscoveredSkill) (*Skill, map[string]servedFile, string) { p, err := skillpkg.Load(s.SourcePath) @@ -144,44 +130,14 @@ func load(s ssync.DiscoveredSkill) (*Skill, map[string]servedFile, string) { base := "skill://" + escapePath(s.RelPath) skill := &Skill{URI: base + "/SKILL.md", Frontmatter: p.Frontmatter} files := make(map[string]servedFile, len(p.Files)) - left := int64(skillpkg.MaxBytes) // the walk checked sizes too, but files can grow since for _, f := range p.Files { - // SKILL.md is hashed from the bytes its frontmatter came from, so the entry - // never pairs old frontmatter with a newer file's digest. - sum, size := fmt.Sprintf("sha256:%x", sha256.Sum256(p.SkillMD)), int64(len(p.SkillMD)) - if f.Rel != "SKILL.md" { - if sum, size, err = hashFile(f.Path, left); err != nil { - return nil, nil, err.Error() - } - } - left -= size uri := base + "/" + escapePath(f.Rel) - files[uri] = servedFile{dir: p.Dir, rel: f.Rel, digest: sum} - skill.Resources = append(skill.Resources, File{URI: uri, Digest: sum, Size: size}) + files[uri] = servedFile{dir: p.Dir, rel: f.Rel, digest: f.Digest} + skill.Resources = append(skill.Resources, File{URI: uri, Digest: f.Digest, Size: f.Size}) } return skill, files, "" } -// hashFile returns the digest and size of one read of the file, so both describe -// the same bytes even when the file is replaced while the catalog is built. It -// stops past limit bytes, so a file that grew cannot stall the build. -func hashFile(path string, limit int64) (string, int64, error) { - f, err := os.Open(path) - if err != nil { - return "", 0, err - } - defer f.Close() - h := sha256.New() - n, err := io.Copy(h, io.LimitReader(f, limit+1)) - if err != nil { - return "", 0, err - } - if n > limit { - return "", 0, fmt.Errorf("is larger than %d MiB", skillpkg.MaxBytes>>20) - } - return fmt.Sprintf("sha256:%x", h.Sum(nil)), n, nil -} - // Skill returns the served skill whose SKILL.md URI is uri. func (c *Catalog) Skill(uri string) (*Skill, bool) { key, ok := canonical(uri) @@ -213,7 +169,7 @@ func (c *Catalog) Read(uri string) ([]byte, error) { } // A file edited since it was listed would fail the client's digest check; // the next refresh lists it again. - if fmt.Sprintf("sha256:%x", sha256.Sum256(data)) != sf.digest { + if skillpkg.Digest(data) != sf.digest { return nil, fmt.Errorf("%s changed since it was listed; list the skills again", uri) } return data, nil diff --git a/internal/skillserve/catalog_test.go b/internal/skillserve/catalog_test.go index 263d1605e..41295d8bb 100644 --- a/internal/skillserve/catalog_test.go +++ b/internal/skillserve/catalog_test.go @@ -185,12 +185,18 @@ func TestBuild_SkipsSkillWhoseDescriptionOrCompatibilityIsTooLong(t *testing.T) } } -// The size limit holds for the bytes hashed, not only the sizes the walk saw. -func TestHashFile_StopsPastTheSizeLimit(t *testing.T) { - path := filepath.Join(t.TempDir(), "big.bin") - writeFile(t, path, strings.Repeat("x", skillpkg.MaxBytes+1)) - if _, _, err := hashFile(path, skillpkg.MaxBytes); err == nil { - t.Error("hashFile succeeded past the limit, want an error") +// The 16 MiB limit counts the bytes read, SKILL.md included. +func TestBuild_SkipsSkillOverTheSizeLimit(t *testing.T) { + src := t.TempDir() + writeFile(t, filepath.Join(src, "big/SKILL.md"), skillMD("big")) + writeFile(t, filepath.Join(src, "big/data.bin"), strings.Repeat("x", skillpkg.MaxBytes-len(skillMD("big"))+1)) + + c, err := (&Builder{Source: src}).Build() + if err != nil { + t.Fatal(err) + } + if len(c.Skills) != 0 || !hasWarning(c, "skipped big: is larger than 16 MiB") { + t.Errorf("skills=%v warnings=%v, want big skipped", c.Skills, c.Skipped) } } @@ -347,7 +353,7 @@ func TestBuild_SkipsSkillWithNonStringCompatibilityOrOversizedSkillMD(t *testing if err != nil { t.Fatal(err) } - if len(c.Skills) != 0 || !hasWarning(c, "skipped list") || !hasWarning(c, "skipped huge: SKILL.md is over") { + if len(c.Skills) != 0 || !hasWarning(c, "skipped list") || !hasWarning(c, "skipped huge: is larger than 16 MiB") { t.Errorf("skills=%v warnings=%v, want list and huge skipped", c.Skills, c.Skipped) } } diff --git a/internal/skillserve/server.go b/internal/skillserve/server.go index 918c411d8..06e027de9 100644 --- a/internal/skillserve/server.go +++ b/internal/skillserve/server.go @@ -9,7 +9,7 @@ import ( "mime" "net/http" "path" - "slices" + "sort" "strings" "sync" "time" @@ -159,12 +159,7 @@ func (s *service) list(_ context.Context, _ *mcp.ServerSession, p *listSkillsPar if !strings.HasPrefix(p.Cursor, "skill://") { return nil, invalidParams("invalid cursor") } - start, _ = slices.BinarySearchFunc(c.Skills, p.Cursor, func(s *Skill, uri string) int { - if s.URI <= uri { - return -1 - } - return 1 - }) + start = sort.Search(len(c.Skills), func(i int) bool { return c.Skills[i].URI > p.Cursor }) } end := min(start+pageSize, len(c.Skills)) res := &listSkillsResult{Cacheable: s.cacheable(), ResultType: "complete", Skills: c.Skills[start:end]} diff --git a/internal/utils/frontmatter.go b/internal/utils/frontmatter.go index e39f51b4e..eb6a9ada6 100644 --- a/internal/utils/frontmatter.go +++ b/internal/utils/frontmatter.go @@ -223,11 +223,12 @@ func ParseFrontmatterMap(content []byte) (map[string]any, error) { if strings.TrimSuffix(lines[0], "\r") != "---" { return nil, fmt.Errorf("no frontmatter at the start") } - if !slices.ContainsFunc(lines[1:], func(l string) bool { return strings.TrimSpace(l) == "---" }) { + end := slices.IndexFunc(lines[1:], func(l string) bool { return strings.TrimSpace(l) == "---" }) + if end < 0 { return nil, fmt.Errorf("unclosed frontmatter: no closing ---") } - raw := extractFrontmatterRawFromBytes(content) - if raw == "" { + raw := strings.Join(lines[1:end+1], "\n") + if strings.TrimSpace(raw) == "" { return nil, fmt.Errorf("no frontmatter") } var fm map[string]any From a6166ed27bcf10371d5f9b68272d232060d63b0a Mon Sep 17 00:00:00 2001 From: Willie Date: Tue, 6 Oct 2026 16:18:03 +0800 Subject: [PATCH 19/26] fix(mcp): match a skill's name to its directory exactly MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The name rules are checked after NFKC, but the directory is the skill path's last segment, which the Skills extension requires to equal the name. A fullwidth abc in directory abc passed and was published under a URI that did not match its name; the comparison is now exact. --- internal/skillpkg/skillpkg.go | 9 ++++++--- internal/skillserve/catalog_test.go | 6 ++++-- 2 files changed, 10 insertions(+), 5 deletions(-) diff --git a/internal/skillpkg/skillpkg.go b/internal/skillpkg/skillpkg.go index 107e72d89..c8f77b9dc 100644 --- a/internal/skillpkg/skillpkg.go +++ b/internal/skillpkg/skillpkg.go @@ -167,9 +167,10 @@ func hashAtMost(path string, limit int64) (string, int64, error) { // ValidateName returns why a SKILL.md name breaks the Agent Skills naming rules // (including name == directory name), or "" when it follows them. Like the -// reference validator, it takes lowercase Unicode letters and digits after NFKC +// reference validator, it checks lowercase Unicode letters and digits after NFKC // normalization and counts the limit in characters. func ValidateName(name, dirName string) string { + exact := name name = norm.NFKC.String(strings.TrimSpace(name)) if name == "" { return "SKILL.md is missing a name" @@ -188,8 +189,10 @@ func ValidateName(name, dirName string) string { }) { return fmt.Sprintf("SKILL.md name %q must use only lowercase letters, numbers, and hyphens", name) } - if name != norm.NFKC.String(dirName) { - return fmt.Sprintf("SKILL.md name %q does not match directory name %q", name, dirName) + // Exactly, not only after NFKC: the directory is the skill path's last segment, + // which the Skills extension requires to equal the name. + if exact != dirName { + return fmt.Sprintf("SKILL.md name %q does not match directory name %q", exact, dirName) } return "" } diff --git a/internal/skillserve/catalog_test.go b/internal/skillserve/catalog_test.go index 41295d8bb..df6ab60e8 100644 --- a/internal/skillserve/catalog_test.go +++ b/internal/skillserve/catalog_test.go @@ -208,13 +208,15 @@ func TestBuild_AcceptsLowercaseUnicodeNames(t *testing.T) { writeFile(t, filepath.Join(src, "café/SKILL.md"), skillMD("café")) writeFile(t, filepath.Join(src, "Été/SKILL.md"), skillMD("Été")) writeFile(t, filepath.Join(src, "a_b/SKILL.md"), skillMD("a_b")) + // The URI leaf is the directory, and it must equal the name exactly, not only after NFKC. + writeFile(t, filepath.Join(src, "abc/SKILL.md"), skillMD("abc")) c, err := (&Builder{Source: src}).Build() if err != nil { t.Fatal(err) } - if len(c.Skills) != 2 || !hasWarning(c, "skipped Été") || !hasWarning(c, "skipped a_b") { - t.Errorf("skills=%v warnings=%v, want 技能-審查 and café served, Été and a_b skipped", c.Skills, c.Skipped) + if len(c.Skills) != 2 || !hasWarning(c, "skipped Été") || !hasWarning(c, "skipped a_b") || !hasWarning(c, "skipped abc") { + t.Errorf("skills=%v warnings=%v, want 技能-審查 and café served, Été, a_b and fullwidth abc skipped", c.Skills, c.Skipped) } } From 76a49ada77f569b399b7bedf18b33dcb5a125a0b Mon Sep 17 00:00:00 2001 From: Willie Date: Tue, 6 Oct 2026 16:26:49 +0800 Subject: [PATCH 20/26] fix(mcp): find the frontmatter without splitting the whole SKILL.md Splitting the file into lines cost one string header per line, so a 16 MiB newline-heavy body allocated about 256 MiB per parse. The parser now scans lines up to the closing --- and keeps only offsets. --- internal/utils/frontmatter.go | 25 +++++++++++++++++++------ internal/utils/frontmatter_test.go | 17 +++++++++++++++++ 2 files changed, 36 insertions(+), 6 deletions(-) diff --git a/internal/utils/frontmatter.go b/internal/utils/frontmatter.go index eb6a9ada6..2f0907580 100644 --- a/internal/utils/frontmatter.go +++ b/internal/utils/frontmatter.go @@ -7,7 +7,6 @@ import ( "fmt" "os" "path/filepath" - "slices" "strings" "gopkg.in/yaml.v3" @@ -218,16 +217,30 @@ func extractFrontmatterRaw(filePath string) string { // The Agent Skills format requires the file to begin with it, closed by a second ---. func ParseFrontmatterMap(content []byte) (map[string]any, error) { content = bytes.TrimPrefix(content, []byte("\xef\xbb\xbf")) - lines := strings.Split(string(content), "\n") - // Exactly ---: an indented delimiter does not open frontmatter. A CRLF file keeps its \r. - if strings.TrimSuffix(lines[0], "\r") != "---" { + // Scan line by line up to the closing ---, keeping only offsets, so memory does + // not grow with the line count of a large body. + start, end := -1, -1 + pos := 0 + for line := range bytes.Lines(content) { + if start < 0 { + // Exactly ---: an indented delimiter does not open frontmatter. CRLF is fine. + if string(bytes.TrimRight(line, "\r\n")) != "---" { + return nil, fmt.Errorf("no frontmatter at the start") + } + start = len(line) + } else if string(bytes.TrimSpace(line)) == "---" { + end = pos + break + } + pos += len(line) + } + if start < 0 { return nil, fmt.Errorf("no frontmatter at the start") } - end := slices.IndexFunc(lines[1:], func(l string) bool { return strings.TrimSpace(l) == "---" }) if end < 0 { return nil, fmt.Errorf("unclosed frontmatter: no closing ---") } - raw := strings.Join(lines[1:end+1], "\n") + raw := string(content[start:end]) if strings.TrimSpace(raw) == "" { return nil, fmt.Errorf("no frontmatter") } diff --git a/internal/utils/frontmatter_test.go b/internal/utils/frontmatter_test.go index 3eb87e30a..ff8659d20 100644 --- a/internal/utils/frontmatter_test.go +++ b/internal/utils/frontmatter_test.go @@ -1,8 +1,10 @@ package utils import ( + "bytes" "os" "path/filepath" + "runtime" "testing" ) @@ -307,3 +309,18 @@ enabled: true }) } } + +// A newline-heavy body must not cost memory per line: only the frontmatter is kept. +func TestParseFrontmatterMap_MemoryDoesNotGrowWithBodyLines(t *testing.T) { + content := append([]byte("---\nname: a\n---\n"), bytes.Repeat([]byte("\n"), 16<<20)...) + var before, after runtime.MemStats + runtime.GC() + runtime.ReadMemStats(&before) + if _, err := ParseFrontmatterMap(content); err != nil { + t.Fatal(err) + } + runtime.ReadMemStats(&after) + if got := after.TotalAlloc - before.TotalAlloc; got > 1<<20 { + t.Errorf("parsing allocated %d bytes, want under 1 MiB", got) + } +} From db3840b0317df429014992acbd71a4b738a36f32 Mon Sep 17 00:00:00 2001 From: Willie Date: Tue, 6 Oct 2026 16:36:51 +0800 Subject: [PATCH 21/26] fix(mcp): keep an edited serve command's -p and reject padded names Changing the served target rebuilt the command from the dashboard scope, so editing `skillshare mcp serve -p --target old` in the global dashboard silently dropped -p; the command now keeps its own flag. Skill names were trimmed before validation, so a name and directory padded with the same spaces passed. Names are no longer trimmed, and the spaces fail the character rule. --- internal/skillpkg/skillpkg.go | 3 ++- internal/skillserve/catalog_test.go | 6 +++++- ui/src/components/mcp/MCPServerDialog.test.tsx | 10 ++++++++++ ui/src/components/mcp/MCPServerDialog.tsx | 3 ++- 4 files changed, 19 insertions(+), 3 deletions(-) diff --git a/internal/skillpkg/skillpkg.go b/internal/skillpkg/skillpkg.go index c8f77b9dc..811d54b20 100644 --- a/internal/skillpkg/skillpkg.go +++ b/internal/skillpkg/skillpkg.go @@ -170,8 +170,9 @@ func hashAtMost(path string, limit int64) (string, int64, error) { // reference validator, it checks lowercase Unicode letters and digits after NFKC // normalization and counts the limit in characters. func ValidateName(name, dirName string) string { + // Not trimmed: surrounding whitespace is not a letter, digit or hyphen, so it fails below. exact := name - name = norm.NFKC.String(strings.TrimSpace(name)) + name = norm.NFKC.String(name) if name == "" { return "SKILL.md is missing a name" } diff --git a/internal/skillserve/catalog_test.go b/internal/skillserve/catalog_test.go index df6ab60e8..0fea8e969 100644 --- a/internal/skillserve/catalog_test.go +++ b/internal/skillserve/catalog_test.go @@ -210,12 +210,16 @@ func TestBuild_AcceptsLowercaseUnicodeNames(t *testing.T) { writeFile(t, filepath.Join(src, "a_b/SKILL.md"), skillMD("a_b")) // The URI leaf is the directory, and it must equal the name exactly, not only after NFKC. writeFile(t, filepath.Join(src, "abc/SKILL.md"), skillMD("abc")) + // Surrounding whitespace is not part of a valid name, even when the directory has it too. + if runtime.GOOS != "windows" { + writeFile(t, filepath.Join(src, " sp /SKILL.md"), strings.Replace(skillMD("x"), "name: x", `name: " sp "`, 1)) + } c, err := (&Builder{Source: src}).Build() if err != nil { t.Fatal(err) } - if len(c.Skills) != 2 || !hasWarning(c, "skipped Été") || !hasWarning(c, "skipped a_b") || !hasWarning(c, "skipped abc") { + if len(c.Skills) != 2 || !hasWarning(c, "skipped Été") || !hasWarning(c, "skipped a_b") || !hasWarning(c, "skipped abc") || (runtime.GOOS != "windows" && !hasWarning(c, "skipped sp ")) { t.Errorf("skills=%v warnings=%v, want 技能-審查 and café served, Été, a_b and fullwidth abc skipped", c.Skills, c.Skipped) } } diff --git a/ui/src/components/mcp/MCPServerDialog.test.tsx b/ui/src/components/mcp/MCPServerDialog.test.tsx index cd32b7ac5..51e8468f2 100644 --- a/ui/src/components/mcp/MCPServerDialog.test.tsx +++ b/ui/src/components/mcp/MCPServerDialog.test.tsx @@ -108,6 +108,16 @@ describe('MCP server dialog', () => { await waitFor(() => expect(mcpApi.save).toHaveBeenCalledWith(expect.objectContaining({ server: { command: 'skillshare', args: ['mcp', 'serve', '--target', 'app@claude'] } }))); }); + it("keeps an existing command's -p when the served target changes", async () => { + const user = userEvent.setup(); + vi.mocked(api.listTargets).mockResolvedValue({ targets: [{ name: 'old', skillsEnabled: true }, { name: 'new', skillsEnabled: true }] as Target[], sourceSkillCount: 1 }); + renderDialog({ serve: true, initial: { name: 'skillshare', server: { command: 'skillshare', args: ['mcp', 'serve', '-p', '--target', 'old'] } } }); + await user.click(screen.getByRole('combobox', { name: 'Skills to serve' })); + await user.click(await screen.findByRole('option', { name: 'Same as target new' })); + await user.click(screen.getByRole('button', { name: 'Save' })); + await waitFor(() => expect(mcpApi.save).toHaveBeenCalledWith(expect.objectContaining({ server: expect.objectContaining({ command: 'skillshare', args: ['mcp', 'serve', '--target', 'new', '-p'] }) }))); + }); + it('warns that an Agent already getting skills by sync would see them twice', async () => { vi.mocked(api.listTargets).mockResolvedValue({ targets: [{ name: 'claude', skillsEnabled: true } as Target], sourceSkillCount: 1 }); renderDialog({ serve: true }); diff --git a/ui/src/components/mcp/MCPServerDialog.tsx b/ui/src/components/mcp/MCPServerDialog.tsx index 688825b2c..4917ba968 100644 --- a/ui/src/components/mcp/MCPServerDialog.tsx +++ b/ui/src/components/mcp/MCPServerDialog.tsx @@ -145,7 +145,8 @@ function ServerForm({ draft, validation, patch, off, saving, editing, order, vis