mirror of
https://github.com/runkids/skillshare.git
synced 2026-11-19 02:17:09 +00:00
feat(mcp): write per-Agent native fields from the source (#579)
* feat(mcp): write per-Agent native fields from the source Some MCP settings have no portable form, such as Codex's default_tools_approval_mode or Claude Code's per-server timeout. Sync kept them only while an entry survived, so a recreated entry (for example after a rename) lost them, and every machine needed them added by hand again. A server's `options` now holds these fields per Agent, and sync writes them as given. The field ledger that piOptions used is extended to every Agent, so sync removes an option it wrote once the source drops it, and reports a conflict when the Agent changed it since. Options are refused when they could break the entry or leak a secret: fields Skillshare writes (including portable names some Agents rename), values a native format cannot write back (null, arrays of tables), options.pi (piOptions covers Pi), disabled entries, and credentials as plain text, since the Agent's file may be committed. The dashboard has no editor for options yet but keeps them on save. Refs: #578 * fix(mcp): close gaps in per-Agent options found in review - A credential option passed if it merely contained "${", so text around a reference, or another Agent's syntax, was written out as plain text. It must now be a whole-value reference in the Agent's own syntax, and Codex and Antigravity options, which read no references, cannot hold one. - The Kilo Code project check looked only at portable env references, so an {env:VAR} in options reached a project file Kilo refuses to load. - A replace resolution left the dropped-option conflict in place, so the plan stayed blocked; replace now lets the source win and prunes those fields. - Adopting an entry that already matched skipped writing its options until a later sync; the takeover now writes them. * fix(mcp): refuse numeric credentials and constrain option values in the schema - YAML reads an unquoted secret such as clientSecret: 123456 as a number, which the credential check skipped, so sync wrote it out as plain text. A mapping under a sensitive name such as credentials also hid its plainly named fields. Sensitivity now carries down through mappings and lists, and a number under a sensitive name is refused. - The schema allowed any value inside an Agent's options, so editors accepted null or nested lists that LoadSource then rejects. A recursive optionValue definition now matches the runtime rules. * docs(mcp): name every Agent whose options cannot hold a credential The docs named only Codex and Antigravity, but Claude Desktop, Goose, Junie, LM Studio and Warp read no environment references there either, so a source such as options.goose.apiKey: "${GOOSE_KEY}" looked valid while LoadSource refused it.
This commit is contained in:
@@ -374,6 +374,28 @@ func findRepoRoot(t *testing.T) string {
|
||||
}
|
||||
}
|
||||
|
||||
// The schema accepts only option values sync can write back unchanged, as LoadSource does.
|
||||
func TestSchema_MCPOptionValuesMatchRuntime(t *testing.T) {
|
||||
data, err := os.ReadFile("../../schemas/mcp.schema.json")
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
var schema map[string]any
|
||||
if err := json.Unmarshal(data, &schema); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
defs := schema["$defs"].(map[string]any)
|
||||
options := defs["server"].(map[string]any)["properties"].(map[string]any)["options"].(map[string]any)
|
||||
if options["additionalProperties"].(map[string]any)["additionalProperties"].(map[string]any)["$ref"] != "#/$defs/optionValue" {
|
||||
t.Fatalf("option fields unconstrained: %v", options["additionalProperties"])
|
||||
}
|
||||
scalar, _ := json.Marshal(defs["optionScalar"])
|
||||
value, _ := json.Marshal(defs["optionValue"])
|
||||
if string(scalar) != `{"type":["string","number","boolean"]}` || !strings.Contains(string(value), `"items":{"$ref":"#/$defs/optionScalar"}`) {
|
||||
t.Fatalf("option value allows null or nested lists: %s %s", scalar, value)
|
||||
}
|
||||
}
|
||||
|
||||
func TestSchema_TargetsAllowFiles(t *testing.T) {
|
||||
root := findRepoRoot(t)
|
||||
cases := map[string]func(defs map[string]any) any{
|
||||
|
||||
@@ -84,6 +84,9 @@ type Server struct {
|
||||
// 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"`
|
||||
// Options are other Agents' native per-server fields Skillshare has no setting for, keyed
|
||||
// by Agent, such as Codex's default_tools_approval_mode. They are written as given.
|
||||
Options map[string]map[string]any `yaml:"options,omitempty" json:"options,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.
|
||||
@@ -348,6 +351,9 @@ func (s Server) Validate(name string) error {
|
||||
if err := s.validatePiOptions(name); err != nil {
|
||||
return err
|
||||
}
|
||||
if err := s.validateOptions(name); err != nil {
|
||||
return err
|
||||
}
|
||||
if !s.Tools.IsZero() {
|
||||
switch {
|
||||
case s.Disabled:
|
||||
|
||||
@@ -0,0 +1,128 @@
|
||||
package mcp
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"slices"
|
||||
"strings"
|
||||
)
|
||||
|
||||
var portableFields = []string{"command", "args", "env", "url", "headers", "type", "transport"}
|
||||
|
||||
func (s Server) validateOptions(name string) error {
|
||||
if len(s.Options) == 0 {
|
||||
return nil
|
||||
}
|
||||
if s.Disabled {
|
||||
return fmt.Errorf("MCP %s: options cannot be set on a disabled entry; it only switches the server off", name)
|
||||
}
|
||||
for _, agent := range sortedKeys(s.Options) {
|
||||
switch {
|
||||
case agent == "pi":
|
||||
return fmt.Errorf("MCP %s: options.pi is not used; set Pi's fields in piOptions", name)
|
||||
case !validTarget(agent):
|
||||
return fmt.Errorf("MCP %s: options.%s is not an Agent; use an Agent name such as codex or claude", name, agent)
|
||||
}
|
||||
for _, key := range sortedKeys(s.Options[agent]) {
|
||||
// Some Agents rename the portable fields, such as OpenCode's environment, so both names are refused.
|
||||
if slices.Contains(additionalManagedFields(agent), key) || slices.Contains(portableFields, key) {
|
||||
return fmt.Errorf("MCP %s: options.%s cannot set %s; Skillshare writes that field from the server's own settings", name, agent, key)
|
||||
}
|
||||
if !optionValue(s.Options[agent][key], false) {
|
||||
return fmt.Errorf("MCP %s: options.%s.%s must be a string, number, boolean, list of those, or a mapping of them", name, agent, key)
|
||||
}
|
||||
if field := literalSecret(agent, key, s.Options[agent][key], false); field != "" {
|
||||
if prefix := envRefPrefix(agent); prefix != "" {
|
||||
return fmt.Errorf("MCP %s: options.%s.%s holds a credential as plain text; make the whole value an environment reference, %sVAR}", name, agent, field, prefix)
|
||||
}
|
||||
return fmt.Errorf("MCP %s: options.%s.%s holds a credential, and %s cannot read an environment reference there; keep it out of options", name, agent, field, agent)
|
||||
}
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// optionValue accepts what every native format writes back unchanged: TOML has no null,
|
||||
// and Skillshare's TOML writer refuses an array of tables.
|
||||
func optionValue(value any, inList bool) bool {
|
||||
switch v := value.(type) {
|
||||
case string, bool, int, int64, uint64, float64:
|
||||
return true
|
||||
case []any:
|
||||
for _, item := range v {
|
||||
if inList || !optionValue(item, true) {
|
||||
return false
|
||||
}
|
||||
}
|
||||
return !inList
|
||||
case map[string]any:
|
||||
for _, item := range v {
|
||||
if !optionValue(item, false) {
|
||||
return false
|
||||
}
|
||||
}
|
||||
return !inList
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
// literalSecret names the first field holding a credential as plain text, as import judges
|
||||
// one. The Agent's file may be committed, so only a whole environment reference in the
|
||||
// Agent's own syntax may stand there; text around one would still be written out. Everything
|
||||
// under a sensitive name is sensitive, and a number there is a credential written as plain text.
|
||||
func literalSecret(agent, key string, value any, sensitive bool) string {
|
||||
sensitive = sensitive || sensitiveKey.MatchString(key)
|
||||
switch v := value.(type) {
|
||||
case string:
|
||||
prefix := envRefPrefix(agent)
|
||||
ref := prefix != "" && strings.HasPrefix(v, prefix) && strings.HasSuffix(v, "}") && envName.MatchString(v[len(prefix):len(v)-1])
|
||||
if v != "" && (sensitive || hasURLPassword(v)) && !ref {
|
||||
return key
|
||||
}
|
||||
case int, int64, uint64, float64:
|
||||
if sensitive {
|
||||
return key
|
||||
}
|
||||
case []any:
|
||||
for _, item := range v {
|
||||
if field := literalSecret(agent, key, item, sensitive); field != "" {
|
||||
return field
|
||||
}
|
||||
}
|
||||
case map[string]any:
|
||||
for _, name := range sortedKeys(v) {
|
||||
if field := literalSecret(agent, name, v[name], sensitive); field != "" {
|
||||
return key + "." + field
|
||||
}
|
||||
}
|
||||
}
|
||||
return ""
|
||||
}
|
||||
|
||||
// hasReference reports an interpolation anywhere in an Agent's options.
|
||||
func hasReference(value any) bool {
|
||||
switch v := value.(type) {
|
||||
case string:
|
||||
return hasInterpolation(v)
|
||||
case []any:
|
||||
return slices.ContainsFunc(v, hasReference)
|
||||
case map[string]any:
|
||||
for _, item := range v {
|
||||
if hasReference(item) {
|
||||
return true
|
||||
}
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
// withOptions adds the Agent's options to a rendered entry. A field Render already wrote,
|
||||
// such as Copilot's tools, belongs to the server's own settings.
|
||||
func withOptions(target string, s Server, out map[string]any) (map[string]any, error) {
|
||||
for _, key := range sortedKeys(s.Options[target]) {
|
||||
if _, set := out[key]; set {
|
||||
return nil, fmt.Errorf("options.%s cannot set %s; Skillshare writes that field from the server's own settings", target, key)
|
||||
}
|
||||
out[key] = s.Options[target][key]
|
||||
}
|
||||
return out, nil
|
||||
}
|
||||
@@ -0,0 +1,170 @@
|
||||
package mcp
|
||||
|
||||
import (
|
||||
"os"
|
||||
"path/filepath"
|
||||
"slices"
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
// options carries native per-server fields Skillshare has no setting for, per Agent. Refs: #578.
|
||||
func TestOptionsSyncFollowsSource(t *testing.T) {
|
||||
s := testService(t)
|
||||
sync := func(servers string) (codex, claude string) {
|
||||
t.Helper()
|
||||
config := "mcp:\n targets: [codex, claude]\n servers:\n" + servers
|
||||
if err := os.WriteFile(s.ConfigPath, []byte(config), 0600); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
plan, err := s.Preview()
|
||||
if err != nil || plan.Blocked {
|
||||
t.Fatalf("%+v %v", plan, err)
|
||||
}
|
||||
if _, err := s.Apply(plan.Revision); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
a, _ := os.ReadFile(filepath.Join(s.Home, ".codex", "config.toml"))
|
||||
b, _ := os.ReadFile(filepath.Join(s.Home, ".claude.json"))
|
||||
return string(a), string(b)
|
||||
}
|
||||
options := " options:\n codex:\n default_tools_approval_mode: approve\n claude:\n timeout: 600000\n"
|
||||
codex, claude := sync(" docs:\n url: https://example.com/mcp\n" + options)
|
||||
if !strings.Contains(codex, "default_tools_approval_mode = 'approve'") || strings.Contains(codex, "timeout") {
|
||||
t.Fatalf("codex: %s", codex)
|
||||
}
|
||||
if !strings.Contains(claude, `"timeout": 600000`) || strings.Contains(claude, "approval") {
|
||||
t.Fatalf("claude: %s", claude)
|
||||
}
|
||||
// A recreated entry gets the fields too, which hand-added ones did not.
|
||||
codex, claude = sync(" renamed:\n url: https://example.com/mcp\n" + options)
|
||||
if !strings.Contains(codex, "[mcp_servers.renamed]") || !strings.Contains(codex, "default_tools_approval_mode = 'approve'") || strings.Contains(codex, "[mcp_servers.docs]") {
|
||||
t.Fatalf("codex after rename: %s", codex)
|
||||
}
|
||||
if !strings.Contains(claude, `"timeout": 600000`) || strings.Contains(claude, `"docs"`) {
|
||||
t.Fatalf("claude after rename: %s", claude)
|
||||
}
|
||||
// Dropping an option removes the field sync wrote.
|
||||
codex, claude = sync(" renamed:\n url: https://example.com/mcp\n")
|
||||
if strings.Contains(codex, "default_tools_approval_mode") || strings.Contains(claude, "timeout") {
|
||||
t.Fatalf("options not removed:\n%s\n%s", codex, claude)
|
||||
}
|
||||
}
|
||||
|
||||
// An option the Agent changed since sync is not removed silently when the source drops it.
|
||||
func TestDroppedOptionChangedInAgentConflicts(t *testing.T) {
|
||||
s := testService(t)
|
||||
write := func(config string) *Plan {
|
||||
t.Helper()
|
||||
if err := os.WriteFile(s.ConfigPath, []byte(config), 0600); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
plan, err := s.Preview()
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
return plan
|
||||
}
|
||||
plan := write("mcp:\n targets: [claude]\n servers:\n docs:\n url: https://example.com/mcp\n options:\n claude:\n timeout: 600000\n")
|
||||
if _, err := s.Apply(plan.Revision); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
path := filepath.Join(s.Home, ".claude.json")
|
||||
data, _ := os.ReadFile(path)
|
||||
if err := os.WriteFile(path, []byte(strings.Replace(string(data), "600000", "900000", 1)), 0600); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
plan = write("mcp:\n targets: [claude]\n servers:\n docs:\n url: https://example.com/mcp\n")
|
||||
if !plan.Blocked || !strings.HasPrefix(plan.Changes[0].Message, "Agent setting changed since sync") {
|
||||
t.Fatalf("%+v", plan.Changes)
|
||||
}
|
||||
// An explicit replace lets the source win and removes the field.
|
||||
server := Server{URL: "https://example.com/mcp"}
|
||||
plan, err := s.PreviewMutation(Mutation{Name: "docs", Server: &server, Replace: true, Resolutions: []Resolution{{Target: "claude", Name: "docs", Action: "replace"}}})
|
||||
if err != nil || plan.Blocked || plan.Changes[0].Fields == nil || !slices.Contains(plan.Changes[0].Fields.Removed, "timeout") {
|
||||
t.Fatalf("replace: %+v %v", plan, err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestOptionsRejected(t *testing.T) {
|
||||
for name, server := range map[string]Server{
|
||||
"switch only": {Disabled: true, Options: map[string]map[string]any{"claude": {"timeout": 1}}},
|
||||
"unknown Agent": {URL: "https://example.com", Options: map[string]map[string]any{"nope": {"timeout": 1}}},
|
||||
"pi has piOptions": {URL: "https://example.com", Options: map[string]map[string]any{"pi": {"timeout": 1}}},
|
||||
"a field Skillshare writes": {URL: "https://example.com", Options: map[string]map[string]any{"codex": {"url": "https://other.example"}}},
|
||||
"a portable name Render renames": {Command: "echo", Options: map[string]map[string]any{"opencode": {"args": []any{"x"}}}},
|
||||
"null": {URL: "https://example.com", Options: map[string]map[string]any{"claude": {"timeout": nil}}},
|
||||
"array of tables": {URL: "https://example.com", Options: map[string]map[string]any{"codex": {"x": []any{map[string]any{"a": 1}}}}},
|
||||
} {
|
||||
if err := server.Validate("docs"); err == nil || !strings.Contains(err.Error(), "options") {
|
||||
t.Errorf("%s: got %v", name, err)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// A credential in options reaches the Agent's file, which a project may commit. Refs: #578.
|
||||
func TestOptionsRefusePlainTextSecrets(t *testing.T) {
|
||||
secret := Server{URL: "https://example.com", Options: map[string]map[string]any{"opencode": {"oauth": map[string]any{"clientSecret": "abc"}}}}
|
||||
if err := secret.Validate("docs"); err == nil || !strings.Contains(err.Error(), "options.opencode.oauth.clientSecret") {
|
||||
t.Fatalf("plain text: got %v", err)
|
||||
}
|
||||
reference := Server{URL: "https://example.com", Options: map[string]map[string]any{"opencode": {"oauth": map[string]any{"clientSecret": "{env:DOCS_SECRET}"}}, "claude": {"api_key": "${DOCS_KEY}"}}}
|
||||
if err := reference.Validate("docs"); err != nil {
|
||||
t.Fatalf("environment reference: %v", err)
|
||||
}
|
||||
// Only a whole reference in the Agent's own syntax keeps the secret out of the file.
|
||||
for name, options := range map[string]map[string]map[string]any{
|
||||
"text around a reference": {"opencode": {"api_key": "secret-{env:DOCS_KEY}"}},
|
||||
"another Agent's syntax": {"claude": {"api_key": "{env:DOCS_KEY}"}},
|
||||
"an Agent without references": {"codex": {"api_key": "${DOCS_KEY}"}},
|
||||
// YAML reads an unquoted number as one, and a credentials mapping names its fields plainly.
|
||||
"a number": {"opencode": {"api_key": 123456}},
|
||||
"under a sensitive name": {"opencode": {"api_key": map[string]any{"value": "abc"}}},
|
||||
} {
|
||||
if err := (Server{URL: "https://example.com", Options: options}).Validate("docs"); err == nil || !strings.Contains(err.Error(), "api_key") {
|
||||
t.Errorf("%s: got %v", name, err)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Kilo discards a project file holding any {env:} reference, options included. Refs: #578.
|
||||
func TestKiloCodeProjectRefusesReferencesInOptions(t *testing.T) {
|
||||
s := testService(t)
|
||||
if err := os.WriteFile(s.ConfigPath, []byte("mcp:\n targets: [kilocode]\n servers:\n docs:\n url: https://example.com/mcp\n options:\n kilocode:\n oauth: {clientSecret: \"{env:DOCS_SECRET}\"}\n"), 0600); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
s.ProjectRoot = t.TempDir()
|
||||
if _, err := s.Preview(); err == nil || !strings.Contains(err.Error(), "Kilo") {
|
||||
t.Fatalf("project config must refuse the reference: %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
// Taking over an entry that matches writes the source's options in the same sync. Refs: #578.
|
||||
func TestAdoptionWritesOptions(t *testing.T) {
|
||||
s := testService(t)
|
||||
path := filepath.Join(s.Home, ".claude.json")
|
||||
if err := os.WriteFile(path, []byte(`{"mcpServers":{"docs":{"type":"http","url":"https://example.com/mcp"}}}`), 0600); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if err := os.WriteFile(s.ConfigPath, []byte("mcp:\n targets: [claude]\n servers:\n docs:\n url: https://example.com/mcp\n options:\n claude:\n timeout: 600000\n"), 0600); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
plan, err := s.Preview()
|
||||
if err != nil || plan.Blocked {
|
||||
t.Fatalf("%+v %v", plan, err)
|
||||
}
|
||||
if _, err := s.Apply(plan.Revision); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if data, _ := os.ReadFile(path); !strings.Contains(string(data), `"timeout": 600000`) {
|
||||
t.Fatalf("option not written on takeover: %s", data)
|
||||
}
|
||||
}
|
||||
|
||||
// Copilot's tools list is not a managed field, but Render writes it, so an option cannot replace it.
|
||||
func TestOptionsCannotReplaceRenderedField(t *testing.T) {
|
||||
server := Server{Command: "echo", Options: map[string]map[string]any{"copilot": {"tools": []any{"a"}}}}
|
||||
if _, err := Render("copilot", server); err == nil || !strings.Contains(err.Error(), "options") {
|
||||
t.Fatalf("got %v", err)
|
||||
}
|
||||
}
|
||||
@@ -191,12 +191,12 @@ func importPiOption(name, key string, value any, warnings *[]string) any {
|
||||
|
||||
func piFieldHash(value any) string { data, _ := json.Marshal(value); return digest(data) }
|
||||
|
||||
func piOwnedFields(entry map[string]any) map[string]string {
|
||||
func ownedFields(target string, entry map[string]any) map[string]string {
|
||||
fields := map[string]string{}
|
||||
for key, value := range entry {
|
||||
managed := false
|
||||
for _, field := range additionalManagedFields("pi") {
|
||||
managed = managed || key == field && key != "enabled"
|
||||
for _, field := range additionalManagedFields(target) {
|
||||
managed = managed || key == field && !(target == "pi" && key == "enabled")
|
||||
}
|
||||
if !managed {
|
||||
fields[key] = piFieldHash(value)
|
||||
|
||||
+23
-11
@@ -89,7 +89,9 @@ type ownership struct {
|
||||
Name string `json:"name"`
|
||||
Hash string `json:"hash"`
|
||||
// A nil Root is legacy ownership; an empty root records global scope.
|
||||
Root *string `json:"root,omitempty"`
|
||||
Root *string `json:"root,omitempty"`
|
||||
// PiFields hash the fields outside Hash that this config wrote, such as options, so
|
||||
// sync can remove them once the config stops setting them. Named before it covered every Agent.
|
||||
PiFields map[string]string `json:"piFields,omitempty"`
|
||||
}
|
||||
|
||||
@@ -516,7 +518,7 @@ func (s *Service) checkScope(name, target string, server Server) error {
|
||||
return fmt.Errorf("Claude MCP %s: Claude Code never sends %s to a remote server and reads it as empty; copy the value into a variable with a name of your own and reference that", name, v.FromEnv)
|
||||
}
|
||||
}
|
||||
case target == "kilocode" && s.ProjectRoot != "" && server.usesEnv():
|
||||
case target == "kilocode" && s.ProjectRoot != "" && (server.usesEnv() || hasReference(server.Options["kilocode"])):
|
||||
return fmt.Errorf("Kilo Code MCP %s: Kilo does not allow environment references in project config and ignores the whole file when it finds one; remove fromEnv here or define this server in global mode", name)
|
||||
}
|
||||
return nil
|
||||
@@ -646,16 +648,16 @@ func (s *Service) previewResolved(source *Source, resolutions []Resolution) (*Pl
|
||||
}
|
||||
wantHash := entryHash(managedEntry(target, want))
|
||||
prune := map[string]bool{}
|
||||
pruneConflict := false
|
||||
// Fields this config wrote earlier and no longer sets go, unless Pi changed them since.
|
||||
if target == "pi" && want != nil && managed && owned.Owner == source.ConfigPath {
|
||||
var changed []string
|
||||
// Fields this config wrote earlier and no longer sets go, unless the Agent changed them since.
|
||||
if want != nil && managed && owned.Owner == source.ConfigPath {
|
||||
for field, hash := range owned.PiFields {
|
||||
if _, set := want[field]; set {
|
||||
continue
|
||||
}
|
||||
if value, exists := current[field]; exists {
|
||||
if piFieldHash(value) != hash {
|
||||
pruneConflict = true
|
||||
changed = append(changed, field)
|
||||
} else {
|
||||
prune[field] = true
|
||||
}
|
||||
@@ -680,6 +682,13 @@ func (s *Service) previewResolved(source *Source, resolutions []Resolution) (*Pl
|
||||
owned = ownership{Owner: source.ConfigPath, Target: target, Path: path, Name: name, Hash: currentHash}
|
||||
managed = true
|
||||
p.state.Entries[key] = owned
|
||||
// Replace lets the source win, so the changed fields it no longer sets go too.
|
||||
if resolution.Action == "replace" {
|
||||
for _, field := range changed {
|
||||
prune[field] = true
|
||||
}
|
||||
changed = nil
|
||||
}
|
||||
}
|
||||
change := Change{Target: shown, Path: path, Name: name, Root: changeRoot(target, path, s.ProjectRoot, projectRoots)}
|
||||
if change.Switch = switchOnly(target, want); want == nil {
|
||||
@@ -696,8 +705,8 @@ func (s *Service) previewResolved(source *Source, resolutions []Resolution) (*Pl
|
||||
// records the entry as owned at its current hash, which lets the cases below write
|
||||
// over it.
|
||||
change.Action, change.Message = "conflict", "existing entry is a Pi project override of a global server; replace it, or remove the override with /mcp in Pi"
|
||||
case pruneConflict:
|
||||
change.Action, change.Message = "conflict", "Pi setting changed since sync; import it before removing the cleared setting"
|
||||
case len(changed) > 0:
|
||||
change.Action, change.Message = "conflict", "Agent setting changed since sync; import it before removing the cleared setting"
|
||||
case managed && owned.Owner != source.ConfigPath:
|
||||
change.Action, change.Message = "conflict", "managed by another Skillshare config: "+owned.Owner
|
||||
// A config that is gone can never release the entry, so an explicit resolution
|
||||
@@ -721,6 +730,11 @@ func (s *Service) previewResolved(source *Source, resolutions []Resolution) (*Pl
|
||||
// the takeover and unticking the Agent later removes the entry. Refs: #303.
|
||||
// A switch the person turned off in the Agent stays theirs.
|
||||
change.Action = "adopt"
|
||||
// Options the entry lacks are written on takeover, not left for the next sync.
|
||||
if agentFieldsChanged(target, current, want) {
|
||||
change.Action = "update"
|
||||
f.changes[name] = withAgentFields(target, current, want)
|
||||
}
|
||||
p.state.Entries[key] = ownership{Owner: source.ConfigPath, Target: target, Path: path, Name: name, Hash: currentHash}
|
||||
case currentHash == wantHash:
|
||||
// Already as desired, e.g. after pulling a teammate's change or
|
||||
@@ -758,9 +772,7 @@ func (s *Service) previewResolved(source *Source, resolutions []Resolution) (*Pl
|
||||
if want != nil && change.Action != "conflict" {
|
||||
if own, ok := p.state.Entries[key]; ok && own.Owner == source.ConfigPath {
|
||||
own.Root = &root
|
||||
if target == "pi" {
|
||||
own.PiFields = piOwnedFields(want)
|
||||
}
|
||||
own.PiFields = ownedFields(target, want)
|
||||
p.state.Entries[key] = own
|
||||
}
|
||||
}
|
||||
|
||||
+26
-7
@@ -45,8 +45,33 @@ func renderDisabled(target string, s Server) (map[string]any, error) {
|
||||
return nil, fmt.Errorf("%s cannot turn off a global server from a project file; disabled supports claude, opencode, kilocode, pi and omp", target)
|
||||
}
|
||||
|
||||
// envRefPrefix is how the Agent's file names an environment variable, closed by "}", or ""
|
||||
// for an Agent whose file cannot: Codex forwards variables by name instead.
|
||||
func envRefPrefix(target string) string {
|
||||
switch {
|
||||
case openCodeFormat(target):
|
||||
return "{env:"
|
||||
case target == "claude" || target == "grok":
|
||||
return "${"
|
||||
case target == "codex" || target == "antigravity":
|
||||
return ""
|
||||
}
|
||||
if format, ok := clientFormats[target]; ok {
|
||||
return format.refPrefix
|
||||
}
|
||||
return "${env:"
|
||||
}
|
||||
|
||||
// Render converts a portable definition to a native entry without reading env.
|
||||
func Render(target string, s Server) (map[string]any, error) {
|
||||
out, err := renderEntry(target, s)
|
||||
if err != nil || s.Disabled {
|
||||
return out, err
|
||||
}
|
||||
return withOptions(target, s, out)
|
||||
}
|
||||
|
||||
func renderEntry(target string, s Server) (map[string]any, error) {
|
||||
if !validTarget(target) {
|
||||
return nil, fmt.Errorf("unsupported MCP target %q", target)
|
||||
}
|
||||
@@ -79,13 +104,7 @@ func Render(target string, s Server) (map[string]any, error) {
|
||||
if v.FromEnv == "" {
|
||||
return v.Literal
|
||||
}
|
||||
if openCodeFormat(target) {
|
||||
return "{env:" + v.FromEnv + "}"
|
||||
}
|
||||
if target == "claude" || target == "grok" {
|
||||
return "${" + v.FromEnv + "}"
|
||||
}
|
||||
return "${env:" + v.FromEnv + "}"
|
||||
return envRefPrefix(target) + v.FromEnv + "}"
|
||||
}
|
||||
if s.Command != "" {
|
||||
out["command"] = s.Command
|
||||
|
||||
@@ -276,7 +276,7 @@ func LoadSource(configPath string) (*Source, error) {
|
||||
}
|
||||
note(migrateServers(servers, global), "", s.Path != path)
|
||||
if s.Servers, err = ParseServers(servers); err != nil {
|
||||
return nil, fmt.Errorf("invalid MCP server fields: use command/args/env or url/headers/bearerToken and optional targets/transport/piOptions, or disabled with targets")
|
||||
return nil, fmt.Errorf("invalid MCP server fields: use command/args/env or url/headers/bearerToken and optional targets/transport/tools/options/piOptions, or disabled with targets")
|
||||
}
|
||||
}
|
||||
for name, server := range s.Servers {
|
||||
|
||||
@@ -7,6 +7,8 @@
|
||||
"additionalProperties": false,
|
||||
"properties": {"servers": {"$ref": "#/$defs/servers"}},
|
||||
"$defs": {
|
||||
"optionScalar": {"type": ["string", "number", "boolean"]},
|
||||
"optionValue": {"description": "What every native format writes back unchanged: no null, and a list holds only scalars.", "anyOf": [{"$ref": "#/$defs/optionScalar"}, {"type": "array", "items": {"$ref": "#/$defs/optionScalar"}}, {"type": "object", "additionalProperties": {"$ref": "#/$defs/optionValue"}}]},
|
||||
"targets": {"type": "array", "uniqueItems": true, "items": {"anyOf": [{"enum": ["claude", "codex", "cursor", "vscode", "opencode", "kilocode", "grok", "antigravity", "amp", "claude-desktop", "cline", "copilot", "factory", "gemini", "goose", "junie", "kiro", "lmstudio", "warp", "windsurf", "pi", "omp"]}, {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$", "description": "A target that is another account of an Agent, declared under targets with agent and config_dir. Global config only."}]}},
|
||||
"directTools": {
|
||||
"deprecated": true,
|
||||
@@ -93,11 +95,12 @@
|
||||
"directTools": {"$ref": "#/$defs/directTools"},
|
||||
"tools": {"$ref": "#/$defs/tools"},
|
||||
"piOptions": {"type": "object", "description": "Pi built-in per-server options. Known built-in fields are validated; unknown fields are preserved. pi-mcp-adapter-only fields are refused: set tool lists in tools; exposure and toolExposure cannot be combined with tools."},
|
||||
"options": {"type": "object", "propertyNames": {"enum": ["claude", "codex", "cursor", "vscode", "opencode", "kilocode", "grok", "antigravity", "amp", "claude-desktop", "cline", "copilot", "factory", "gemini", "goose", "junie", "kiro", "lmstudio", "warp", "windsurf", "omp"]}, "additionalProperties": {"type": "object", "additionalProperties": {"$ref": "#/$defs/optionValue"}}, "description": "Native per-server fields of other Agents, keyed by Agent, written into that Agent's entry as given, such as codex: {default_tools_approval_mode: approve} or claude: {timeout: 600000}. Fields Skillshare writes from the server's own settings are refused; values are strings, numbers, booleans, lists of those, or mappings of them. Credentials must be a whole-value environment reference in the Agent's own syntax, such as ${VAR} or {env:VAR}, never plain text; options of Codex, Antigravity, Claude Desktop, Goose, Junie, LM Studio and Warp, which read no references there, cannot hold one. Set Pi's fields in piOptions. Sync removes an option it wrote once the source drops it."},
|
||||
"piOptionsPrune": {"type": "boolean", "deprecated": true, "description": "Ignored since 0.23.0: sync always removes Pi options Skillshare wrote that are unchanged. Saving the config drops it."},
|
||||
"disabled": {"const": true, "description": "Project mode only: turn off a server that the Agent's global config defines. Supported by claude, opencode and kilocode."}
|
||||
},
|
||||
"oneOf": [
|
||||
{"required": ["disabled"], "not": {"anyOf": [{"required": ["directTools"]}, {"required": ["tools"]}, {"required": ["command"]}, {"required": ["url"]}, {"required": ["args"]}, {"required": ["env"]}, {"required": ["headers"]}, {"required": ["bearerToken"]}, {"required": ["transport"]}]}},
|
||||
{"required": ["disabled"], "not": {"anyOf": [{"required": ["directTools"]}, {"required": ["tools"]}, {"required": ["options"]}, {"required": ["command"]}, {"required": ["url"]}, {"required": ["args"]}, {"required": ["env"]}, {"required": ["headers"]}, {"required": ["bearerToken"]}, {"required": ["transport"]}]}},
|
||||
{"required": ["command"], "not": {"anyOf": [{"required": ["disabled"]}, {"required": ["url"]}, {"required": ["headers"]}, {"required": ["bearerToken"]}]}, "properties": {"transport": {"const": "stdio"}}},
|
||||
{"required": ["url"], "not": {"anyOf": [{"required": ["disabled"]}, {"required": ["command"]}, {"required": ["args"]}, {"required": ["env"]}]}, "properties": {"transport": {"const": "streamable-http"}}}
|
||||
]
|
||||
|
||||
@@ -118,6 +118,7 @@ mcp:
|
||||
| `transport` | Optional `stdio` or `streamable-http`; inferred when omitted. Legacy SSE is not supported |
|
||||
| `targets` | Receiving clients for this server. `[]` keeps it in Skillshare only |
|
||||
| `tools` | `{allow, deny}`: which tools reach the model, translated per Agent. See [Tool policy](#tool-policy) |
|
||||
| `options` | `{<client>: {field: value}}`: other Agents' native per-server fields written as given, e.g. `codex: {default_tools_approval_mode: approve}`, `claude: {timeout: 600000}`. Values: scalars, lists of scalars, or mappings; no `null`. Managed fields (`url`, `command`, `env`, `headers`, `type`, `enabled`, Codex `enabled_tools`…) and `options.pi` (use `piOptions`) are refused; credentials (by field name or a URL password) must be a whole-value environment reference in the Agent's own syntax (`${VAR}`, `{env:VAR}`), never plain text, and options of an Agent that reads no references there (Codex, Antigravity, Claude Desktop, Goose, Junie, LM Studio, Warp) cannot hold one; not allowed with `disabled`. Sync removes an option it wrote once the source drops it |
|
||||
| `piOptions` | Other Pi built-in per-server fields. See [Pi](#pi) |
|
||||
| `disabled` | `true` only, no connection fields, and a project must be in scope: project mode, or a root under `mcp.projects`. See [Turn off a global server in one project](#turn-off-a-global-server-in-one-project) |
|
||||
|
||||
@@ -135,7 +136,8 @@ Names such as `company-docs` (letters, digits, hyphens) work across all clients.
|
||||
- A differing unmanaged entry is a conflict. Resolve it with `mcp import --replace` or
|
||||
an explicit per-entry replacement. Inspect conflicts with `skillshare mcp --json`.
|
||||
- Only the fields Skillshare writes are compared. Agent-only fields in an entry, such
|
||||
as timeouts, are kept across syncs. Tool filters come from `tools`.
|
||||
as timeouts, are kept across syncs; fields set through `options` are written and
|
||||
removed by sync. Tool filters come from `tools`.
|
||||
- Turning a managed server off by hand in the Agent's file (`enabled: false`,
|
||||
`disabled: true`) is reported as a conflict. Pi and OMP connection entries preserve
|
||||
`enabled` as an Agent setting; changing it alone is not a conflict.
|
||||
@@ -223,7 +225,7 @@ setups usually go wrong.
|
||||
definitions are rejected without touching the file; convert them to tables first.
|
||||
- `cwd`, `http_headers_helper`, approval modes, timeouts (`startup_timeout_sec`) and
|
||||
the `oauth` table have no portable form. Import leaves them out with a warning, and
|
||||
sync keeps them in the existing entry. `enabled_tools`/`disabled_tools` come from
|
||||
sync keeps them in the existing entry; set them from the source with `options.codex`. `enabled_tools`/`disabled_tools` come from
|
||||
`tools` (exact names only) and import back into it.
|
||||
- Servers bundled by a Codex plugin live under `plugins.<plugin>.mcp_servers` and are
|
||||
not managed here.
|
||||
|
||||
@@ -19,6 +19,8 @@ export interface MCPServer {
|
||||
bearerToken?: { fromEnv: string };
|
||||
/** Per-server fields written into Pi's built-in MCP as given. */
|
||||
piOptions?: Record<string, unknown>;
|
||||
/** Other Agents' native per-server fields, keyed by Agent, written as given. */
|
||||
options?: Record<string, Record<string, unknown>>;
|
||||
tools?: MCPToolPolicy;
|
||||
/** Project mode: the whole entry, turning off a server the Agent's global config defines. */
|
||||
disabled?: boolean;
|
||||
|
||||
@@ -145,6 +145,15 @@ describe('MCP server dialog', () => {
|
||||
await waitFor(() => expect(mcpApi.save).toHaveBeenCalledWith(expect.objectContaining({ server })));
|
||||
});
|
||||
|
||||
// Refs: #578. The dialog has no editor for options, so saving must not drop them.
|
||||
it('keeps other Agents\' options when editing', async () => {
|
||||
const user = userEvent.setup();
|
||||
const server = { url: 'https://docs.example/mcp', targets: ['codex'], options: { codex: { default_tools_approval_mode: 'approve' } } };
|
||||
renderDialog({ initial: { name: 'docs', server } });
|
||||
await user.click(screen.getByRole('button', { name: 'Save' }));
|
||||
await waitFor(() => expect(mcpApi.save).toHaveBeenCalledWith(expect.objectContaining({ server })));
|
||||
});
|
||||
|
||||
// Refs: #289. Unticking Pi must not drop its settings from the source.
|
||||
it('keeps Pi settings when Pi is unticked', async () => {
|
||||
const user = userEvent.setup();
|
||||
|
||||
@@ -313,6 +313,8 @@ export default function MCPServerDialog({ initial, defaultTargets, existingNames
|
||||
if (off) return { disabled: true };
|
||||
const next = connection();
|
||||
if (options.value && Object.keys(options.value).length > 0) next.piOptions = options.value;
|
||||
// The dialog has no editor for these yet; keep what the source has.
|
||||
if (server?.options) next.options = server.options;
|
||||
const tools = cleanToolPolicy(draft.tools);
|
||||
if (tools) next.tools = tools;
|
||||
return next;
|
||||
|
||||
@@ -80,7 +80,7 @@ const conflictKeys: Record<string, string> = {
|
||||
[shadowMessage]: 'mcp.claudeLocalShadow',
|
||||
'managed by another Skillshare config': 'mcp.conflictOtherConfig',
|
||||
'left over from a Skillshare config that was removed; import it or explicitly replace this entry': 'mcp.conflictOrphaned',
|
||||
'Pi setting changed since sync; import it before removing the cleared setting': 'mcp.conflictChanged',
|
||||
'Agent setting changed since sync; import it before removing the cleared setting': 'mcp.conflictChanged',
|
||||
'Agent configuration changed; import it or explicitly replace this entry': 'mcp.conflictChanged',
|
||||
'existing entry is not managed; import it to explicitly adopt it': 'mcp.conflictUnmanaged',
|
||||
'existing entry is a Pi project override of a global server; replace it, or remove the override with /mcp in Pi': 'mcp.conflictPiOverride',
|
||||
|
||||
@@ -226,7 +226,8 @@ when Codex is selected. A target that cannot represent a setting blocks the
|
||||
preview instead of dropping it. Client-specific placeholders and input prompts must
|
||||
be resolved explicitly before import. Agent-specific fields such as Codex
|
||||
`startup_timeout_sec` or `cwd` are not imported; import lists them as warnings, and
|
||||
sync keeps them in that Agent's existing entry.
|
||||
sync keeps them in that Agent's existing entry. To manage them from the source, set them
|
||||
under the server's [`options`](../../reference/commands/mcp.md#agent-options).
|
||||
|
||||
## Import existing connections
|
||||
|
||||
|
||||
@@ -127,6 +127,7 @@ Skillshare config. The schema is `schemas/mcp.schema.json` in the repository.
|
||||
| `transport` | Optional `stdio` or `streamable-http`; inferred when omitted |
|
||||
| `targets` | Optional receiving clients; overrides `mcp.targets`. An empty list keeps the server in Skillshare only. See [below](#keep-a-server-without-syncing-it) |
|
||||
| `tools` | Which tools reach the model: `allow`, `deny`. Written once and translated per Agent. See [Tool policy](#tool-policy) |
|
||||
| `options` | Other Agents' native per-server fields, keyed by client ID, such as a Codex approval mode or a Claude Code timeout. See [below](#agent-options) |
|
||||
| `piOptions` | Other per-server fields of Pi's built-in MCP. See [Pi](#pi-options) |
|
||||
| `disabled` | `true` only, no other connection fields, and a project must be in scope: project mode, or a root under `mcp.projects`. See [below](#turn-off-a-global-server-in-one-project) |
|
||||
|
||||
@@ -138,6 +139,40 @@ digits, dots, underscores and hyphens. A server must select at least one client
|
||||
either directly or through `mcp.targets` before synchronization, unless its own
|
||||
`targets` is an empty list.
|
||||
|
||||
### Other Agent settings {#agent-options}
|
||||
|
||||
`options` writes native fields that have no portable form into one Agent's entry, as
|
||||
given. Each key is a client ID; an account target receives the options of its Agent.
|
||||
|
||||
```yaml
|
||||
servers:
|
||||
docs:
|
||||
url: https://example.com/mcp
|
||||
targets: [codex, claude]
|
||||
options:
|
||||
codex:
|
||||
default_tools_approval_mode: approve
|
||||
claude:
|
||||
timeout: 600000
|
||||
```
|
||||
|
||||
- Values are strings, numbers, booleans, lists of those, or mappings of them. `null` and
|
||||
lists of mappings are refused, because not every native format writes them back.
|
||||
- A field Skillshare writes from the server's own settings, such as `url`, `command`,
|
||||
`env`, `headers`, `type`, `enabled` or Codex `enabled_tools`, is refused.
|
||||
- Pi's fields go in [`piOptions`](#pi-options); `options.pi` is refused.
|
||||
- A credential, judged by its field name (token, secret, password, API key, authorization,
|
||||
credential) or a password in a URL, must be an environment reference in the Agent's own
|
||||
syntax that makes up the whole value, such as `${VAR}` for Claude Code or `{env:VAR}`
|
||||
for OpenCode. Plain text, or text around a reference, is refused, because the Agent's
|
||||
file may be committed. Codex, Antigravity, Claude Desktop, Goose, Junie, LM Studio and Warp
|
||||
read no references there, so their options cannot hold a credential.
|
||||
- Options for a client the server does not reach are kept and not written.
|
||||
- Sync writes the fields again when it recreates an entry, for example after a rename.
|
||||
When the source drops an option, the next sync removes the field it wrote, unless
|
||||
the Agent changed it since; that is a conflict to import or replace.
|
||||
- The dashboard has no editor for `options` yet. Editing the server there keeps them.
|
||||
|
||||
### Keep a server without syncing it
|
||||
|
||||
A server with `targets: []` stays in the Skillshare source and is written to no client.
|
||||
@@ -239,7 +274,7 @@ Additional client details:
|
||||
project the synced servers do not load, without an error. `cwd`,
|
||||
`http_headers_helper`, approval modes, timeouts and the `oauth` table
|
||||
have no portable form: import leaves them out with a warning and sync keeps them in
|
||||
the existing entry. `enabled_tools` and `disabled_tools` come from the
|
||||
the existing entry. To set them from the source, use [`options.codex`](#agent-options). `enabled_tools` and `disabled_tools` come from the
|
||||
[tool policy](#tool-policy) and are imported into it. MCP servers that a Codex plugin bundles are configured under
|
||||
`plugins.<plugin>.mcp_servers` and are not managed here.
|
||||
- Claude Desktop file sync supports **stdio only**, on macOS and Windows.
|
||||
@@ -474,7 +509,7 @@ skillshare sync mcp
|
||||
[`mcp.projects`](#manage-several-projects-from-the-global-config). In the global
|
||||
`mcp.servers`, where no project is in scope, it is refused.
|
||||
- **`disabled` stands alone.** The entry takes `targets` only. Adding `command`, `url`,
|
||||
`env`, `headers`, `piOptions` or `tools` is an error.
|
||||
`env`, `headers`, `options`, `piOptions` or `tools` is an error.
|
||||
- **`targets` can be left out.** The entry then follows the project's targets: on every
|
||||
sync it goes to the clients the project uses that have a per-project switch. Under
|
||||
`mcp.projects`, where Skillshare also knows the global server of that name, it is
|
||||
@@ -984,7 +1019,8 @@ command migrates it. Targets receive the change on the next `sync`.
|
||||
- JSONC comments and unrelated settings are preserved. Changed owned entries
|
||||
are replaced as a unit, so comments inside those entries may change. Only the
|
||||
fields Skillshare writes are compared and replaced; Agent-specific fields such
|
||||
as timeouts are kept.
|
||||
as timeouts are kept. Fields set through [`options`](#agent-options) are written
|
||||
and removed by sync.
|
||||
Defaults an Agent fills in, such as `"type": "stdio"`, an empty `env` or
|
||||
header name case, are not changes. Turning a managed server off with
|
||||
`enabled: false` or `disabled: true` is reported as a conflict.
|
||||
|
||||
+2
-1
@@ -217,7 +217,8 @@ Codex はローカル変数を名前で転送するため、Codex を選択す
|
||||
ブロックします。クライアント固有のプレースホルダーと入力プロンプトは、Import の前に明示的に解決して
|
||||
おく必要があります。Codex の `startup_timeout_sec` や `cwd` のような Agent 固有のフィールドは
|
||||
Import されません。Import はそれらを警告として一覧表示し、Sync はその Agent の既存エントリ内にそれらを
|
||||
維持します。
|
||||
維持します。source から管理するには、サーバーの
|
||||
[`options`](../../reference/commands/mcp.md#agent-options) に設定します。
|
||||
|
||||
## 既存の接続をインポートする
|
||||
|
||||
|
||||
@@ -96,6 +96,7 @@ Add、edit、remove、import では、**Save and sync** または **Save only**
|
||||
| `transport` | 任意の `stdio` または `streamable-http`。省略時は推測される |
|
||||
| `targets` | 任意の受け取り側クライアント。`mcp.targets` を上書きする。空のリストにすると、サーバーは Skillshare 内にのみ保持される。[下記](#keep-a-server-without-syncing-it)を参照 |
|
||||
| `tools` | どのツールをモデルに渡すか: `allow`、`deny`。一度書けば Agent ごとに変換される。[ツールポリシー](#tool-policy)を参照 |
|
||||
| `options` | 他の Agent のネイティブなサーバー別フィールド。クライアント ID をキーにする。Codex の承認モードや Claude Code のタイムアウトなど。[下記](#agent-options)を参照 |
|
||||
| `piOptions` | Pi の内蔵 MCP のその他のサーバー別フィールド。[Pi](#pi-options)を参照 |
|
||||
| `disabled` | `true` のみ、他の接続フィールドを伴わない、かつ project がスコープ内にあること: project mode、または `mcp.projects` 配下の root。[下記](#turn-off-a-global-server-in-one-project)を参照 |
|
||||
|
||||
@@ -107,6 +108,36 @@ Add、edit、remove、import では、**Save and sync** または **Save only**
|
||||
`mcp.targets` 経由で少なくとも 1 つのクライアントを選択する必要があります。ただし、サーバー自身の
|
||||
`targets` が空のリストである場合は除きます。
|
||||
|
||||
### その他の Agent 設定 {#agent-options}
|
||||
|
||||
`options` は、ポータブルな形式がないネイティブフィールドを、1 つの Agent のエントリにそのまま書き込みます。
|
||||
キーはクライアント ID で、アカウント target はその Agent の options を受け取ります。
|
||||
|
||||
```yaml
|
||||
servers:
|
||||
docs:
|
||||
url: https://example.com/mcp
|
||||
targets: [codex, claude]
|
||||
options:
|
||||
codex:
|
||||
default_tools_approval_mode: approve
|
||||
claude:
|
||||
timeout: 600000
|
||||
```
|
||||
|
||||
- 値は文字列、数値、真偽値、それらのリスト、またはそれらのマッピングです。`null` とマッピングのリストは拒否されます。すべてのネイティブ形式が書き戻せるとは限らないためです。
|
||||
- `url`、`command`、`env`、`headers`、`type`、`enabled`、Codex の `enabled_tools` のように、Skillshare がサーバー自身の設定から書き込むフィールドは拒否されます。
|
||||
- Pi のフィールドは [`piOptions`](#pi-options) に置きます。`options.pi` は拒否されます。
|
||||
- 認証情報(フィールド名が token、secret、password、API key、authorization、credential を含むもの、
|
||||
または URL 内のパスワード)は、その Agent 自身の書式による環境変数参照にする必要があります。
|
||||
値全体が参照である必要があります。例: Claude Code なら `${VAR}`、OpenCode なら `{env:VAR}`。
|
||||
Agent のファイルはコミットされることがあるため、平文や参照の前後に文字がある値は拒否されます。
|
||||
Codex、Antigravity、Claude Desktop、Goose、Junie、LM Studio、Warp はそこで参照を読まないため、その options に認証情報は置けません。
|
||||
- サーバーが届かないクライアントの options は保持され、書き込まれません。
|
||||
- sync は、リネームの後などにエントリを作り直すとき、そのフィールドを再び書き込みます。
|
||||
source から option を外すと、次の sync は書き込んだフィールドを削除します。ただし、その後に Agent が変更していた場合は除きます。それは import または replace で解決する競合です。
|
||||
- ダッシュボードには `options` のエディターがまだありません。そこでサーバーを編集しても `options` は保持されます。
|
||||
|
||||
### 同期せずにサーバーを保持する {#keep-a-server-without-syncing-it}
|
||||
|
||||
`targets: []` を持つサーバーは Skillshare の source に残り、どのクライアントにも書き込まれません。
|
||||
@@ -178,7 +209,7 @@ JSON エントリは、そのファイル自体のインデントに合わせて
|
||||
|
||||
- `codex` の送信先は、Codex CLI、Codex IDE 拡張機能、ChatGPT デスクトップアプリが共有する 1 つの `config.toml` です。そのため、`codex` に同期したサーバーはこの 3 つすべてに表示されます。ChatGPT デスクトップアプリでは **Settings → MCP servers** の下に表示されます。
|
||||
Codex は、trust している project でのみ `.codex/config.toml` を読み込みます。trust していない project では、同期されたサーバーはエラーなく読み込まれません。`cwd`、
|
||||
`http_headers_helper`、承認モード、タイムアウト、`oauth` テーブルにはポータブルな形式がありません。インポートではこれらを警告付きで除外し、sync は既存のエントリ内にそれらを維持します。`enabled_tools` と `disabled_tools` は[ツールポリシー](#tool-policy)から書き込まれ、インポート時もそこに取り込まれます。Codex の plugin が同梱する MCP サーバーは `plugins.<plugin>.mcp_servers` の下に設定され、ここでは管理されません。
|
||||
`http_headers_helper`、承認モード、タイムアウト、`oauth` テーブルにはポータブルな形式がありません。インポートではこれらを警告付きで除外し、sync は既存のエントリ内にそれらを維持します。source から設定するには [`options.codex`](#agent-options) を使います。`enabled_tools` と `disabled_tools` は[ツールポリシー](#tool-policy)から書き込まれ、インポート時もそこに取り込まれます。Codex の plugin が同梱する MCP サーバーは `plugins.<plugin>.mcp_servers` の下に設定され、ここでは管理されません。
|
||||
- Claude Desktop のファイル sync は macOS と Windows で **stdio のみ**に対応します。
|
||||
ディレクトリは macOS では `~/Library/Application Support/Claude`、
|
||||
Windows では `%APPDATA%/Claude` です。リモートコネクタはアプリケーション内で設定してください。
|
||||
@@ -343,7 +374,7 @@ skillshare sync mcp
|
||||
[`mcp.projects`](#manage-several-projects-from-the-global-config) 内の project root の下にエントリを
|
||||
置いてください。project がスコープ内にない global の `mcp.servers` では拒否されます。
|
||||
- **`disabled` は単独で指定します。** このエントリが取れるのは `targets` のみです。`command`、`url`、
|
||||
`env`、`headers`、`piOptions`、`tools` を追加するとエラーになります。
|
||||
`env`、`headers`、`options`、`piOptions`、`tools` を追加するとエラーになります。
|
||||
- **`targets` は省略できます。** その場合、エントリは project の target に従います。sync のたびに、
|
||||
project が使うクライアントのうち、project ごとのスイッチを持つものに書き込まれます。Skillshare が同名の
|
||||
global サーバーも把握している `mcp.projects` 配下では、そのサーバーの書き込み先クライアントにさらに
|
||||
@@ -775,7 +806,7 @@ mcp:
|
||||
|
||||
- JSONC のコメントと無関係な設定は保持されます。変更された所有エントリは
|
||||
ひとまとまりとして置き換えられるため、それらのエントリ内のコメントは変わる可能性があります。比較・置換の対象となるのは
|
||||
Skillshare が書き込むフィールドのみで、タイムアウトなどの Agent 固有のフィールドは保持されます。
|
||||
Skillshare が書き込むフィールドのみで、タイムアウトなどの Agent 固有のフィールドは保持されます。[`options`](#agent-options) で設定したフィールドは、sync が書き込み、削除します。
|
||||
`"type": "stdio"`、空の `env`、ヘッダー名の大文字小文字などの Agent が補完するデフォルト値は
|
||||
変更とはみなされません。管理下のサーバーを `enabled: false` や `disabled: true` でオフにすることは
|
||||
競合として報告されます。
|
||||
|
||||
+2
-1
@@ -215,7 +215,8 @@ Codex는 이름으로 로컬 변수를 전달하므로, Codex를 선택했다면
|
||||
미리보기 자체를 막습니다. 클라이언트별 플레이스홀더와 입력 프롬프트는 import 전에
|
||||
명시적으로 해결해야 합니다. Codex의 `startup_timeout_sec`나 `cwd`처럼 Agent 특화
|
||||
필드는 import되지 않습니다. import는 이를 경고로 나열하며, sync는 해당 Agent의 기존
|
||||
항목에 그대로 유지합니다.
|
||||
항목에 그대로 유지합니다. source에서 관리하려면 서버의
|
||||
[`options`](../../reference/commands/mcp.md#agent-options)에 설정합니다.
|
||||
|
||||
## 기존 연결 가져오기
|
||||
|
||||
|
||||
@@ -123,6 +123,7 @@ source가 한 번 저장되기 전에 검증되며, 이후의 네이티브 파
|
||||
| `transport` | 선택적으로 `stdio` 또는 `streamable-http`; 생략 시 추론됨 |
|
||||
| `targets` | 선택적 수신 client; `mcp.targets`를 재정의. 빈 목록이면 서버를 Skillshare에만 유지합니다. [아래](#keep-a-server-without-syncing-it) 참고 |
|
||||
| `tools` | 어떤 도구가 모델에 전달되는지: `allow`, `deny`. 한 번 작성하면 Agent별로 변환됩니다. [도구 정책](#tool-policy) 참고 |
|
||||
| `options` | 다른 Agent의 네이티브 서버별 필드. client ID를 키로 사용하며, 예를 들어 Codex 승인 모드나 Claude Code 타임아웃. [아래](#agent-options) 참고 |
|
||||
| `piOptions` | Pi 내장 MCP의 그 밖의 서버별 필드. [Pi](#pi-options) 참고 |
|
||||
| `disabled` | `true`만 가능, 다른 연결 필드 불가, 그리고 project가 scope 안에 있어야 합니다: project mode이거나 `mcp.projects` 아래의 root. [아래](#turn-off-a-global-server-in-one-project) 참고 |
|
||||
|
||||
@@ -133,6 +134,36 @@ Client ID는 `claude`, `codex`, `cursor`, `vscode`, `opencode`, `kilocode`,
|
||||
사용합니다. 서버는 동기화 전에 직접 또는 `mcp.targets`를 통해 최소 하나의 client를
|
||||
선택해야 합니다. 단, 서버 자체의 `targets`가 빈 목록인 경우는 예외입니다.
|
||||
|
||||
### 그 밖의 Agent 설정 {#agent-options}
|
||||
|
||||
`options`는 이식 가능한 형태가 없는 네이티브 필드를 한 Agent의 항목에 있는 그대로 작성합니다.
|
||||
각 키는 client ID이며, 계정 target은 해당 Agent의 options를 받습니다.
|
||||
|
||||
```yaml
|
||||
servers:
|
||||
docs:
|
||||
url: https://example.com/mcp
|
||||
targets: [codex, claude]
|
||||
options:
|
||||
codex:
|
||||
default_tools_approval_mode: approve
|
||||
claude:
|
||||
timeout: 600000
|
||||
```
|
||||
|
||||
- 값은 문자열, 숫자, 불리언, 그 목록, 또는 그 매핑입니다. `null`과 매핑의 목록은 거부됩니다. 모든 네이티브 형식이 이를 다시 쓸 수 있는 것은 아니기 때문입니다.
|
||||
- `url`, `command`, `env`, `headers`, `type`, `enabled`, Codex `enabled_tools`처럼 Skillshare가 서버 자체 설정에서 작성하는 필드는 거부됩니다.
|
||||
- Pi의 필드는 [`piOptions`](#pi-options)에 넣습니다. `options.pi`는 거부됩니다.
|
||||
- 자격 증명(필드 이름에 token, secret, password, API key, authorization, credential이 들어가거나
|
||||
URL에 비밀번호가 있는 값)은 해당 Agent 자체 문법의 환경 변수 참조여야 합니다. 예: Claude Code는
|
||||
`${VAR}`, OpenCode는 `{env:VAR}`이며 값 전체가 참조여야 합니다. Agent의 파일이 커밋될 수
|
||||
있으므로 평문이나 참조 앞뒤에 글자가 붙은 값은 거부됩니다. Codex, Antigravity, Claude Desktop, Goose, Junie, LM Studio, Warp는
|
||||
그곳의 참조를 읽지 않으므로 해당 options에는 자격 증명을 둘 수 없습니다.
|
||||
- 서버가 도달하지 않는 client의 options는 유지되며 작성되지 않습니다.
|
||||
- sync는 이름 변경 후처럼 항목을 다시 만들 때 해당 필드를 다시 작성합니다.
|
||||
source에서 option을 빼면 다음 sync가 작성했던 필드를 제거합니다. 단, 그 뒤 Agent가 변경했다면 제거하지 않으며, 이는 import 또는 replace로 해결할 충돌입니다.
|
||||
- 대시보드에는 아직 `options` 편집기가 없습니다. 거기서 서버를 편집해도 `options`는 유지됩니다.
|
||||
|
||||
### Keep a server without syncing it {#keep-a-server-without-syncing-it}
|
||||
|
||||
`targets: []`인 서버는 Skillshare source에 남아 있으며 어떤 client에도 작성되지 않습니다.
|
||||
@@ -229,7 +260,7 @@ mode에서는 프로젝트에 MCP 파일이 있거나 client가 전역적으로
|
||||
프로젝트에서만 `.codex/config.toml`을 읽습니다. 신뢰하지 않는 프로젝트에서는
|
||||
동기화된 서버가 오류 없이 로드되지 않습니다. `cwd`, `http_headers_helper`, 승인
|
||||
모드, 타임아웃, `oauth` 테이블은 이식 가능한 형태가 없습니다: import는
|
||||
이를 경고와 함께 제외하고, sync는 기존 항목에 그대로 유지합니다. `enabled_tools`와
|
||||
이를 경고와 함께 제외하고, sync는 기존 항목에 그대로 유지합니다. source에서 설정하려면 [`options.codex`](#agent-options)를 사용합니다. `enabled_tools`와
|
||||
`disabled_tools`는 [도구 정책](#tool-policy)에서 만들어지며, import 시 도구 정책으로
|
||||
가져옵니다. Codex 플러그인이
|
||||
번들하는 MCP 서버는 `plugins.<plugin>.mcp_servers` 아래에 구성되며 여기서 관리되지
|
||||
@@ -449,7 +480,7 @@ skillshare sync mcp
|
||||
항목을 [`mcp.projects`](#manage-several-projects-from-the-global-config)의 프로젝트
|
||||
root 아래에 두세요. project가 scope에 없는 global `mcp.servers`에서는 거부됩니다.
|
||||
- **`disabled`는 단독으로 사용됩니다.** 항목은 `targets`만 받습니다. `command`, `url`,
|
||||
`env`, `headers`, `piOptions`, `tools`를 추가하면 오류입니다.
|
||||
`env`, `headers`, `options`, `piOptions`, `tools`를 추가하면 오류입니다.
|
||||
- **`targets`는 생략할 수 있습니다.** 그러면 항목은 프로젝트의 target을
|
||||
따릅니다: sync할 때마다 프로젝트가 사용하는 client 중 프로젝트별 스위치가 있는
|
||||
client에 작성됩니다. Skillshare가 같은 이름의 global 서버도 알고 있는
|
||||
@@ -919,7 +950,7 @@ target은 다음 `sync`에서 변경 사항을 받습니다.
|
||||
|
||||
- JSONC 주석과 관련 없는 설정은 보존됩니다. 변경된 소유 항목은 하나의 단위로
|
||||
교체되므로, 해당 항목 안의 주석은 바뀔 수 있습니다. Skillshare가 작성하는 필드만
|
||||
비교되고 교체되며, 타임아웃 같은 Agent 고유 필드는 유지됩니다.
|
||||
비교되고 교체되며, 타임아웃 같은 Agent 고유 필드는 유지됩니다. [`options`](#agent-options)로 설정한 필드는 sync가 작성하고 제거합니다.
|
||||
`"type": "stdio"`, 빈 `env`, 헤더 이름 대소문자처럼 Agent가 채우는 기본값은
|
||||
변경으로 간주되지 않습니다. `enabled: false`나 `disabled: true`로 관리되는 서버를
|
||||
끄는 것은 충돌로 보고됩니다.
|
||||
|
||||
+2
-1
@@ -216,7 +216,8 @@ Codex 会依名称转发本地变量,因此当选择 Codex 时,`env.KEY.from
|
||||
是 `KEY`。当某个 Target 无法表示某项设置时,会阻止预览,而不是直接丢弃它。
|
||||
客户端专属的占位符与输入提示,必须在 Import 前先行明确解析。Agent 专属的
|
||||
字段,例如 Codex 的 `startup_timeout_sec` 或 `cwd`,不会被 Import;Import 会将其
|
||||
列为警告,sync 则会保留该 Agent 现有条目中的这些字段。
|
||||
列为警告,sync 则会保留该 Agent 现有条目中的这些字段。若要从 source 管理它们,请在 server 的
|
||||
[`options`](../../reference/commands/mcp.md#agent-options) 下设置。
|
||||
|
||||
## 导入现有连接
|
||||
|
||||
|
||||
+33
-3
@@ -125,6 +125,7 @@ Skillshare 配置中。schema 是仓库中的 `schemas/mcp.schema.json`。
|
||||
| `transport` | 可选的 `stdio` 或 `streamable-http`;省略时会自动推断 |
|
||||
| `targets` | 可选的接收方 client;覆盖 `mcp.targets`。空列表会让该 server 只保留在 Skillshare 中。参见[下文](#keep-a-server-without-syncing-it) |
|
||||
| `tools` | 哪些工具会提供给模型:`allow`、`deny`。只需写一次,会按各 Agent 转换。参见[工具策略](#tool-policy) |
|
||||
| `options` | 其他 Agent 的原生单个 server 字段,以 client ID 为 key,例如 Codex 的审批模式或 Claude Code 的超时。参见[下文](#agent-options) |
|
||||
| `piOptions` | Pi 内置 MCP 的其他单个 server 字段。参见 [Pi](#pi-options) |
|
||||
| `disabled` | 仅限 `true`,不能有其他连接字段,且必须有 project 在作用范围内:project mode,或 `mcp.projects` 下的某个项目根目录。参见[下文](#turn-off-a-global-server-in-one-project) |
|
||||
|
||||
@@ -136,6 +137,35 @@ Client ID 有 `claude`、`codex`、`cursor`、`vscode`、`opencode`、`kilocode`
|
||||
直接或通过 `mcp.targets` 选择至少一个 client,除非它自己的
|
||||
`targets` 是空列表。
|
||||
|
||||
### 其他 Agent 设置 {#agent-options}
|
||||
|
||||
`options` 会把没有可移植形式的原生字段,按原样写入某个 Agent 的条目。
|
||||
每个 key 是一个 client ID;账号 target 会收到其所属 Agent 的 options。
|
||||
|
||||
```yaml
|
||||
servers:
|
||||
docs:
|
||||
url: https://example.com/mcp
|
||||
targets: [codex, claude]
|
||||
options:
|
||||
codex:
|
||||
default_tools_approval_mode: approve
|
||||
claude:
|
||||
timeout: 600000
|
||||
```
|
||||
|
||||
- 值可以是字符串、数字、布尔值、由它们组成的列表,或由它们组成的映射。`null` 和映射列表会被拒绝,因为并非每种原生格式都能把它们写回。
|
||||
- Skillshare 根据 server 自身设置写入的字段会被拒绝,例如 `url`、`command`、`env`、`headers`、`type`、`enabled` 或 Codex 的 `enabled_tools`。
|
||||
- Pi 的字段放在 [`piOptions`](#pi-options) 中;`options.pi` 会被拒绝。
|
||||
- 凭据(字段名含 token、secret、password、API key、authorization、credential,或 URL 中带密码)
|
||||
必须使用该 Agent 自身语法的环境变量引用,例如 Claude Code 用 `${VAR}`、OpenCode 用
|
||||
`{env:VAR}`,且整个值必须就是引用。Agent 的文件可能会被提交,因此明文或引用前后带有文字的值会被拒绝。
|
||||
Codex、Antigravity、Claude Desktop、Goose、Junie、LM Studio 和 Warp 不会读取那里的引用,所以它们的 options 不能放凭据。
|
||||
- 该 server 触达不到的 client 的 options 会被保留,但不会写入。
|
||||
- 当 sync 重新创建条目时,例如重命名之后,会再次写入这些字段。
|
||||
当 source 删掉某个 option 时,下一次 sync 会移除它写入的字段,除非 Agent 在此之后改过它;那属于需要 import 或 replace 的冲突。
|
||||
- 仪表板暂时没有 `options` 的编辑器。在那里编辑 server 会保留它们。
|
||||
|
||||
### 保留 server 但不同步 {#keep-a-server-without-syncing-it}
|
||||
|
||||
带有 `targets: []` 的 server 会保留在 Skillshare source 中,不会被写入任何 client。
|
||||
@@ -233,7 +263,7 @@ client 还没写入文件时,打开最近一个已存在的文件夹。这样
|
||||
项目中,同步的 server 不会被加载,也不会报错。`cwd`、
|
||||
`http_headers_helper`、审批模式、超时以及 `oauth` 表
|
||||
都没有可移植的形式:import 会将它们省略并给出警告,sync 则会将它们保留在
|
||||
现有条目中。`enabled_tools` 和 `disabled_tools` 来自
|
||||
现有条目中。若要从 source 设置它们,请使用 [`options.codex`](#agent-options)。`enabled_tools` 和 `disabled_tools` 来自
|
||||
[工具策略](#tool-policy),导入时也会读回策略中。由 Codex 插件捆绑的 MCP server 配置在
|
||||
`plugins.<plugin>.mcp_servers` 下,不由此处管理。
|
||||
- Claude Desktop 的文件同步**仅支持 stdio**,仅限 macOS 和 Windows。
|
||||
@@ -447,7 +477,7 @@ skillshare sync mcp
|
||||
[`mcp.projects`](#manage-several-projects-from-the-global-config) 下的某个项目根目录里。
|
||||
在 global `mcp.servers` 中没有 project 在作用范围内,因此会被拒绝。
|
||||
- **`disabled` 必须单独存在。** 该条目只能带 `targets`。添加 `command`、`url`、
|
||||
`env`、`headers`、`piOptions` 或 `tools` 会报错。
|
||||
`env`、`headers`、`options`、`piOptions` 或 `tools` 会报错。
|
||||
- **`targets` 可以省略。** 此时该条目会跟随项目的 targets:每次同步时,它都会写入
|
||||
该项目所用且支持按项目开关的 client。在 `mcp.projects` 下,Skillshare 还知道
|
||||
同名的 global server,因此范围会进一步缩小到该 server 写入的那些 client。之后更改项目的
|
||||
@@ -900,7 +930,7 @@ mcp:
|
||||
- JSONC 注释和不相关的设置会被保留。发生变化的、由 Skillshare 拥有的条目
|
||||
会作为一个整体被替换,因此这些条目内部的注释可能会改变。只有
|
||||
Skillshare 写入的字段会被比较和替换;Agent 专属的字段,例如超时,会被
|
||||
保留。
|
||||
保留。通过 [`options`](#agent-options) 设置的字段由 sync 写入和移除。
|
||||
由 Agent 自动填充的默认值,例如 `"type": "stdio"`、空的 `env` 或
|
||||
header 名称大小写,不算作变更。用 `enabled: false` 或 `disabled: true`
|
||||
关闭一个被管理的 server 会被报告为冲突。
|
||||
|
||||
+2
-1
@@ -204,7 +204,8 @@ Codex 是以名稱轉發本機變數,因此選擇 Codex 時,`env.KEY.fromEnv
|
||||
若某個 target 無法表示某項設定,會直接阻擋預覽,而不是默默捨棄它。client 專屬的
|
||||
佔位符與輸入提示(input prompts)必須先明確解析後才能匯入。Agent 專屬的欄位,
|
||||
例如 Codex 的 `startup_timeout_sec` 或 `cwd`,不會被匯入;匯入會將它們列為警告,
|
||||
並在同步時保留在該 Agent 既有的項目中。
|
||||
並在同步時保留在該 Agent 既有的項目中。若要從 source 管理它們,請在 server 的
|
||||
[`options`](../../reference/commands/mcp.md#agent-options) 下設定。
|
||||
|
||||
## 匯入既有的連線
|
||||
|
||||
|
||||
+33
-3
@@ -95,6 +95,7 @@ Add、edit、remove 與 import 在 **Save and sync** 或 **Save only** 之前會
|
||||
| `transport` | 選填的 `stdio` 或 `streamable-http`;省略時自動推斷 |
|
||||
| `targets` | 選填的接收端 clients;覆寫 `mcp.targets`。空清單會讓 server 只保留在 Skillshare 中。參見[下方說明](#keep-a-server-without-syncing-it) |
|
||||
| `tools` | 哪些工具會提供給模型:`allow`、`deny`。只需寫一次,會依各 Agent 轉換。參見[工具政策](#tool-policy) |
|
||||
| `options` | 其他 Agent 的原生單一 server 欄位,以 client ID 為鍵,例如 Codex 的核准模式或 Claude Code 的逾時。參見[下方說明](#agent-options) |
|
||||
| `piOptions` | Pi 內建 MCP 的其他單一 server 欄位。參見 [Pi](#pi-options) |
|
||||
| `disabled` | 只能是 `true`,不能有其他連線欄位,且必須有 project 在作用範圍內:project mode,或 `mcp.projects` 下的某個 root。參見[下方說明](#turn-off-a-global-server-in-one-project) |
|
||||
|
||||
@@ -105,6 +106,35 @@ Client ID 有 `claude`、`codex`、`cursor`、`vscode`、`opencode`、`kilocode`
|
||||
數字、點、底線與連字號。一個 server 必須直接或透過 `mcp.targets`
|
||||
選擇至少一個 client 才能同步,除非它自己的 `targets` 是空清單。
|
||||
|
||||
### 其他 Agent 設定 {#agent-options}
|
||||
|
||||
`options` 會把沒有可攜式對應形式的原生欄位,原樣寫入某個 Agent 的項目。
|
||||
每個鍵是一個 client ID;帳號 target 會收到其所屬 Agent 的 options。
|
||||
|
||||
```yaml
|
||||
servers:
|
||||
docs:
|
||||
url: https://example.com/mcp
|
||||
targets: [codex, claude]
|
||||
options:
|
||||
codex:
|
||||
default_tools_approval_mode: approve
|
||||
claude:
|
||||
timeout: 600000
|
||||
```
|
||||
|
||||
- 值可以是字串、數字、布林值、由它們組成的清單,或由它們組成的對應表。`null` 與對應表清單會被拒絕,因為並非每種原生格式都能把它們寫回。
|
||||
- Skillshare 依 server 自身設定寫入的欄位會被拒絕,例如 `url`、`command`、`env`、`headers`、`type`、`enabled` 或 Codex 的 `enabled_tools`。
|
||||
- Pi 的欄位放在 [`piOptions`](#pi-options) 中;`options.pi` 會被拒絕。
|
||||
- 憑證(欄位名稱含 token、secret、password、API key、authorization、credential,或 URL 中帶密碼)
|
||||
必須使用該 Agent 自己語法的環境變數參照,例如 Claude Code 用 `${VAR}`、OpenCode 用
|
||||
`{env:VAR}`,且整個值必須就是參照。Agent 的檔案可能會被 commit,因此明文或參照前後帶有文字的值會被拒絕。
|
||||
Codex、Antigravity、Claude Desktop、Goose、Junie、LM Studio 與 Warp 不會讀取那裡的參照,所以它們的 options 不能放憑證。
|
||||
- 該 server 觸及不到的 client 的 options 會被保留,但不會寫入。
|
||||
- 當 sync 重新建立項目時,例如重新命名之後,會再次寫入這些欄位。
|
||||
當 source 移除某個 option 時,下一次 sync 會移除它寫入的欄位,除非 Agent 在那之後改過它;那屬於需要 import 或 replace 的衝突。
|
||||
- 儀表板目前沒有 `options` 的編輯器。在那裡編輯 server 會保留它們。
|
||||
|
||||
### 保留 server 但不同步 {#keep-a-server-without-syncing-it}
|
||||
|
||||
帶有 `targets: []` 的 server 會留在 Skillshare source 中,不會寫入任何 client。
|
||||
@@ -200,7 +230,7 @@ Dashboard 只會提供目前 scope 與主機平台可用的目的地。每個 se
|
||||
project 中,已同步的 servers 不會載入,且不會顯示錯誤。`cwd`、
|
||||
`http_headers_helper`、核准模式、逾時,以及 `oauth` 表格
|
||||
都沒有可攜式對應形式:import 會將它們省略並顯示警告,sync 則會將它們保留在
|
||||
既有項目中。`enabled_tools` 與 `disabled_tools` 來自[工具政策](#tool-policy),
|
||||
既有項目中。若要從 source 設定它們,請使用 [`options.codex`](#agent-options)。`enabled_tools` 與 `disabled_tools` 來自[工具政策](#tool-policy),
|
||||
匯入時也會讀回政策中。由 Codex plugin 包裝的 MCP servers,會設定在
|
||||
`plugins.<plugin>.mcp_servers` 下,不受此處管理。
|
||||
- Claude Desktop 的檔案同步僅支援 **stdio**,僅限 macOS 與 Windows。
|
||||
@@ -414,7 +444,7 @@ skillshare sync mcp
|
||||
[`mcp.projects`](#manage-several-projects-from-the-global-config) 下的某個 project root。
|
||||
在沒有任何 project 在作用範圍內的 global `mcp.servers` 中,它會被拒絕。
|
||||
- **`disabled` 必須單獨存在。** 該項目只能帶 `targets`。加入 `command`、`url`、
|
||||
`env`、`headers`、`piOptions` 或 `tools` 會是錯誤。
|
||||
`env`、`headers`、`options`、`piOptions` 或 `tools` 會是錯誤。
|
||||
- **`targets` 可以省略。** 該項目會跟著 project 的 targets:每次同步時,它會寫到
|
||||
project 所使用、且支援個別 project 開關的 clients。在 `mcp.projects` 底下,
|
||||
Skillshare 也知道同名的 global server,因此範圍會再縮小到該 server 實際寫入的
|
||||
@@ -872,7 +902,7 @@ mcp:
|
||||
- JSONC 註解與不相關的設定會被保留。已變更的、由 Skillshare 擁有的
|
||||
項目會整體取代,所以那些項目內的註解可能因此改變。只有
|
||||
Skillshare 寫入的欄位會被比對與取代;Agent 專屬欄位(例如逾時設定)
|
||||
會被保留。
|
||||
會被保留。透過 [`options`](#agent-options) 設定的欄位由 sync 寫入與移除。
|
||||
Agent 自行填入的預設值,例如 `"type": "stdio"`、空的 `env` 或
|
||||
header 名稱大小寫,不算變更。用 `enabled: false` 或 `disabled: true`
|
||||
關閉一個受管理的 server,會回報為衝突。
|
||||
|
||||
Reference in New Issue
Block a user