Files
skillshare/internal/mcp/model.go
T
Willie f837f0e94d feat(mcp): turn off a global server for Pi from the project switch
A Pi project entry replaces the global one and is skipped without a
command or url, so a switch-only entry left the server on in Pi and the
project page could not turn it off there. Reporters want a server off in
one project while every other project keeps loading it.

For a project under mcp.projects, the switch now writes the global
server's command, or its url without the query, with enabled: false to
the project's .pi/mcp.json. A disabled server never starts, so args, env
and headers stay out of a file that may be committed, and every sync
rewrites the entry from the global server. A project's own config cannot
see the global server, so pi there is still refused. The migration that
dropped pi from switch-only entries is gone.

Refs #305
2026-10-01 16:08:23 +08:00

431 lines
16 KiB
Go

// Package mcp manages portable MCP declarations and native client configuration.
// It never starts servers, resolves credentials, or performs network requests, except
// for the live probe that `mcp check --live` asks for explicitly.
package mcp
import (
"bytes"
"encoding/json"
"fmt"
"net/url"
"regexp"
"slices"
"strings"
"gopkg.in/yaml.v3"
)
// Value is either a literal or a reference resolved by the receiving client.
type Value struct {
Literal string `json:"-" yaml:"-"`
FromEnv string `json:"fromEnv,omitempty" yaml:"fromEnv,omitempty"`
}
func (v *Value) UnmarshalYAML(n *yaml.Node) error {
if n.Kind == yaml.ScalarNode && n.Tag == "!!str" {
v.Literal = n.Value
return nil
}
if n.Kind != yaml.MappingNode || len(n.Content) != 2 || n.Content[0].Value != "fromEnv" || n.Content[1].Tag != "!!str" {
return fmt.Errorf("expected a string or {fromEnv: VARIABLE}")
}
v.FromEnv = n.Content[1].Value
if !envName.MatchString(v.FromEnv) {
return fmt.Errorf("invalid environment variable name")
}
return nil
}
func (v Value) MarshalYAML() (any, error) {
if v.FromEnv != "" {
return map[string]string{"fromEnv": v.FromEnv}, nil
}
return v.Literal, nil
}
func (v *Value) UnmarshalJSON(data []byte) error {
if len(data) > 0 && data[0] == '"' {
return json.Unmarshal(data, &v.Literal)
}
var ref struct {
FromEnv string `json:"fromEnv"`
}
d := json.NewDecoder(strings.NewReader(string(data)))
d.DisallowUnknownFields()
if err := d.Decode(&ref); err != nil {
return fmt.Errorf("expected a string or environment reference")
}
if !envName.MatchString(ref.FromEnv) {
return fmt.Errorf("invalid environment variable name")
}
v.FromEnv = ref.FromEnv
return nil
}
func (v Value) MarshalJSON() ([]byte, error) {
if v.FromEnv != "" {
return json.Marshal(map[string]string{"fromEnv": v.FromEnv})
}
return json.Marshal(v.Literal)
}
// Server contains only settings that have explicit native adapter mappings.
type Server struct {
Transport string `yaml:"transport,omitempty" json:"transport,omitempty"`
Command string `yaml:"command,omitempty" json:"command,omitempty"`
Args []string `yaml:"args,omitempty" json:"args,omitempty"`
URL string `yaml:"url,omitempty" json:"url,omitempty"`
Env map[string]Value `yaml:"env,omitempty" json:"env,omitempty"`
Headers map[string]Value `yaml:"headers,omitempty" json:"headers,omitempty"`
BearerToken *Value `yaml:"bearerToken,omitempty" json:"bearerToken,omitempty"`
Targets TargetList `yaml:"targets,omitempty" json:"targets,omitzero"`
// Tools is which of the server's tools reach the model, translated per Agent.
Tools ToolPolicy `yaml:"tools,omitempty" json:"tools,omitzero"`
// PiOptions are Pi built-in fields Skillshare has no setting for, such as timeout.
// They are written into Pi's entry as given.
PiOptions PiOptions `yaml:"piOptions,omitempty" json:"piOptions,omitempty"`
// Disabled is the whole entry: it turns off, for one project, a server that the
// Agent's global config defines. Unselecting an Agent already covers a server
// Skillshare defines, so a disabled server carries no command or url.
Disabled bool `yaml:"disabled,omitempty" json:"disabled,omitempty"`
// global is the global server a project's switch-only entry turns off, when the plan
// knows it. Pi needs its command or url to take the switch.
global *Server
}
// legacyServerFields chose Pi's MCP extension and opted in to pruning Pi fields, before
// 0.23.0 made Pi use its built-in MCP and always prune. A config that still has them loads,
// and saving it drops them.
var legacyServerFields = []string{"piExtension", "piOptionsPrune"}
// UnmarshalJSON ignores legacyServerFields and converts directTools as loading does, so a
// dashboard that still sends them can save.
func (s *Server) UnmarshalJSON(data []byte) error {
var fields map[string]json.RawMessage
if err := json.Unmarshal(data, &fields); err != nil {
return err
}
for _, key := range legacyServerFields {
delete(fields, key)
}
var directTools any
if raw, ok := fields["directTools"]; ok {
_ = json.Unmarshal(raw, &directTools)
delete(fields, "directTools")
}
data, err := json.Marshal(fields)
if err != nil {
return err
}
type plain Server
d := json.NewDecoder(bytes.NewReader(data))
d.DisallowUnknownFields()
if err := d.Decode((*plain)(s)); err != nil {
return err
}
s.adoptAdapterTools(directTools, nil, nil)
return nil
}
// adapterPiOptions are pi-mcp-adapter server fields that Pi's built-in MCP (0.99.0) does
// not read. Before 0.23.0 they reached the adapter's file through piOptions.
var adapterPiOptions = []string{"approveTools", "auth", "bearerToken", "bearerTokenEnv", "bearerTokenStore", "caFile", "debug", "exposeResources", "idleTimeout", "inheritEnv", "lifecycle", "protocolVersion", "requestHeadersCommand", "requestTimeoutMs", "searchKeywords", "socket", "tasks", "toolPrefix", "trace"}
func deref(n *yaml.Node) *yaml.Node {
if n != nil && n.Kind == yaml.AliasNode {
return n.Alias
}
return n
}
// migration is what migrateServers needs to know about a servers mapping's scope.
type migration struct {
// piAccounts are the account targets whose Agent is Pi.
piAccounts []string
// directTools is the scope's pi-mcp-adapter default, mcp.directTools or a project's,
// for the servers that reach Pi and set none; defaults are the scope's targets.
directTools any
defaults []string
}
// reachesPi reports a server whose targets, its own or the scope's, include Pi.
func (m migration) reachesPi(server *yaml.Node) bool {
targets := m.defaults
if n := deref(field(server, "targets")); n != nil {
targets = nil
_ = n.Decode(&targets)
}
return slices.ContainsFunc(targets, func(t string) bool { return t == "pi" || slices.Contains(m.piAccounts, t) })
}
// migrateServers rewrites, in place, what 0.23.0 retired in every server of a servers
// mapping, and names the servers each change touched, keyed by what changed:
// - legacyServerFields are dropped; a piExtension that chose pi-mcp-adapter or
// pi-mcp-extension is also keyed "piExtension.<extension>";
// - pi-mcp-adapter piOptions are dropped, keyed "piOptions.<field>";
// - directTools and piOptions includeTools/excludeTools become Pi exposure settings or
// tools (adoptAdapterTools), keyed "piTools", or are dropped, keyed "piTools.<field>".
func migrateServers(servers *yaml.Node, m migration) map[string][]string {
found := map[string][]string{}
servers = deref(servers)
if servers == nil || servers.Kind != yaml.MappingNode {
return found
}
for i := 0; i+1 < len(servers.Content); i += 2 {
name, server := servers.Content[i].Value, deref(servers.Content[i+1])
if server.Kind != yaml.MappingNode {
continue
}
for _, key := range legacyServerFields {
if n := deref(field(server, key)); n != nil {
if key == "piExtension" && (n.Value == "pi-mcp-adapter" || n.Value == "pi-mcp-extension") {
found[key+"."+n.Value] = append(found[key+"."+n.Value], name)
}
drop(server, key)
found[key] = append(found[key], name)
}
}
if options := deref(field(server, "piOptions")); options != nil && options.Kind == yaml.MappingNode {
for _, key := range adapterPiOptions {
if field(options, key) != nil {
drop(options, key)
found["piOptions."+key] = append(found["piOptions."+key], name)
}
}
}
if dropped, ok := migrateAdapterTools(server, m); ok {
found["piTools"] = append(found["piTools"], name)
for _, key := range dropped {
found["piTools."+key] = append(found["piTools."+key], name)
}
}
if options := deref(field(server, "piOptions")); options != nil && options.Kind == yaml.MappingNode && len(options.Content) == 0 {
drop(server, "piOptions")
}
}
return found
}
// migrateAdapterTools converts one server's directTools, or the scope's when it reaches Pi
// and sets none, and its piOptions includeTools/excludeTools. It reports whether the server
// had any, and which of them it dropped.
func migrateAdapterTools(server *yaml.Node, m migration) ([]string, bool) {
var directTools any
var include, exclude []any
had := false
disabled := deref(field(server, "disabled"))
if n := field(server, "directTools"); n != nil {
_ = n.Decode(&directTools)
drop(server, "directTools")
had = true
} else if m.directTools != nil && m.directTools != false && disabled == nil && m.reachesPi(server) {
directTools = m.directTools
}
options := deref(field(server, "piOptions"))
if options != nil && options.Kind == yaml.MappingNode {
for key, list := range map[string]*[]any{"includeTools": &include, "excludeTools": &exclude} {
if n := field(options, key); n != nil {
if n.Decode(list) != nil || *list == nil {
*list = []any{}
}
drop(options, key)
had = true
}
}
}
if !had && directTools == nil {
return nil, false
}
// Only what decides the conversion is decoded; the rest of the node stays as written.
var draft Server
if n := field(server, "tools"); n != nil && n.Decode(&draft.Tools) != nil {
draft.Tools.Deny = []string{"unreadable"} // still counts as set
}
for _, key := range []string{"exposure", "toolExposure"} {
if options != nil && field(options, key) != nil {
if draft.PiOptions == nil {
draft.PiOptions = PiOptions{}
}
draft.PiOptions[key] = true
}
}
draft.Disabled = disabled != nil && disabled.Value == "true"
before := draft
dropped := draft.adoptAdapterTools(directTools, include, exclude)
if before.Tools.IsZero() && !draft.Tools.IsZero() {
_ = put(server, "tools", draft.Tools)
}
for _, key := range []string{"exposure", "toolExposure"} {
if value, set := draft.PiOptions[key]; set && before.PiOptions[key] == nil {
if options == nil || options.Kind != yaml.MappingNode {
_ = put(server, "piOptions", map[string]any{})
options = field(server, "piOptions")
}
_ = put(options, key, value)
}
}
return dropped, true
}
// TargetList tells a missing list from an empty one. Missing inherits mcp.targets; empty
// keeps the server in Skillshare and writes it to no Agent, so it has to survive a save.
type TargetList []string
// IsZero makes yaml's omitempty drop only a missing list.
func (t TargetList) IsZero() bool { return t == nil }
var envName = regexp.MustCompile(`^[A-Za-z_][A-Za-z0-9_]*$`)
var serverName = regexp.MustCompile(`^[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}$`)
// Targets are MCP clients, independently of installed skill targets.
var Targets = []string{"claude", "codex", "cursor", "vscode", "opencode", "kilocode", "grok", "antigravity", "amp", "claude-desktop", "cline", "copilot", "factory", "gemini", "goose", "junie", "kiro", "lmstudio", "warp", "windsurf", "pi"}
func hasInterpolation(value string) bool {
return strings.Contains(value, "${") || strings.Contains(value, "{env:") || strings.Contains(value, "{file:")
}
// openCodeFormat reports the clients that read OpenCode's config shape: Kilo Code is an
// OpenCode fork and keeps the same "mcp" section, entry fields and {env:} references.
func openCodeFormat(target string) bool { return target == "opencode" || target == "kilocode" }
func validTarget(target string) bool {
for _, name := range Targets {
if name == target {
return true
}
}
return false
}
// Account is a target that is another config directory of a built-in Agent, such as a
// second Claude account. Its servers are written in that Agent's format, into Dir.
type Account struct {
Agent string `json:"agent"`
Dir string `json:"configDir"`
}
// accountAgents are the Agents whose MCP file follows their config directory.
var accountAgents = []string{"claude", "codex", "pi"}
var accountName = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9._-]*$`)
// validateTargets knows the built-in Agents only. Another name may be an account, which
// the config's targets section declares, so Source.checkTargets settles it.
func validateTargets(targets []string) error {
seen := map[string]bool{}
for _, target := range targets {
if !validTarget(target) && !accountName.MatchString(target) {
return fmt.Errorf("unsupported MCP target %q", target)
}
if seen[target] {
return fmt.Errorf("duplicate MCP target %q", target)
}
seen[target] = true
}
return nil
}
// Validate checks a portable server without executing or connecting to it.
func (s Server) Validate(name string) error {
for key := range s.Env {
if !envName.MatchString(key) {
return fmt.Errorf("MCP %s: invalid environment variable name", name)
}
}
if !serverName.MatchString(name) {
return fmt.Errorf("invalid MCP name %q: use letters, digits, dots, underscores or hyphens", name)
}
if err := s.validatePiOptions(name); err != nil {
return err
}
if !s.Tools.IsZero() {
switch {
case s.Disabled:
return fmt.Errorf("MCP %s: tools cannot be set on a disabled entry; it only switches the server off", name)
case s.PiOptions["toolExposure"] != nil:
return fmt.Errorf("MCP %s: tools and piOptions.toolExposure both set which tools Pi shows; keep it in tools", name)
}
if err := s.Tools.validate(name); err != nil {
return err
}
}
if s.Disabled {
if s.Command != "" || s.URL != "" || s.Transport != "" || s.BearerToken != nil || len(s.Args)+len(s.Env)+len(s.Headers) > 0 {
return fmt.Errorf("MCP %s: disabled turns off a server the Agent already has; leave out its command, url and settings", name)
}
return validateTargets(s.Targets)
}
if (s.Command == "") == (s.URL == "") {
return fmt.Errorf("MCP %s requires exactly one of command or url", name)
}
if err := validateTargets(s.Targets); err != nil {
return err
}
if s.Transport != "" && s.Transport != "stdio" && s.Transport != "streamable-http" {
return fmt.Errorf("MCP %s: unsupported transport %q", name, s.Transport)
}
if s.URL != "" {
u, err := url.Parse(s.URL)
if err != nil || u.Host == "" || (u.Scheme != "http" && u.Scheme != "https") || u.User != nil || u.Fragment != "" {
return fmt.Errorf("MCP %s requires an HTTP(S) URL without embedded credentials or fragment", name)
}
for key := range u.Query() {
if sensitiveKey.MatchString(key) {
return fmt.Errorf("MCP %s: put credentials in environment-backed headers, not URL parameters", name)
}
}
if s.Transport == "stdio" || len(s.Args) > 0 || len(s.Env) > 0 {
return fmt.Errorf("MCP %s: remote servers cannot have stdio settings", name)
}
} else if s.Transport == "streamable-http" || len(s.Headers) > 0 || s.BearerToken != nil {
return fmt.Errorf("MCP %s: stdio servers cannot have HTTP settings", name)
}
if s.BearerToken != nil && !envName.MatchString(s.BearerToken.FromEnv) {
return fmt.Errorf("MCP %s: bearerToken requires fromEnv", name)
}
for _, values := range []map[string]Value{s.Env, s.Headers} {
for key, v := range values {
if sensitiveKey.MatchString(key) && v.FromEnv == "" {
return fmt.Errorf("MCP %s: sensitive settings require fromEnv", name)
}
if hasInterpolation(v.Literal) {
return fmt.Errorf("MCP %s: use fromEnv instead of client-specific interpolation", name)
}
if v.FromEnv != "" && (!envName.MatchString(v.FromEnv) || v.Literal != "") {
return fmt.Errorf("MCP %s: invalid environment reference", name)
}
}
}
for _, value := range append([]string{s.Command, s.URL}, s.Args...) {
if hasInterpolation(value) {
return fmt.Errorf("MCP %s: command, args and URL must be portable literals", name)
}
}
for key, v := range s.Headers {
if strings.EqualFold(key, "Authorization") {
if s.BearerToken != nil {
return fmt.Errorf("MCP %s: choose bearerToken or Authorization, not both", name)
}
if v.FromEnv == "" {
return fmt.Errorf("MCP %s: Authorization requires an environment reference", name)
}
}
}
return nil
}
// usesEnv reports whether any value is read from the environment when the Agent starts.
func (s Server) usesEnv() bool {
if s.BearerToken != nil && s.BearerToken.FromEnv != "" {
return true
}
for _, values := range []map[string]Value{s.Env, s.Headers} {
for _, v := range values {
if v.FromEnv != "" {
return true
}
}
}
return false
}