# DMAP-AI MCP server

The service exposes the existing FastMCP tools at `/mcp/` and a private owner analytics API at `/admin/analytics/`. Analytics uses one final SQLite row per meaningful analytical tool invocation. A returned `{ "ok": false }` result and a raised exception are failures; protocol discovery, health traffic, and `debug_ping` are not counted.

## Local development

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements-dev.txt
Copy-Item .env.example .env
python -m pytest -q
$env:DMAP_ANALYTICS_MARK_TEST_TRAFFIC='true'
uvicorn server:app --host 127.0.0.1 --port 8001
```

SQLite is automatically initialized. It uses WAL, foreign keys, a five-second busy timeout, short transactions, parameterized SQL, and indexes for time, tools, status, identifiers, and mapped locations. Timestamps are UTC. Dashboard queries default to `America/Chicago` but accept any installed IANA timezone.

## Configuration

- `DMAP_ANALYTICS_DB_PATH`: SQLite path; local default `data/analytics.sqlite3`. Production should use a persistent directory outside the Git checkout.
- `DMAP_ANALYTICS_HASH_SECRET`: long random server-only HMAC secret. Changing it breaks identifier continuity. It is not used to invent identifiers.
- `DMAP_ANALYTICS_ADMIN_SUBS`: comma-separated Auth0 `sub` allowlist. Never expose this in frontend code.
- `DMAP_ANALYTICS_MARK_TEST_TRAFFIC`: marks newly captured events as test traffic.
- `DMAP_ANALYTICS_ALLOWED_ORIGINS`: comma-separated exact production/development CORS origins.
- `AUTH0_DOMAIN`: Auth0 tenant domain without a scheme.
- `AUTH0_AUDIENCE`: expected API audience.
- `DMAP_API_BASE`: existing DMAP analysis backend base URL.

Every analytics route validates an Auth0 RS256 token through JWKS, issuer, audience, and expiration. Authorization requires `read:dmap-analytics` in `permissions` or `scope`, or an exact subject in the server-only allowlist. Private responses use `Cache-Control: no-store`.

The current MCP service is stateless and does not authenticate callers, so it has neither a server-issued stable session identifier nor a verified end-user subject. `session_hash` and `user_hash` therefore remain null, and the dashboard reports Estimated Sessions, Authenticated Users, and Active Sessions as **Unavailable**. It never derives identity from IP address or user agent.

## Historical import

The importer accepts journal CSV columns `timestamp,service,priority,pid,message`, ignores repeated headers and discovery traffic, imports only known tool names supported by reliable evidence, redacts `api_key` query values before deduplication, and stores neither messages nor URLs.

```powershell
python scripts\import_journal_csv.py C:\path\to\dmap_ai_mcp_logs_30days.csv --dry-run
python scripts\import_journal_csv.py C:\path\to\dmap_ai_mcp_logs_30days.csv
python scripts\import_journal_csv.py C:\path\to\test_logs.csv --mark-test
```

Repeated imports are idempotent through a SHA-256 source-event fingerprint. Historical logs never produce user or session counts.

## Production deployment outline

Use the server's existing deployment method after backup and approval. Set `DMAP_ANALYTICS_DB_PATH` to a persistent path such as `/var/lib/dmap-ai-mcp/analytics.sqlite3`, create that directory owned by the systemd service user, install `requirements.txt`, and restart `dmap-ai-mcp`. Do not put secret values on a command line or in Git; place them in the existing protected environment file.

Before upgrade, stop writes briefly if required by the current deployment and back up SQLite with its online backup command:

```bash
sqlite3 /var/lib/dmap-ai-mcp/analytics.sqlite3 ".backup '/var/backups/dmap-ai-mcp/analytics-$(date -u +%Y%m%dT%H%M%SZ).sqlite3'"
```

Rollback consists of restoring the prior Git commit/virtual environment according to the existing service procedure, restoring the environment file backup, and restarting the service. The schema is additive; keep the database backup even when application code is rolled back.

Recommended retention is 13 months for aggregate trend comparison, reviewed against actual volume and policy. No automatic deletion is enabled. Back up the database before any deliberate purge and delete in bounded UTC ranges.