mirror of
https://github.com/runkids/skillshare.git
synced 2026-11-20 20:34:19 +00:00
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:
@@ -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}")) ;;
|
||||
|
||||
@@ -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'
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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'
|
||||
|
||||
@@ -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]' \
|
||||
|
||||
@@ -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"},
|
||||
|
||||
@@ -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()
|
||||
}
|
||||
Reference in New Issue
Block a user