pebbler-mcp

# Pebbler MCP

Let your agent collect human feedback on two images and explain the results. Pebbler runs image preference tests with participants on the **Pebbler app**.

Your agent retrieves current pricing, package details and availability before creating a test. The purchase uses a live quote and stays within the spending limits you configure. Pricing and package sizes are not fixed by this connector.

Version 1 supports image A/B preference tests. These measure which image people prefer, rather than product conversion or causal effects. Completed response counts are not guaranteed. Surveys and text-only comparisons are not supported.

## Connect your agent

Use an MCP app that supports local servers and Node.js 22 or later. Add this configuration to your app:

```json
{
    "mcpServers": {
        "pebbler": {
            "command": "npx",
            "args": ["-y", "@pebbler/pebbler-mcp@0.1.0"]
        }
    }
}
```

Pebbler's production settings are included. You can explore current packages and create drafts without enabling payments.

## Enable purchases

Use a dedicated wallet funded with native USDC on Base. Configure these settings locally in your MCP app's environment or secret settings:

| Setting                      | What to provide                                                          |
| ---------------------------- | ------------------------------------------------------------------------ |
| `PEBBLER_ALLOW_PAYMENTS`     | Set to `true` when you want the agent to make purchases                  |
| `PEBBLER_WALLET_PRIVATE_KEY` | Your wallet's signing key, supplied privately                            |
| `PEBBLER_MAX_PURCHASE_USDC`  | Your chosen maximum spend per test, as a positive decimal USDC amount    |
| `PEBBLER_MAX_TOTAL_USDC`     | Your chosen cumulative spending limit, as a positive decimal USDC amount |

Both spending limits are required when payments are enabled. They are your budget, not the price of a test. If a quote exceeds either limit, the connector stops instead of raising your budget. Payments stay disabled until you enable them explicitly.

The wallet key remains local. Do not put it in a prompt or share it in a conversation. Prices and quotes are fetched by the agent; you do not need to configure them.

## Ask for a test

For example:

> Check the current package and price, then compare these two image URLs. Tell me the quote before buying and stay within my configured budget.

Provide two publicly accessible HTTPS image URLs and a clear question. Use images you own or have permission to use, and keep the URLs available while responses are collected.

Your agent can show the current offer, create a draft, purchase the test and check progress. You can read partial results while collection continues or return later to ask for the final counts and vote shares. Retrieving results is included in the purchase.

## Available tools

| Tool                 | Purpose                                                              |
| -------------------- | -------------------------------------------------------------------- |
| `get_catalog`        | Retrieve current packages, prices, supported inputs and availability |
| `create_study`       | Prepare an image comparison and obtain its quote                     |
| `quote_study`        | Refresh a quote before payment has been signed                       |
| `purchase_study`     | Purchase the quoted test within your wallet's spending limits        |
| `get_study_status`   | Check progress and when to check again                               |
| `get_study_results`  | Retrieve aggregate A/B votes and shares                              |
| `list_local_studies` | Find your saved tests after returning or restarting                  |

The agent learns each tool's inputs automatically when connected. It should read the catalog first, use the quote for the purchase, and follow the returned polling interval when checking progress.

## Returning to your results

Keep the connector's private local state folder backed up. It retains access to your tests and their purchase history across restarts. You can choose a folder with `PEBBLER_STATE_DIR`; use the same folder when returning to existing tests.

Your total spending limit counts retained signed purchases, including unresolved attempts, and does not reset automatically. Increase it deliberately if you want to buy more tests. Keep the original state rather than deleting it to reset your budget.

If a purchase is interrupted or pending, ask the agent to retry that same purchase. The connector preserves its identifiers and payment authorization instead of signing another payment. Reading progress and results does not require another purchase.

## Try an example

The included `examples/run-study.mjs` demonstrates discovery and creating an image comparison. It prints the live catalog and quote; purchasing requires the `--purchase` flag and your locally configured wallet and budgets.

## License

MIT. Original example image assets are included under the same license.