Metadata-Version: 2.4
Name: exclugo-mcp
Version: 0.1.3
Summary: MCP server for the Exclugo healthcare compliance screening platform
Author: Exclugo
License: MIT
Requires-Python: >=3.10
Requires-Dist: httpx>=0.25
Requires-Dist: mcp[cli]>=1.0
Description-Content-Type: text/markdown

# Exclugo for Claude

Use Claude (or any AI assistant) to control your Exclugo account — manage facilities, employees, vendors, licenses, billing, reports, and more, just by typing what you want in plain English.

---

## Setup (3 steps — about 5 minutes)

You don't need to know how to code. Just follow these steps in order.

### Step 1 — Install `uv`

`uv` is a tiny tool that runs Exclugo for Claude. You only have to install it once.

**On a Mac:**

1. Open the **Terminal** app (press `Cmd + Space`, type "Terminal", press Enter).
2. Copy and paste this line into Terminal, then press Enter:

   ```bash
   curl -LsSf https://astral.sh/uv/install.sh | sh
   ```

3. **Quit Terminal completely** (`Cmd + Q`) and reopen it. This is important.

**On Windows:**

1. Open **PowerShell** (press the Windows key, type "PowerShell", press Enter).
2. Copy and paste this line, then press Enter:

   ```powershell
   powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
   ```

3. **Close PowerShell completely** and reopen it.

---

### Step 2 — Get your Exclugo API token

Ask your Exclugo administrator to give you an **API token**. It will look like a long string of letters and numbers, e.g. `abc123def456...`.

