cp .env.example .env
npm install
npm run db:up # postgres via docker compose, localhost:5433
npm run db:migrate # applies src/db/schema.sql idempotently
npm run db:seed # seeds a demo workspace; prints the login email
# In production (compiled image, no tsx): node dist/scripts/seed.js [email protected]
npm run build:app # builds the MCP App UI bundle into app/dist/app.html
npm run dev # tsx watch src/index.ts
Choose Streamable HTTP, point it at http://localhost:3000/mcp, and connect. The inspector will hit the OAuth flow and open the login page in your browser. Without SMTP_URL or RESEND_API_KEY set, magic-link sign-in doesn't send an email — the link is printed to the server log and also shown directly on the "check your email" page, so local dev never needs a real mailbox.
src/
index.ts entry point
config.ts env vars, plans, scopes
db/ schema.sql, migration runner, query helpers
lib/ dates, duration parsing, rates, ids, errors, money
services/ workspace, time entries, invoices, propose (catch-up), audit
mcp/ McpServer setup: tools, resources, prompts (src/mcp/server.ts)
auth/ OAuth provider, login/consent routes, sessions, Google OIDC
http/ express app, docs/marketing routes, web app routes, invoice pages
import/ CSV import (Toggl/Harvest/Clockify)
stripe/ billing checkout, Connect onboarding, webhook handling
email/ email sending via SMTP (nodemailer) or Resend (magic links, invoice emails)
pdf/ invoice PDF rendering (pdfkit)
app/ MCP App UI source; scripts/build-app.ts bundles it into app/dist/app.html,
which src/mcp/app-resource.ts embeds as an MCP UI resource and
src/http/routes/invoice-public.ts reuses for the public invoice page
skills/ bundled Claude skills (log-day, catch-up, weekly-report,
invoice-client, month-close) — also exposed as MCP prompts
.claude-plugin/ Claude plugin/connector manifest
.codex-plugin/ ChatGPT/Codex plugin manifest
docs/ privacy.md, terms.md, docs.md, landing.md, llms.txt — served live
at /privacy, /terms, /docs, /, and /llms.txt by src/http/routes/docs.ts
test/ unit tests (vitest) and the golden prompt set
Tallied runs on any host that gives you a stable HTTPS origin — Fly.io, Railway, Render, or similar.
Before submitting to a connector directory, see docs/listing.md for store-listing copy and screenshots, and the product spec's submission checklist for the full requirements. Note that Claude's connector directory requires the submitting organization to be on a Team (or Enterprise) plan.