README

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`	`@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`	`@beli/client`	Typed API client with login-once session management (auto-refresh). Validates responses against the contract.
`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

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 for the npx beli-mcp quickstart and client configuration.

License

MIT

beli-mcp