Collections

Both ad-hoc agent calls and persisted declarative collections. Collections are plain YAML or JSON files - git-friendly, diffable, and shareable.

Why collections

Ad-hoc tool calls are great for exploration, but teams also need repeatable test suites. Lunge collections let you define ordered steps once and re-run them with a single tool call. Variables thread from one step to the next; assertions gate execution; only and tags filter runs.

Format

A collection is a list of named steps. Each step is a tool invocation with inputs, optional assertions, and optional extractions. The runner threads extracted values into the next step's inputs.

# collections/login-flow.yaml
name: Login flow
steps:
  - name: login
    tool: http_request
    input:
      method: POST
      url: "{{baseUrl}}/login"
      body: { user: "a", pass: "{{secret_pass}}" }
    extract: { token: "$.token" }

  - name: me
    tool: http_request
    input:
      url: "{{baseUrl}}/me"
      auth: { type: bearer, token: "{{token}}" }
    assert: [{ status: 200 }]

  - name: invoices
    tool: http_request
    input:
      url: "{{baseUrl}}/invoices"
      auth: { type: bearer, token: "{{token}}" }
      query: { limit: 10 }
    extract: { firstInvoiceId: "$.items[0].id" }

Running a collection

{
  "tool": "run_collection",
  "input": {
    "path": "collections/login-flow.yaml",
    "env": "dev",
    "tags": ["smoke"]
  }
}

Output is a per-step summary: status, assertions, extracted vars, and handles - same token-efficient shape as individual tool calls.

Listing collections

{ "tool": "list_collections", "input": {} }

Filters

• only - run only the named step(s).
• tags - run only steps tagged with any of the given tags.
• env - resolve {{vars}} against a named environment.

Collections are the bridge between one-off agent exploration and repeatable, reviewable test suites - all behind the same MCP tool surface.