Files
FireworksApp/fireworks_detect/MCP_README.md
T

26 lines
2.6 KiB
Markdown

# BoomCast read-only MCP
The stateless Streamable HTTP endpoint is `POST /mcp/` on the **existing Django web server**. The normal local development command uses `127.0.0.1:8000`; MCP needs no second port or process. Use the public HTTPS Django origin for a remote client. Do not expose the local HTTP listener directly.
Run migrations, then issue a separate credential for an active user who has both `fireworks_detect.view_event` and `fireworks_detect.view_pendingevent` permissions:
```sh
python manage.py migrate
python manage.py create_mcp_token USERNAME --name "My MCP client"
```
The command prints the token once. Configure the MCP client with a Streamable HTTP URL such as `https://django.jorendegraaf.eu/mcp/` and header `Authorization: Bearer bmcp_...`. Refresh the client's MCP tools after configuring it. A sensor `ss_...` Bearer token, browser login cookie, or anonymous request cannot access the endpoint. To revoke a credential, set its `McpAccessToken.revoked_at` in Django admin/shell (or delete the record). Removing either Django view permission or deactivating the user also denies access. MCP uses the same Django user permission backend as admin; no write permissions are needed.
Available tools: `submissions_list`, `submissions_get`, `submissions_stats`, and `pending_summary`. Date filters use `YYYY-MM-DD` and apply to review date. A query covers at most 366 days; if omitted, the default is the most recent 366 days. List pages are capped at 100 items and offset 10,000. The endpoint is limited to 120 requests per minute per user. It accepts JSON responses for MCP initialize, tool discovery and tool calls. It supports no write methods or server state changes.
Only approved `Event` rows are individually available. The existing review workflow **deletes denied `PendingEvent` rows**, so historical denial statistics and manually confirmed sound classes do not exist in the current data model. MCP reports `review_outcome: approved`, `confirmed_classification: null`, and `confirmed_classification_available: false` rather than treating a YAMNet prediction as a human confirmation. Pending results contain counts only. The only location field is the existing H3 cell or a cell calculated using the configured H3 resolution; exact coordinates, audio, filenames, free-text locations, notes, sensor identity, and raw classifier responses are omitted.
For a quick protocol check after client setup:
```sh
curl -sS https://django.jorendegraaf.eu/mcp/ \
-H "Authorization: Bearer $BOOMCAST_MCP_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```