曼特卡托
直接连接到您的分析平台 鲜味 PostgreSQL数据库。提供 Vite+React仪表板一 FastAPI后端一 45命令Python命令行界面一 41工具MCP服务器和a JavaScript跟踪器 --因此，您可以从浏览器、终端或人工智能代理中探索您的数据。
快速开始
git clone https://github.com/g-battaglia/mantecato-analytics.git
cd mantecato-analytics
# Configure
cp .env.example .env
# Edit .env — add DATABASE_URL (your Umami DB) and SESSION_SECRET
# Frontend
cd frontend && npm install && npm run dev
# Backend
cd backend && uv run uvicorn app.main:app --port 8100 --reload仪表板在以下位置打开 http://localhost:4180 （使用您的Umami凭据登录）。 API运行于 http://localhost:8100.
API密钥
CLI、MCP服务器和AI代理集成所需：
- 打开仪表盘→ 设置→ API密钥
- 点击 新钥匙 并复制密钥(
mtk_...) - 添加到
.env:MANTECATO_API_KEY=mtk_...
______________________________________________________________________
建筑
core/ mantecato-core — shared query engine, DB, filters (no framework deps)
backend/ mantecato-backend — FastAPI REST API
cli/ mantecato-cli — 45-command terminal interface
mcp/ mantecato-mcp — 41-tool MCP server (stdio + HTTP)
frontend/ Vite 6 + React 19 SPA
packages/tracker/ @mantecato/tracker — JS tracking script (Umami-compatible)所有查询都在 core/mantecato_core/queries/ -由API、CLI和MCP服务器共享。没有ORM——使用asyncpg的原始SQL。
曼特卡托是 只读 根据您的Umami数据库。仅写入到内部表（API键、保存的视图、仪表板、注释）。
______________________________________________________________________
网络仪表盘
15个分析页面加上一个自定义仪表板构建器：
| 第页 | 描述 |
|---|---|
| 概述 | 页面浏览量、访问者、跳出率、时间序列、顶部、频道、活动 |
| 页面 | 每页浏览量、页面停留时间、进入/退出、跳出率 |
| 来源 | 推荐人、UTM参数、渠道、点击ID |
| 事件 | 具有属性细分的自定义事件指标 |
| 会话 | 会话列表，按事件回放完整事件 |
| 设备 | 浏览器、操作系统、设备类型、屏幕大小、语言 |
| 地理 | 带有交互式世界地图的国家/地区/城市 |
| 实时 | 实时活跃访客和活动流 |
| 比较 | 同期对比 |
| 保留 | 队列保留矩阵 |
| 漏斗 | 具有下降率的多步转换 |
| 旅程 | 用户路径桑基图 |
| 收入 | 收入汇总、时间序列、细分 |
| 参与 | 会话持续时间分布和百分位数 |
| 仪表盘 | 具有PDF/PNG导出功能的自定义小部件仪表板 |
机器人检测
智能三层机器人检测：已知的UA模式、空用户代理和统计集群检测（按国家+设备对会话进行分组，标记跳出率>90%的高容量组）。可在设置中按站点配置。
______________________________________________________________________
命令行界面
cd cli
# Full analytics report
uv run mantecato report --site mysite.com --period 30d
# Filtered to mobile traffic
uv run mantecato report --site mysite.com -p 30d --filter device:eq:mobile
# JSON output for programmatic use
uv run mantecato stats --site mysite.com -p 90d -f json
# Conversion funnel
uv run mantecato funnel --site mysite.com --steps "/,/pricing,/signup"
# Individual queries with filters
uv run mantecato pages --site mysite.com --filter referrer_domain:contains:google
uv run mantecato devices --site mysite.com --dimension browser --filter country:eq:US全局选项： -s , -p , --filter , -f json|table|csv, -l , -g
筛选器语法： column:operator:value --16列×6个运算符。可重复。
45个命令，涵盖分析查询、CRUD操作、配置管理和终端UI。完整参考： docs/cli.md
______________________________________________________________________
MCP服务器
41个AI代理集成工具。支持 标准 （当地）和 超文本传输协议 （远程）运输。
本地（stdio）——克劳德桌面、克劳德代码、光标等。
{
"mcpServers": {
"mantecato": {
"command": "uv",
"args": ["run", "--directory", "/path/to/mantecato/mcp", "mantecato-mcp"],
"env": {
"DATABASE_URL": "postgresql://...",
"MANTECATO_API_KEY": "mtk_...",
"PYTHONPATH": "/path/to/mantecato/core"
}
}
}
}远程（HTTP）--Claude.ai，远程代理
MCP服务器可以部署为具有OAuth 2.0身份验证的HTTP服务：
# Start HTTP server
cd mcp && PYTHONPATH=../core DATABASE_URL=... MCP_API_KEY=... \
uv run mantecato-mcp --transport http --port 8200从任何MCP客户端连接：
{
"mcpServers": {
"mantecato": {
"url": "https://your-deployment.example.com/mcp",
"headers": { "Authorization": "Bearer " }
}
}
}对于Claude.ai，请通过以下方式添加 设置→ 集成→ 添加自定义连接器 使用OAuth客户端ID和客户端密钥。
完整工具参考： docs/mcp-server.md
______________________________________________________________________
追踪器
@mantecato/tracker --轻量级JavaScript跟踪脚本，与Umami兼容 /api/send 终点。
或者以编程方式使用：
import { createTracker } from '@mantecato/tracker';
const tracker = createTracker({
websiteId: 'your-site-uuid',
baseUrl: 'https://your-instance.com',
});
tracker.pageview();
tracker.event('button_click', { variant: 'cta' });
tracker.revenue(29.99, 'USD');______________________________________________________________________
码头工人
cp .env.example .env
# Edit .env with DATABASE_URL and SESSION_SECRET
docker compose up -d --build仪表板位于 http://localhost:4180，API，网址： http://localhost:8100.
# CLI via Docker
docker compose --profile cli run --rm cli report --site mysite.com -p 30d
# MCP server via Docker
docker compose --profile mcp run --rm mcp适用于Docker Desktop、Apple Containers、Podman或任何符合OCI标准的运行时环境。
生产指南： ****
______________________________________________________________________
AI代理设置
适用于 克劳德代码, Claude.ai, 克劳德桌面版, 开源代码, 克莱恩, 光标，以及任何兼容MCP的客户端。
| 模式 | 最适合 |
|---|---|
| 命令行界面 | 任何具有shell访问权限的代理--run cd cli && uv run mantecato |
| MCP （标准） | 本地代理——通过stdin/stdout进行结构化工具调用 |
| MCP（HTTP） | 远程代理——部署为具有承载身份验证的HTTP服务 |
Claude Code包含4个斜线命令： /analytics, /traffic-report, /content-audit, /funnel-analysis.
看 docs/ai-agents.md 针对特定平台的设置。
______________________________________________________________________
文档
______________________________________________________________________
技术栈
| 层 | 技术 |
|---|---|
| 前端 | Vite 6+React 19+React路由器7 |
| 造型 | 尾风CSS 4+沙纹/ui+根 |
| 图表 | Recharts，反应简单的地图，d3 sankey |
| 数据 | TanStack查询+TanStack表（虚拟化） |
| 状态 | 状态 |
| 后端 | FastAPI+Uvicorn+asyncpg |
| CLI | 打字机+丰富+文本 |
| MCP | MCP Python SDK（标准输入+流式HTTP） |
| 跟踪器 | TypeScript、ESM+CJS+UMD |
| 数据库 | PostgreSQL（直接异步，无ORM） |
| Auth | JWT会话（web）、SHA-256 API密钥（CLI/MCP）、OAuth 2.0（远程MCP） |
许可证
版权所有（c）2025贾科莫·巴塔利亚
该项目根据 GNU Affero通用公共许可证v3.0 （AGPLv3）。看 许可证 全文。
这意味着什么
- 你可以 自由安装、使用和修改 Mantecato用于任何目的
- 如果将其修改并部署为网络服务，则必须 分享您的更改 AGPLv3下
- 你 不能 在没有商业许可的情况下将其合并到专有软件中
商业/双重许可
A. 商业许可证 适用于需要在专有产品中嵌入Mantecato、在不披露源代码的情况下部署修改版本或获得自定义安装和支持的组织。
联系 giacomo@mantecato.com 用于许可和自定义部署选项。