(If you'd rather use your normal Exclugo username and password instead, you can — see the "Logging in with username/password" section below.)

---

### Step 3 — Tell Claude Desktop about Exclugo

1. Open Claude Desktop.
2. Click the **Claude** menu at the top → **Settings…** → **Developer** → **Edit Config**.
3. A file called `claude_desktop_config.json` will open.
4. Paste this in (replace `your-token-here` with the token from Step 2):

   ```json
   {
     "mcpServers": {
       "exclugo": {
         "command": "uvx",
         "args": ["exclugo-mcp"],
         "env": {
           "EXCLUGO_BASE_URL": "https://app.exclugo.com",
           "EXCLUGO_API_TOKEN": "your-token-here"
         }
       }
     }
   }
   ```

   > **Already have other MCP servers?** Just add the `"exclugo": { ... }` block inside your existing `"mcpServers"` section.

5. Save the file (`Cmd + S` or `Ctrl + S`).
6. **Fully quit Claude Desktop** (`Cmd + Q` on Mac) and reopen it.

That's it! You should now see a 🔌 hammer icon at the bottom of the Claude chat box. Click it and you'll see all the Exclugo tools available.

---

## Try it out

Type one of these into Claude:

- *"Show me all my Exclugo facilities."*
- *"List the licenses expiring in the next 30 days."*
- *"Pull up the report for John Smith at Sunrise Care."*
- *"Show me last month's invoices."*
- *"Add a new employee named Jane Doe to facility #42, SSN 123-45-6789, born 1980-05-15."*

Claude will use Exclugo on your behalf and show you the results.

---

## What you can do

You have the same access in Claude that you have when logged into Exclugo on the website. If you're an admin, you can do admin things. If you're a client user, you can do client things. **All your existing permissions and restrictions still apply.**

You can:

- 📋 **Browse your data** — facilities, employees, vendors, licenses, NPIs, reports, invoices
- ➕ **Add new records** — order new background checks, add employees, register licenses
- ✏️ **Edit records** — update employee info, change facility settings, add notes to reports
- 🔍 **Search & filter** — find people by SSN, find expiring licenses, search reports
- 📊 **View dashboards** — alerts, processing status, monitoring summaries
- 💰 **Manage billing** — view invoices, generate PDFs, run commission reports
- 📅 **Manage calendar** — create events, send reminders
- ▶️ **Trigger monitoring** — sex offender, DMF, NPI, exclusion checks
- 📤 **Bulk uploads** — review upload logs, resolve failed records

---

## Logging in with username/password (optional)

If you don't want to use a fixed token, you can have Claude log in for you. In Step 3, leave out the `EXCLUGO_API_TOKEN` line:

```json
{
  "mcpServers": {
    "exclugo": {
      "command": "uvx",
      "args": ["exclugo-mcp"],
      "env": {
        "EXCLUGO_BASE_URL": "https://app.exclugo.com"
      }
    }
  }
}
```

Then ask Claude: *"Log into Exclugo as username `myuser` with password `mypass`."* Claude will store the session for you until you close it.

---

## Troubleshooting

### Claude shows "Failed to spawn process: No such file or directory"

This means `uv` isn't installed yet, or you didn't restart after installing.

**Fix:**
1. Re-do Step 1 to install `uv`.
2. **Completely quit Claude Desktop** (`Cmd + Q` on Mac, right-click tray icon → Quit on Windows) and reopen it. Don't just close the window.

If that still doesn't work, find where `uv` was installed:

- Open Terminal/PowerShell and run: `which uvx` (Mac/Linux) or `where.exe uvx` (Windows).
- Copy the full path it shows you (e.g. `/Users/yourname/.local/bin/uvx`).
- Paste that full path into your config in place of `"uvx"`:

  ```json
  "command": "/Users/yourname/.local/bin/uvx",
  ```

### Claude says "I don't have access to Exclugo tools"

- Make sure you saved the config file.
- Make sure you fully quit Claude Desktop and reopened it.
- Check the JSON for typos — every quote and bracket matters. Try pasting it into [jsonlint.com](https://jsonlint.com) to verify it's valid.

### "401 Unauthorized" when Claude tries to do something

Your token is wrong, expired, or the username/password is incorrect. Get a fresh token from your Exclugo admin.

### "403 Forbidden" when Claude tries to do something

You don't have permission for that action. The MCP enforces the same permissions as the Exclugo website — if you can't do something on the website, you can't do it here either. Contact your admin if you need access.

---

## For administrators

### Generating an API token for a user

From your Exclugo Django shell:

```bash
python manage.py shell -c "
from rest_framework.authtoken.models import Token
from django.contrib.auth.models import User
user = User.objects.get(username='THE_USERNAME')
token, created = Token.objects.get_or_create(user=user)
print(f'Token: {token.key}')
"
```

Send the printed token to the user. They paste it into their config in Step 3.

### Permissions

The MCP calls Exclugo's existing REST API — meaning **all role-based access controls already enforced by Django apply automatically**:

- Admin users → full admin access
- Client users → only their own facilities, restricted by their `client_user_settings` permissions
- Reseller users → only their reseller's clients
- Free-tier clients → blocked from premium features

You don't need to change any backend code. Whatever a user can do on the website, they can do via Claude.

### Publishing a new version (for the package author)

```bash
cd exclugo-mcp
# bump version in pyproject.toml first!
rm -rf dist
pip install build twine
python -m build
twine upload dist/*
```

---

## All available tools (~78)

<details>
<summary>Click to expand the full tool list</summary>

### Authentication
- `authenticate` — Log in with username/password

### Facilities
`list_facilities`, `get_facility`, `create_facility`, `update_facility`, `delete_facility`, `get_facility_products`, `get_facility_fees`, `get_facility_files`, `get_facility_report`, `get_facilities_by_product`

### Employees
`create_employee`, `edit_employee`, `search_employees`, `search_by_ssn`, `get_employee_address_history`

### Vendors
`create_vendor_individual`, `create_vendor_organization`, `edit_vendor`, `search_vendors`

### Licenses
`create_license`, `get_expiring_licenses`, `run_single_license_check`, `add_manual_license_check`, `get_license_files`, `generate_613a_letter`, `send_613a_email`, `email_license_status`

### NPIs
`create_npi`, `edit_npi`, `search_npis`

### Reports & Searches
`list_reports`, `get_report`, `get_report_searches`, `get_search_detail`, `get_search_alerts`, `get_ssn_trace`, `get_report_history`, `add_report_note`, `save_report_document`, `get_source_lists`

### Billing
`list_invoices`, `get_invoice`, `create_invoice_pdf`, `get_invoice_excel`, `auto_create_invoices`, `bulk_invoice_action`, `get_billing_alerts`, `list_sales_reps`, `get_commission_by_month`, `create_iif_file`

### Calendar
`create_calendar`, `get_calendar_for_facility`, `get_calendar_events`, `get_all_events`, `calendar_override`, `send_email_reminder`

### Users
`get_current_user`, `list_admin_users`, `get_user_detail`, `add_client_user`, `get_client_users`, `get_user_facilities`

### Uploads
`admin_upload`, `client_upload`, `get_upload_logs`, `get_failed_records`, `resolve_failed_records`

### Monitoring triggers
`run_exclusion_matching`, `run_sex_offender_check`, `run_dmf_check`, `run_npi_check`, `run_ssn_plus_exclusion_check`, `run_ssn_verification`

### Dashboard / client
`get_dashboard`, `get_client_report`, `update_alert`, `disable_monitoring`

</details>

---

## License

MIT
