feat(mcp): serve skills over MCP with the SEP-2640 Skills extension

Agents on a disposable VM, in a hosted assistant or behind an MCP gateway can
reach an MCP endpoint but not the folder skills sync to, so they got tools and
none of the user's skills (#428).

`skillshare mcp serve` is a read-only server for the skills skillshare already
manages. It declares io.modelcontextprotocol/skills and implements skills/list,
skills/get and resources/read: one entry per skill, its URI from the source
path, the full frontmatter, and every file with a sha256 digest and size.
--target applies that target's selection, and the source is reread at most
every 5 seconds so install, update, enable and disable show up without a
restart; unchanged files keep their digest. stdio is the default; --http
serves Streamable HTTP and needs SKILLSHARE_MCP_TOKEN off loopback.

Skills the extension cannot carry are skipped with a warning instead of being
published incomplete: a name that breaks the Agent Skills rules or differs from
its directory, more than 512 files or 16 MiB, or a nested skill that is not
served. --check lists them without serving. The naming rules moved to
internal/skillpkg so sync and the server share them.

Few clients support the extension yet, so the server also offers list_skills
and read_skill tools. A client that declares the extension does not see them,
so it never gets each skill twice.

sync.SelectTargetSkills is the one place that turns discovered skills into a
target's selection (enabled, include/exclude, frontmatter targets).

