stessa-client-ts

TypeScript client library and MCP server for Stessa, a rental-property accounting platform (owned by Roofstock). Built in the same shape as tenantcloud-client-ts.

This is not an official Stessa product. Stessa does not publish a public API; this library works against their internal app.stessa.com/api endpoints, reverse-engineered from the web app's compiled bundle (see docs/api-findings.md). It can break whenever Stessa changes their frontend. Use at your own risk.

Live-verification status: endpoints and field names were discovered statically from the SPA bundle and are exercised here against mocked responses, not yet confirmed against a live account. Treat field names as best-effort; the stessa_request escape hatch and stessa://catalog resource give you the full surface to verify against your own data.

Packages

Package	Description
packages/client	stessa-client: typed API client (properties, portfolios, banking, documents, transactions, tenancies), {data}/JSON:API envelope handling, money ({cents, currency_iso}) parsing, token stores, CDP browser auth
packages/mcp	stessa-mcp: MCP server (stdio) exposing Stessa to AI agents, plus a login/logout/install/serve CLI and a hosted multi-user server

Quick start

MCP server (local)

npx stessa-mcp install claude-code   # or: claude-desktop

Restart Claude Code and ask things like "what's my portfolio equity?", "list my properties", or "show my bank account balances". The first time, the agent notices you are not signed in and offers to open a Stessa sign-in window (Auth0 login); the session is captured into your OS credential store. To sign in ahead of time: npx stessa-mcp login.

Hosted server (Claude on web, teams)

stessa-mcp serve runs a multi-user remote server: OAuth 2.1 in front (claude.ai custom-connector flow, email + invite code), an encrypted per-user Stessa session vault in Postgres, and per-person pairing via stessa-mcp login --remote. Each teammate's tool calls run under their own Stessa account. Each company hosts its own instance (fork or clone this repo). Step-by-step Railway guide: docs/DEPLOY_RAILWAY.md.

Client library

import { StessaClient, SecureTokenStore } from "stessa-client";
import { CdpTokenProvider } from "stessa-client/cdp";

const tc = new StessaClient(
  new CdpTokenProvider({ tokenStore: new SecureTokenStore(), allowInteractiveLogin: true }),
);

const portfolios = await tc.portfolios.list();
const properties = await tc.properties.list({ scope: { portfolio_id: portfolios[0].id } });
const accounts = await tc.banking.accounts();

// Any other endpoint (see stessa://catalog):
const summary = await tc.request("GET", "/api/v2/summary");

MCP tools

13 tools plus resources stessa://guide, stessa://catalog, stessa://property/{id}, stessa://portfolio/{id}:

• Core reads: get_user, list_portfolios, get_summary, list_properties, get_property, list_bank_accounts, list_documents, list_tenancies, list_scheduled_incomes
• Financials: get_transactions_summary, list_transaction_categories, get_report_data
• Escape hatch: stessa_request (any of the ~110 cataloged endpoints; see stessa://catalog)

Tool responses flatten money to {cents, amount, currency} and resolve property/portfolio IDs to names via an entity cache. Money-moving banking endpoints (transfers, card creation) are intentionally reachable only through stessa_request, so they are always explicit.

How authentication works

Stessa uses Auth0 (custom domain auth.roofstock.com); the SPA holds a short-lived bearer in memory and a durable session cookie, and mints fresh bearers via GET /api/token_from_session. The CDP token provider:

1. Returns the in-memory bearer if its JWT is still valid
2. Loads from the token store; if the bearer is expiring, exchanges the stored session cookie for a new one
3. Connects to a running Chromium (debug port 9222), reads the app.stessa.com session cookie, and mints a bearer from it
4. If allowed, launches a temporary browser window for interactive Auth0 login, then captures the session

Development

npm install
npm run build      # tsc --build for both packages
npm test           # vitest (client parsing + MCP server + remote OAuth)

See SPEC.md for design decisions and docs/api-findings.md for the documented internal API surface.

License

MIT.