# WORKSPACE — MCP + A2A Use-Case Catalog

## Goals

- Identify **high-leverage** MCP tools/resources and A2A agent workflows across the ByteLyst workspace.
- Provide a **prioritized backlog** that maps cleanly onto existing services:
  - `platform-service` (telemetry, diagnostics, jobs, settings, auth, webhooks, etc.)
  - `extraction-service` (structured extraction, async jobs)
  - dashboards (admin/tracker)
  - shared packages + mobile SDKs
  - product repos (ChronoMind, NomGap, PeakPulse, MindLyst, JarvisJr, LysnrAI)

## What “MCP” and “A2A” mean in this workspace

- **MCP server**: exposes authoritative product/platform capabilities as tools/resources.
  - Tools should map to stable APIs (prefer calling service endpoints / repositories rather than scraping UI).
  - Resources should expose read-mostly context: schemas, runbooks, current status, recent incidents, etc.
- **A2A**: multiple specialized agents collaborating via explicit contracts.
  - Example: _Support agent_ → _Triage agent_ → _Diagnostics agent_ → _Fix agent_ → _Release agent_.

## Reality check: “exists today” vs “proposed tool surface”

- **Backed by existing services today**
  - Telemetry query/clusters/policies (platform-service)
  - Telemetry client config (`GET /api/telemetry/config`, ETag-based)
  - Diagnostics sessions + ingest (platform-service)
  - Extraction extract/batch/jobs/health (extraction-service)
  - Jobs/flags/settings/webhooks endpoints (platform-service)
- **Proposed tools that may require new endpoints or privileged integrations**
  - `secrets.rotate(...)`, `services.restart(...)` (depends on Key Vault/infra integration)
  - UX-lab dataset generators (`dev.generateTelemetryDataset(...)`) (local-only helper tooling)
  - Compound tools like `support.createDebugPack(...)` (implemented in MCP layer as orchestration)

## Prioritization rubric

- **P0**: removes constant manual toil; immediate engineering impact.
- **P1**: unlocks new ops / reliability capabilities.
- **P2**: enables new product intelligence / automations.
- **P3**: experimental / UX labs.

## P0 — Highest leverage (do first)

### 1) Incident / Support “one-click evidence” pack (Telemetry + Diagnostics)

- **Why**
  - You already have rich primitives: `telemetry` (clusters + policies) and `diagnostics` (remote sessions).
  - The missing piece is automated _assembly_ of a support-ready packet.
- **MCP tools**
  - `telemetry.queryEvents(filters)`
  - `telemetry.listClusters(filters)`
  - `telemetry.updateClusterStatus(clusterId, pk, status)`
  - `diagnostics.createSession(targetUserId|targetAnonymousId|targetDeviceId, config)`
  - `diagnostics.getSession(sessionId)`
  - `diagnostics.getLogs(sessionId, filters)`
  - `diagnostics.getTraces(sessionId, filters)`
  - `diagnostics.listScreenshots(sessionId)`
- **A2A agents**
  - **SupportTriageAgent**: extracts identifiers from user report (email/userId/anonymousInstallId, appVersion). (Maps to `targetAnonymousId` for diagnostics.)
  - **TelemetryAnalystAgent**: pulls clusters + timelines; proposes policy changes.
  - **DiagnosticsOrchestratorAgent**: starts a debug session when needed; monitors results.
  - **ReportWriterAgent**: produces a “Debug Pack” markdown/PDF.

### 2) Telemetry policy authoring assistant (safe-by-default)

- **Why**
  - Policies are powerful but easy to over-collect. Assistant can:
    - suggest targeting
    - set auto-expiry
    - choose sampling
- **MCP tools**
  - `telemetry.listPolicies()`
  - `telemetry.previewPolicy(targeting)`
  - `telemetry.createPolicy(input)`
  - `telemetry.updatePolicy(id, updates)`
- **A2A agents**
  - **PolicyPlannerAgent**: proposes policy with guardrails.
  - **PolicyReviewerAgent**: checks privacy constraints + expiry + scope.

### 3) “Ops Copilot” for platform-service modules

- **Why**
  - platform-service contains many modules (auth, flags, delivery, jobs, settings, maintenance, etc.).
  - Most ops tasks are combinations of a few actions (query, toggle, trigger job).
- **MCP tools**
  - `jobs.list()` / `jobs.trigger(name)` / `jobs.listRuns(name)`
  - `maintenance.get()` / `maintenance.set(mode, schedule)`
  - `flags.list()` / `flags.set(key, enabled, targeting)`
  - `settings.get(userId)` / `settings.set(userId, patch)`
  - `webhooks.listSubscriptions()` / `webhooks.test()` / `webhooks.rotateSecret()`
- **A2A agents**
  - **OpsAgent**: executes operations.
  - **ComplianceAgent**: ensures audit trail + least privilege.

### 4) Extraction service “task builder” and evaluation loop