Refs: #428
This commit is contained in:
Willie
2026-10-06 14:18:16 +08:00
parent 71b7c79aad
commit cc7d802411
25 changed files with 1698 additions and 47 deletions
+2 -2
View File
@@ -38,7 +38,7 @@ _skillshare() {
local unlink_flags="--help -h"
local list_flags="--verbose -v --json -j --no-tui --type -t --status --sort -s --all --help -h"
local sync_flags="--all --dry-run -n --force -f --json --quiet -q --help -h"
local mcp_flags="--tools-allow --tools-deny --pi-options --url --target --from --file --sync --replace --disabled --keep-files --revision --dry-run -n --json --no-tui --no-dns --live --timeout --help -h"
local mcp_flags="--tools-allow --tools-deny --pi-options --url --target --from --file --sync --replace --disabled --keep-files --revision --dry-run -n --json --no-tui --no-dns --live --timeout --http --check --help -h"
local status_flags="--json --help -h"
local hooks_flags="--file --from --sync --replace --keep-files --revision --dry-run -n --json --help -h"
local diff_flags="--no-tui --patch --stat --json --help -h"
@@ -256,7 +256,7 @@ _skillshare() {
list) COMPREPLY=($(compgen -W "${list_flags} ${global_flags}" -- "${cur}")) ;;
sync) COMPREPLY=($(compgen -W "${sync_flags} ${global_flags}" -- "${cur}")) ;;
plugin) COMPREPLY=($(compgen -W "add discover import list inspect sync check update enable disable remove --target --from --plugin --name --source-ref --entry --revision --dry-run -n --json --no-tui --help -h ${global_flags}" -- "${cur}")) ;;
mcp) COMPREPLY=($(compgen -W "add check edit import list remove restore ${mcp_flags} ${global_flags}" -- "${cur}")) ;;
mcp) COMPREPLY=($(compgen -W "add check edit import list remove restore serve ${mcp_flags} ${global_flags}" -- "${cur}")) ;;
status) COMPREPLY=($(compgen -W "${status_flags} ${global_flags}" -- "${cur}")) ;;
hooks) COMPREPLY=($(compgen -W "add disable edit enable import list remove restore sync ${hooks_flags} ${global_flags}" -- "${cur}")) ;;
diff) COMPREPLY=($(compgen -W "${diff_flags} ${global_flags}" -- "${cur}")) ;;
+3 -1
View File
@@ -52,6 +52,8 @@ complete -c skillshare -n '__fish_skillshare_using_command mcp' -l pi-options -r
complete -c skillshare -n '__fish_skillshare_using_command mcp' -l no-dns -d 'Skip host lookups'
complete -c skillshare -n '__fish_skillshare_using_command mcp' -l live -d 'check: start or call each server'
complete -c skillshare -n '__fish_skillshare_using_command mcp' -l timeout -r -d 'check --live: per-server timeout'
complete -c skillshare -n '__fish_skillshare_using_command mcp' -l http -r -d 'serve: Streamable HTTP listen address'
complete -c skillshare -n '__fish_skillshare_using_command mcp' -l check -d 'serve: list skipped skills without serving'
complete -c skillshare -n '__fish_skillshare_using_command mcp' -l url -r -d 'MCP endpoint'
complete -c skillshare -n '__fish_skillshare_using_command mcp' -l target -r -a 'claude codex cursor vscode opencode kilocode grok antigravity amp claude-desktop cline copilot factory gemini goose junie kiro lmstudio warp windsurf pi omp' -d 'Receiving client'
complete -c skillshare -n '__fish_skillshare_using_command mcp' -l from -r -a 'claude codex cursor vscode opencode kilocode grok antigravity amp claude-desktop cline copilot factory gemini goose junie kiro lmstudio warp windsurf pi omp' -d 'Import client'
@@ -65,7 +67,7 @@ complete -c skillshare -n '__fish_skillshare_using_command mcp' -l dry-run -s n
complete -c skillshare -n '__fish_skillshare_using_command mcp' -l json -d 'JSON output'
complete -c skillshare -n '__fish_skillshare_using_command mcp' -l no-tui -d 'Disable interactive menus'
complete -c skillshare -n '__fish_skillshare_using_command mcp' -l help -s h -d 'Show help'
complete -c skillshare -n '__fish_skillshare_using_command mcp' -a 'add check edit import list remove restore'
complete -c skillshare -n '__fish_skillshare_using_command mcp' -a 'add check edit import list remove restore serve'
complete -c skillshare -n __fish_skillshare_no_subcommand -a hooks -d 'Manage Agent hooks'
complete -c skillshare -n '__fish_skillshare_using_command hooks' -a 'add disable edit enable import list remove restore sync'
complete -c skillshare -n '__fish_skillshare_using_command hooks' -l file -r -F -d 'Entry or native file'
+3 -1
View File
@@ -50,7 +50,7 @@ def "nu-complete skillshare plugin" [] {
}
def "nu-complete skillshare mcp" [] {
[add check edit import list remove restore]
[add check edit import list remove restore serve]
}
def "nu-complete skillshare mcp-target" [] {
@@ -89,6 +89,8 @@ export extern "skillshare mcp" [
--no-dns # Skip host lookups
--live # check: start or call each server
--timeout: string # check --live: per-server timeout, such as 10s
--http: string # serve: Streamable HTTP listen address
--check # serve: list skipped skills without serving
--no-tui
--project(-p)
--global(-g)
+2 -1
View File
@@ -54,6 +54,7 @@ $_skillshareCompleter = {
@{ Name = 'list'; Desc = 'MCP list' }
@{ Name = 'remove'; Desc = 'MCP remove' }
@{ Name = 'restore'; Desc = 'MCP restore' }
@{ Name = 'serve'; Desc = 'MCP serve' }
)
'hooks' = @(
@{ Name = 'add'; Desc = 'Hooks add' }
@@ -207,7 +208,7 @@ $_skillshareCompleter = {
'enable' = '--dry-run', '-n', '--kind', '--help', '-h', '--project', '-p', '--global', '-g'
'disable' = '--dry-run', '-n', '--kind', '--help', '-h', '--project', '-p', '--global', '-g'
'analyze' = '--verbose', '-v', '--filter', '--no-tui', '--json', '--help', '-h', '--project', '-p', '--global', '-g'
'mcp' = '--tools-allow', '--tools-deny', '--pi-options', '--target', '--from', '--url', '--file', '--sync', '--replace', '--disabled', '--keep-files', '--revision', '--dry-run', '-n', '--json', '--no-dns', '--live', '--timeout', '--no-tui', '--help', '-h', '--project', '-p', '--global', '-g'
'mcp' = '--tools-allow', '--tools-deny', '--pi-options', '--target', '--from', '--url', '--file', '--sync', '--replace', '--disabled', '--keep-files', '--revision', '--dry-run', '-n', '--json', '--no-dns', '--live', '--timeout', '--http', '--check', '--no-tui', '--help', '-h', '--project', '-p', '--global', '-g'
'plugin' = '--target', '--from', '--plugin', '--name', '--source-ref', '--entry', '--revision', '--dry-run', '-n', '--json', '--no-tui', '--help', '-h', '--project', '-p', '--global', '-g'
'extras memory' = '--from', '--version', '--search', '--update-mode', '--json', '--help', '-h', '--project', '-p', '--global', '-g'
'extras' = '--mode', '--target', '--source', '--file', '--as', '--flatten', '--no-flatten', '--add-target', '--remove-target', '--prune', '--from', '--dry-run', '--force', '-f', '--json', '--no-tui', '--help', '-h', '--project', '-p', '--global', '-g'
+3 -1
View File
@@ -96,7 +96,7 @@ _skillshare() {
;;
mcp)
_arguments \
'1:command:(add check edit import list remove restore)' \
'1:command:(add check edit import list remove restore serve)' \
'--tools-allow[Only these tools, comma-separated, * matches any characters; empty clears]:tools:' \
'--tools-deny[Never these tools, comma-separated, * matches any characters; empty clears]:tools:' \
'--pi-options[Other Pi built-in per-server fields as JSON]:json:' \
@@ -115,6 +115,8 @@ _skillshare() {
'--no-dns[Skip host lookups]' \
'--live[check: start or call each server]' \
'--timeout[check --live: per-server timeout]:duration:' \
'--http[serve: Streamable HTTP listen address]:address:' \
'--check[serve: list skipped skills without serving]' \
'--no-tui[Disable interactive menus]' \
$global_flags \
'--help[Show help]' \
+4
View File
@@ -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 <addr> [--target <name>]; global unless -p;\n--check lists skipped skills without serving"},
}},
helpGroup{title: "Options", rows: []helpRow{
{"--target <client>", "Receiving client; repeat for several, or none to keep the\nserver in Skillshare without writing it to any Agent"},
+160
View File
@@ -0,0 +1,160 @@
package main
import (
"context"
"errors"
"fmt"
"net"
"net/http"
"os"
"os/signal"
"strings"
"syscall"
"time"
"github.com/modelcontextprotocol/go-sdk/mcp"
"skillshare/internal/config"
"skillshare/internal/skillserve"
"skillshare/internal/ui"
)
const mcpServeUsage = "skillshare mcp serve [--target <name>] [--http <addr> | --check] [-g|-p]"
// mcpServeTokenEnv holds the bearer token HTTP clients must send.
const mcpServeTokenEnv = "SKILLSHARE_MCP_TOKEN"
// cmdMCPServe serves the managed skills over MCP (SEP-2640). It never writes:
// stdout carries the protocol, so diagnostics go to stderr.
func cmdMCPServe(args []string) error {
mode, rest, err := parseModeArgs(args, "--target", "--http")
if err != nil {
return err
}
var target, addr string
check := false
for i := 0; i < len(rest); i++ {
switch a := rest[i]; a {
case "--check":
check = true
case "--target", "--http":
if i+1 == len(rest) {
return fmt.Errorf("%s requires a value", a)
}
i++
if a == "--target" {
target = rest[i]
} else {
addr = rest[i]
}
default:
return fmt.Errorf("unknown mcp serve argument %q; usage: %s", a, mcpServeUsage)
}
}
if check && addr != "" {
return fmt.Errorf("--check starts no server; drop --http")
}
// A gateway chooses the working directory, so only -p selects project mode.
b := &skillserve.Builder{Target: target}
var targets map[string]config.TargetConfig
if mode == modeProject {
cwd, err := os.Getwd()
if err != nil {
return err
}
rt, err := loadProjectRuntime(cwd)
if err != nil {
return err
}
b.Source, b.Walk, targets = rt.sourcePath, rt.skillsWalk(), rt.targets
} else {
cfg, err := config.Load()
if err != nil {
return err
}
b.Source, b.Walk, targets = cfg.EffectiveSkillsSource(), cfg.SkillsWalk(), cfg.Targets
}
if target != "" {
tc, ok := targets[target]
if !ok {
return fmt.Errorf("unknown target %q", target)
}
sc := tc.SkillsConfig()
if !sc.IsEnabled() {
return fmt.Errorf("target %q has skills disabled", target)
}
b.Skills = &sc
}
if check {
return printMCPServeCheck(b)
}
token := os.Getenv(mcpServeTokenEnv)
if addr != "" && token == "" && !isLoopbackAddr(addr) {
return fmt.Errorf("refusing to serve on %s without authentication: set %s, or bind a loopback address such as 127.0.0.1:8765", addr, mcpServeTokenEnv)
}
srv, err := skillserve.NewServer(b, skillserve.Options{Version: version, Warn: os.Stderr, Refresh: 5 * time.Second})
if err != nil {
return err
}
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
if addr == "" {
return srv.Run(ctx, &mcp.StdioTransport{})
}
ln, err := net.Listen("tcp", addr)
if err != nil {
return err
}
httpSrv := &http.Server{Handler: skillserve.HTTPHandler(srv, token), ReadHeaderTimeout: 10 * time.Second}
go func() {
<-ctx.Done()
httpSrv.Close()
}()
fmt.Fprintf(os.Stderr, "Serving skills over MCP at http://%s/\n", ln.Addr())
if err := httpSrv.Serve(ln); !errors.Is(err, http.ErrServerClosed) {
return err
}
return nil
}
// printMCPServeCheck builds the catalog the server would serve and lists the
// skills it would skip, without starting a server.
func printMCPServeCheck(b *skillserve.Builder) error {
start := time.Now()
c, err := b.Build()
if err != nil {
return err
}
labels := make([]string, len(c.Skipped))
for i, s := range c.Skipped {
labels[i] = s.Path
}
width := ui.RowWidth(labels...)
for _, s := range c.Skipped {
ui.Row(ui.MarkWarn, s.Path, s.Reason, width)
}
text, mark := plural(len(c.Skills), "skill")+" served", ui.MarkOK
if len(c.Skipped) > 0 {
text, mark = text+fmt.Sprintf(", %d skipped", len(c.Skipped)), ui.MarkWarn
}
ui.Done(mark, text, time.Since(start))
return nil
}
// isLoopbackAddr reports whether a listen address only accepts local
// connections. An empty host listens on every interface.
func isLoopbackAddr(addr string) bool {
host, _, err := net.SplitHostPort(addr)
if err != nil || host == "" {
return false
}
if strings.EqualFold(host, "localhost") {
return true
}
ip := net.ParseIP(host)
return ip != nil && ip.IsLoopback()
}