An open API and MCP server for pet screening.

# 1. Mint an API key from the admin UI, then call the API.
$ export LP_TOKEN="lp_live_abcdef123456..."

# 2. List properties you have access to.
$ curl -H "Authorization: Bearer $LP_TOKEN" \
       https://demo.leashpass.com/api/v1/properties

# 3. Create a pet for a resident.
$ curl -X POST -H "Authorization: Bearer $LP_TOKEN" \
       -H "Content-Type: application/json" \
       -H "Idempotency-Key: $(uuidgen)" \
       -d '{"name":"Buddy","species":"dog","sex":"male"}' \
       https://demo.leashpass.com/api/v1/pets

# 4. Attach a vaccination record to that pet's profile (multipart upload, 202 + status).
$ curl -X POST -H "Authorization: Bearer $LP_TOKEN" \
       -H "Idempotency-Key: $(uuidgen)" \
       -F "document_type=vaccination_record" \
       -F "file=@./rabies-2025.pdf;type=application/pdf" \
       https://demo.leashpass.com/api/v1/profiles/petprof_.../documents

# 1. Mint an API key at /admin/api-keys/new with these scopes:
#    mcp:connect, properties:read, users:read, pets:read,
#    profiles:read, profiles:review, documents:read

# 2. Add LeashPass to Claude Desktop's config:
#    ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "leashpass": {
      "transport": "sse",
      "url": "https://demo.leashpass.com/mcp/sse",
      "headers": {
        "Authorization": "Bearer lp_live_abcdef...",
        "LeashPass-Acting-User": "agent:claude-desktop"
      }
    }
  }
}

# 3. Restart Claude Desktop and ask:
#    "What pet profiles need review at Acme East?"
#    "Approve Buddy's profile with the note 'pet rent $50/month'."
#    "Show me the vaccination record on Cooper's profile."

12 read tools (properties, residents, pets, profiles, documents) plus transition_profile and reopen_profile for state changes, update_pet / update_profile_manager_note for manager write-back, notify_resident_about_profile for templated emails, six Phase 2.0 tools for manager-initiated application requests (create_application_request, get_application_request, list_application_requests, update_application_request, submit_application_request, cancel_application_request) — the conversion on submit creates a real pet + scored pet_profile from the resident’s conversational walkthrough — attach_document_to_profile (Phase 2.1) that materialises a staged chat upload into a real document, and two Phase 2.2 preview tools (preview_transition_profile and preview_notification) that produce structured snapshots the chat UI renders as visual confirmation widgets before destructive actions fire — the action tools refuse calls without a valid preview_id with a structured permission_denied response, so the two-phase commit is enforced at the tool gate, not by prompt etiquette. Phase 2.2.2 added get_profile_workflow, the read-only sibling of preview_transition_profile — same vertical-pipeline widget, no Confirm button, no preview_id; for status-style questions like “where is Buddy in the process?” or “show me Charlie's final journey”. Phase 2.3 codified the chat response surface as a small vocabulary of structured-markdown patterns (review-queue-table, priority-callout, action-prompt, summary-card) the LLM emits directly in prose and the frontend upgrades to styled components — integrators building their own UIs can detect the same fenced-block tags to render branded components without changing the agent prompt. The inline status-pill vocabulary (📥 submitted, 🔍 under_review, etc.) upgrades inline markdown code spans automatically. All token names + WCAG contrast notes live in docs/styling.md. Phase 2.4 added three server-rendered widget tools (list_review_queue, get_priority_item, get_profile_summary) that author the same structured payloads as Phase 2.3’s patterns — but on the server, not in the LLM. The chat handler detects each tool by name and wraps the JSON response in the canonical fenced widget block (review-queue-table / priority-callout / summary-card); the frontend renderer stays unchanged. For integrators building their own chat surface against the MCP server: call these tools the same way you’d call any other read, then either render the JSON into your own UI directly or apply the wrap pattern (detect by tool name, emit a ```<widget-tag>\n<json>\n``` fenced block in the assistant message stream, let your markdown renderer pick it up). No LLM-side JSON authoring required; the auto-scope-by-role gate keeps a profiles:read key honest about org / property / resident-on-profile boundaries. See docs/chat.md § Server-rendered visuals. Integrators building their own UIs follow the same preview-then-confirm pattern: call the preview tool, surface the snapshot to the user, then call the action tool with the returned preview_id — the preview_id lands on the success audit row's before_json so preview→confirm chains stay joinable in the audit log. Every workflow tool writes both an MCP-context audit row and a domain audit row, so the audit feed is unified across REST and MCP. Tool results include human-readable display fields so agents can surface conversational responses (“Buddy (Golden Retriever) for Maria Garcia at Acme East — under_review, score 4”) without follow-up lookups to resolve IDs into names. Full MCP reference → · Demo walkthrough →

