stessa-client-ts
ericmanyc/stessa-client-ts
Unofficial TypeScript client + MCP server for Stessa (rental-property accounting). Not an official Stessa product.
Instalação
npx convez-ai ericmanyc/stessa-client-ts1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
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/apiendpoints, 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_requestescape hatch andstessa://catalogresource 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; seestessa://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:
- Returns the in-memory bearer if its JWT is still valid
- Loads from the token store; if the bearer is expiring, exchanges the stored session cookie for a new one
- Connects to a running Chromium (debug port 9222), reads the
app.stessa.comsession cookie, and mints a bearer from it - 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.