DMAP AI 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

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.

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:

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.