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

Package	Version	Description
@avala-ai/sdk	0.5.0	TypeScript SDK for the Avala API
@avala-ai/mcp-server	0.5.0	MCP server for AI assistant integrations

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

Resource	Methods	Description
avala.permissions	get()	Discover the current credential's scopes, capabilities, and toolsets
avala.datasets	list(), get(uid)	Browse and inspect datasets
avala.projects	list(), get(uid)	Browse and inspect projects
avala.exports	list(), get(uid), create()	Create and manage annotation exports
avala.tasks	list(), get(uid)	Browse tasks with project/status filters
avala.storageConfigs	list(), create(), test(), delete()	Manage cloud storage connections

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 pnpm monorepo. To get started:

pnpm install
pnpm -r build
pnpm -r test

Documentation

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

License

MIT - see LICENSE for details.