diff --git a/.devcontainer/ensure-agent-clis.sh b/.devcontainer/ensure-agent-clis.sh index 4f74e7294..4cec21c02 100755 --- a/.devcontainer/ensure-agent-clis.sh +++ b/.devcontainer/ensure-agent-clis.sh @@ -6,20 +6,25 @@ set -euo pipefail PREFIX="$HOME/.local/agent-clis" -# bin → npm package +# bin → npm package, optionally @version. A pinned package is reinstalled when the +# volume holds another version; an unpinned one is installed once and left alone. declare -A PACKAGES=( [claude]="@anthropic-ai/claude-code" [codex]="@openai/codex" - [pi]="@earendil-works/pi-coding-agent" + [pi]="@earendil-works/pi-coding-agent@1.0.4" ) for bin in "${!PACKAGES[@]}"; do + spec="${PACKAGES[$bin]}" + name="$spec" want="" + if [[ "${spec:1}" == *@* ]]; then name="${spec%@*}" want="${spec##*@}"; fi # Check the package, not the binary: a package that moved to a new name (Pi, from # @mariozechner) leaves the old one's binary behind, which would never be replaced. - if [ ! -d "$PREFIX/lib/node_modules/${PACKAGES[$bin]}" ]; then - echo "▸ Installing $bin (${PACKAGES[$bin]}) …" + have=$(node -p "require('$PREFIX/lib/node_modules/$name/package.json').version" 2>/dev/null || true) + if [ -z "$have" ] || { [ -n "$want" ] && [ "$have" != "$want" ]; }; then + echo "▸ Installing $bin ($spec) …" rm -f "$PREFIX/bin/$bin" - if ! npm install -g --prefix "$PREFIX" --no-fund --no-audit "${PACKAGES[$bin]}" >/dev/null 2>&1; then + if ! npm install -g --prefix "$PREFIX" --no-fund --no-audit "$spec" >/dev/null 2>&1; then echo "⚠ Could not install $bin; plugin checks against it will report it missing." >&2 continue fi diff --git a/ai_docs/tests/mcp_serve_runbook.md b/ai_docs/tests/mcp_serve_runbook.md new file mode 100644 index 000000000..cd01ae74a --- /dev/null +++ b/ai_docs/tests/mcp_serve_runbook.md @@ -0,0 +1,191 @@ +# 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 +- A non-loopback `--http` address with a token but no `--tls-cert`/`--tls-key` 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 + +### 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 +- 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..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 --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" @@ -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..7cdedb202 100644 --- a/cmd/skillshare/completion_fish.go +++ b/cmd/skillshare/completion_fish.go @@ -52,6 +52,10 @@ 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 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' 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 +69,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..e0f0b4ba4 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,10 @@ 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 + --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) --global(-g) diff --git a/cmd/skillshare/completion_powershell.go b/cmd/skillshare/completion_powershell.go index 4f8d2c072..350ae5029 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', '--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 429031abe..2ffd10e26 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,10 @@ _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:' \ + '--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 \ '--help[Show help]' \ 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/main.go b/cmd/skillshare/main.go index 0c2e95624..868beb909 100644 --- a/cmd/skillshare/main.go +++ b/cmd/skillshare/main.go @@ -81,7 +81,14 @@ func main() { // Migrate legacy dirs (backups/trash/logs) to XDG data/state dirs 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 { + os.Stdout = os.Stderr // ui writes through fmt.Printf + } reportMigrationResults(results) + os.Stdout = stdout // Set version for other packages to use versioncheck.Version = version @@ -131,6 +138,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,7 +151,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. - if !isStructuredOutput(args) { + if !isStructuredOutput(args) && !serving { fmt.Println() // Check for updates (non-blocking, silent on errors) diff --git a/cmd/skillshare/mcp.go b/cmd/skillshare/mcp.go index 20ba3ac09..bee71c34c 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 [--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 new file mode 100644 index 000000000..429236a55 --- /dev/null +++ b/cmd/skillshare/mcp_serve.go @@ -0,0 +1,183 @@ +package main + +import ( + "context" + "errors" + "fmt" + "maps" + "net" + "net/http" + "os" + "os/signal" + "slices" + "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 [--tls-cert --tls-key ] | --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 { + 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 + } + check := false + for i := 0; i < len(rest); i++ { + a := rest[i] + if a == "--check" { + check = true + 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] + } + 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} + 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) + } + + // Off loopback, the token must exist and must not cross the network in plain text. + token := os.Getenv(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}) + if err != nil { + return err + } + ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM) + defer stop() + + if addr == "" { + // A client stopping the server with a signal is a normal exit, as for --http. + if err := srv.Run(ctx, &mcp.StdioTransport{}); !errors.Is(err, context.Canceled) { + return err + } + return nil + } + 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() + }() + 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 +} + +// 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/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/go.mod b/go.mod index 7c5fc5999..c455a99c9 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,13 +11,16 @@ 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 + golang.org/x/text v0.26.0 gopkg.in/yaml.v3 v3.0.1 ) @@ -43,6 +45,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 +60,13 @@ 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/text v0.26.0 // indirect + golang.org/x/oauth2 v0.35.0 // indirect + golang.org/x/sync v0.20.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/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/skillpkg/skillpkg.go b/internal/skillpkg/skillpkg.go new file mode 100644 index 000000000..1ebcf8a9d --- /dev/null +++ b/internal/skillpkg/skillpkg.go @@ -0,0 +1,213 @@ +// 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 ( + "crypto/sha256" + "fmt" + "io" + "os" + "path/filepath" + "strings" + "unicode" + "unicode/utf8" + + "golang.org/x/text/unicode/norm" + + "skillshare/internal/sourcewalk" + "skillshare/internal/utils" +) + +// Per-skill limits from SEP-2640, and the Agent Skills field limits in characters. +const ( + MaxFiles = 512 + MaxBytes = 16 << 20 + MaxDescription = 1024 + MaxCompatibility = 500 +) + +// 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 + Digest string // sha256: + Size int64 +} + +// 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 + 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. + 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") + } + content, err := readAtMost(skillPath, info, MaxBytes) + 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) + } + 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) + } + // 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 || 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) + } + + 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 + } + if info.IsDir() { + if info.Name() == ".git" { + return filepath.SkipDir + } + return nil + } + 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) + } + sum, n, err := hashAtMost(path, info, left) + if err != nil { + return err + } + left -= n + p.Files = append(p.Files, File{Path: path, Rel: filepath.ToSlash(rel), Digest: sum, Size: n}) + return nil + }) + if err != nil { + return nil, err + } + return p, nil +} + +// Digest is the manifest digest of b. +func Digest(b []byte) string { return fmt.Sprintf("sha256:%x", sha256.Sum256(b)) } + +// openSame opens path and checks that it is the file info (from Lstat) described, +// so a file swapped for a link after it was checked is not followed. +func openSame(path string, info os.FileInfo) (*os.File, error) { + f, err := os.Open(path) + if err != nil { + return nil, err + } + if got, err := f.Stat(); err != nil || !os.SameFile(info, got) { + f.Close() + return nil, fmt.Errorf("%s changed while it was read", filepath.Base(path)) + } + return f, nil +} + +// readAtMost reads the file, failing past limit bytes. +func readAtMost(path string, info os.FileInfo, limit int64) ([]byte, error) { + f, err := openSame(path, info) + 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, errTooLarge + } + return data, nil +} + +// hashAtMost streams the file into its digest and size, failing past limit bytes. +func hashAtMost(path string, info os.FileInfo, limit int64) (string, int64, error) { + f, err := openSame(path, info) + 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 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(name) + if name == "" { + return "SKILL.md is missing a name" + } + 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, "-") { + 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) + } + 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) + } + // 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.go b/internal/skillserve/catalog.go new file mode 100644 index 000000000..ff2cdb9f9 --- /dev/null +++ b/internal/skillserve/catalog.go @@ -0,0 +1,238 @@ +// 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" + "maps" + "net/url" + "os" + "slices" + "strings" + + "skillshare/internal/config" + "skillshare/internal/skillpkg" + "skillshare/internal/sourcewalk" + ssync "skillshare/internal/sync" +) + +// extensionID is the SEP-2640 capability key. +const extensionID = "io.modelcontextprotocol/skills" + +var errNotFound = errors.New("not found") + +// afterDiscover runs between discovery and the loads; tests change the tree there. +var afterDiscover = func() {} + +// 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, 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 { + 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 URI; Skipped is in source path order. +type Catalog struct { + Skills []*Skill + Skipped []Skip + bySkill map[string]*Skill + byFile map[string]servedFile +} + +// Builder builds catalogs from the skills source. +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 +} + +// 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 + } + afterDiscover() + // Discovery and the loads read the tree separately. A skill added, removed or + // toggled in between would leave a parent publishing the files of a skill the + // catalog does not list, so build again until discovery agrees with the loads. + for range 3 { + c, err := b.build(all) + if err != nil { + return nil, err + } + again, err := ssync.DiscoverSourceSkillsAll(b.Source, b.Walk) + if err != nil { + return nil, err + } + if slices.EqualFunc(all, again, func(x, y ssync.DiscoveredSkill) bool { + return x.RelPath == y.RelPath && x.Disabled == y.Disabled + }) { + return c, nil + } + all = again + } + return nil, errors.New("the skills source kept changing while it was read; list the skills again") +} + +func (b *Builder) build(all []ssync.DiscoveredSkill) (*Catalog, error) { + var err error + 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) }) + + // Deepest first, so a nested skill skipped for any reason also skips its parents, + // which would otherwise publish its files as their own. + c := &Catalog{bySkill: map[string]*Skill{}, byFile: map[string]servedFile{}} + 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]) + } + // A parent lists its nested skills' files under the same URIs. If one changed + // between the two reads, the entries disagree; serve the parent next refresh + // rather than overwrite what the nested skill advertises. + for uri, f := range files { + if old, ok := c.byFile[uri]; reason == "" && ok && old.digest != f.digest { + reason = "a nested skill changed while it was read; it is served after the next refresh" + } + } + if reason != "" { + c.Skipped = append(c.Skipped, Skip{Path: s.RelPath, Reason: reason}) + unserved = append(unserved, s.RelPath) + continue + } + 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 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) + if err != nil { + return nil, 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 { + uri := base + "/" + escapePath(f.Rel) + 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, "" +} + +// 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() + 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 skillpkg.Digest(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 { + 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..00a654149 --- /dev/null +++ b/internal/skillserve/catalog_test.go @@ -0,0 +1,415 @@ +package skillserve + +import ( + "crypto/sha256" + "encoding/hex" + "fmt" + "os" + "path/filepath" + "runtime" + "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) + } +} + +// A parent and its nested skill list the same files under the same URIs; an +// unchanged tree serves both. +func TestBuild_ServesParentAndNestedSkillTogether(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}).Build() + if err != nil { + t.Fatal(err) + } + if len(c.Skills) != 2 { + t.Errorf("skills=%v warnings=%v, want suite and suite/child served", c.Skills, c.Skipped) + } +} + +// A nested skill created after discovery would otherwise be published only as a +// file of its parent. +func TestBuild_ListsNestedSkillCreatedDuringTheBuild(t *testing.T) { + src := t.TempDir() + writeFile(t, filepath.Join(src, "suite/SKILL.md"), skillMD("suite")) + afterDiscover = func() { writeFile(t, filepath.Join(src, "suite/child/SKILL.md"), skillMD("child")) } + t.Cleanup(func() { afterDiscover = func() {} }) + + c, err := (&Builder{Source: src}).Build() + if err != nil { + t.Fatal(err) + } + if len(c.Skills) != 2 { + t.Errorf("skills=%v warnings=%v, want suite and suite/child served", c.Skills, c.Skipped) + } +} + +func TestBuild_SkipsParentOfInvalidNestedSkill(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("other")) + + c, err := (&Builder{Source: src}).Build() + if err != nil { + t.Fatal(err) + } + if len(c.Skills) != 0 || !hasWarning(c, "contains suite/child") { + t.Errorf("skills=%v warnings=%v, want suite skipped because its child is skipped", c.Skills, c.Skipped) + } +} + +// A non-string key decodes to a map JSON cannot encode, which would fail the whole skills/list page. +func TestBuild_SkipsSkillWhoseFrontmatterJSONCannotCarry(t *testing.T) { + src := t.TempDir() + writeFile(t, filepath.Join(src, "ok/SKILL.md"), skillMD("ok")) + writeFile(t, filepath.Join(src, "odd/SKILL.md"), "---\nname: odd\ndescription: Use when testing odd\nmetadata:\n 1: x\n---\n") + + c, err := (&Builder{Source: src}).Build() + if err != nil { + t.Fatal(err) + } + if len(c.Skills) != 1 || c.Skills[0].URI != "skill://ok/SKILL.md" || !hasWarning(c, "skipped odd") { + t.Errorf("skills=%v warnings=%v, want odd skipped and ok served", c.Skills, c.Skipped) + } +} + +// 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")) + 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")) + writeFile(t, filepath.Join(src, "closer/SKILL.md"), "---\nname: closer\ndescription: Use when testing\n ---\n# closer\n") + + 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") || !hasWarning(c, "skipped indented") || !hasWarning(c, "skipped closer") { + t.Errorf("skills=%v warnings=%v, want late, unclosed open and indented skipped", c.Skills, c.Skipped) + } +} + +// 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") + 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") || !hasWarning(c, "skipped blank") { + t.Errorf("skills=%v warnings=%v, want long and compat skipped, wide served", c.Skills, c.Skipped) + } +} + +// 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) + } +} + +// 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")) + // 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") || (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) + } +} + +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) + } + // 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) + } + 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) + } + } +} + +// 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_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) != 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) + } +} + +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: is larger than 16 MiB") { + 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") + } + src := t.TempDir() + writeFile(t, filepath.Join(src, "doc/SKILL.md"), skillMD("doc")) + writeFile(t, filepath.Join(src, `doc/a\b.txt`), "x") + c, err := (&Builder{Source: src}).Build() + if err != nil { + t.Fatal(err) + } + if data, err := c.Read("skill://doc/a%5Cb.txt"); err != nil || string(data) != "x" { + t.Errorf("Read = %q, %v; want the listed file", data, err) + } +} diff --git a/internal/skillserve/server.go b/internal/skillserve/server.go new file mode 100644 index 000000000..5efe2ce1f --- /dev/null +++ b/internal/skillserve/server.go @@ -0,0 +1,226 @@ +package skillserve + +import ( + "context" + "crypto/subtle" + "errors" + "fmt" + "io" + "mime" + "net/http" + "path" + "sort" + "strings" + "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. Cross-origin browser requests are +// refused, so a web page cannot reach a loopback server that has no token. +func HTTPHandler(srv *mcp.Server, token string) http.Handler { + h := mcp.NewStreamableHTTPHandler(func(*http.Request) *mcp.Server { return srv }, &mcp.StreamableHTTPOptions{ + Stateless: true, + CrossOriginProtection: http.NewCrossOriginProtection(), + }) + 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 + } + // 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 != "" { + if !strings.HasPrefix(p.Cursor, "skill://") { + return nil, invalidParams("invalid cursor") + } + 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]} + if end < len(c.Skills) { + res.NextCursor = c.Skills[end-1].URI + } + 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..4224a676a --- /dev/null +++ b/internal/skillserve/server_test.go @@ -0,0 +1,217 @@ +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) + } +} + +// 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"}) + 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) + } + } +} + +// A web page in the browser must not reach a loopback server that has no token. +func TestHTTPHandler_RejectsCrossOriginBrowserRequests(t *testing.T) { + srv, err := NewServer(&Builder{Source: t.TempDir()}, Options{}) + if err != nil { + t.Fatal(err) + } + req := httptest.NewRequest(http.MethodPost, "http://127.0.0.1:8765/", strings.NewReader(`{}`)) + req.Header.Set("Origin", "https://evil.example") + req.Header.Set("Sec-Fetch-Site", "cross-site") + rec := httptest.NewRecorder() + HTTPHandler(srv, "").ServeHTTP(rec, req) + if rec.Code != http.StatusForbidden { + t.Errorf("cross-origin request: status %d, want 403", 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/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 } 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..bc27048c5 100644 --- a/internal/utils/frontmatter.go +++ b/internal/utils/frontmatter.go @@ -2,6 +2,8 @@ package utils import ( "bufio" + "bytes" + "encoding/json" "fmt" "os" "path/filepath" @@ -211,6 +213,48 @@ func extractFrontmatterRaw(filePath string) string { return strings.Join(lines, "\n") } +// 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) { + content = bytes.TrimPrefix(content, []byte("\xef\xbb\xbf")) + // 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.TrimRight(line, "\r\n")) == "---" { // also exactly --- + end = pos + break + } + pos += len(line) + } + if start < 0 { + return nil, fmt.Errorf("no frontmatter at the start") + } + if end < 0 { + return nil, fmt.Errorf("unclosed frontmatter: no closing ---") + } + raw := string(content[start:end]) + if strings.TrimSpace(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) + } + // A non-string key decodes to map[any]any, which JSON cannot carry. + if _, err := json.Marshal(fm); err != nil { + return nil, fmt.Errorf("frontmatter JSON cannot carry: %w", err) + } + return fm, nil +} + // ParseFrontmatterFields reads a SKILL.md file once and returns the values of // multiple frontmatter fields. This avoids opening the same file repeatedly // when multiple fields are needed (e.g. description + license). 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) + } +} 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..bef37acff 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 [--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 ``` ## Automation rules @@ -50,6 +52,18 @@ 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, 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` 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 + 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..a9e62fab2 --- /dev/null +++ b/tests/integration/mcp_serve_test.go @@ -0,0 +1,209 @@ +//go:build !online + +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" +) + +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") +} + +// 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() + sb.WriteConfig("source: " + sb.SourcePath + "\ntargets: {}\n") + + r := sb.RunCLI("mcp", "serve", "--target", "nope") + + // stdout is the protocol stream, so the error goes to stderr alone. + r.AssertFailure(t) + r.AssertErrorContains(t, `unknown target "nope"`) + if r.Stdout != "" { + 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) + } +} 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..51e8468f2 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,50 @@ 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 })); + }); + + // A root under mcp.projects is served from the global config, where its targets live, so no -p. + it("serves a project's own target selection from the global config", async () => { + const user = userEvent.setup(); + vi.mocked(api.listTargets).mockResolvedValue({ + targets: [ + { name: 'claude', skillsEnabled: true }, + { name: 'app@claude', project: '/work/app', skillsEnabled: true }, + { name: 'web@claude', project: '/work/web', skillsEnabled: true }, + ] as Target[], + sourceSkillCount: 1, + }); + renderDialog({ serve: true, project: '/work/app' }); + await user.click(screen.getByRole('combobox', { name: 'Skills to serve' })); + const own = await screen.findByRole('option', { name: 'Same as target app@claude' }); + expect(screen.queryByRole('option', { name: 'Same as target web@claude' })).not.toBeInTheDocument(); + await user.click(own); + await user.click(screen.getByRole('button', { name: 'Save' })); + 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 }); + 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..4917ba968 100644 --- a/ui/src/components/mcp/MCPServerDialog.tsx +++ b/ui/src/components/mcp/MCPServerDialog.tsx @@ -1,6 +1,8 @@ import { useContext, useState } from 'react'; import { Check, KeyRound, Link2, Plus, SquareTerminal, X } from 'lucide-react'; import { mcpApi, mcpOffTargets, type MCPMutation, type MCPServer } from '../../api/mcp'; +import { useAvailableTargetsQuery, useSyncedTargetsQuery } from '../../hooks/useSharedQueries'; +import { shortenHome } from '../../lib/paths'; import AgentIcon from '../AgentIcon'; import Button from '../Button'; import DialogShell from '../DialogShell'; @@ -13,7 +15,20 @@ 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. + * A root under mcp.projects adds its own project targets (app@claude), which live in the global config too. + */ +function useSkillTargets(enabled: boolean, project?: string) { + const own = useSyncedTargetsQuery({ enabled }); + const tools = useAvailableTargetsQuery({ enabled }); + const on = (own.data?.targets ?? []).filter((x) => x.skillsEnabled && (!x.project || (project !== undefined && shortenHome(x.project) === shortenHome(project)))); + // A target syncs skills to its Agent, named after the @ in a project target; a tool also reads other targets' folders (universal's ~/.agents/skills). + const synced = new Set([...on.map((x) => x.agent ?? x.name.slice(x.name.lastIndexOf('@') + 1)), ...(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 +83,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 +100,8 @@ interface ServerFormProps { order: readonly string[]; visibleTargets: Set; isProject: boolean; + project?: string; + serve: boolean; onMode: Props['onMode']; onSave: () => Promise; error: string; @@ -92,23 +111,28 @@ 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, project, serve, onMode, onSave, error, probe, mutation }: ServerFormProps) { const t = useT(); + const { isProjectMode } = useAppContext(); const { name, http, targets } = draft; const { nameError } = validation; const selectedTargets = new Set(targets); + const skillTargets = useSkillTargets(serve, project); + 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 +141,17 @@ function ServerForm({ draft, validation, patch, off, saving, editing, order, vis {nameError && {nameError}}
- {!off && ( + {serve && ( +