{
  "name": "smartmacros-mcp",
  "version": "0.1.1",
  "homepage": "https://smartmacros.pages.dev/mcp",
  "npm": "https://www.npmjs.com/package/smartmacros-mcp",
  "install": {
    "command": "npx",
    "args": [
      "-y",
      "smartmacros-mcp"
    ],
    "env": {
      "SMARTMACROS_TOKEN": "<pairing token from SmartMacros Settings > AI access>"
    }
  },
  "resources": [
    {
      "uri": "smartmacros://guide",
      "mimeType": "text/markdown",
      "description": "How to write macros and steps. Read before create_macro or run_steps.",
      "mirror": "https://smartmacros.pages.dev/mcp-guide.md"
    }
  ],
  "groups": [
    {
      "id": "macros",
      "title": "Macros",
      "description": "Read and write the macros saved in SmartMacros.",
      "tools": [
        {
          "name": "list_macros",
          "title": "List macros",
          "description": "All macros saved in SmartMacros with id, name, start URL, step count, data rows and last run status.",
          "inputSchema": {
            "type": "object",
            "properties": {},
            "$schema": "http://json-schema.org/draft-07/schema#"
          }
        },
        {
          "name": "get_macro",
          "title": "Get macro",
          "description": "Full JSON of one macro: steps with their locators, data source, variables, triggers.",
          "inputSchema": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Macro id from list_macros"
              }
            },
            "required": [
              "id"
            ],
            "additionalProperties": false,
            "$schema": "http://json-schema.org/draft-07/schema#"
          }
        },
        {
          "name": "create_macro",
          "title": "Create macro",
          "description": "Saves a new macro. Read smartmacros://guide first. Steps need only type, target (locators), value and options; ids, labels and defaults are filled in by SmartMacros.",
          "inputSchema": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "description": "Name shown in SmartMacros"
              },
              "startUrl": {
                "type": "string",
                "format": "uri",
                "description": "Page where the task starts"
              },
              "steps": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "description": "Step type, see the smartmacros://guide resource"
                    },
                    "target": {
                      "anyOf": [
                        {
                          "type": "object",
                          "properties": {
                            "locators": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "kind": {
                                    "type": "string"
                                  },
                                  "type": {
                                    "type": "string",
                                    "description": "Alias of kind"
                                  },
                                  "value": {
                                    "type": "string"
                                  },
                                  "tag": {
                                    "type": "string"
                                  }
                                },
                                "required": [
                                  "value"
                                ],
                                "additionalProperties": false
                              }
                            }
                          },
                          "required": [
                            "locators"
                          ],
                          "additionalProperties": true
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "How to find the element: locators best first, {kind, value}"
                    },
                    "value": {
                      "type": [
                        "string",
                        "number",
                        "boolean"
                      ]
                    },
                    "options": {
                      "type": "object",
                      "additionalProperties": {}
                    },
                    "label": {
                      "type": "string",
                      "description": "Sentence shown in the UI; generated when omitted"
                    }
                  },
                  "required": [
                    "type"
                  ],
                  "additionalProperties": true
                },
                "minItems": 1,
                "description": "Steps in order; usually begins with a navigate step"
              },
              "dataSource": {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "const": "inline",
                    "default": "inline"
                  },
                  "columns": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Column names; each becomes a {{variable}}"
                  },
                  "rows": {
                    "type": "array",
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "description": "One array of cell values per row, same order as columns"
                  },
                  "startRow": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "Skip this many rows"
                  }
                },
                "required": [
                  "columns",
                  "rows"
                ],
                "additionalProperties": false,
                "description": "Table of rows to repeat the macro over"
              },
              "vars": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                },
                "description": "Fixed variables, used as {{name}}"
              },
              "tags": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Labels for searching in the side panel"
              }
            },
            "required": [
              "name",
              "steps"
            ],
            "additionalProperties": false,
            "$schema": "http://json-schema.org/draft-07/schema#"
          }
        },
        {
          "name": "update_macro",
          "title": "Update macro",
          "description": "Replaces the given fields of an existing macro. Pass steps to replace the whole step list; pass dataSource to replace the data rows.",
          "inputSchema": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Macro id from list_macros"
              },
              "name": {
                "type": "string",
                "description": "New name"
              },
              "startUrl": {
                "type": "string",
                "description": "New start page"
              },
              "steps": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "description": "Step type, see the smartmacros://guide resource"
                    },
                    "target": {
                      "anyOf": [
                        {
                          "type": "object",
                          "properties": {
                            "locators": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "kind": {
                                    "type": "string"
                                  },
                                  "type": {
                                    "type": "string",
                                    "description": "Alias of kind"
                                  },
                                  "value": {
                                    "type": "string"
                                  },
                                  "tag": {
                                    "type": "string"
                                  }
                                },
                                "required": [
                                  "value"
                                ],
                                "additionalProperties": false
                              }
                            }
                          },
                          "required": [
                            "locators"
                          ],
                          "additionalProperties": true
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "How to find the element: locators best first, {kind, value}"
                    },
                    "value": {
                      "type": [
                        "string",
                        "number",
                        "boolean"
                      ]
                    },
                    "options": {
                      "type": "object",
                      "additionalProperties": {}
                    },
                    "label": {
                      "type": "string",
                      "description": "Sentence shown in the UI; generated when omitted"
                    }
                  },
                  "required": [
                    "type"
                  ],
                  "additionalProperties": true
                },
                "description": "Replaces the whole step list"
              },
              "dataSource": {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "const": "inline",
                    "default": "inline"
                  },
                  "columns": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Column names; each becomes a {{variable}}"
                  },
                  "rows": {
                    "type": "array",
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "description": "One array of cell values per row, same order as columns"
                  },
                  "startRow": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "Skip this many rows"
                  }
                },
                "required": [
                  "columns",
                  "rows"
                ],
                "additionalProperties": false,
                "description": "Replaces the data rows"
              },
              "vars": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                },
                "description": "Replaces the fixed variables"
              },
              "tags": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Replaces the tags"
              }
            },
            "required": [
              "id"
            ],
            "additionalProperties": false,
            "$schema": "http://json-schema.org/draft-07/schema#"
          }
        },
        {
          "name": "delete_macro",
          "title": "Delete macro",
          "description": "Deletes a macro permanently.",
          "inputSchema": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Macro id from list_macros"
              }
            },
            "required": [
              "id"
            ],
            "additionalProperties": false,
            "$schema": "http://json-schema.org/draft-07/schema#"
          }
        }
      ]
    },
    {
      "id": "runs",
      "title": "Runs",
      "description": "Start a macro, follow it, answer when it waits, stop it.",
      "tools": [
        {
          "name": "run_macro",
          "title": "Run macro",
          "description": "Runs a saved macro in Chrome. mode 'once' runs it one time, 'rows' once per data row. With wait=true (default) the call returns when the run finishes or needs the user, with per-row results, variables and repairs.",
          "inputSchema": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Macro id from list_macros"
              },
              "mode": {
                "type": "string",
                "enum": [
                  "once",
                  "rows"
                ],
                "default": "once",
                "description": "once = one run, rows = once per data row"
              },
              "data": {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "const": "inline",
                    "default": "inline"
                  },
                  "columns": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Column names; each becomes a {{variable}}"
                  },
                  "rows": {
                    "type": "array",
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "description": "One array of cell values per row, same order as columns"
                  },
                  "startRow": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "Skip this many rows"
                  }
                },
                "required": [
                  "columns",
                  "rows"
                ],
                "additionalProperties": false,
                "description": "Rows to use for this run only; leaves the saved macro unchanged"
              },
              "wait": {
                "type": "boolean",
                "default": true,
                "description": "false returns at once; follow the run with run_status"
              },
              "timeoutSeconds": {
                "type": "integer",
                "minimum": 5,
                "maximum": 3600,
                "default": 600,
                "description": "How long to wait for the run to finish"
              }
            },
            "required": [
              "id"
            ],
            "additionalProperties": false,
            "$schema": "http://json-schema.org/draft-07/schema#"
          }
        },
        {
          "name": "run_status",
          "title": "Run status",
          "description": "State of the current or last run: status, row, step, repairs, variables, whether it waits for the user, last log lines.",
          "inputSchema": {
            "type": "object",
            "properties": {},
            "$schema": "http://json-schema.org/draft-07/schema#"
          }
        },
        {
          "name": "answer_run",
          "title": "Answer a waiting run",
          "description": "When run_status shows status waiting_user: retry the step, skip it, skip the row, continue after a pause, or stop. Picking an element on the page needs the user.",
          "inputSchema": {
            "type": "object",
            "properties": {
              "choice": {
                "type": "string",
                "enum": [
                  "retry",
                  "skip",
                  "skipRow",
                  "continue",
                  "stop"
                ],
                "description": "retry the step, skip it, skip the rest of this row, continue after a pause, or stop the run"
              }
            },
            "required": [
              "choice"
            ],
            "additionalProperties": false,
            "$schema": "http://json-schema.org/draft-07/schema#"
          }
        },
        {
          "name": "stop_run",
          "title": "Stop run",
          "description": "Stops the current run. Rows already finished stay finished.",
          "inputSchema": {
            "type": "object",
            "properties": {},
            "$schema": "http://json-schema.org/draft-07/schema#"
          }
        }
      ]
    },
    {
      "id": "browser",
      "title": "Browser",
      "description": "Look at the open page and act on it without saving a macro.",
      "tools": [
        {
          "name": "open_tab",
          "title": "Open tab",
          "description": "Opens a URL in a new tab and makes it active. Returns the tab id for page_snapshot and find_elements.",
          "inputSchema": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string",
                "format": "uri",
                "description": "Address to open"
              }
            },
            "required": [
              "url"
            ],
            "additionalProperties": false,
            "$schema": "http://json-schema.org/draft-07/schema#"
          }
        },
        {
          "name": "page_snapshot",
          "title": "Page snapshot",
          "description": "Title, URL, visible text and the interactive elements of the active tab (or tabId), each with a ready-to-use locator. Use it before writing steps for a page.",
          "inputSchema": {
            "type": "object",
            "properties": {
              "tabId": {
                "type": "integer",
                "description": "Tab from open_tab; the active tab when omitted"
              },
              "maxElements": {
                "type": "integer",
                "minimum": 1,
                "maximum": 400,
                "default": 120,
                "description": "Most interactive elements to return"
              },
              "textChars": {
                "type": "integer",
                "minimum": 0,
                "maximum": 20000,
                "default": 3000,
                "description": "How much of the visible page text to return"
              }
            },
            "additionalProperties": false,
            "$schema": "http://json-schema.org/draft-07/schema#"
          }
        },
        {
          "name": "find_elements",
          "title": "Find elements",
          "description": "Finds elements on the active tab (or tabId) that match a description such as 'email field' or 'Save button', scored, each with locators to put into a step target.",
          "inputSchema": {
            "type": "object",
            "properties": {
              "description": {
                "type": "string",
                "description": "Plain words, e.g. 'email field' or 'Save button'"
              },
              "tabId": {
                "type": "integer",
                "description": "Tab from open_tab; the active tab when omitted"
              },
              "max": {
                "type": "integer",
                "minimum": 1,
                "maximum": 20,
                "default": 5,
                "description": "Most candidates to return"
              }
            },
            "required": [
              "description"
            ],
            "additionalProperties": false,
            "$schema": "http://json-schema.org/draft-07/schema#"
          }
        },
        {
          "name": "run_steps",
          "title": "Run steps now",
          "description": "Runs a list of steps in the active tab (or at url) without saving a macro. Use it to control the browser directly: open a page, fill a form, read values. Same executor and repairs as saved macros.",
          "inputSchema": {
            "type": "object",
            "properties": {
              "steps": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "description": "Step type, see the smartmacros://guide resource"
                    },
                    "target": {
                      "anyOf": [
                        {
                          "type": "object",
                          "properties": {
                            "locators": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "kind": {
                                    "type": "string"
                                  },
                                  "type": {
                                    "type": "string",
                                    "description": "Alias of kind"
                                  },
                                  "value": {
                                    "type": "string"
                                  },
                                  "tag": {
                                    "type": "string"
                                  }
                                },
                                "required": [
                                  "value"
                                ],
                                "additionalProperties": false
                              }
                            }
                          },
                          "required": [
                            "locators"
                          ],
                          "additionalProperties": true
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "How to find the element: locators best first, {kind, value}"
                    },
                    "value": {
                      "type": [
                        "string",
                        "number",
                        "boolean"
                      ]
                    },
                    "options": {
                      "type": "object",
                      "additionalProperties": {}
                    },
                    "label": {
                      "type": "string",
                      "description": "Sentence shown in the UI; generated when omitted"
                    }
                  },
                  "required": [
                    "type"
                  ],
                  "additionalProperties": true
                },
                "minItems": 1,
                "description": "Steps to run now, in order"
              },
              "url": {
                "type": "string",
                "format": "uri",
                "description": "Open this URL first"
              },
              "vars": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                },
                "description": "Variables for {{name}} in the steps"
              },
              "timeoutSeconds": {
                "type": "integer",
                "minimum": 5,
                "maximum": 3600,
                "default": 300,
                "description": "How long to wait for the steps to finish"
              }
            },
            "required": [
              "steps"
            ],
            "additionalProperties": false,
            "$schema": "http://json-schema.org/draft-07/schema#"
          }
        }
      ]
    },
    {
      "id": "history",
      "title": "History and status",
      "description": "What ran, what was repaired, and whether the link is up.",
      "tools": [
        {
          "name": "list_runs",
          "title": "Run history",
          "description": "Recent runs with macro name, rows done, repairs and results.",
          "inputSchema": {
            "type": "object",
            "properties": {
              "limit": {
                "type": "integer",
                "minimum": 1,
                "maximum": 100,
                "default": 20,
                "description": "Most runs to return, newest first"
              }
            },
            "additionalProperties": false,
            "$schema": "http://json-schema.org/draft-07/schema#"
          }
        },
        {
          "name": "list_repairs",
          "title": "Repair log",
          "description": "Steps SmartMacros repaired: macro, step, old and new locator, who solved it, confidence.",
          "inputSchema": {
            "type": "object",
            "properties": {
              "limit": {
                "type": "integer",
                "minimum": 1,
                "maximum": 200,
                "default": 30,
                "description": "Most repairs to return, newest first"
              }
            },
            "additionalProperties": false,
            "$schema": "http://json-schema.org/draft-07/schema#"
          }
        },
        {
          "name": "connection_status",
          "title": "Connection status",
          "description": "Whether the SmartMacros extension is connected to this bridge, and its build.",
          "inputSchema": {
            "type": "object",
            "properties": {},
            "$schema": "http://json-schema.org/draft-07/schema#"
          }
        }
      ]
    }
  ]
}