lisa-dev

The LISA local-development CLI (lisa), a thin HTTP client of LISA.DataAccessServer. TypeScript / Node, distributed via npm. It does not embed the FIND parser — the one engine lives only in the C# server. Spec: mcp-docs/lisa-dev-toolchain.md.

Implemented: lisa mcp, lisa login, lisa claim, lisa install-desktop. Targets the multi-tenant server (data-access-server-mt.md): every call is scoped to a --site, and lisa login is a rolled email OTP that caches a site-scoped bearer.

The CLI is data access only — read-only FIND + schema for Claude. Widget/app authoring (the former lisa dev Vite proxy) lives in the web application now, not here.

Build

cd lisa-dev
npm install
npm run build      # tsc -> dist/

Install & upgrade (end users)

Install globally and call the lisa binary directly — do not launch via bare-name npx @lisatech/data-access …. A bare name lets npx run whatever copy is already on PATH (a stale global) instead of the latest, so you can silently keep running an old version.

npm install -g @lisatech/data-access@latest
lisa version            # confirm what's installed

Point your MCP host at the global binary (command lisa, args ["mcp"]) rather than an npx invocation.

Upgrading (global installs do not auto-update):

npm outdated -g @lisatech/data-access            # is a newer version out?
npm install -g @lisatech/data-access@latest      # upgrade in place

After upgrading, restart/reconnect the MCP server in your client (the running MCP process holds the old binary in memory until it relaunches). In Claude Desktop that's a full quit + reopen; Claude Code can reconnect the server.

lisa mcp — stdio MCP server

Exposes a read-only data-access surface over the live data server, scoped to the configured site:

• discover_schema — the exposed tables/columns (call first).
• find_examples(intent) — proven, approved FIND queries for this site that match the user's intent (ranked, stale-dropped server-side). Same corpus the web Find agent uses.
• run_find_query(query, params) — run a read-only FIND.
• reconnect(code) — redeem a connect code to refresh the session (no terminal).
• resource lisa://guide/find — the FIND dialect guide (hub + on-demand detail topics).

Config comes from the environment (the MCP-native mechanism):

• LISA_SERVER_URL (default http://localhost:5187)
• LISA_SITE (the {site} segment, e.g. dev)
• LISA_TOKEN (the site-scoped bearer; usually resolved from cached lisa login creds)

Server errors (incl. the "use FIND, not SELECT" teaching message) come back as isError tool results so Claude can self-correct.

Config resolution (all subcommands)

Every subcommand resolves URL + site + token the same way: explicit environment wins (LISA_SERVER_URL / LISA_SITE / LISA_TOKEN), then the credentials cached by lisa login / lisa claim, then defaults (http://localhost:5187). So lisa mcp via .mcp.json (which carries LISA_SITE but no token) picks up the bearer from a prior sign-in.

lisa login — sign in (email OTP) and cache a site bearer

lisa login --site dev                       # prompts for email, emails a code, prompts for it
lisa login --site dev --email [email protected]     # skip the email prompt

--site is required; --url defaults to the resolved server URL. The flow requests a one-time code (POST /auth/request-otp), prompts for it, exchanges it at POST /auth/cli-token for a site-scoped bearer, validates it (a GET /s/{site}/lisa/schema probe — also catches "not a member of this site"), and caches {serverUrl, site, token} to ~/.lisa/credentials.json (plaintext — OS keychain is later hardening). The bearer is a fixed ~8h token (sliding-refresh is later work). Used by lisa mcp.

When it expires (the server returns 401), refresh the cached bearer with lisa login … or lisa claim …. lisa mcp re-reads ~/.lisa/credentials.json on a 401 and retries, so the next tool call picks up the new token with no MCP/host restart. On a 401, the tool result also carries the exact re-auth steps (the site's Connect-page URL + the lisa claim command).

lisa claim — redeem a connect code (no OTP)

The re-auth half of the connect flow (mcp-docs/claude-code-connect.md). A signed-in browser generates a single-use connect code on the site's Connect page; redeeming it caches a site bearer without an email round-trip.

lisa claim <code> --url https://<your-server>      # the Connect page prints this exact line

It exchanges the code at POST /auth/redeem-claim, validates the bearer, and caches {serverUrl, site, token} — same cache as lisa login.

lisa install-desktop — register in Claude Desktop

Writes (or removes) the LISA MCP entry in the Claude Desktop config, so there's no JSON to hand-edit. It locates its own cli.js, merges non-destructively (preserves any other MCP servers), and refuses to touch a malformed config.

lisa install-desktop              # add/replace the "lisa" server, then quit + reopen Desktop
lisa install-desktop --dry-run    # print the resulting config without writing
lisa install-desktop --remove     # pull the "lisa" entry back out

Use it in Claude clients

End users (CS staff / customers) don't clone this repo — they install the published package @lisatech/data-access and connect. The self-service flow is the site's Connect page (/s/{site}/utils/connect.html): it bakes in their server/site/email and emits the exact lisa login / lisa install-desktop / lisa claim commands. INSTALL.md (repo root) is the no-browser fallback + the publishing notes.

Local development of this package: the repo's .mcp.json registers the server as lisa (with LISA_SITE=dev) pointing at the local build. Make sure the C# data server is running (dotnet run --project LISA.DataAccessServer), run lisa login --site dev once to cache a bearer, enable the lisa MCP server, and restart Claude Code to pick it up. Then ask Claude to discover the schema and run a FIND.

Self-test

scripts/run-mcp-selftest.sh        # drives the stdio MCP server over the real wire protocol
npm run test:installdesktop        # offline unit test of the Desktop-config merge logic

run-mcp-selftest.sh provisions the tenant DB and the control plane, starts the MT data server (OTP to a file sink, Local file hosting), obtains a site bearer via the OTP → /auth/cli-token flow, then asserts the read-only data-access surface (two tools + discover_schema/run_find_query + the FIND guide) over the real wire protocol. test:installdesktop is offline (no server) and checks the non-destructive merge, refuse-on-malformed, --remove, and per-OS config paths. Both exit 0/1.