Two surfaces, one tool catalog. External agents (Claude Desktop, customer PMS) talk to the MCP server over SSE with an API key; logged-in LeashPass users get an embedded chat at /chat with session-cookie auth. Both run through the same ExecuteTool dispatcher and emit the same mcp.tool.* audit rows; only the auth shape and transport differ. Chat backend reference →

Chat-first onboarding. Every role lands on /chat immediately after sign-in (Phase 1f.3). The page auto-fires a personalized briefing on first load: a structured system prompt tells the model to greet the user by name, confirm their role and access scope, surface 2–3 high-priority items (submitted profiles awaiting review, profiles stuck in under_review for more than a week, stale needs_info profiles, duplicate documents), and suggest one or two concrete next actions. Operators without an organization pin get a tailored variant that walks them through “Switch organization” before doing anything org-scoped. Within 5–10 seconds of clicking the demo login an evaluator sees the agent doing real work; the briefing prompt is visible in the conversation history (transparent — not a hidden trick).

Operator-tunable agent behavior. Self-hosters can shape how the chat assistant responds across the whole instance without touching code or restarting the binary (Phase 1f.4). The operator UI at /admin/site-settings edits four overlay knobs that layer onto the hardcoded base prompt as the final system-prompt sections (so operator instructions land last and therefore most-weighted):

• Tone — formal / neutral / casual.
• Terminology overrides — map LeashPass-default terms to your house language (residents=tenants, profile=application, …).
• Additional instructions — up to 2000 characters appended verbatim ("Always cite the rubric version", "End approvals with 'Welcome to the building!'").
• Site-wide policy notes — up to 5000 characters rendered as a dedicated POLICY NOTES section the model cites when relevant ("Buildings 1–4 cap at 2 pets per unit").

Save and the next chat turn reflects the change — no restart, no redeploy. Every save writes a site.settings.updated audit row with a full before/after diff. Per-org, per-user, and conversation-level overrides are deferred to a future phase; site-wide is the right granularity for a single-tenant self-hosted deployment.

Honest permission model. Every MCP write tool runs through a single Phase 1f.5 gate (internal/mcp/tools/permissions.go). When a caller is denied, the tool returns a structured payload — not a prose string — with stable fields useful for external integrators:

{
  "error_code":   "permission_denied",
  "reason":       "manager_not_assigned_to_property",
  "user_role":    "manager",
  "required":     "admin in this org, OR a manager assigned to property prop_01...",
  "alternatives": ["Sandra Chen (admin)", "Rachel Nguyen (manager assigned to this property)"],
  "message":      "permission_denied: this manager is not assigned to the property. Either an admin or one of the assigned managers needs to perform this action."
}

Surfaces: the JSON-RPC error.data field on MCP responses, the tool_result content in chat sessions, and the after_json column on the mcp.tool.<tool>.permission_denied audit row (distinct action from .failure, so operators can filter for gate hits without scraping error strings). The reason codes are stable — manager_not_assigned_to_property, operator_no_org_pin, role_cannot_write — safe to branch on in external integrations.

# 1. Run the binary. Defaults to SQLite at ./leashpass.db.
$ docker run -p 8080:8080 -v lp-data:/data \
       ghcr.io/leashpass/leashpass:latest

# 2. Bootstrap the first admin account.
$ curl -X POST http://localhost:8080/bootstrap \
       -d '{"email":"you@example.com"}'

# 3. Smoke-test the API.
$ curl http://localhost:8080/api/v1/properties \
       -H "Authorization: Bearer $LP_TOKEN"