Avala TypeScript SDK + MCP Server

Official TypeScript SDK and MCP server for the Avala API — the open Physical AI Data Platform. Programmatically manage sensor datasets (MCAP, LiDAR, video), annotation projects, exports, tasks, and fleet devices.

Note: This repository is a read-only mirror. To report bugs or request features, please open an issue. See CONTRIBUTING.md for details.

Packages

SDK Quick Start

npm install @avala-ai/sdk

import Avala from "@avala-ai/sdk";

const avala = new Avala();  // reads AVALA_API_KEY env var

// List datasets
const page = await avala.datasets.list({ limit: 10 });
page.items.forEach(d => console.log(d.uid, d.name));

// Get a specific dataset
const dataset = await avala.datasets.get("dataset-uid");

// Create an export
const exp = await avala.exports.create({ project: "project-uid" });
console.log(exp.uid, exp.status);

// List tasks with filters
const tasks = await avala.tasks.list({ project: "project-uid", status: "completed" });

Authentication

The client reads your API key from the AVALA_API_KEY environment variable by default:

export AVALA_API_KEY="avk_your_api_key"

Or pass it explicitly:

const avala = new Avala({ apiKey: "avk_your_api_key" });

Delegated services may instead pass an OAuth access token issued specifically for the Avala API:

const avala = new Avala({ accessToken: apiAudienceAccessToken });

apiKey and accessToken are mutually exclusive. Do not pass an ID token or a token issued for another resource (for example, an MCP-server token); exchange it for an Avala API-audience token first.

Pagination

All .list() methods return a CursorPage with .items, .hasMore, and .nextCursor:

let page = await avala.datasets.list({ limit: 20 });

for (const dataset of page.items) {
  console.log(dataset.name);
}

if (page.hasMore) {
  const nextPage = await avala.datasets.list({ cursor: page.nextCursor });
}

Error Handling

import Avala, { AvalaError, NotFoundError, RateLimitError } from "@avala-ai/sdk";

try {
  const dataset = await avala.datasets.get("nonexistent");
} catch (e) {
  if (e instanceof NotFoundError) {
    console.log("Dataset not found");
  } else if (e instanceof RateLimitError) {
    console.log("Rate limited");
  } else if (e instanceof AvalaError) {
    console.log(`API error: ${e.message}`);
  }
}

Available Resources

MCP Server

The @avala-ai/mcp-server package provides an MCP server that lets AI assistants (Claude, etc.) interact with your Avala data.

npm install -g @avala-ai/mcp-server
avala-mcp-server

See MCP Setup Guide for configuration details.

Development

This is a Bun workspace. To get started (Node 20+ and npm are also required):

bun install --frozen-lockfile
bun run build
bun run test
bun run lint

bun run test includes bun run test:package: build both packages, pack them with npm, install the tarballs into a disposable directory outside the workspace, and initialize/list tools through the installed MCP executable using Node. This needs access to the public npm registry for third-party dependencies, but uses no real Avala credentials and makes no Avala API calls. The SDK and MCP versions and the MCP server's exact SDK dependency must match; npm does not rewrite workspace:* when packing.

Documentation

• TypeScript SDK Guide
• MCP Setup Guide
• API Reference
• Quickstart
• Examples

License

MIT - see LICENSE for details.