- **Why**
  - extraction-service already has model registry, caching, async jobs, sidecar health.
  - Task prompts/examples are high leverage; building & evaluating them is repetitive.
- **MCP tools**
  - `extraction.extract(text, taskId, modelId)`
  - `extraction.extractBatch(inputs)`
  - `extraction.submitJob(inputs, webhookUrl?)`
  - `extraction.getJob(jobId)`
  - `extraction.sidecarHealth()`
  - `extraction.metrics()` / `extraction.cacheStats()`
- **A2A agents**
  - **TaskDesignerAgent**: drafts taskPrompt + examples.
  - **EvalRunnerAgent**: runs eval sets, compares outputs.
  - **PromptRegressionAgent**: ensures no quality regressions.

## P1 — Operational maturity

### 5) Automated regression watch: telemetry clusters → auto diagnostics session

- **Why**
  - telemetry clusters already have severity escalation + webhook alerts.
  - diagnostics supports remote sessions.
- **Flow**
  - Cluster crosses threshold → A2A triggers a targeted diagnostics session for a small segment.
- **MCP tools**
  - `telemetry.listClusters()`
  - `diagnostics.createSession(...)`

### 6) Secret rotation “assistant” (Key Vault + config propagation)

- **Why**
  - Secrets already resolved centrally via `@bytelyst/config`.
  - Rotation is still error-prone across services/dashboards.
- **MCP tools/resources**
  - Resource: `secrets.mapping` (which env vars resolve which AKV secrets)
  - Tool: `secrets.rotate(name)` (where permitted) + `services.restart(service)` (optional)

### 7) Webhook subscription lifecycle assistant

- **Why**
  - You have webhooks + delivery logs; assistants can recommend retries, disable rules, test endpoints.
- **MCP tools**
  - `webhooks.listSubscriptions(productId)`
  - `webhooks.listDeliveries(subscriptionId)`
  - `webhooks.rotateSecret(subscriptionId)`
  - `webhooks.test(subscriptionId)`

## P2 — Product intelligence and automation

### 8) A/B experimentation assistant (platform-service `ab-testing`, `experiments`)

- **Use**
  - Draft experiment plan, compute exposure targeting, monitor telemetry signals.

### 9) “Changelog writer” from merged PRs + telemetry impact

- **Use**
  - Collect changes; relate to drop in cluster counts; propose release notes.

## P3 — UX-lab accelerators

### 10) MCP-driven UX Lab data generators

- **Why**
  - UX lab apps (telemetry explorer, ops UI kit) need rich sample datasets.
- **MCP tool**
  - `dev.generateTelemetryDataset(shape, size, seed)`

## Key findings from product code scan (2026-03-05)

See [`DOMAIN_PRODUCTS.md`](./DOMAIN_PRODUCTS.md) for the full per-product breakdown.

**Critical cross-product gap found:**

- `@bytelyst/diagnostics-client` is **not initialised in any of the 6 product apps**.
  - Adding it to each app's bootstrap is the cheapest MCP win: it immediately enables `SupportTriageAgent` to start remote debug sessions from a single tool call — no per-product code beyond a one-line init.

**Extraction pipeline gaps found:**

- **LysnrAI**: `TranscriptDoc.extractions[]` + `extractedAt` fields exist in schema but are **not reliably populated** — the extraction pipeline needs a backfill agent.
- **ChronoMind**: `nl-parser.ts` is a local 13 KB rule engine — good candidate for an extraction task (`nl-timer-parse`) to enable server-side model improvement + eval loop.

**New P0 additions from scan:**

### 11) LysnrAI transcript extraction backfill

- **Why**: `TranscriptDoc` already has `extractions[]`, `extractionMetadata`, `extractedAt`. The fields are empty for most historical transcripts.
- **MCP tool**: `lysnrai.transcripts.runExtraction(transcriptId)`
- **A2A agent**: `TranscriptExtractionPipelineAgent` — batch queries `extractedAt IS NULL`, calls extraction-service, updates docs.

### 12) Diagnostics-client bootstrap for all product apps

- **Why**: Enables SupportTriageAgent for all 6 products with near-zero per-product work.
- **Action**: Add `DiagnosticsClient.getInstance({...}).start()` in each app's layout/main bootstrap.
- **Products**: ChronoMind (`web/src/app/layout.tsx`), NomGap (`src/app/_layout.tsx`), MindLyst (`mindlyst-native/web/src/app/layout.tsx`), JarvisJr (`web/src/app/layout.tsx`), LysnrAI (`user-dashboard-web/src/app/layout.tsx`), PeakPulse (iOS `PeakPulseApp.swift`).

## Cross-product patterns that MCP/A2A should standardize

- **Telemetry**
  - Common event naming + “productId is mandatory” invariant.
- **Kill switch**
  - Single check path; consistent failure mode (fail-open).
- **Extraction**
  - Task IDs used consistently across products (triage, reflection, insights, etc.).
- **Workflows**
  - Release/build/test workflows can become A2A playbooks using MCP tools.
