Dmap Ai Mcp Server

DMAP-AI MCP 服务

该服务在 /mcp/ 提供现有的 FastMCP 工具，并在 /admin/analytics/ 提供仅供所有者使用的分析 API。每次有意义的分析工具调用都会在分析数据中生成一条最终 SQLite 记录。返回 { "ok": false } 的结果和抛出的异常均视为失败；协议发现、健康检查流量和 debug_ping 不计入统计。

本地开发

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 会自动初始化。它使用 WAL、外键、五秒忙碌超时、短事务、参数化 SQL，以及针对时间、工具、状态、标识符和映射位置创建的索引。时间戳使用 UTC。仪表板查询默认使用 America/Chicago，但也接受任何已安装的 IANA 时区。

配置

• DMAP_ANALYTICS_DB_PATH：SQLite 路径；本地默认值为 data/analytics.sqlite3。生产环境应使用 Git 工作区之外的持久化目录。
• DMAP_ANALYTICS_HASH_SECRET：仅供服务器使用的长随机 HMAC 密钥。更改后会中断标识符的连续性。该密钥不会用于臆造标识符。
• DMAP_ANALYTICS_ADMIN_SUBS：以逗号分隔的 Auth0 sub 许可名单。切勿在前端代码中公开。
• DMAP_ANALYTICS_MARK_TEST_TRAFFIC：将新捕获的事件标记为测试流量。
• DMAP_ANALYTICS_ALLOWED_ORIGINS：以逗号分隔的精确生产／开发 CORS 来源。
• AUTH0_DOMAIN：不带协议的 Auth0 租户域名。
• AUTH0_AUDIENCE：预期的 API 受众。
• DMAP_API_BASE：现有 DMAP 分析后端的基 URL。

每个分析路由都会通过 JWKS、颁发者、受众和过期时间验证 Auth0 RS256 令牌。授权要求 permissions 或 scope 中包含 read:dmap-analytics，或令牌主题与仅供服务器使用的许可名单中的条目完全匹配。私有响应使用 Cache-Control: no-store。

当前 MCP 服务是无状态的，且不会对调用者进行身份验证，因此既没有由服务器签发的稳定会话标识符，也没有经过验证的最终用户主题。因此，session_hash 和 user_hash 均保持为空，仪表板会将 Estimated Sessions、Authenticated Users 和 Active Sessions 显示为 Unavailable。它绝不会根据 IP 地址或用户代理推断身份。

历史数据导入

导入器接受包含 timestamp,service,priority,pid,message 列的日志 CSV，会忽略重复表头和发现流量，仅导入有可靠证据支持的已知工具名称，在去重前会对 api_key 查询参数值进行脱敏，并且不会存储消息或 URL。

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

通过 SHA-256 源事件指纹，重复导入具有幂等性。历史日志不会生成用户或会话计数。

生产部署概述

备份并获得批准后，使用服务器现有的部署方法。将 DMAP_ANALYTICS_DB_PATH 设置为持久化路径，例如 /var/lib/dmap-ai-mcp/analytics.sqlite3；创建由 systemd 服务用户拥有的该目录，安装 requirements.txt，然后重启 dmap-ai-mcp。不要在命令行或 Git 中放置密钥值；请将其存放在现有的受保护环境文件中。

升级前，如当前部署需要，请短暂停止写入，并使用 SQLite 的在线备份命令进行备份：

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

回滚时，按照现有服务流程恢复之前的 Git 提交／虚拟环境，恢复环境文件备份，然后重启服务。架构采用增量扩展；即使回滚了应用代码，也要保留数据库备份。

建议保留 13 个月，以便比较汇总趋势，并根据实际数据量和政策进行审查。目前未启用自动删除。进行任何有意清理前，请先备份数据库，并按有界的 UTC 日期范围删除数据。