Skip to content

Add analytics MCP app (embedded dashboard) + tasks_analytics MCP tool #1563

Description

@legreffier

Summary

Add an analytics MCP app — an embedded MCP Apps surface that renders the
agent-work-analytics dashboard inside an MCP host (e.g. a chat client), reusing
the shared <AnalyticsBoard> React component shipped in #1551.

This is the deferred MCP-app follow-up to #1373 / #1551. #1551 delivered the
reusable analytics UI (@moltnet/task-ui) and the Console integration; the design
explicitly scoped the MCP app as a follow-up built on the exported AnalyticsBoard.

Background

The one surface still missing is the MCP app, so an agent/human interacting
through an MCP host can pull up the same analytics without the Console.

Key constraint: MCP apps use tools, not REST

MCP apps never receive a bearer token or call REST directly — the iframe reads
data through the host bridge via app.callServerTool({ name, arguments })
against deterministic MCP server tools (see apps/mcp-server/src/task-app.ts:
"The iframe never receives a bearer token or talks to REST directly").

#1550 added only the REST endpoint — there is no analytics MCP tool yet. So
this issue has two cohesive parts (the app is inert without the tool → one PR).

Scope

1. MCP server tool tasks_analytics_activity

  • New deterministic tool in apps/mcp-server wrapping
    @moltnet/task-analytics-service.getActivityAnalytics.
  • TypeBox input schema mirroring the REST query: completedAfter, completedBefore,
    tags, taskTypes, profileIds, diaryIds, claimedByAgentIds, groupBy
    (none|day|tag|taskType|profile|diary|agent|providerModel).
  • Team scope resolved from the MCP session (not an x-moltnet-team-id header).
  • Returns TaskActivityAnalyticsResponse (same shape as the REST endpoint /
    the generated client / @moltnet/task-ui's type).
  • Register in the legreffier MCP tool surface; add to the tool-schema tests.

2. Analytics MCP app libs/analytics-mcp-app (React)

Mirrors libs/entry-explore-mcp-app (the existing React MCP-app precedent —
task-mcp-app is vanilla DOM and can't render the React AnalyticsBoard):

  • metadata.tsANALYTICS_MCP_APP_NAME = 'moltnet_task_analytics', _TITLE,
    _RESOURCE_URI = 'ui://moltnet/tasks/analytics.html'.
  • main.tsxcreateRoot<AnalyticsApp/>.
  • AnalyticsApp.tsxuseApp from @modelcontextprotocol/ext-apps/react; seed
    filters from the ontoolinput opener payload; call tasks_analytics_activity
    via a typed callTool; map the tool JSON result → TaskActivityAnalyticsResponse;
    render <AnalyticsBoard> (from @moltnet/task-ui) under MoltThemeProvider.
    Owns the explicit loading/error/empty/ready status mapping (same logic as the
    Console TaskAnalyticsPage).
  • adapter/tool-caller.ts + tool-calls.ts (typed callTool for
    tasks_analytics_activity, snake_case args mirroring the server schema) +
    mcp-adapter.ts (camelCase filters → snake_case args; result JSON → response
    type). Unit tests mirroring entry-explore-mcp-app/src/adapter/*.test.ts.
  • theme-tokens.ts, styles.css, index.ts (re-exports metadata constants),
    singlefile vite.config.ts, tsconfigs, package.json
    (react/react-dom + @modelcontextprotocol/ext-apps + @moltnet/task-ui +
    @themoltnet/design-system).
  • Registration: apps/mcp-server/src/analytics-app.ts (mirror task-app.ts /
    entry-explore-app.ts) serving the built HTML resource, plus
    apps/mcp-server/__tests__/analytics-app.test.ts.

Reuse / non-goals

Acceptance criteria

  • tasks_analytics_activity MCP tool returns a valid TaskActivityAnalyticsResponse
    for the caller's team, honouring all filters + groupBy.
  • libs/analytics-mcp-app renders <AnalyticsBoard> with real data pulled
    through the host bridge, across loading/error/empty/ready states.
  • Registered + served by mcp-server; opener tool seeds initial filters.
  • Adapter + tool unit tests; mcp-server registration test.
  • lint, typecheck, test, build green for the new lib + mcp-server.

References

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions