# beli

Reverse-engineered **Beli** API contract and an **MCP server** — a TypeScript
monorepo built zod-first.

> Unofficial. Built from static + dynamic analysis of the Beli Android app
> (v9.3.1). Snapshot of a private API with no compatibility guarantee. For
> personal interoperability with your own account; rate-limit politely.

## Packages

| Package | Published as | What it is |
|---------|--------------|------------|
| [`packages/contract`](./packages/contract) | `@beli/contract` | **zod schemas = source of truth** for every endpoint payload, a typed endpoint registry, and an OpenAPI 3.1 doc generated from the schemas. |
| [`packages/client`](./packages/client) | `@beli/client` | Typed API client with login-once session management (auto-refresh). Validates responses against the contract. |
| [`packages/mcp-server`](./packages/mcp-server) | `beli-mcp` | The MCP server (`npx beli-mcp`). Tools for search, reviews, photos, bookmarks, and local drafts. |

`research/` holds the reverse-engineering artifacts (analysis docs, captures,
the original Python reference client) and is **not published**.

## Architecture (zod-first)

```
zod schemas (contract)  ──▶  TypeScript types  (z.infer)
        │                          │
        ├──▶  OpenAPI 3.1  (generated byproduct: @beli/contract/openapi.json)
        │
        └──▶  @beli/client (validates req/resp)  ──▶  beli-mcp tools
```

The zod schemas are the single definition: they produce the static types, do
runtime validation in the client, back the MCP tool input schemas, and emit the
publishable OpenAPI document. Nothing is hand-duplicated.

## Develop

```bash
npm install
npm run typecheck     # tsc -b across all packages
npm run build         # build libs (tsc) + bundle the CLI (tsup)
npm run gen:openapi   # regenerate packages/contract/openapi.json from zod
```

## Use the server

See [`packages/mcp-server/README.md`](./packages/mcp-server/README.md) for the
`npx beli-mcp` quickstart and client configuration.

## License

MIT