The package format

Every field below is checked before a package is stored. Validation failures come back as the zod issue list, keyed by the path that failed.

A tool is metadata plus a binding. The description and the input schema are the entire interface an agent sees, so they carry the weight. An agent picks a tool by reading them and nothing else.

This is where the format earns its keep. Instead of shipping a script that pokes at the DOM, you declare the requests the site's own front end already makes, and the extension derives the call. Everything is data, so a reader can audit a package by reading it.

An endpoint

An auth source

Placeholders

{{param}} in a path, query value, form field, body leaf, or GraphQL variable is substituted from the bound tool's input. For a tool-bound endpoint, every placeholder must name a property of that tool's inputSchema, or the package is rejected, which also means a typo can't reach a user as an empty string. The same check covers an auth source's fetch endpoint (path/query only) and its pattern; an endpoint no tool binds to is never scanned at all. A query/form/path placeholder for a param the agent didn't supply interpolates to an empty string, while a body/graphql.variables leaf that is exactly one {{param}} yields undefined and drops out of the JSON entirely. There is no escape hatch for a literal {{ yet.

Two tools against a site's own JSON API: one read, one write that needs a CSRF token the site hands out on a different endpoint. This document validates: it is parsed against the schema by the test suite, so it can't drift from the format.

{
  "version": 1,
  "domain": "acme.com",
  "urlPatterns": [
    "*://*.acme.com/*"
  ],
  "title": "Example Notes",
  "description": "Search and create notes on acme.com as the logged-in user, through the site's own JSON API. Reads need no token; writes attach the CSRF token the session endpoint hands out.",
  "minEngine": 1,
  "changelog": "Initial version: notes_search, notes_create.",
  "api": {
    "baseUrl": "https://www.acme.com",
    "auth": {
      "csrf": {
        "source": {
          "endpoint": "session",
          "extract": [
            "data",
            "csrfToken"
          ]
        },
        "sendAs": {
          "in": "header",
          "name": "X-CSRF-Token"
        },
        "ttlSeconds": 300
      }
    },
    "endpoints": {
      "session": {
        "method": "GET",
        "path": "/api/session.json"
      },
      "searchNotes": {
        "method": "GET",
        "path": "/api/notes",
        "query": {
          "q": "{{query}}",
          "limit": "{{limit}}"
        },
        "returns": "notes[].{id: id, title: title, updated_at: updated_at}"
      },
      "createNote": {
        "method": "POST",
        "path": "/api/notes",
        "body": {
          "title": "{{title}}",
          "body": "{{body}}"
        },
        "auth": [
          "csrf"
        ],
        "errorPath": [
          "errors"
        ],
        "returns": "note.{id: id, url: url}"
      }
    }
  },
  "tools": [
    {
      "name": "notes_search",
      "description": "Search the logged-in user's notes on acme.com by keyword. Returns the matching notes' ids, titles, and last-updated timestamps, newest first.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "description": "Keywords to search note titles and bodies for"
          },
          "limit": {
            "type": "integer",
            "description": "How many notes to return (1-50)"
          }
        },
        "required": [
          "query"
        ]
      },
      "annotations": {
        "readOnlyHint": true
      },
      "execution": {
        "mode": "api",
        "endpoint": "searchNotes"
      }
    },
    {
      "name": "notes_create",
      "description": "Create a new note on acme.com as the logged-in user. Returns the new note's id and URL.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "description": "Note title"
          },
          "body": {
            "type": "string",
            "description": "Note body (plain text)"
          }
        },
        "required": [
          "title",
          "body"
        ]
      },
      "annotations": {
        "readOnlyHint": false
      },
      "execution": {
        "mode": "api",
        "endpoint": "createNote"
      }
    }
  ]
}

The three curated packages in the repository are the same thing against real sites, and cover the awkward cases: Reddit extracts a JSON token into a header, Hacker News scrapes its tokens out of HTML with pattern, Google Maps needs stripPrefix and projects positional arrays. Read them.

Paste the JSON or POST /api/packages with a Bearer API key. Same schema either way. Nothing reviews it; it goes live when it validates.

Versions are append-only. A new version is a POST to /api/packages/:id/versions with version set to one above the current highest, and only the owner may publish one. urlPatterns, tools, api, minEngine and changelog are version-scoped and travel with the content. Title, description, domain and pageType are package metadata and are edited in place.

Installs pin to a version, so publishing a new one never moves anybody. They update when they choose to. That cuts both ways: a version you published is a version someone may still be running. What you grant when you publish is worth reading once.