Skip to content

Every agent's model. One place. Codex on DeepSeek, Claude Code on Kimi, from the menu bar.

cli: magpie tools lists, and magpie tool calls, the tools magpie's MCP servers give agents (iwinux)

yetoneea1f9492bc34
diff --git a/README.md b/README.md
index a0239b00e..096aa726e 100644
--- a/README.md
+++ b/README.md
@@ -67,6 +67,7 @@ magpie group add "Opus anywhere" models=claude/claude-opus-5-5,copilot/claude-op
magpie claude group/opus-anywhere # fails over between subscriptions
magpie save work && magpie use work # profiles
magpie quota # what's left on every plan
+magpie tool generate_image "a magpie, watercolour" -o hero.png # magpie's image, vision and search tools, called directly
magpie tui # the whole thing, in a terminal
```
diff --git a/README.zh-CN.md b/README.zh-CN.md
index ae61ffe34..51d5e14d2 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -67,6 +67,7 @@ magpie group add "Opus anywhere" models=claude/claude-opus-5-5,copilot/claude-op
magpie claude group/opus-anywhere # 在多个订阅间自动切换
magpie save work && magpie use work # 方案
magpie quota # 每个套餐还剩多少
+magpie tool generate_image "一只喜鹊,水彩" -o hero.png # 直接调用 magpie 的生图、识图、搜索工具
magpie tui # 全部功能,在终端里
```
diff --git a/docs/reference.md b/docs/reference.md
index 8df47a86e..68b5d3c2c 100644
--- a/docs/reference.md
+++ b/docs/reference.md
@@ -2651,8 +2651,26 @@ magpie quota # what is left of every subscription, plan and k
magpie quota refresh codex # read Codex's cards again now (once per 30s)
magpie quota wait codex # block until a Codex account has allowance again
magpie quota credits [email protected] off # hold a ChatGPT account at its limit instead of spending credits
+
+magpie tools # the tools magpie's MCP servers give agents, with their parameters
+magpie tools generate_image # one tool in full
+magpie tool generate_image "a magpie on a branch, watercolour" --size 1536x1024 -o hero.png
+magpie tool generate_image --n 2 --quality high --background transparent "an app icon" # hero.png, then numbered
+magpie tool analyze_image ./shot.png --prompt "what does the error say?"
+magpie tool web_search "go 1.27 release notes"
```
+`magpie tool` calls a tool through the running magpie's own MCP servers
+(image generation, image recognition, web search and plugins' tools), as an
+agent's MCP call does, so it has the same tools and parameters, models from
+Settings, and the same usage counting. A parameter is `--<param> <value>`; the
+words left over are the tool's one required text. An unknown or missing
+parameter is refused before anything is called. An image or video it makes is
+saved at `-o` (a file or a folder) or in the current folder, never over a file
+that is there; `--json` prints the raw answer. It needs magpie running (the
+app, `magpie serve` or the service); `MAGPIE_GATEWAY=<url>` points it at
+another.
+
In the app, click any value to open a filtered list; type to search or to
enter something that is not listed; `esc` closes the panel. Profiles are the
chips at the bottom: click to apply, `×` to delete, *+ save current* to add.
diff --git a/docs/subsystems/gateway-routing.md b/docs/subsystems/gateway-routing.md
index 10a624b95..3afcdcc39 100644
--- a/docs/subsystems/gateway-routing.md
+++ b/docs/subsystems/gateway-routing.md
@@ -787,6 +787,19 @@ model, checked before the arguments. Nothing is written into the agent's
project. Settings › Models shows the address (`#imageMcpRow`, below
`#visionMcpRow`).
+Each answer also carries `_meta` for a client that acts on it rather than
+reads it: `usemagpie.ai/pending` is the id to wait on (`PendingMeta`, beside
+the text that says to call `generation_result`), and `usemagpie.ai/files`
+lists each file made (`FilesMeta`, `MadeFile`: its URL, and `inline` when the
+image is in the content too). `magpie tool` ([`tool_cli.go`](../../internal/cli/tool_cli.go))
+is such a client: it lists and calls the tools of every server in
+`OwnMCPServers` (image, vision, web search, plugin tools) over HTTP with the
+local token and the `magpie-tool/1` User-Agent, waits on a pending id, and
+saves the files (`imagemcp.Target` names them, never over a file). It starts
+nothing of its own (#3318) and refuses an unknown or missing parameter before
+calling. Covered by `TestToolDrawsThroughTheGateway` (the real gateway, a fake
+vendor) and the other `TestTool*` tests.
+
Covered by `TestImageMCPDrawsAndServesTheImage`, `TestImageMCPSaysWhenOff`,
`TestImageMCPGuarded`, `TestImageMCPHeldToKeyLimit`,
`TestImageMCPSlowDrawingIsWaitedOn`, `TestImageMCPMakesVideos`,
diff --git a/internal/cli/help_cli.go b/internal/cli/help_cli.go
index ed4b97c3d..e0e665d73 100644
--- a/internal/cli/help_cli.go
+++ b/internal/cli/help_cli.go
@@ -64,6 +64,8 @@ func helpFor(args []string) string {
return sessionsUsage
case "search":
return searchUsage
+ case "tool", "tools":
+ return toolUsage
case "visible":
return visibleUsage
case "webdav", "dav":
diff --git a/internal/cli/main.go b/internal/cli/main.go
index 7750da29c..cab7505cc 100644
--- a/internal/cli/main.go
+++ b/internal/cli/main.go
@@ -121,6 +121,8 @@ const usage = `magpie — one place to pick every agent's model
magpie gateway-key models <id> [all|<provider>/<model>|<provider>/* ...] the models a key may use, every one unless it names some
magpie gateway-key quotas <id> [on|off] whether a key held to a budget, models or accounts is told the quotas of what it may use
magpie mcp image the image and video generation MCP server an agent is given from the library (stdio)
+ magpie tools [<name>] the tools magpie's MCP servers give agents (images, vision, web search, plugins'), with their parameters
+ magpie tool <name> [--<param> <value>…] [<words>] [-o <file|folder>] [--json] call one through the running magpie; an image or video it makes is saved
magpie usage [today|7d|30d|all] tokens and cost per agent, model and subscription account (30d)
magpie usage --csv [--account <name>] [today|7d|30d|all] every request as CSV (or one account's): the model asked for, sent and served, tokens, cost, time, status, account
magpie usage [--csv [--account <name>]] --last <dur>|--days <n> the same for a window ending now (24h, 90m, 1.5 days), not from a midnight
@@ -299,6 +301,10 @@ func run(args []string) error {
return claudebridge.RunMCP(args[1:])
case "statusline":
return statuslineCmd(args)
+ case "tools":
+ return toolsCmd(args[1:])
+ case "tool":
+ return toolCmd(args[1:])
}
}
startUp()
diff --git a/internal/cli/tool_cli.go b/internal/cli/tool_cli.go
new file mode 100644
index 000000000..7f38f3cfd
--- /dev/null
+++ b/internal/cli/tool_cli.go
@@ -0,0 +1,831 @@
+package cli
+
+// magpie tools and magpie tool: the tools magpie's own MCP servers give
+// agents (image generation, image recognition, web search, plugins'
+// tools), listed and called from the terminal (iwinux on Discord). They
+// are asked of the running gateway's MCP servers themselves
+// (gateway.OwnMCPServers), so the tools, their parameters and what they
+// do are the ones an agent gets, and nothing else is started (#3318).
+
+import (
+ "bytes"
+ "encoding/base64"
+ "encoding/json"
+ "errors"
+ "fmt"
+ "io"
+ "net/http"
+ "net/url"
+ "os"
+ "path/filepath"
+ "regexp"
+ "slices"
+ "strconv"
+ "strings"
+ "time"
+
+ "github.com/yetone/magpie/internal/gateway"
+ "github.com/yetone/magpie/internal/imagemcp"
+)
+
+const toolUsage = `usage:
+ magpie tools every tool magpie's MCP servers give agents, with its parameters
+ magpie tools <name> one tool: what it does and each parameter
+ magpie tool <name> [--<param> <value>…] [<words>…] [-o <file|folder>] [--json]
+ call one through the running magpie, as an agent's MCP call is
+
+ A parameter is --<param> <value> or --<param>=<value> (- and _ alike); a list
+ parameter is given once per item. The words left over are the tool's one required
+ text (generate_image's prompt, web_search's query, analyze_image's image), else its
+ prompt. A file named in a parameter is read by magpie on this computer.
+ An image or video the tool makes is saved: -o names a file or a folder (with --n 2 or
+ more a number is added to the name), else it goes in this folder, named from the
+ prompt; a file that is there is never written over. Text is printed. --json prints
+ the tool's answer as it came and saves nothing.
+ An unknown parameter, or a missing required one, is refused before anything is
+ called. The models are the ones magpie's Settings pick (Images › Image generation,
+ Image recognition, Web search). It asks the gateway at the port in Settings' Gateway
+ address (or MAGPIE_ADDR; MAGPIE_GATEWAY=<url> for another).
+
+ e.g. magpie tool generate_image "a magpie on a branch, watercolour" --size 1536x1024 -o hero.png
+ magpie tool generate_image --n 2 --quality high --background transparent "an app icon"
+ magpie tool analyze_image ./shot.png --prompt "what does the error say?"
+ magpie tool web_search "go 1.27 release notes"`
+
+// toolAgent is the User-Agent the calls go with: magpie's own, as the
+// image tool's (gateway.DrawAgent), so a vendor is sent magpie's.
+const toolAgent = "magpie-tool/1"
+
+// toolCallMost bounds one ask of the gateway: the image server answers
+// within about 20s, a plugin's tool within 55s, and a look at a large
+// image or a slow page takes longer.
+var toolCallMost = 10 * time.Minute
+
+// toolWaitMost is how long a drawing or video still being made is waited
+// on, and toolPoll the pause between asks after it.
+var (
+ toolWaitMost = 30 * time.Minute
+ toolPoll = time.Second
+)
+
+// toolGateway is the running gateway, asked as an agent's MCP client asks.
+type toolGateway struct {
+ base string
+ client *http.Client
+ next int
+}
+
+func newToolGateway() *toolGateway {
+ base := strings.TrimRight(os.Getenv("MAGPIE_GATEWAY"), "/")
+ if base == "" {
+ base = gateway.URL()
+ }
+ return &toolGateway{base: base, client: &http.Client{Timeout: toolCallMost}}
+}
+
+// errNoMagpie is a gateway that doesn't answer at all.
+type errNoMagpie struct {
+ base string
+ err error
+}
+
+func (e errNoMagpie) Error() string {
+ return fmt.Sprintf("magpie isn't running at %s: open the app or run magpie serve, then try again (%v)", e.base, e.err)
+}
+
+func (g *toolGateway) do(method, path string, body []byte) (*http.Response, error) {
+ r, err := http.NewRequest(method, g.base+path, bytes.NewReader(body))
+ if err != nil {
+ return nil, err
+ }
+ if body != nil {
+ r.Header.Set("Content-Type", "application/json")
+ r.Header.Set("Accept", "application/json, text/event-stream")
+ }
+ r.Header.Set("Authorization", "Bearer "+gateway.Token)
+ r.Header.Set("User-Agent", toolAgent)
+ res, err := g.client.Do(r)
+ if err != nil {
+ return nil, errNoMagpie{g.base, err}
+ }
+ return res, nil
+}
+
+// rpc posts one JSON-RPC request to the MCP server at path: its result,
+// or what went wrong.
+func (g *toolGateway) rpc(path, method string, params any) (json.RawMessage, error) {
+ g.next++
+ body, _ := json.Marshal(map[string]any{"jsonrpc": "2.0", "id": g.next, "method": method, "params": params})
+ res, err := g.do(http.MethodPost, path, body)
+ if err != nil {
+ return nil, err
+ }
+ defer res.Body.Close()
+ data, err := io.ReadAll(io.LimitReader(res.Body, 512<<20))
+ if err != nil {
+ return nil, fmt.Errorf("the answer from %s was cut off: %w", g.base, err)
+ }
+ switch {
+ case res.StatusCode == http.StatusNotFound:
+ return nil, fmt.Errorf("the magpie at %s has no %s: it is older than this one, update it", g.base, path)
+ case res.StatusCode != http.StatusOK:
+ return nil, fmt.Errorf("the magpie at %s answered %s: %s", g.base, res.Status, strings.TrimSpace(string(data)))
+ }
+ var m struct {
+ Result json.RawMessage `json:"result"`
+ Error *struct {
+ Message string `json:"message"`
+ } `json:"error"`
+ }
+ if err := json.Unmarshal(data, &m); err != nil {
+ return nil, fmt.Errorf("what %s answered isn't JSON-RPC: is it magpie? (%v)", g.base, err)
+ }
+ if m.Error != nil {
+ return nil, errors.New(m.Error.Message)
+ }
+ return m.Result, nil
+}
+
+// fetch is a file the gateway made, at u's path on the gateway asked: a
+// URL may name the address agents are given (MAGPIE_PUBLIC_URL), and the
+// key goes nowhere else.
+func (g *toolGateway) fetch(u string) ([]byte, error) {
+ pu, err := url.Parse(u)
+ if err != nil || !strings.HasPrefix(pu.Path, "/") {
+ return nil, fmt.Errorf("%q isn't a file of magpie's", u)
+ }
+ res, err := g.do(http.MethodGet, pu.RequestURI(), nil)
+ if err != nil {
+ return nil, err
+ }
+ defer res.Body.Close()
+ data, err := io.ReadAll(io.LimitReader(res.Body, 1<<30))
+ if err != nil {
+ return nil, fmt.Errorf("downloading %s was cut off: %w", pu.Path, err)
+ }
+ if res.StatusCode != http.StatusOK {
+ return nil, fmt.Errorf("downloading %s: %s %s", pu.Path, res.Status, strings.TrimSpace(string(data)))
+ }
+ return data, nil
+}
+
+// toolParam is a parameter's JSON Schema, as much of it as the terminal
+// needs.
+type toolParam struct {
+ Type any `json:"type"`
+ Description string `json:"description"`
+ Items *toolParam `json:"items"`
+ Enum []any `json:"enum"`
+ Minimum *float64 `json:"minimum"`
+ Maximum *float64 `json:"maximum"`
+}
+
+// kind is the parameter's type: the first of a list that isn't null.
+func (p toolParam) kind() string {
+ switch t := p.Type.(type) {
+ case string:
+ return t
+ case []any:
+ for _, v := range t {
+ if s, ok := v.(string); ok && s != "null" {
+ return s
+ }
+ }
+ }
+ return ""
+}
+
+// listedTool is one tool of one of the gateway's MCP servers.
+type listedTool struct {
+ Server string `json:"server"`
+ path string
+ Name string `json:"name"`
+ Description string `json:"description"`
+ InputSchema struct {
+ Properties map[string]toolParam `json:"properties"`
+ Required []string `json:"required"`
+ } `json:"inputSchema"`
+}
+
+// params are the tool's parameter names, the required first, each part in
+// name order.
+func (t listedTool) params() []string {
+ var names []string
+ for k := range t.InputSchema.Properties {
+ names = append(names, k)
+ }
+ slices.SortFunc(names, func(a, b string) int {
+ ra, rb := t.required(a), t.required(b)
+ if ra != rb {
+ if ra {
+ return -1
+ }
+ return 1
+ }
+ return strings.Compare(a, b)
+ })
+ return names
+}
+
+func (t listedTool) required(name string) bool { return slices.Contains(t.InputSchema.Required, name) }
+
+// wordsParam is the parameter the words left over are: the one required
+// text, else prompt; "" when the tool has neither.
+func (t listedTool) wordsParam() string {
+ var texts []string
+ for _, r := range t.InputSchema.Required {
+ if p, ok := t.InputSchema.Properties[r]; ok && p.kind() == "string" {
+ texts = append(texts, r)
+ }
+ }
+ if len(texts) == 1 {
+ return texts[0]
+ }
+ if p, ok := t.InputSchema.Properties["prompt"]; ok && p.kind() == "string" {
+ return "prompt"
+ }
+ return ""
+}
+
+// listTools asks each of the gateway's MCP servers for its tools; a server
+// that can't say is noted, a gateway that doesn't answer is the error.
+func listTools(g *toolGateway) ([]listedTool, []string, error) {
+ var out []listedTool
+ var notes []string
+ for _, srv := range gateway.OwnMCPServers {
+ res, err := g.rpc(srv.Path, "tools/list", map[string]any{})
+ if err != nil {
+ var no errNoMagpie
+ if errors.As(err, &no) {
+ return nil, nil, err
+ }
+ notes = append(notes, srv.Name+": "+err.Error())
+ continue
+ }
+ var l struct {
+ Tools []listedTool `json:"tools"`
+ }
+ if err := json.Unmarshal(res, &l); err != nil {
+ notes = append(notes, srv.Name+": its tool list isn't one: "+err.Error())
+ continue
+ }
+ for _, t := range l.Tools {
+ t.Server, t.path = srv.Name, srv.Path
+ out = append(out, t)
+ }
+ }
+ return out, notes, nil
+}
+
+// findTool is the tool called name: the first server's of those that have
+// one (gateway.OwnMCPServers' order).
+func findTool(tools []listedTool, name string) (listedTool, bool) {
+ for _, t := range tools {
+ if t.Name == name {
+ return t, true
+ }
+ }
+ return listedTool{}, false
+}
+
+// firstSentence is a description's first sentence, on one line.
+func firstSentence(s string) string {
+ s = strings.Join(strings.Fields(s), " ")
+ if i := strings.Index(s, ". "); i >= 0 {
+ s = s[:i+1]
+ }
+ if r := []rune(s); len(r) > 140 {
+ s = string(r[:139]) + "…"
+ }
+ return s
+}
+
+// paramShape is how a parameter's value is written: <text>, <1-4>, …
+func paramShape(p toolParam) string {
+ var shape string
+ switch p.kind() {
+ case "integer", "number":
+ shape = "number"
+ if p.kind() == "integer" {
+ shape = "whole number"
+ }
+ if p.Minimum != nil && p.Maximum != nil {
+ shape = strconv.FormatFloat(*p.Minimum, 'f', -1, 64) + "-" + strconv.FormatFloat(*p.Maximum, 'f', -1, 64)
+ }
+ case "boolean":
+ shape = "true|false"
+ case "array":
+ item := toolParam{Type: "string"}
+ if p.Items != nil {
+ item = *p.Items
+ }
+ return paramShape(item) + "…"
+ case "object":
+ shape = "json"
+ default:
+ shape = "text"
+ }
+ if len(p.Enum) > 0 {
+ var vs []string
+ for _, v := range p.Enum {
+ vs = append(vs, fmt.Sprint(v))
+ }
+ shape = strings.Join(vs, "|")
+ }
+ return "<" + shape + ">"
+}
+
+// toolsCmd: magpie tools [<name>]
+func toolsCmd(args []string) error {
+ for _, a := range args {
+ if strings.HasPrefix(a, "-") {
+ return fmt.Errorf("unknown flag %s (magpie tools [<name>])", a)
+ }
+ }
+ if len(args) > 1 {
+ return errors.New("magpie tools takes one tool's name at most (magpie tools [<name>])")
+ }
+ g := newToolGateway()
+ tools, notes, err := listTools(g)
+ if err != nil {
+ return err
+ }
+ if len(args) == 1 {
+ t, ok := findTool(tools, args[0])
+ if !ok {
+ return unknownTool(args[0], tools, notes)
+ }
+ fmt.Print(toolHelp(t))
+ return nil
+ }
+ server := ""
+ for _, t := range tools {
+ if t.Server != server {
+ if server != "" {
+ fmt.Println()
+ }
+ server = t.Server
+ fmt.Println(bold.Render(server))
+ }
+ fmt.Printf(" %-20s %s\n", t.Name, firstSentence(t.Description))
+ var ps []string
+ for _, n := range t.params() {
+ p := "--" + n + " " + paramShape(t.InputSchema.Properties[n])
+ if t.required(n) {
+ p += " (required)"
+ }
+ ps = append(ps, p)
+ }
+ if len(ps) > 0 {
+ fmt.Printf(" %-20s %s\n", "", muted.Render(strings.Join(ps, " ")))
+ }
+ }
+ if len(tools) == 0 {
+ fmt.Println(muted.Render(" no tools: the magpie running has none on"))
+ }
+ for _, n := range notes {
+ fmt.Println(muted.Render(" " + n))
+ }
+ fmt.Println(muted.Render("\nmagpie tools <name> for one in full · magpie tool <name> --<param> <value> … to call it"))
+ return nil
+}
+
+// toolHelp is one tool in full.
+func toolHelp(t listedTool) string {
+ var b strings.Builder
+ fmt.Fprintf(&b, "%s %s\n", bold.Render(t.Name), muted.Render("("+t.Server+", "+t.path+")"))
+ fmt.Fprintf(&b, " %s\n\n", strings.Join(strings.Fields(t.Description), " "))
+ for _, n := range t.params() {
+ p := t.InputSchema.Properties[n]
+ head := "--" + n + " " + paramShape(p)
+ if t.required(n) {
+ head += " required"
+ }
+ fmt.Fprintf(&b, " %s\n", head)
+ if d := strings.Join(strings.Fields(p.Description), " "); d != "" {
+ fmt.Fprintf(&b, " %s\n", muted.Render(d))
+ }
+ }
+ if w := t.wordsParam(); w != "" {
+ fmt.Fprintf(&b, "\n the words after the name are its --%s: magpie tool %s <%s>\n", w, t.Name, w)
+ }
+ return b.String()
+}
+
+func unknownTool(name string, tools []listedTool, notes []string) error {
+ var names []string
+ for _, t := range tools {
+ names = append(names, t.Name)
+ }
+ msg := fmt.Sprintf("no tool called %q: nothing was called; there is %s (magpie tools)", name, strings.Join(names, ", "))
+ if len(names) == 0 {
+ msg = fmt.Sprintf("no tool called %q: the magpie running has no tools on", name)
+ }
+ if len(notes) > 0 {
+ msg += " (" + strings.Join(notes, "; ") + ")"
+ }
+ return errors.New(msg)
+}
+
+// toolCall is a call as the command line asks it.
+type toolCall struct {
+ args map[string]any
+ output string
+ json bool
+}
+
+// parseToolArgs reads in, what follows magpie tool <name>, against t's
+// parameters: nothing is called on an error.
+func parseToolArgs(t listedTool, in []string) (toolCall, error) {
+ c := toolCall{args: map[string]any{}}
+ props := t.InputSchema.Properties
+ var words []string
+ for i := 0; i < len(in); i++ {
+ a := in[i]
+ if a == "--" {
+ words = append(words, in[i+1:]...)
+ break
+ }
+ switch a {
+ case "--json":
+ c.json = true
+ continue
+ case "-o", "--output":
+ if i+1 >= len(in) || in[i+1] == "" {
+ return c, fmt.Errorf("%s needs a file or a folder: nothing was called", a)
+ }
+ c.output = in[i+1]
+ i++
+ continue
+ }
+ if v, ok := strings.CutPrefix(a, "--output="); ok {
+ if v == "" {
+ return c, errors.New("--output needs a file or a folder: nothing was called")
+ }
+ c.output = v
+ continue
+ }
+ if !strings.HasPrefix(a, "--") {
+ if len(a) > 1 && a[0] == '-' {
+ return c, fmt.Errorf("unknown flag %s: nothing was called (words that begin with - go after --)", a)
+ }
+ words = append(words, a)
+ continue
+ }
+ name, val, hasVal := strings.Cut(a[2:], "=")
+ key := paramKey(props, name)
+ if key == "" {
+ return c, fmt.Errorf("%s takes no --%s: nothing was called; it takes %s (magpie tools %s)", t.Name, name, paramList(t), t.Name)
+ }
+ p := props[key]
+ if !hasVal {
+ if p.kind() == "boolean" {
+ val = "true"
+ if i+1 < len(in) && (in[i+1] == "true" || in[i+1] == "false") {
+ val = in[i+1]
+ i++
+ }
+ } else {
+ if i+1 >= len(in) {
+ return c, fmt.Errorf("--%s needs a value: nothing was called", name)
+ }
+ val = in[i+1]
+ i++
+ }
+ }
+ if p.kind() == "array" {
+ item := toolParam{Type: "string", Description: p.Description}
+ if p.Items != nil {
+ item = *p.Items
+ if item.Description == "" {
+ item.Description = p.Description
+ }
+ }
+ v, err := paramValue(key, item, val)
+ if err != nil {
+ return c, err
+ }
+ list, _ := c.args[key].([]any)
+ c.args[key] = append(list, v)
+ continue
+ }
+ if _, dup := c.args[key]; dup {
+ return c, fmt.Errorf("--%s is given twice: nothing was called", key)
+ }
+ v, err := paramValue(key, p, val)
+ if err != nil {
+ return c, err
+ }
+ c.args[key] = v
+ }
+ if len(words) > 0 {
+ w := t.wordsParam()
+ if w == "" {
+ return c, fmt.Errorf("%s takes no words, only --<param> <value>: nothing was called; it takes %s", t.Name, paramList(t))
+ }
+ if _, dup := c.args[w]; dup {
+ return c, fmt.Errorf("--%s is given, and the words %q too: nothing was called", w, strings.Join(words, " "))
+ }
+ v, err := paramValue(w, props[w], strings.Join(words, " "))
+ if err != nil {
+ return c, err
+ }
+ c.args[w] = v
+ }
+ var missing []string
+ for _, r := range t.InputSchema.Required {
+ if _, ok := c.args[r]; !ok {
+ missing = append(missing, "--"+r)
+ }
+ }
+ if len(missing) > 0 {
+ return c, fmt.Errorf("%s needs %s: nothing was called (magpie tools %s)", t.Name, strings.Join(missing, " and "), t.Name)
+ }
+ return c, nil
+}
+
+// paramKey is the parameter name names, - and _ alike; "" for none.
+func paramKey(props map[string]toolParam, name string) string {
+ if _, ok := props[name]; ok {
+ return name
+ }
+ norm := func(s string) string { return strings.ReplaceAll(s, "-", "_") }
+ for k := range props {
+ if norm(k) == norm(name) {
+ return k
+ }
+ }
+ return ""
+}
+
+func paramList(t listedTool) string {
+ var ps []string
+ for _, n := range t.params() {
+ ps = append(ps, "--"+n)
+ }
+ if len(ps) == 0 {
+ return "nothing"
+ }
+ return strings.Join(ps, ", ")
+}
+
+// paramValue is val as p's type takes it.
+func paramValue(name string, p toolParam, val string) (any, error) {
+ var v any
+ switch p.kind() {
+ case "integer":
+ n, err := strconv.ParseInt(strings.TrimSpace(val), 10, 64)
+ if err != nil {
+ return nil, fmt.Errorf("--%s takes a whole number, not %q: nothing was called", name, val)
+ }
+ v = n
+ case "number":
+ f, err := strconv.ParseFloat(strings.TrimSpace(val), 64)
+ if err != nil {
+ return nil, fmt.Errorf("--%s takes a number, not %q: nothing was called", name, val)
+ }
+ v = f
+ case "boolean":
+ b, err := strconv.ParseBool(strings.TrimSpace(val))
+ if err != nil {
+ return nil, fmt.Errorf("--%s takes true or false, not %q: nothing was called", name, val)
+ }
+ v = b
+ case "object", "array":
+ if err := json.Unmarshal([]byte(val), &v); err != nil {
+ return nil, fmt.Errorf("--%s takes JSON, not %q: nothing was called", name, val)
+ }
+ default:
+ v = localFile(p, val)
+ }
+ if len(p.Enum) > 0 && !slices.ContainsFunc(p.Enum, func(e any) bool { return fmt.Sprint(e) == fmt.Sprint(v) }) {
+ return nil, fmt.Errorf("--%s takes %s, not %q: nothing was called", name, paramShape(toolParam{Enum: p.Enum}), val)
+ }
+ return v, nil
+}
+
+// localFile is val made absolute when p takes a file and val names one
+// here, relative to this folder: the gateway doesn't know it.
+func localFile(p toolParam, val string) string {
+ d := strings.ToLower(p.Description)
+ if !strings.Contains(d, "file") || !strings.Contains(d, "path") || val == "" || filepath.IsAbs(val) || strings.Contains(val, "://") || strings.HasPrefix(strings.ToLower(val), "data:") {
+ return val
+ }
+ if st, err := os.Stat(val); err != nil || st.IsDir() {
+ return val
+ }
+ if abs, err := filepath.Abs(val); err == nil {
+ return abs
+ }
+ return val
+}
+
+// toolAnswer is a tools/call result.
+type toolAnswer struct {
+ Content []struct {
+ Type string `json:"type"`
+ Text string `json:"text"`
+ Data string `json:"data"`
+ MimeType string `json:"mimeType"`
+ } `json:"content"`
+ IsError bool `json:"isError"`
+ Meta map[string]json.RawMessage `json:"_meta"`
+}
+
+func (a toolAnswer) text() string {
+ var b strings.Builder
+ for _, c := range a.Content {
+ if c.Type == "text" && c.Text != "" {
+ b.WriteString(strings.TrimRight(c.Text, "\n") + "\n")
+ }
+ }
+ return b.String()
+}
+
+// stillMaking is the id an answer says to wait on with generation_result;
+// a gateway older than PendingMeta says it in its text alone.
+var stillMakingText = regexp.MustCompile(gateway.GenerationResultTool + ` with id "([^"]+)"`)
+
+func (a toolAnswer) pending() string {
+ var id string
+ if raw, ok := a.Meta[gateway.PendingMeta]; ok && json.Unmarshal(raw, &id) == nil {
+ return id
+ }
+ if a.IsError {
+ return ""
+ }
+ if m := stillMakingText.FindStringSubmatch(a.text()); m != nil {
+ return m[1]
+ }
+ return ""
+}
+
+// callTool calls t with args and waits for what it makes: the answer.
+func callTool(g *toolGateway, t listedTool, args map[string]any) (json.RawMessage, error) {
+ res, err := g.rpc(t.path, "tools/call", map[string]any{"name": t.Name, "arguments": args})
+ deadline := time.Now().Add(toolWaitMost)
+ for err == nil {
+ var a toolAnswer
+ json.Unmarshal(res, &a)
+ id := a.pending()
+ if id == "" || time.Now().After(deadline) {
+ break
+ }
+ fmt.Fprintln(os.Stderr, muted.Render("still being made ("+id+"), waiting…"))
+ time.Sleep(toolPoll)
+ res, err = g.rpc(t.path, "tools/call", map[string]any{"name": gateway.GenerationResultTool, "arguments": map[string]any{"id": id}})
+ }
+ return res, err
+}
+
+// toolCmd: magpie tool <name> [--<param> <value>…] [<words>…] [-o <path>] [--json]
+func toolCmd(args []string) error {
+ if len(args) == 0 || strings.HasPrefix(args[0], "-") {
+ return errors.New("magpie tool needs a tool's name first: magpie tool <name> --<param> <value> … (magpie tools lists them)")
+ }
+ g := newToolGateway()
+ tools, notes, err := listTools(g)
+ if err != nil {
+ return err
+ }
+ t, ok := findTool(tools, args[0])
+ if !ok {
+ return unknownTool(args[0], tools, notes)
+ }
+ c, err := parseToolArgs(t, args[1:])
+ if err != nil {
+ return err
+ }
+ res, err := callTool(g, t, c.args)
+ if err != nil {
+ return err
+ }
+ if c.json {
+ var out bytes.Buffer
+ if json.Indent(&out, res, "", " ") != nil {
+ out.Reset()
+ out.Write(res)
+ }
+ fmt.Println(out.String())
+ var a toolAnswer
+ json.Unmarshal(res, &a)
+ if a.IsError {
+ return errors.New(t.Name + " answered with an error")
+ }
+ return nil
+ }
+ var a toolAnswer
+ if err := json.Unmarshal(res, &a); err != nil {
+ return fmt.Errorf("%s's answer isn't one: %v", t.Name, err)
+ }
+ if a.IsError {
+ return errors.New(strings.TrimSpace(a.text()))
+ }
+ fmt.Print(a.text())
+ prompt, _ := c.args["prompt"].(string)
+ if prompt == "" {
+ prompt = t.Name
+ }
+ saved, err := saveMade(g, a, c.output, prompt)
+ for _, p := range saved {
+ fmt.Printf("%s %s\n", green.Render("saved"), p)
+ }
+ return err
+}
+
+// made is one file an answer brings: its bytes, or where to get them.
+type made struct {
+ data []byte
+ url string
+}
+
+// saveMade saves the images and videos answer a brings, at output (a file
+// or a folder) or in this folder: the paths saved.
+func saveMade(g *toolGateway, a toolAnswer, output, prompt string) ([]string, error) {
+ var inline [][]byte
+ for _, c := range a.Content {
+ if c.Type != "image" && c.Type != "video" {
+ continue
+ }
+ b, err := base64.StdEncoding.DecodeString(c.Data)
+ if err != nil {
+ return nil, fmt.Errorf("an image came back broken: %v", err)
+ }
+ inline = append(inline, b)
+ }
+ var files []gateway.MadeFile
+ if raw, ok := a.Meta[gateway.FilesMeta]; ok {
+ json.Unmarshal(raw, &files)
+ }
+ var all []made
+ if len(files) == 0 {
+ for _, b := range inline {
+ all = append(all, made{data: b})
+ }
+ }
+ for _, f := range files {
+ if f.Inline && len(inline) > 0 {
+ all = append(all, made{data: inline[0]})
+ inline = inline[1:]
+ continue
+ }
+ all = append(all, made{url: f.URL})
+ }
+ if len(all) == 0 {
+ return nil, nil
+ }
+ dir, err := os.Getwd()
+ if err != nil {
+ return nil, err
+ }
+ at := output
+ if at == "" {
+ at = "."
+ }
+ var saved []string
+ for i, m := range all {
+ if m.data == nil {
+ if m.data, err = g.fetch(m.url); err != nil {
+ return saved, err
+ }
+ }
+ path, err := imagemcp.Target(dir, at, prompt, madeExt(m.data), i, len(all))
+ if err != nil {
+ return saved, err
+ }
+ if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+ return saved, err
+ }
+ f, err := os.OpenFile(path, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o644)
+ if err != nil {
+ return saved, err
+ }
+ _, werr := f.Write(m.data)
+ if cerr := f.Close(); werr == nil {
+ werr = cerr
+ }
+ if werr != nil {
+ os.Remove(path)
+ return saved, werr
+ }
+ saved = append(saved, path)
+ }
+ return saved, nil
+}
+
+// madeExt is the extension of what data is.
+func madeExt(data []byte) string {
+ switch ct := http.DetectContentType(data); {
+ case ct == "image/jpeg":
+ return ".jpg"
+ case ct == "image/webp":
+ return ".webp"
+ case ct == "image/gif":
+ return ".gif"
+ case strings.HasPrefix(ct, "video/webm"):
+ return ".webm"
+ case strings.HasPrefix(ct, "video/"):
+ return ".mp4"
+ }
+ return ".png"
+}
diff --git a/internal/cli/tool_cli_test.go b/internal/cli/tool_cli_test.go
new file mode 100644
index 000000000..242d5f9fe
--- /dev/null
+++ b/internal/cli/tool_cli_test.go
@@ -0,0 +1,416 @@
+package cli
+
+import (
+ "bytes"
+ "encoding/base64"
+ "encoding/json"
+ "image"
+ "image/png"
+ "io"
+ "net"
+ "net/http"
+ "net/http/httptest"
+ "os"
+ "path/filepath"
+ "strings"
+ "sync"
+ "testing"
+
+ "github.com/yetone/magpie/internal/catalog"
+ "github.com/yetone/magpie/internal/gateway"
+ "github.com/yetone/magpie/internal/provider"
+)
+
+// a one-pixel PNG
+func tinyPNG(t *testing.T) []byte {
+ t.Helper()
+ var b bytes.Buffer
+ if err := png.Encode(&b, image.NewRGBA(image.Rect(0, 0, 1, 1))); err != nil {
+ t.Fatal(err)
+ }
+ return b.Bytes()
+}
+
+// fakeTools is a gateway's MCP servers as `magpie tool` asks them: the
+// image server's generate_image and generation_result, the web search
+// server's web_search, and every request it was sent.
+type fakeTools struct {
+ mu sync.Mutex
+ calls []string // "<path> <method> <tool> <arguments>"
+ gets []string // "<path> <Authorization>"
+ // call answers a tools/call; nil answers with an empty text
+ call func(name string, args map[string]any) map[string]any
+ file []byte
+}
+
+func (f *fakeTools) toolCalls() []string {
+ f.mu.Lock()
+ defer f.mu.Unlock()
+ var out []string
+ for _, c := range f.calls {
+ if strings.Contains(c, " tools/call ") {
+ out = append(out, c)
+ }
+ }
+ return out
+}
+
+func (f *fakeTools) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+ if r.Header.Get("Authorization") != "Bearer "+gateway.Token || r.Header.Get("User-Agent") != toolAgent {
+ http.Error(w, "unauthorised", 401)
+ return
+ }
+ if r.Method == http.MethodGet {
+ f.mu.Lock()
+ f.gets = append(f.gets, r.URL.Path)
+ f.mu.Unlock()
+ w.Write(f.file)
+ return
+ }
+ var m struct {
+ ID json.RawMessage `json:"id"`
+ Method string `json:"method"`
+ Params struct {
+ Name string `json:"name"`
+ Arguments map[string]any `json:"arguments"`
+ } `json:"params"`
+ }
+ json.NewDecoder(r.Body).Decode(&m)
+ args, _ := json.Marshal(m.Params.Arguments)
+ f.mu.Lock()
+ f.calls = append(f.calls, r.URL.Path+" "+m.Method+" "+m.Params.Name+" "+string(args))
+ f.mu.Unlock()
+ var result any
+ switch {
+ case m.Method == "tools/list" && r.URL.Path == gateway.ImageMCPPath:
+ result = map[string]any{"tools": []any{
+ map[string]any{"name": "generate_image", "description": "Generates an image from a text prompt. More words here.", "inputSchema": map[string]any{
+ "type": "object", "required": []string{"prompt"},
+ "properties": map[string]any{
+ "prompt": map[string]any{"type": "string", "description": "What to draw"},
+ "n": map[string]any{"type": "integer", "minimum": 1, "maximum": 4},
+ "quality": map[string]any{"type": "string", "enum": []string{"low", "medium", "high", "auto"}},
+ "reference_images": map[string]any{"type": "array", "items": map[string]any{"type": "string"}, "description": "Images to edit: file paths or URLs"},
+ }}},
+ map[string]any{"name": gateway.GenerationResultTool, "description": "Waits.", "inputSchema": map[string]any{
+ "type": "object", "required": []string{"id"}, "properties": map[string]any{"id": map[string]any{"type": "string"}}}},
+ }}
+ case m.Method == "tools/list" && r.URL.Path == gateway.SearchMCPPath:
+ result = map[string]any{"tools": []any{
+ map[string]any{"name": "web_search", "description": "Searches the web.", "inputSchema": map[string]any{
+ "type": "object", "required": []string{"query"},
+ "properties": map[string]any{"query": map[string]any{"type": "string"}, "deep": map[string]any{"type": "boolean"}}}},
+ }}
+ case m.Method == "tools/list":
+ result = map[string]any{"tools": []any{}}
+ case m.Method == "tools/call" && f.call != nil:
+ result = f.call(m.Params.Name, m.Params.Arguments)
+ case m.Method == "tools/call":
+ result = map[string]any{"content": []any{map[string]any{"type": "text", "text": "done"}}}
+ }
+ json.NewEncoder(w).Encode(map[string]any{"jsonrpc": "2.0", "id": m.ID, "result": result})
+}
+
+// toolHere is a fake gateway magpie tool asks, and a folder of its own the
+// command runs in.
+func toolHere(t *testing.T) (*fakeTools, string) {
+ t.Helper()
+ f := &fakeTools{}
+ srv := httptest.NewServer(f)
+ t.Cleanup(srv.Close)
+ t.Setenv("MAGPIE_GATEWAY", srv.URL)
+ dir := t.TempDir()
+ t.Chdir(dir)
+ was := toolPoll
+ toolPoll = 0
+ t.Cleanup(func() { toolPoll = was })
+ return f, dir
+}
+
+func filesIn(t *testing.T, dir string) []string {
+ t.Helper()
+ ents, err := os.ReadDir(dir)
+ if err != nil {
+ t.Fatal(err)
+ }
+ var out []string
+ for _, e := range ents {
+ out = append(out, e.Name())
+ }
+ return out
+}
+
+// magpie tools lists every server's tools, each with its parameters.
+func TestToolsListsTheServersTools(t *testing.T) {
+ toolHere(t)
+ out, err := runOut(t, "tools")
+ if err != nil {
+ t.Fatal(err)
+ }
+ for _, want := range []string{"image", "generate_image", "Generates an image from a text prompt.", "--prompt <text> (required)", "--n <1-4>", "--quality <low|medium|high|auto>", "web-search", "web_search", "--deep <true|false>"} {
+ if !strings.Contains(out, want) {
+ t.Errorf("no %q in:\n%s", want, out)
+ }
+ }
+ if strings.Contains(out, "More words here") {
+ t.Errorf("the list has more than a description's first sentence:\n%s", out)
+ }
+ out, err = runOut(t, "tools", "generate_image")
+ if err != nil || !strings.Contains(out, "More words here") || !strings.Contains(out, "magpie tool generate_image <prompt>") {
+ t.Fatalf("one tool: %v\n%s", err, out)
+ }
+ if _, err := runOut(t, "tools", "draw"); err == nil || !strings.Contains(err.Error(), `no tool called "draw"`) {
+ t.Fatalf("an unknown tool: %v", err)
+ }
+}
+
+// Parameters are read against the tool's schema: types, - and _ alike,
+// lists given once per item, the words left over its prompt.
+func TestToolReadsParameters(t *testing.T) {
+ _, dir := toolHere(t)
+ os.WriteFile(filepath.Join(dir, "ref.png"), tinyPNG(t), 0o644)
+ tools, _, err := listTools(newToolGateway())
+ if err != nil {
+ t.Fatal(err)
+ }
+ img, _ := findTool(tools, "generate_image")
+ c, err := parseToolArgs(img, []string{"a", "magpie", "--n", "2", "--quality=high", "--reference-images", "ref.png", "--reference_images", "https://x/y.png", "-o", "out", "--json"})
+ if err != nil {
+ t.Fatal(err)
+ }
+ got, _ := json.Marshal(c.args)
+ want, _ := json.Marshal(map[string]any{"prompt": "a magpie", "n": 2, "quality": "high", "reference_images": []string{filepath.Join(dir, "ref.png"), "https://x/y.png"}})
+ if string(got) != string(want) || c.output != "out" || !c.json {
+ t.Fatalf("got %s %q %v, want %s", got, c.output, c.json, want)
+ }
+ search, _ := findTool(tools, "web_search")
+ if c, err := parseToolArgs(search, []string{"--deep", "go", "news"}); err != nil || c.args["query"] != "go news" || c.args["deep"] != true {
+ t.Fatalf("words are the query: %v %v", c.args, err)
+ }
+ if c, err := parseToolArgs(search, []string{"--", "-x", "y"}); err != nil || c.args["query"] != "-x y" {
+ t.Fatalf("words after --: %v %v", c.args, err)
+ }
+}
+
+// An unknown parameter, a missing required one or a bad value is refused
+// before anything is called.
+func TestToolRefusesWhatItDoesntKnowAndCallsNothing(t *testing.T) {
+ f, dir := toolHere(t)
+ for _, args := range [][]string{
+ {"tool", "generate_image", "--model", "gpt-image-1", "a magpie"},
+ {"tool", "generate_image", "--n", "2"},
+ {"tool", "generate_image", "--n", "two", "a magpie"},
+ {"tool", "generate_image", "--quality", "ultra", "a magpie"},
+ {"tool", "generate_image", "--prompt", "a", "a magpie"},
+ {"tool", "generate_image", "--n", "1", "--n", "2", "a magpie"},
+ {"tool", "generate_image", "-x", "a magpie"},
+ {"tool", "generate_image", "a magpie", "-o"},
+ {"tool", "draw", "a magpie"},
+ {"tool"},
+ } {
+ _, err := runOut(t, args...)
+ if err == nil {
+ t.Errorf("magpie %s: no error", strings.Join(args, " "))
+ }
+ }
+ if c := f.toolCalls(); len(c) != 0 {
+ t.Fatalf("a refused call was made: %v", c)
+ }
+ if got := filesIn(t, dir); len(got) != 0 {
+ t.Fatalf("a refused call wrote %v", got)
+ }
+ _, err := runOut(t, "tool", "generate_image", "--model", "x", "a magpie")
+ if err == nil || !strings.Contains(err.Error(), "takes no --model") || !strings.Contains(err.Error(), "--prompt") || !strings.Contains(err.Error(), "nothing was called") {
+ t.Fatalf("an unknown parameter: %v", err)
+ }
+}
+
+// --help prints the usage and asks the gateway nothing.
+func TestToolHelpCallsNothing(t *testing.T) {
+ f, dir := toolHere(t)
+ for _, args := range [][]string{{"tool", "generate_image", "a magpie", "--help"}, {"tool", "-h"}, {"tools", "--help"}, {"tool", "help"}} {
+ out, err := runOut(t, args...)
+ if err != nil || !strings.Contains(out, "magpie tool <name>") {
+ t.Fatalf("magpie %s: %v\n%s", strings.Join(args, " "), err, out)
+ }
+ }
+ f.mu.Lock()
+ defer f.mu.Unlock()
+ if len(f.calls) != 0 || len(f.gets) != 0 || len(filesIn(t, dir)) != 0 {
+ t.Fatalf("--help asked %v %v", f.calls, f.gets)
+ }
+}
+
+// An image the tool makes is saved: at -o, else here named from the
+// prompt, never over a file that is there; text is printed.
+func TestToolSavesTheImage(t *testing.T) {
+ f, dir := toolHere(t)
+ pic := tinyPNG(t)
+ f.call = func(name string, args map[string]any) map[string]any {
+ return map[string]any{
+ "content": []any{
+ map[string]any{"type": "text", "text": "Drew 1 image with art/gpt-image-1"},
+ map[string]any{"type": "image", "mimeType": "image/png", "data": base64.StdEncoding.EncodeToString(pic)},
+ },
+ "_meta": map[string]any{gateway.FilesMeta: []any{map[string]any{"url": "http://127.0.0.1:3425" + gateway.ImageMCPFiles + "a.png", "inline": true}}},
+ }
+ }
+ out, err := runOut(t, "tool", "generate_image", "a magpie on a branch", "-o", "hero.png")
+ if err != nil {
+ t.Fatal(err)
+ }
+ if got, err := os.ReadFile(filepath.Join(dir, "hero.png")); err != nil || !bytes.Equal(got, pic) {
+ t.Fatalf("hero.png: %v", err)
+ }
+ if !strings.Contains(out, "Drew 1 image") || !strings.Contains(out, filepath.Join(dir, "hero.png")) {
+ t.Fatalf("printed %q", out)
+ }
+ // hero.png is there: the next is saved beside it
+ if _, err := runOut(t, "tool", "generate_image", "a magpie on a branch", "-o", "hero.png"); err != nil {
+ t.Fatal(err)
+ }
+ if got := filesIn(t, dir); len(got) != 2 {
+ t.Fatalf("files %v: one was written over", got)
+ }
+ // no -o: here, named from the prompt
+ if _, err := runOut(t, "tool", "generate_image", "a magpie on a branch"); err != nil {
+ t.Fatal(err)
+ }
+ if got := strings.Join(filesIn(t, dir), " "); len(filesIn(t, dir)) != 3 || !strings.Contains(got, "magpie") {
+ t.Fatalf("files %s", got)
+ }
+ if c := f.toolCalls(); len(c) != 3 || !strings.Contains(c[0], gateway.ImageMCPPath+` tools/call generate_image {"prompt":"a magpie on a branch"}`) {
+ t.Fatalf("calls %v", c)
+ }
+ // --json prints the answer and saves nothing
+ out, err = runOut(t, "tool", "generate_image", "--json", "a magpie")
+ if err != nil || !strings.Contains(out, gateway.FilesMeta) || len(filesIn(t, dir)) != 3 {
+ t.Fatalf("--json: %v %q", err, out)
+ }
+}
+
+// One still being made is waited on with generation_result, and one that
+// isn't inline is downloaded from the gateway asked, with its key.
+func TestToolWaitsOnWhatIsStillMade(t *testing.T) {
+ f, dir := toolHere(t)
+ f.file = []byte("\x00\x00\x00\x18ftypmp42\x00\x00\x00\x00mp42isomfake-mp4-bytes")
+ asks := 0
+ f.call = func(name string, args map[string]any) map[string]any {
+ if name == "generate_image" {
+ return map[string]any{
+ "content": []any{map[string]any{"type": "text", "text": `still being made: call generation_result with id "img_1"`}},
+ "_meta": map[string]any{gateway.PendingMeta: "img_1"},
+ }
+ }
+ if asks++; asks < 2 {
+ // a gateway older than _meta: its text alone says to wait
+ return map[string]any{"content": []any{map[string]any{"type": "text", "text": `still: call generation_result with id "img_1" again`}}}
+ }
+ return map[string]any{
+ "content": []any{map[string]any{"type": "text", "text": "made"}},
+ "_meta": map[string]any{gateway.FilesMeta: []any{map[string]any{"url": "https://magpie.example.net/v1/videos/img_1/content"}}},
+ }
+ }
+ out, err := runOut(t, "tool", "generate_image", "a kite", "-o", "clips")
+ if err != nil {
+ t.Fatal(err)
+ }
+ c := f.toolCalls()
+ if len(c) != 3 || !strings.Contains(c[1], `generation_result {"id":"img_1"}`) || !strings.Contains(c[2], `generation_result {"id":"img_1"}`) {
+ t.Fatalf("calls %v", c)
+ }
+ f.mu.Lock()
+ gets := f.gets
+ f.mu.Unlock()
+ if len(gets) != 1 || gets[0] != "/v1/videos/img_1/content" {
+ t.Fatalf("downloaded %v", gets)
+ }
+ saved := filesIn(t, filepath.Join(dir, "clips"))
+ if len(saved) != 1 || filepath.Ext(saved[0]) != ".mp4" || !strings.Contains(out, "saved") {
+ t.Fatalf("saved %v, printed %q", saved, out)
+ }
+}
+
+// A tool's error is the command's, and nothing is saved.
+func TestToolErrorIsSaid(t *testing.T) {
+ f, dir := toolHere(t)
+ f.call = func(string, map[string]any) map[string]any {
+ return map[string]any{"content": []any{map[string]any{"type": "text", "text": "no image model is set"}}, "isError": true}
+ }
+ if _, err := runOut(t, "tool", "web_search", "go"); err == nil || err.Error() != "no image model is set" {
+ t.Fatalf("err %v", err)
+ }
+ if len(filesIn(t, dir)) != 0 {
+ t.Fatal("saved")
+ }
+}
+
+// With no magpie running it says so, plainly.
+func TestToolSaysMagpieIsntRunning(t *testing.T) {
+ l, err := net.Listen("tcp", "127.0.0.1:0")
+ if err != nil {
+ t.Fatal(err)
+ }
+ addr := l.Addr().String()
+ l.Close()
+ t.Setenv("MAGPIE_GATEWAY", "http://"+addr)
+ for _, args := range [][]string{{"tools"}, {"tool", "web_search", "go"}} {
+ if _, err := runOut(t, args...); err == nil || !strings.Contains(err.Error(), "magpie isn't running at http://"+addr) {
+ t.Fatalf("magpie %s: %v", strings.Join(args, " "), err)
+ }
+ }
+}
+
+// Against the real gateway, with a fake vendor: the image server's own
+// tools and schema are what magpie tool lists and calls, and the image the
+// vendor drew is saved.
+func TestToolDrawsThroughTheGateway(t *testing.T) {
+ home := t.TempDir()
+ t.Setenv("HOME", home)
+ t.Setenv("USERPROFILE", home)
+ t.Setenv("XDG_CONFIG_HOME", t.TempDir())
+ t.Setenv("XDG_CACHE_HOME", t.TempDir())
+ t.Setenv("MAGPIE_PUBLIC_URL", "")
+ pic := tinyPNG(t)
+ var sent []string
+ var mu sync.Mutex
+ up := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ b, _ := io.ReadAll(r.Body)
+ mu.Lock()
+ sent = append(sent, r.URL.Path+" "+string(b))
+ mu.Unlock()
+ if r.URL.Path != "/v1/images/generations" {
+ http.NotFound(w, r)
+ return
+ }
+ json.NewEncoder(w).Encode(map[string]any{"data": []any{map[string]any{"b64_json": base64.StdEncoding.EncodeToString(pic)}}})
+ }))
+ t.Cleanup(up.Close)
+ if err := provider.Save(provider.Provider{ID: "art", Name: "Art", Chat: up.URL + "/v1", Key: "key", Models: []string{"text", "gpt-image-1"}}); err != nil {
+ t.Fatal(err)
+ }
+ if err := catalog.SaveLive("art", up.URL+"/v1", []catalog.Model{{ID: "text"}}); err != nil {
+ t.Fatal(err)
+ }
+ gw := httptest.NewServer(gateway.New().Handler())
+ t.Cleanup(gw.Close)
+ t.Setenv("MAGPIE_GATEWAY", gw.URL)
+ dir := t.TempDir()
+ t.Chdir(dir)
+ out, err := runOut(t, "tools")
+ if err != nil || !strings.Contains(out, "generate_image") || !strings.Contains(out, "--prompt <text> (required)") || !strings.Contains(out, "analyze_image") || !strings.Contains(out, "web_search") {
+ t.Fatalf("tools: %v\n%s", err, out)
+ }
+ out, err = runOut(t, "tool", "generate_image", "a magpie", "--size", "1024x1024", "-o", "hero.png")
+ if err != nil {
+ t.Fatalf("%v\n%s", err, out)
+ }
+ if got, err := os.ReadFile(filepath.Join(dir, "hero.png")); err != nil || !bytes.Equal(got, pic) {
+ t.Fatalf("hero.png: %v (printed %q)", err, out)
+ }
+ mu.Lock()
+ defer mu.Unlock()
+ if len(sent) != 1 || !strings.Contains(sent[0], `"prompt":"a magpie"`) || !strings.Contains(sent[0], `"size":"1024x1024"`) {
+ t.Fatalf("vendor was sent %v", sent)
+ }
+}
diff --git a/internal/gateway/image_mcp.go b/internal/gateway/image_mcp.go
index bc613f7ad..3ccc91755 100644
--- a/internal/gateway/image_mcp.go
+++ b/internal/gateway/image_mcp.go
@@ -42,6 +42,27 @@ const ImageMCPPath = "/mcp/magpie/image"
// ImageMCPFiles is where the images it made are served from.
const ImageMCPFiles = ImageMCPPath + "/files/"
+// Under these keys of a tool result's _meta the image server tells a
+// client that saves what it made (magpie tool) what its text tells an
+// agent: the id to wait on with generation_result, and each file made, at
+// its URL, and whether it is in the answer itself.
+const (
+ PendingMeta = "usemagpie.ai/pending"
+ FilesMeta = "usemagpie.ai/files"
+)
+
+// MadeFile is one file a tool result's FilesMeta names.
+type MadeFile struct {
+ URL string `json:"url"`
+ Inline bool `json:"inline,omitempty"`
+}
+
+// withMeta is res with v under its _meta's key k.
+func withMeta(res map[string]any, k string, v any) map[string]any {
+ res["_meta"] = map[string]any{k: v}
+ return res
+}
+
// The tools Magpie Image and the image MCP server have.
const (
GenerateImageTool = "generate_image"
@@ -303,6 +324,7 @@ func (s *Server) imageMCPDrawn(rec *replyRecorder, key, base string) map[string]
}
var content []any
var urls, lost, revised []string
+ var files []MadeFile
for i, d := range out.Data {
var img []byte
mt := d.Mime
@@ -332,9 +354,11 @@ func (s *Server) imageMCPDrawn(rec *replyRecorder, key, base string) map[string]
mt = "image/png"
}
urls = append(urls, base+ImageMCPFiles+s.imageMCPKeepFile(img, mt, key))
- if len(img) <= imageMCPInline {
+ inline := len(img) <= imageMCPInline
+ if inline {
content = append(content, map[string]any{"type": "image", "data": base64.StdEncoding.EncodeToString(img), "mimeType": mt})
}
+ files = append(files, MadeFile{URL: urls[len(urls)-1], Inline: inline})
if d.Revised != "" {
revised = append(revised, d.Revised)
}
@@ -364,7 +388,7 @@ func (s *Server) imageMCPDrawn(rec *replyRecorder, key, base string) map[string]
fmt.Fprintf(&b, "The model said: %s\n", t)
}
content = append([]any{map[string]any{"type": "text", "text": b.String()}}, content...)
- return map[string]any{"content": content, "isError": false}
+ return withMeta(map[string]any{"content": content, "isError": false}, FilesMeta, files)
}
// imageMCPFilm starts generate_video's video and answers with where to
@@ -476,7 +500,8 @@ func (s *Server) imageMCPVideo(r *http.Request, id string) map[string]any {
if v.Seconds != "" {
length = v.Seconds + "-second "
}
- return toolResult(fmt.Sprintf("Generated a %svideo with %s. Download the mp4 from (with the same Authorization header as this server, from another computer):\n- %s/v1/videos/%s/content\n", length, v.Model, imageMCPBase(r), id), false)
+ at := imageMCPBase(r) + "/v1/videos/" + id + "/content"
+ return withMeta(toolResult(fmt.Sprintf("Generated a %svideo with %s. Download the mp4 from (with the same Authorization header as this server, from another computer):\n- %s\n", length, v.Model, at), false), FilesMeta, []MadeFile{{URL: at}})
case "failed":
msg := "it gave no reason"
if v.Error != nil && v.Error.Message != "" {
@@ -485,8 +510,8 @@ func (s *Server) imageMCPVideo(r *http.Request, id string) map[string]any {
return toolResult("the video failed: "+msg, true)
}
if !time.Now().Add(imageMCPPoll).Before(deadline) {
- return toolResult(fmt.Sprintf("The video is still being made (%s, %d s so far; it can take a few minutes). It goes on without this call. "+
- "Don't ask for it again: call %s with id %q to wait for it and get where to download it.\n", cmp.Or(v.Status, "queued"), int(time.Since(started)/time.Second), GenerationResultTool, id), false)
+ return withMeta(toolResult(fmt.Sprintf("The video is still being made (%s, %d s so far; it can take a few minutes). It goes on without this call. "+
+ "Don't ask for it again: call %s with id %q to wait for it and get where to download it.\n", cmp.Or(v.Status, "queued"), int(time.Since(started)/time.Second), GenerationResultTool, id), false), PendingMeta, id)
}
select {
case <-r.Context().Done():
@@ -553,8 +578,8 @@ func (s *Server) imageMCPAwait(r *http.Request, j *imageJob) map[string]any {
case <-limit.C:
case <-r.Context().Done():
}
- return toolResult(fmt.Sprintf("The image is still being made (%d s so far; it can take a few minutes). It goes on without this call. "+
- "Don't ask for it again: call %s with id %q to wait for it and get it.\n", int(time.Since(j.started)/time.Second), GenerationResultTool, j.id), false)
+ return withMeta(toolResult(fmt.Sprintf("The image is still being made (%d s so far; it can take a few minutes). It goes on without this call. "+
+ "Don't ask for it again: call %s with id %q to wait for it and get it.\n", int(time.Since(j.started)/time.Second), GenerationResultTool, j.id), false), PendingMeta, j.id)
}
// imageMCPKeepFile keeps img for an hour, for key, and is its file's name.
diff --git a/internal/gateway/image_mcp_test.go b/internal/gateway/image_mcp_test.go
index 597b15748..a25e08108 100644
--- a/internal/gateway/image_mcp_test.go
+++ b/internal/gateway/image_mcp_test.go
@@ -54,10 +54,15 @@ type imageReply struct {
Type, Text, Data, MimeType string
}
IsError bool
+ Meta map[string]json.RawMessage `json:"_meta"`
}
Error *struct{ Message string }
}
+// meta is what the answer's _meta holds at k, as JSON ("" for nothing):
+// what `magpie tool` waits on and saves by, beside the text an agent reads
+func (m imageReply) meta(k string) string { return string(m.Result.Meta[k]) }
+
func readImageReply(t *testing.T, w *httptest.ResponseRecorder) imageReply {
t.Helper()
if w.Code != 200 {
@@ -134,6 +139,9 @@ func TestImageMCPDrawsAndServesTheImage(t *testing.T) {
if len(urls) != 1 || !strings.HasPrefix(urls[0], "http://127.0.0.1:3425"+ImageMCPFiles) || !strings.HasSuffix(urls[0], ".png") || !strings.Contains(m.Result.Content[0].Text, "art/") {
t.Fatalf("text: %q", m.Result.Content[0].Text)
}
+ if got, want := m.meta(FilesMeta), `[{"url":"`+urls[0]+`","inline":true}]`; got != want || m.meta(PendingMeta) != "" {
+ t.Fatalf("_meta %v, want files %s", m.Result.Meta, want)
+ }
got := imageGet(h, "127.0.0.1:5000", urls[0])
if got.Code != 200 || got.Body.String() != string(pngBytes) || got.Header().Get("Content-Type") != "image/png" || got.Header().Get("X-Content-Type-Options") != "nosniff" {
t.Fatalf("file: %d %v %q", got.Code, got.Header(), got.Body.String())
@@ -304,6 +312,9 @@ func TestImageMCPSlowDrawingIsWaitedOn(t *testing.T) {
t.Fatalf("still drawing: %+v", m)
}
id := strings.Trim(strings.Fields(text[i:])[0], `".,`)
+ if got := m.meta(PendingMeta); got != `"`+id+`"` || m.meta(FilesMeta) != "" {
+ t.Fatalf("_meta %v, want pending %s", m.Result.Meta, id)
+ }
// another key's call can't have it
m = readImageReply(t, imagePost(h, "127.0.0.1:5000", imageToolCall(GenerationResultTool, map[string]any{"id": id}), "Authorization", "Bearer "+secrets[1]))
if !m.Result.IsError || !strings.Contains(m.Result.Content[0].Text, "no image is being made") {
@@ -315,6 +326,9 @@ func TestImageMCPSlowDrawingIsWaitedOn(t *testing.T) {
if m.Result.IsError || len(m.Result.Content) != 2 || m.Result.Content[1].Data != base64.StdEncoding.EncodeToString(pngBytes) {
t.Fatalf("waited on: %+v", m)
}
+ if m.meta(PendingMeta) != "" || !strings.Contains(m.meta(FilesMeta), `"inline":true`) {
+ t.Fatalf("waited on _meta: %v", m.Result.Meta)
+ }
if n := len(e.got("/v1/images/generations")); n != 1 {
t.Fatalf("drew %d times", n)
}
@@ -340,6 +354,9 @@ func TestImageMCPMakesVideos(t *testing.T) {
t.Fatalf("still making: %+v", m)
}
id := strings.Trim(strings.Fields(text[i:])[0], `".,`)
+ if got := m.meta(PendingMeta); got != `"`+id+`"` {
+ t.Fatalf("_meta %v, want pending %s", m.Result.Meta, id)
+ }
imageMCPWithin = time.Minute
m = readImageReply(t, imagePost(h, "127.0.0.1:5000", imageToolCall(GenerationResultTool, map[string]any{"id": id})))
text = m.Result.Content[0].Text
@@ -347,6 +364,9 @@ func TestImageMCPMakesVideos(t *testing.T) {
if m.Result.IsError || len(urls) != 1 || urls[0] != "http://127.0.0.1:3425/v1/videos/"+id+"/content" || !strings.Contains(text, "6-second") || !strings.Contains(text, "grok/grok-imagine-video") {
t.Fatalf("video: %+v", m)
}
+ if got, want := m.meta(FilesMeta), `[{"url":"`+urls[0]+`"}]`; got != want || m.meta(PendingMeta) != "" {
+ t.Fatalf("video _meta %v, want files %s", m.Result.Meta, want)
+ }
if w := imageGet(h, "127.0.0.1:5000", urls[0]); w.Code != 200 || w.Body.String() != "fake-mp4-bytes" {
t.Fatalf("content: %d %s", w.Code, w.Body.String())
}
diff --git a/internal/gateway/search_mcp.go b/internal/gateway/search_mcp.go
index 6042caebc..ab11837f5 100644
--- a/internal/gateway/search_mcp.go
+++ b/internal/gateway/search_mcp.go
@@ -29,6 +29,16 @@ import (
// segments under /mcp/, so it can't hide a signed-in server's /mcp/{name}.
const SearchMCPPath = "/mcp/magpie/web-search"
+// OwnMCPServers are the MCP servers the gateway serves itself, by the
+// names `magpie tools` lists their tools under, in the order a tool name
+// two of them have is looked for.
+var OwnMCPServers = []struct{ Name, Path string }{
+ {"image", ImageMCPPath},
+ {"vision", VisionMCPPath},
+ {"web-search", SearchMCPPath},
+ {"tools", ToolsMCPPath},
+}
+
// searchMCPVersions are the MCP versions the server speaks, newest first:
// a client asking for one of them is answered in it, any other in the first.
var searchMCPVersions = []string{"2025-06-18", "2025-03-26", "2024-11-05"}
diff --git a/internal/imagemcp/imagemcp.go b/internal/imagemcp/imagemcp.go
index dea67fac0..d2fa3a6a8 100644
--- a/internal/imagemcp/imagemcp.go
+++ b/internal/imagemcp/imagemcp.go
@@ -616,6 +616,14 @@ func reference(project, ref string) (string, error) {
return "data:" + mt + ";base64," + base64.StdEncoding.EncodeToString(b), nil
}
+// Target is where the i-th of n files made from prompt, of extension ext,
+// goes under dir: path as a file (numbered when n > 1) or a folder, else a
+// name from the prompt in dir's generated-images/ (generated-videos/);
+// never a file that is there. `magpie tool` saves what it is given by it.
+func Target(dir, path, prompt, ext string, i, n int) (string, error) {
+ return target(dir, path, prompt, ext, i, n)
+}
+
var unslug = regexp.MustCompile(`[^a-z0-9]+`)
// target is where the i-th of n images goes: path as a file (numbered when
diff --git a/site/public/docs/ja/start.html b/site/public/docs/ja/start.html
index 6539c4c9a..fa4043b7e 100644
--- a/site/public/docs/ja/start.html
+++ b/site/public/docs/ja/start.html
@@ -262,6 +262,7 @@ magpie claude group/opus-anywhere <span class="c"># これを使う</span></p
<tr><td><code>magpie codex default</code></td><td>エージェント自身のデフォルトに戻し、magpie の設定を取り除く</td></tr>
<tr><td><code>magpie save work</code> · <code>use work</code></td><td>プロファイルを保存・適用</td></tr>
<tr><td><code>magpie usage 7d</code></td><td>エージェントとモデルごとのトークンとコスト</td></tr>
+ <tr><td><code>magpie tools</code> · <code>magpie tool generate_image "…" -o hero.png</code></td><td>magpie が MCP でエージェントに渡すツール(画像生成、画像認識、Web 検索、プラグインのツール)を一覧し、直接呼び出す。生成した画像はファイルに保存</td></tr>
<tr><td><code>magpie tray</code></td><td>メニューバーのアイコンだけで起動</td></tr>
</table></div>
diff --git a/site/public/docs/start.html b/site/public/docs/start.html
index 49acbeee5..9f81c430b 100644
--- a/site/public/docs/start.html
+++ b/site/public/docs/start.html
@@ -262,6 +262,7 @@ magpie claude group/opus-anywhere <span class="c"># use it</span></pre>
<tr><td><code>magpie codex default</code></td><td>Back to the agent’s own default, magpie’s wiring removed</td></tr>
<tr><td><code>magpie save work</code> · <code>use work</code></td><td>Save and apply a profile</td></tr>
<tr><td><code>magpie usage 7d</code></td><td>Tokens and cost per agent and model</td></tr>
+ <tr><td><code>magpie tools</code> · <code>magpie tool generate_image "…" -o hero.png</code></td><td>The tools magpie gives agents over MCP (image generation, image recognition, web search, plugins’), listed and called directly; an image it makes is saved</td></tr>
<tr><td><code>magpie tray</code></td><td>Start with the menu bar icon only</td></tr>
</table></div>
diff --git a/site/public/docs/zh/start.html b/site/public/docs/zh/start.html
index 30dae0e76..6be0068c4 100644
--- a/site/public/docs/zh/start.html
+++ b/site/public/docs/zh/start.html
@@ -262,6 +262,7 @@ magpie claude group/opus-anywhere <span class="c"># 使用它</span></pre>
<tr><td><code>magpie codex default</code></td><td>恢复 Agent 自己的默认值,移除 magpie 的接入</td></tr>
<tr><td><code>magpie save work</code> · <code>use work</code></td><td>保存、应用方案</td></tr>
<tr><td><code>magpie usage 7d</code></td><td>按 Agent 和模型统计 token 与费用</td></tr>
+ <tr><td><code>magpie tools</code> · <code>magpie tool generate_image "…" -o hero.png</code></td><td>列出并直接调用 magpie 通过 MCP 给 Agent 的工具(生图、识图、联网搜索、插件的工具);生成的图片保存到文件</td></tr>
<tr><td><code>magpie tray</code></td><td>只启动菜单栏图标</td></tr>
</table></div>