{"record":{"id":"af467e5810346720","repo":"sipeed/picoclaw","slug":"usage-picoclaw-mcp-add-flags-name-command-or","errorCode":null,"errorMessage":"usage: picoclaw mcp add [flags] <name> <command-or-url> [args...] or picoclaw mcp add [flags] <name> -- <command> [args...]","messagePattern":"usage: picoclaw mcp add \\[flags\\] <name> <command-or-url> \\[args\\.\\.\\.\\] or picoclaw mcp add \\[flags\\] <name> -- <command> \\[args\\.\\.\\.\\]","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/picoclaw/internal/mcp/add.go","lineNumber":152,"sourceCode":"\t\tcase arg == \"--header\" || arg == \"-H\":\n\t\t\tif i+1 >= len(args) {\n\t\t\t\treturn addOptions{}, \"\", \"\", nil, false, fmt.Errorf(\"missing value for %s\", arg)\n\t\t\t}\n\t\t\ti++\n\t\t\topts.Headers = append(opts.Headers, args[i])\n\t\tcase strings.HasPrefix(arg, \"--header=\"):\n\t\t\topts.Headers = append(opts.Headers, strings.TrimPrefix(arg, \"--header=\"))\n\t\tcase strings.HasPrefix(arg, \"-\") && len(positional) >= 2:\n\t\t\tserverArgs = append(serverArgs, args[i:]...)\n\t\t\ti = len(args)\n\t\tdefault:\n\t\t\tpositional = append(positional, arg)\n\t\t}\n\t}\n\n\tif len(explicitCommand) > 0 {\n\t\tif len(positional) != 1 {\n\t\t\treturn addOptions{}, \"\", \"\", nil, false, fmt.Errorf(\n\t\t\t\t\"usage: picoclaw mcp add [flags] <name> <command-or-url> [args...] or picoclaw mcp add [flags] <name> -- <command> [args...]\",\n\t\t\t)\n\t\t}\n\t\tif len(explicitCommand) == 0 {\n\t\t\treturn addOptions{}, \"\", \"\", nil, false, fmt.Errorf(\"missing stdio command after --\")\n\t\t}\n\t\treturn opts, positional[0], explicitCommand[0], explicitCommand[1:], false, nil\n\t}\n\n\tif len(positional) < 2 {\n\t\treturn addOptions{}, \"\", \"\", nil, false, fmt.Errorf(\n\t\t\t\"usage: picoclaw mcp add [flags] <name> <command-or-url> [args...] or picoclaw mcp add [flags] <name> -- <command> [args...]\",\n\t\t)\n\t}\n\n\ttargetArgs := make([]string, 0, len(positional)-2+len(serverArgs))\n\ttargetArgs = append(targetArgs, positional[2:]...)\n\ttargetArgs = append(targetArgs, serverArgs...)","sourceCodeStart":134,"sourceCodeEnd":170,"githubUrl":"https://github.com/sipeed/picoclaw/blob/49183d7e8daed0dba89ddbb6fcb60089401d9680/cmd/picoclaw/internal/mcp/add.go#L134-L170","documentation":"When the mcp add argument list contains `--`, everything after it is treated as the explicit server command (explicitCommand). This error fires when explicitCommand is non-empty but the positional count before `--` is not exactly 1 - the parser expects exactly the server <name> there, nothing more, nothing less.","triggerScenarios":"`picoclaw mcp add name npx -- -y server` (2 positionals before --, e.g. name plus a command-or-url) or `picoclaw mcp add -- cmd arg` (0 positionals).","commonSituations":"Leaving the old command-or-url in place after adding `--`; forgetting the server name; assuming `--` can follow any argument layout.","solutions":["Use the exact layout: `picoclaw mcp add [flags] <name> -- <command> [args...]`","Remove the extra positional (usually the command-or-url) before `--`","Or drop `--` and use the plain form `picoclaw mcp add <name> <command-or-url> [args...]`"],"exampleFix":"# before\npicoclaw mcp add fs npx -- -y @mcp/fs\n# after\npicoclaw mcp add fs -- npx -y @mcp/fs","handlingStrategy":"validation","validationCode":"# exactly one positional before --\nset -- name cmd arg1   # wrong\nset -- name -- cmd arg1 # right\npicoclaw mcp add \"$@\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Memorize the two layouts: <name> <cmd-or-url> [args...] vs <name> -- <cmd> [args...]","With `--`, delete the command-or-url token; only the name remains","Put picoclaw flags before the name; everything after `--` is the server command"],"tags":["mcp","cli","usage","arguments"],"backgroundTag":null,"analyzedSha":"49183d7e8daed0dba89ddbb6fcb60089401d9680","analyzedAt":"2026-08-15T21:55:41.315Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}