# Avala TypeScript SDK + MCP Server

[![npm: @avala-ai/sdk](https://img.shields.io/npm/v/@avala-ai/sdk)](https://www.npmjs.com/package/@avala-ai/sdk)
[![npm: @avala-ai/mcp-server](https://img.shields.io/npm/v/@avala-ai/mcp-server)](https://www.npmjs.com/package/@avala-ai/mcp-server)
[![CI](https://github.com/avala-ai/avala-sdk-ts/actions/workflows/ci.yml/badge.svg)](https://github.com/avala-ai/avala-sdk-ts/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Official TypeScript SDK and MCP server for the [Avala API](https://avala.ai/docs) — 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](https://github.com/avala-ai/avala-sdk-ts/issues). See [CONTRIBUTING.md](CONTRIBUTING.md) for details.

## Packages

| Package | Version | Description |
|---------|---------|-------------|
| [`@avala-ai/sdk`](./packages/sdk) | 0.5.0 | TypeScript SDK for the Avala API |
| [`@avala-ai/mcp-server`](./packages/mcp-server) | 0.5.0 | MCP server for AI assistant integrations |

## SDK Quick Start

```bash
npm install @avala-ai/sdk
```

```typescript
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:

```bash
export AVALA_API_KEY="avk_your_api_key"
```

Or pass it explicitly:

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

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

```typescript
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`:

```typescript
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

```typescript
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.

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

See [MCP Setup Guide](https://avala.ai/docs/integrations/mcp-setup) for configuration details.

## Development

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

```bash
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](https://avala.ai/docs/sdks/typescript)
- [MCP Setup Guide](https://avala.ai/docs/integrations/mcp-setup)
- [API Reference](https://avala.ai/docs/api-reference/overview)
- [Quickstart](https://avala.ai/docs/getting-started/quickstart)
- [Examples](https://avala.ai/docs/resources/examples)

## License

MIT - see [LICENSE](LICENSE) for details.