# analytics-node

Local privacy-first analytics MCP server for agent usage analytics.

It imports metadata from local client files (Codex, Copilot, Claude, hook log), stores normalized data in a local SQLite DB, and exposes query tools for operational insight.

## Features

- Incremental scan/import with source-specific adapters.
- Runtime event normalization (`mcp`, `skill`, `hook`) without storing prompt/response payloads.
- Query tools with pagination and filters (`summary`, `models`, `sessions`, `events`).
- Imported-data cleanup workflow with dry-run/confirm (`analytics_delete_imported`).
- Privacy guardrails by design (no credentials/token parsing, no raw chat content persistence).

## Tool surface

- `analytics_status`: DB status and high-level counters.
- `analytics_scan`: import/refresh analytics from one or more sources.
- `analytics_summary`: aggregated counters by source/project/model/date.
- `analytics_models`: model usage metrics.
- `analytics_sessions`: session-level listing and totals.
- `analytics_events`: normalized runtime events listing.
- `analytics_delete_imported`: two-step deletion of imported rows (DB only).

## Supported sources

Core sources:

- `codex`
- `copilot`
- `claude`
- `hook_log`
- `client_surface` distinguishes variants (`cli`, `vscode`, `vscode_insiders`, `code`, `desktop`, `unknown`)

## Privacy and security constraints

- No prompt text, response text, or raw payload persistence.
- No credential/token parsing (`*token*`, `*auth*`, credential-like files are skipped).
- No OAuth/auth store reads (including VS Code/Copilot auth stores).
- Path disclosure is minimized in tool outputs and warnings.

## Configuration

Only supported env:

- `ANALYTICS_DB_PATH`

Default DB path:

- `~/.mcp-servers/analytics/analytics.sqlite`

Derived hook log path:

- `dirname(ANALYTICS_DB_PATH)/hooks/events.jsonl`

## Build and tests

- `npm run build`
- `npm run test`
- `npm run smoke`

## Scan behavior

`analytics_scan` is explicit only (no auto-scan at MCP startup).

- `dry_run=true`: planning/check mode, no writes.
- `dry_run=false`: real import/update.
- `force=true`: bypass incremental skip policy when reimport is required.
- Prefer source-targeted scans over full scans.

Recommended order:

1. `analytics_status`
2. read-only queries (`analytics_summary`, `analytics_models`, `analytics_events`, `analytics_sessions`)
3. `analytics_scan` only when stale/missing data is detected

## Delete imported data (M9)

`analytics_delete_imported` removes imported analytics rows from the local SQLite DB only.

Guardrails:

- Never deletes original client files (Codex/Copilot/Claude/hook logs).
- Requires dry-run/confirm two-step flow for real deletion.
- Fails with `DELETE_PLAN_CHANGED` if matched set changes between plan and execution.
- Tracks operations in `delete_runs`.

Flow:

1. Plan (`dry_run=true`, default) -> returns `delete_plan_id` and matched counters.
2. Execute (`dry_run=false`, `confirm_delete=true`, `confirm_plan_id=<id>`).

Filters:

- `sources[]`
- `client_surfaces[]` (`cli`, `desktop`, `vscode`, `vscode_insiders`, `code`, `unknown`)
- `session_kinds[]` (`main`, `subagent`, `task`, `unknown`)
- `date_from/date_to` (ISO)
- or `period_type + period_value` (`day|month|year`)
- date and period filters are mutually exclusive.

Scopes:

- `all` (default)
- `sessions`
- `runtime_events`
- `source_files` (orphans only; warning `SOURCE_FILE_STILL_REFERENCED` when still linked)

## Integration notes

- `genera_mcp_json.sh` / `genera_mcp_json.ps1` include `analytics-mcp-server`.
- Generators propagate only `ANALYTICS_DB_PATH` when set.
- Codex hooks generator passes `--analytics-db-path` with safe Windows quoting.

## Hook log behavior

`hook_log` imports runtime events from `hooks/events.jsonl` (next to DB path).

- Produces `runtime_events` only.
- Does not create `sessions` or message content rows.
- `McpHint` is treated as hook hint (`event_type='hook'`), not real MCP usage.
- `SkillHint` is tracked as skill hint event.

## Skill operativa

- Primary skill: `mcp-analytics-operator`
- Path: `skills/mcp-analytics-operator/SKILL.md`
- References:
  - `skills/mcp-analytics-operator/references/analytics-workflow.md`
  - `skills/mcp-analytics-operator/references/privacy-rules.md`
  - `skills/mcp-analytics-operator/references/deletion-playbook.md`

Read-only workflow:

1. `analytics_status`
2. `analytics_summary`
3. `analytics_models`
4. `analytics_events`
5. `analytics_sessions` only if session-level detail is required

## Troubleshooting (Windows/Ubuntu)

- DB unavailable: verify `ANALYTICS_DB_PATH` and directory permissions.
- Missing sessions/models/events: run targeted `analytics_scan` on the specific source and inspect warnings.
- Missing tokens: if native token counters are not present in source logs, token values remain unavailable (no estimation).
- Missing hook events: verify Sophia hooks are writing `events.jsonl` near analytics DB.
- Parser/source-format warning: treat as adapter-format warning and avoid forcing unsafe import.
- Delete blocked by plan mismatch: rerun dry-run and use the new `confirm_plan_id`.

## Smoke tests

Unified smoke coverage is maintained under `/tests` (single consolidated analytics smoke file for milestone progression).