eyeballdocs
Getting Started

First tool call in 5 minutes

Use the eyeball SDK to load a model-ready toolkit, query a mock mailbox, and inspect one normalized result.

This is the shortest path through eyeball: start the local source-preview stack, load an eyeball toolkit, and execute one canonical tool without creating a third-party account.

1. Start the source preview

Bash
# From an eyeball source checkout:
pnpm install
pnpm --dir mocks install
pnpm build
pnpm dev:stack

@eyeball/sdk is not published to npm yet. The source-preview stack starts Mockhouse, the executor, and the MCP gateway with this development identity:

Bash
export EYEBALL_API_KEY="eyeball_dev_project"
export EYEBALL_EXECUTOR_URL="http://127.0.0.1:3000"

2. Load and run one tool

ts
import { Eyeball } from "@eyeball/sdk";

const eyeball = new Eyeball({
  apiKey: process.env.EYEBALL_API_KEY!,
  baseUrl: process.env.EYEBALL_EXECUTOR_URL!,
});

const bundle = await eyeball.tools.get({
  toolkits: ["gmail"],
  format: "anthropic",
});

const result = await eyeball.tools.run(
  "gmail.search_emails",
  { query: "reservation", pageSize: 5 },
  { userId: "demo_user" },
);

console.log({ modelTools: bundle.tools.length, result });

Save the snippet as example.ts, then run it from the repository root:

Bash
node --import tsx example.ts

format: "anthropic" only chooses the model-facing tool-definition shape. The executor still receives the same canonical eyeball tool name, input, and user scope.

3. Inspect the canonical result

Expected output shape:

JSON
{
  "emails": [
    {
      "messageId": "msg_...",
      "subject": "Reservation confirmed"
    }
  ],
  "nextPageToken": "page_..."
}

Next, connect the same project through the MCP gateway, or choose an integration under Works with your stack.