89 lines
5.5 KiB
Markdown
89 lines
5.5 KiB
Markdown
# Assistant access (MCP)
|
||
|
||
Open **Albums → Assistants** (`/dashboard/assistants`) and create a connection.
|
||
The endpoint is `https://ma.hadlock.tech/api/mcp`, using Streamable HTTP. Configure
|
||
your MCP client to send `Authorization: Bearer <token>` on every request. Tokens
|
||
are displayed once, stored only as SHA-256 hashes, expire after 1–365 days, and
|
||
can be revoked in that screen. Keep them in the client's secret storage, never
|
||
in prompts or source control. This version uses bearer tokens, not OAuth discovery;
|
||
clients must support custom authorization headers. No public/anonymous access.
|
||
|
||
## Permissions
|
||
|
||
Tokens default to read-only statistics/discovery permissions. Enable only the
|
||
existing event, group, and platform permissions needed by that assistant.
|
||
Selections are a ceiling: the same current memberships/roles used by the web UI
|
||
are re-evaluated for every action. Selecting platform permissions never makes an
|
||
ordinary account a platform administrator. Removing a role restricts existing
|
||
tokens; revoking a token blocks new requests, not work already executing.
|
||
|
||
Private photo access is separately restricted by `photos.private.read`, including
|
||
when the token belongs to an owner/admin. Read-only tokens cannot call write tools
|
||
even if they include management permissions for reading associated data.
|
||
|
||
The explicit tool allowlist covers platform stats/settings/users/roles/allowances,
|
||
groups and memberships, events and schedules, photos/submission/note moderation,
|
||
guest lists and notification emails, invitations, exports, and banner/sign workflows.
|
||
It does not expose sessions, token management, guest authentication, SQL, arbitrary
|
||
HTTP requests, or shell commands. New application procedures require explicit review
|
||
before being added to the MCP catalog.
|
||
|
||
## Calling tools
|
||
|
||
Tool names use underscores, for example `manager_stats` and `group_rename`.
|
||
Existing application input goes under `input`. Dates are ISO-8601 strings.
|
||
|
||
```json
|
||
{"name":"manager_stats","arguments":{"input":{"eventId":"EVENT_UUID"}}}
|
||
```
|
||
|
||
Every write requires `confirm: true` in addition to a write-enabled token and the
|
||
required permissions. This is an explicit API acknowledgement, not proof that a
|
||
human approved the action; configure your assistant to ask before destructive
|
||
actions or sending messages.
|
||
|
||
```json
|
||
{"name":"group_rename","arguments":{"input":{"groupId":"GROUP_UUID","name":"Wedding team"},"confirm":true}}
|
||
```
|
||
|
||
Do not automatically retry writes after an ambiguous connection failure. Re-read
|
||
state first: mutations may have succeeded and are not universally idempotent.
|
||
List outputs are paginated with top-level `offset` and `limit` (default 50, max
|
||
100), returning `items`, `total`, and `nextOffset`. Application-specific filters
|
||
and page fields remain inside `input`. Some application queries impose their own
|
||
limits; `total` then reflects that result set rather than all database records.
|
||
|
||
Uploads still go directly to storage using signed URLs. MCP never proxies original
|
||
files. Tool results may contain personal data or signed URLs according to the
|
||
selected permissions—treat the connected assistant as a data recipient. Guest
|
||
notes, names, and other content returned by tools are untrusted data, not instructions.
|
||
|
||
Calls have per-client and per-token rate limits, a 64 KiB request-body cap, origin
|
||
validation, and no-cache responses. Tool audit entries record token/user ids,
|
||
tool name and success, not raw arguments, credentials, or guest data. Existing
|
||
mutation audit entries remain unchanged. No production token is created automatically.
|
||
|
||
## Verification
|
||
|
||
```sh
|
||
MCP_INTEGRATION=1 bun --env-file=.env test apps/web/src/server/mcp/mcp.integration.test.ts
|
||
```
|
||
|
||
The integration test refuses non-local databases and does not send email.
|
||
|
||
## Coolify health checks
|
||
|
||
Both Compose definitions use `/api/health/ready` for web readiness (bounded DB
|
||
probe) and a loopback-only worker `/health` endpoint on port 3001. The worker
|
||
checks DB connectivity and loop heartbeats; a loop stalled for 15 minutes is
|
||
unhealthy. Long exports can exceed this threshold and should be investigated.
|
||
`/api/health` remains process liveness. Responses omit internal dependency details.
|
||
Checks run every 30 seconds, with a 5-second timeout and three retries. No worker
|
||
health port is published. Docker health status by itself does not automatically
|
||
restart an unhealthy container; it supplies readiness information to Coolify.
|
||
# Bulk gallery workflows
|
||
|
||
Use `manager_photos` with `input.limit`, `input.offset`, optional `input.visibility` and `input.processingStatus` to inspect a page. Capture explicit photo IDs; a bulk request never expands to later uploads. `manager_previewBulkPhotos` checks up to 100 IDs for an action (`public`, `hidden`, `private`, `rejected`, `delete`). Pass eligible IDs to `manager_bulkPhotos` with both `input.confirm=true` and the MCP write wrapper's `confirm=true`. Results are per photo, including skipped/failed items. Permissions are rechecked during execution. Deletion skips photos still uploading or processing, permanently removes originals and variants, and can partially succeed; inspect results before retrying.
|
||
|
||
For organizer uploads, `manager_createGalleryPhotos` accepts up to 25 file descriptors and returns presigned PUT URLs in input order. PUT each original directly to storage with its matching Content-Type, then call `manager_completeGalleryPhotos` with successful IDs to validate size and queue transcoding. These actions require existing `settings.manage` permission. Photos start pending review, even when guest publication is automatic. Do not blindly retry creation: it creates a new batch. No file bytes pass through MCP or Next.js.
|