feat: add session tools (get_sessions, get_session_stats, get_session_activity) - #26
Merged
Merged
Conversation
…_activity)
The server exposed aggregate analytics but no way to reach Umami's
per-session data — the sessions that session replay records. Add three
tools wrapping the documented /sessions endpoints:
- get_sessions — GET /websites/{id}/sessions: paginated session list
plus total `count`. Each row carries browser, os,
device, country/region/city, language, screen,
visits, views, firstAt/lastAt.
- get_session_stats — GET /websites/{id}/sessions/stats: flattened totals
(pageviews, visitors, visits, countries, events).
- get_session_activity— GET /websites/{id}/sessions/{sessionId}/activity:
ordered pageview/event timeline for one session.
Notes:
- The activity endpoint rejects missing startAt/endAt on current Umami
(400 "expected number, received NaN") despite the docs marking them
optional, so the client defaults them (0 .. now) when the caller omits
them; callers can still scope with the session's firstAt/lastAt.
- Refactored the shared "validate website_id + normalize dates + run query
+ render" flow into dateRangeQuery/textContent helpers; get_stats and
get_session_stats now share it (removes a dupl-lint hit).
- validateWebsiteID generalized to validateID, plus validateSessionID.
- Added a session-insights prompt and README/tool-table entries.
- .gitignore: also ignore the default `umami-mcp-server` build artifact.
Tested against a live self-hosted Umami: all three tools return real data
(session count, stats, and a full page/event timeline). go test ./... and
golangci-lint v1.64.8 pass.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds three tools that surface Umami's per-session data — the sessions that Session Replay records — which the server didn't expose before:
get_sessionsGET /websites/{id}/sessionscount; each row has browser, os, device, country/region/city, language, screen, visits, views, firstAt/lastAtget_session_statsGET /websites/{id}/sessions/statsget_session_activityGET /websites/{id}/sessions/{sessionId}/activityWhy
People with Session Replay enabled can see recorded sessions in the dashboard but can't reach them through the MCP.
get_sessionsgives the count + metadata, andget_session_activityreconstructs the page/event sequence of a visit — the closest data-level view of what a replay shows.Notes
/activityendpoint returns400 "expected number, received NaN"whenstartAt/endAtare omitted on current Umami, despite the docs marking them optional. The client defaults them (0.. now) so the tool works out of the box; callers can still pass a session'sfirstAt/lastAtto scope.dateRangeQuery/textContenthelpers;get_statsandget_session_statsnow share it.validateWebsiteIDgeneralized tovalidateID, plusvalidateSessionID.session-insightsprompt and README / tool-table entries..gitignore: also ignore the defaultumami-mcp-serverbuild artifact (the existing entries only coveredumami-mcp).Testing
go test ./...— pass (added client tests for all three endpoints +validateSessionID).golangci-lint v1.64.8 run ./...— clean.🤖 Generated with Claude Code