Add JSON MCP tools for richer usage queries

[rowesk]

Summary

• Adds five JSON-oriented MCP tools for richer local usage queries:
  • get_usage_range
  • get_raw_sessions
  • get_current_activity
  • get_hourly_timeline
  • get_daily_summary
• Keeps the existing get_usage_activity tool available for backwards compatibility.
• Adds matching IPC request/response paths between SimplyTrackMCP and the main app.
• Expands UsageAggregator with reusable APIs for clipped session ranges, grouped summaries, current activity, daily summaries, and hourly buckets.
• Adds Swift Testing coverage for the new aggregation behavior and IPC-facing tool methods.

Why

The existing MCP integration is useful, but it only exposes a compact pipe-separated daily summary. That works for quick display, but it is awkward for AI clients and automation because callers have to parse human-oriented text and cannot ask more targeted questions.

These additions make the local MCP integration more useful while preserving the current behavior:

• AI clients can request structured JSON instead of parsing text.
• Callers can inspect raw sessions when they need detail.
• Range and hourly queries make it easier to answer questions like “what did I do this afternoon?” or “how did my work break down by hour?”.
• Current activity can show in-progress sessions without waiting for a completed tracking segment.

Testing

• xcodebuild -project SimplyTrack.xcodeproj -scheme SimplyTrackMCP -configuration Debug CODE_SIGNING_ALLOWED=NO build
• xcodebuild -project SimplyTrack.xcodeproj -scheme SimplyTrack -configuration Debug -skip-testing:SimplyTrackUITests CODE_SIGNING_ALLOWED=NO test
• git diff --check
• End-to-end MCP stdio smoke test using a fake Unix-domain IPC server, verifying:
  • tools/list exposes all six tools.
  • tools/call works for each tool.
  • The MCP helper forwards the expected IPC message types [1, 2, 3, 4, 5, 6, 7].

Verified tools:

• get_usage_activity
• get_usage_range
• get_raw_sessions
• get_current_activity
• get_hourly_timeline
• get_daily_summary

Notes

• get_usage_activity intentionally remains unchanged for existing clients.
• New tools return JSON text payloads so MCP clients can consume results reliably.
• Request DTOs are duplicated between the app target and MCP helper target because the helper target does not import the app target models directly.

[renjfk]

/prerelease

[renjfk]

/prerelease

[github-actions]

Prerelease v0.9-pr70.946c2e0 is ready.

[renjfk]

Hi @rowesk, thanks again for digging into the MCP usage data here.

Could you help me understand the concrete use case for the new JSON tools, specifically why an AI agent would need the data in this format?

I ask because #69 already adds CSV/plain-text export through MCP, which seems aligned with lower token usage and should still be easy for AI clients to parse. For the kind of user questions I have in mind, such as summarizing activity or finding top apps/sites, CSV seems to provide the same underlying information with less MCP/API surface area.

Is there a specific workflow or AI client behavior where CSV/plain text is not enough and structured JSON materially helps?

[renjfk]

Also tagging @xverges here since you mentioned in #3 that having this available without UI interaction, via CLI or MCP, would be useful.

If you have a concrete workflow in mind, I would be interested in your opinion too: would CSV/plain-text MCP output from #69 cover your use case, or would the JSON tools proposed here make something materially easier?

[rowesk]

I think the distinction is that #69 is a great export feature, while this PR is more about making SimplyTrack queryable as a local activity API for agents.

CSV/plain text works well when I want to export a day/week of completed sessions and then analyse it elsewhere. But for agent workflows, the useful pattern is often smaller/more targeted:

• “What am I doing right now?”
• “What did I spend the last 90 minutes on?”
• “Summarise this afternoon by app vs website.”
• “Show my hourly focus pattern today.”
• “What active session is currently running?”
• “Give me exact raw sessions for this window so I can correlate with another tool.”

A few concrete places where JSON should help materially:

1. Current/live activity
   The CSV export excludes active sessions because it only exports completed rows. The JSON tools expose get_current_activity and can include active sessions, which is important for an assistant that is monitoring context in real time.

2. Targeted ranges
   CSV supports day/week export. The JSON tools support arbitrary start/end ranges, so an agent can ask for a small window instead of pulling a full day or week and post-processing it.

3. Correct boundary handling
   The JSON aggregation clips sessions to the requested range and splits sessions across hourly buckets. That avoids the agent having to do time math itself, and avoids misleading results for sessions crossing hour/day/range boundaries.

4. Lower tokens for common summaries
   CSV is smaller row-for-row, but for questions like “top apps/sites today” the JSON summary can return already-aggregated rows with numeric durations. That can be much smaller than exporting every session and asking the model to aggregate.

5. Typed, stable fields
   JSON gives agents stable keys like durationSeconds, startTime, endTime, type, identifier, and isActive. CSV is parseable, but clients have to handle escaping, headers, duration strings, and schema assumptions themselves. Totally fine for spreadsheets, but less ideal for repeated tool calls.

So I’d frame the use cases as:

• feat: add CSV export #69 CSV: export/import, spreadsheets, offline analysis, human-friendly data portability.
• Add JSON MCP tools for richer usage queries #70 JSON tools: live/local agent workflows, precise time-window queries, current activity, summaries, timelines, and structured automation.

I do understand the concern about MCP/API surface area. If you’d prefer fewer tools, I’d be happy to simplify the shape. For example, we could consolidate around a smaller set like:

• get_usage_range
• get_raw_sessions
• get_current_activity

and potentially fold daily/hourly summaries into parameters rather than separate tools.

But I do think structured JSON is still worth having for the agent use case. It is less about replacing CSV export and more about avoiding “export a big file, then parse it” as the default interaction model for agents.

[renjfk]

Thanks, I understand the query use cases better now. The part I am still trying to pin down is the JSON-specific need.

Most examples seem to require query semantics, not necessarily JSON; active/current sessions, arbitrary ranges, clipping and optional aggregation. Those could also be returned as compact CSV/plain text.

Is the concrete use case that you want to pipe this into jq or another deterministic automation client? Or is there a specific MCP client that handles JSON text materially better than CSV/plain text? If the consumer is primarily an LLM agent, I am not yet seeing why compact CSV/range output would not cover the same use cases with lower token and tool-surface cost.

One more point on current/live activity; I am not sure it is as useful in a normal interactive agent workflow as it first sounds.

From the current tracking lifecycle, app sessions are ended when the active app changes and website sessions are ended when the detected domain changes or no website is detected. So if the user switches to Claude Desktop, ChatGPT, Cursor or another MCP client to ask "what am I doing right now?", the active SimplyTrack session is likely to become that AI client itself.

That makes get_current_activity useful mostly for passive/background monitoring, but less useful for the common user-triggered question flow. For SimplyTrack's core purpose, recent historical context like "last 90 minutes" or "this afternoon" seems more valuable than an in-flight session that may just reflect the assistant window.