Vitrus analytics

dev.vitrusv0.6.0更新於 Oct 7, 2026

Read-only web analytics — AI traffic, revenue, goals, funnels — with the SQL behind every number.

已驗證Streamable HTTP可網頁執行Data & Analytics Web Search & Scraping

概覽

AI 產生的概覽

針對 Vitrus 工作區的唯讀網站分析：流量、AI 轉介、營收、目標、漏斗、留存與 Web Vitals，每個數字都附上產生它的 SQL。

功能: 透過 HTTP 將助理連接到 Vitrus 分析工作區，提供 15 個唯讀工具，包括 query_stats（依 20 個維度之一或依日期查詢任意指標，可加篩選）、get_realtime、get_ai_traffic、get_revenue、goal_report、analyze_funnel、get_journeys、get_retention、get_web_vitals、get_errors 與 get_digest。每項指標都以證據記錄的形式回傳，內含 SQL、參數、時間範圍與數值，因此助理可以引用查詢，而不是憑空斷言。連線僅限單一工作區。
適用情境: 適合讓助理回答關於自家網站流量、AI 助理轉介、營收、漏斗、留存或 Core Web Vitals 的問題，並顯示每個數字背後的查詢。適用於已在運作 Vitrus（託管或自架）的團隊，希望在對話中完成報表與排查，而不是打開儀表板。
執行需求: 遠端端點 OAuth（登入並選擇工作區），或使用帶有工作區 API 金鑰的 Authorization: Bearer 標頭。工作區需已有資料，且連線僅限一個工作區。

安裝前請注意

這些工具被描述為唯讀，助理不應修改分析資料。存取透過 OAuth 或工作區 API 金鑰授予；請將該金鑰視為機密，外洩時立即撤銷。可在 Account 的 Connected apps 中斷連線。此服務為託管服務，分析資料會傳送到第三方，而非留在本機。

安裝

在 SourceWeft 中

開啟儀表板中的 Vitrus analytics，將其新增到工作區。
為需要使用其工具的對話啟用該服務。

Web executable，透過 Streamable HTTP。遠端服務在工作區中設定後即可從網頁執行環境執行。

其他 MCP 客戶端

把它新增到你客戶端的 mcpServers 設定中。

{
  "mcpServers": {
    "analytics": {
      "type": "http",
      "url": "https://app.vitrus.dev/mcp"
    }
  }
}

README

[Vitrus — web analytics you can check]

Open-source, cookie-free web analytics. Every number carries the SQL that produced it —
and an AI summary can't ship a number it can't prove. One process, on your own server.

Live demo · Use with ChatGPT / Claude · Website · Cloud · Documentation · Quickstart · Compare · Changelog · Discussions

[License: Apache-2.0] [Runtime dependencies: 0] [Tracker: 2.6 KB gzipped] [Services to install: 0] [CI] [Release]

[The Vitrus dashboard in light and dark, on a demo workspace with sample data: KPIs with evidence badges, a trend against the previous period, and the deterministic digest]

Quickstart

You need Bun 1.3 or newer. That is the whole list.

bash

git clone https://github.com/Vitrus-Dev/vitrus && cd vitrusbun install && bun run build:trackeralias vitrus="bun $PWD/packages/cli/src/cli.ts"
vitrus init                                   # creates ./vitrus.db and a secret saltvitrus site add "My site" example.com         # prints your script tagVITRUS_PASSWORD="a long secret" vitrus start  # ingest + dashboard on http://localhost:3000

git clone https://github.com/Vitrus-Dev/vitrus && cd vitrusbun install && bun run build:trackeralias vitrus="bun $PWD/packages/cli/src/cli.ts"
vitrus init                                   # creates ./vitrus.db and a secret saltvitrus site add "My site" example.com         # prints your script tagVITRUS_PASSWORD="a long secret" vitrus start  # ingest + dashboard on http://localhost:3000

Then one line in your site's <head>:

No Docker Compose file, no database server, no migration step. Rather not run it? app.vitrus.dev is the same engine, hosted, with a free plan — and the live demo opens the full hosted dashboard on sample data, no account needed.

Every number opens the query that made it

Click a figure and you get the SQL that ran, its parameters, the window and the result — not a description of the number, the number's origin. It is the same evidence the AI summary is checked against.

[The unique-visitors figure opened in the evidence panel: the SQL query, its parameters, the result and the time window (demo workspace, sample data)]

That matters more now that models write the reports. When an AI-written sentence contains a number that is not in the evidence, Vitrus drops the sentence before it reaches you:

Visitors are down 18% against the previous period. [e1]The drop coincides with the last deploy. [e1, e7]✗ dropped: "The new theme caused a 41.7% fall in conversion."   → 41.7 is in no evidence record, and "caused" is a claim nobody can make from this data.

Visitors are down 18% against the previous period. [e1]The drop coincides with the last deploy. [e1, e7]✗ dropped: "The new theme caused a 41.7% fall in conversion."   → 41.7 is in no evidence record, and "caused" is a claim nobody can make from this data.

A whole analytics product

[The 3D globe with sessions at their cities] Globe. Sessions at their city, on a canvas drawn from our own geometry — no map provider, no GeoIP database.	[Real-time visitors and the live event feed] Real-time. Who is on the site now, and the latest events, streamed as they arrive.
[AI assistant referrals separated from AI crawler reads] AI traffic. Visitors ChatGPT and Claude sent you, kept apart from the crawlers that read your pages.	[An ordered funnel with drop-off] Funnels. Ordered — a step counts only after the one before it, so the conversion is not inflated.
[A Sankey of page journeys] Journeys. The paths people take, as a Sankey you can filter by start and end.	[Revenue by channel] Revenue. Per currency, never converted, attributed to where the visit began.
[Core Web Vitals at p75] Web Vitals. LCP, INP, CLS, FCP and TTFB at the percentile you choose, per page.	[A retention cohort matrix] Retention. Cohorts of identified users — and an honest blank for days that have not happened yet.

_{Screenshots: the hosted dashboard on a demo workspace; every figure is sample data — open it yourself. The self-hosted
dashboard in this repository is simpler today — see Architecture for exactly which views it renders.}

Ask your AI about your analytics

Vitrus speaks MCP. Your assistant reads your analytics — read-only — and every number it gets back comes with the query that produced it, so it can cite instead of assert. Listed in the official MCP Registry as dev.vitrus/analytics.

Where	How
ChatGPT · Claude (web & desktop)	Add a custom connector with `https://app.vitrus.dev/mcp`, sign in, pick a workspace, Allow.
Claude Code — plugin with 4 skills	`claude plugin marketplace add Vitrus-Dev/vitrus` then `claude plugin install vitrus@vitrus`
Claude Code — server only	`claude mcp add vitrus --transport http https://app.vitrus.dev/mcp`
Cursor	[Add Vitrus to Cursor]
Gemini CLI	`gemini extensions install https://github.com/Vitrus-Dev/vitrus`
Anything else	`{"type": "http", "url": "https://app.vitrus.dev/mcp"}` — OAuth, or `Authorization: Bearer vk_…` (a workspace API key)

The plugin's skills, under plugins/vitrus/skills:

/vitrus:weekly-report — last week against the week before, channels, AI assistants, goals; every figure cited.
/vitrus:traffic-drop — finds the day a number broke and the segment it lives in, then checks errors and Web Vitals.
/vitrus:measurement-plan — reads your code and proposes the events, goals, funnels and revenue calls to add.
/vitrus:ai-search-audit — which assistants send people, which pages the AI crawlers read, and where the two disagree.

15 tools, all read-only: query_stats (any metric by any of 20 dimensions or by day, with filters), get_realtime, get_ai_traffic, get_revenue, goal_report, analyze_funnel, get_journeys, get_retention, get_web_vitals, get_errors, get_digest and more — docs. Connections are scoped to one workspace and can be disconnected any time under Account → Connected apps.

What it is, in one paragraph

Vitrus tells you how many people visit your website, where they come from, what they do and where they leave. It sets no cookies, so you do not need a consent banner. Use the hosted version at vitrus.dev or run it yourself as a single program — there is no database server to install.

Features

The query behind every number. Every metric travels as { id, sql, params, window, value }, and the dashboard opens that exact SQL when you click the badge beside a figure.
AI summaries that cannot invent. Numbers come from deterministic SQL first. The optional model (local Ollama, or your own key — neither is on by default) may rephrase them and may not produce one; a numeric guard drops any sentence it cannot support, and a golden-set eval holds leaks at 0.
AI referrals ≠ AI crawlers. chatgpt.com sending a person and GPTBot reading a page are two different events, classified separately and never summed — by a versioned rule table held at 100% precision and recall by its own eval.
Which pages the crawlers read, per page — the feedback loop GEO/AEO work actually needs.
Verified agent identity. A request signed with Web Bot Auth (RFC 9421 HTTP Message Signatures) is checked against the Ed25519 key its operator publishes, so the signer can be named. A user-agent is a sentence; a signature is proof.
Agent sessions as their own class — kept out of your visitor numbers, reported separately, never silently dropped or counted as people.
Two-layer bot detection, in the open-source core. A user-agent table plus header rules that check whether a request agrees with the browser it claims to be. Recorded and shown, never self-applying: a suspicion is not a verdict.
Everything else you expect — pageviews, sessions, unique and live visitors, bounce rate, visit duration, top / entry / exit pages, referrers, channels, UTM campaigns, devices, browsers, OS, screens, languages, country, custom events with properties, outbound clicks, form submissions, field-level form abandonment, rage and dead clicks, scroll depth, ordered funnels, retention cohorts, Core Web Vitals at p75 and JavaScript errors.
Session replay, opt-in and masked. Off until you switch it on for a site, loaded as a separate script only on pages that carry data-replay, and every text node and input value masked by default. Password, card and one-time-code fields are always blocked. Recordings play in a sandboxed player in the self-hosted dashboard.
City, region and coordinates without a GeoIP database — read from the headers your proxy already sets (Cloudflare, Vercel, CloudFront), coordinates rounded to 0.1°.
Digests: what happened → why → what to do. vitrus digest writes one in your terminal, every line tagged with the evidence ids behind it. The Slack / email / webhook channels and the never-sent-twice scheduler ship in the core.
A read-only MCP server with 15 tools — any metric by any dimension, real-time, AI traffic, revenue, goals, funnels, journeys, retention, vitals, errors — that returns the evidence with every number, so an agent can cite instead of assert. On the cloud, ChatGPT and Claude connect with OAuth (add https://app.vitrus.dev/mcp, sign in, pick a workspace); Claude Code is one line: claude mcp add vitrus --transport http https://app.vitrus.dev/mcp.
Private by construction. No cookies, no stored identifier, no fingerprinting, no consent banner. Do Not Track honoured by default. A 2.6 KB tracker. Zero runtime dependencies, enforced by CI.

Deliberately absent: ad-platform attribution (ROAS/CPA) and multi-touch attribution models, because a model's opinion is not something we can prove.

Self-hosting, in more detail

The Quickstart is the whole install. Set VITRUS_PASSWORD before the port is reachable from outside: the dashboard and the read API then ask for it (HTTP Basic, any user name), while the tracker and ingest stay public because your visitors' browsers call them. Without it, vitrus start prints a warning and anyone who can reach the port can read your analytics.

Want data on screen straight away? vitrus demo <site-id> generates a realistic week of sample traffic.

bash

vitrus site ls                                        # list your sitesvitrus digest <site-id> --days 7                      # deterministic summary, in your terminalvitrus digest <site-id> --llm ollama:gemma3:4b        # phrased by a local model; data never leaves the boxvitrus start --port 8080

vitrus site ls                                        # list your sitesvitrus digest <site-id> --days 7                      # deterministic summary, in your terminalvitrus digest <site-id> --llm ollama:gemma3:4b        # phrased by a local model; data never leaves the boxvitrus start --port 8080

The database path is VITRUS_DB (default ./vitrus.db). Put Cloudflare, Vercel, Fly, CloudFront or Netlify in front and country (and, from Cloudflare, Vercel or CloudFront, region and city) is read from the headers they already set — there is no GeoIP database to download, and without a proxy the dashboard says the data is missing rather than guessing.

How it compares

The open-source alternatives are good, and several do things we do not. This table lists only differences we can state without qualification. Checked 24 September 2026 against each product's own documentation — if a cell is out of date, please open an issue.

	GA4	Plausible	Umami	Rybbit	Vitrus
Open source	✗	✓ AGPL-3.0	✓ MIT	✓ AGPL-3.0	✓ Apache-2.0
Cookie-free, no consent banner	✗	✓	✓	✓	✓
Services to install	—	Postgres + ClickHouse	Postgres or MySQL	Postgres + ClickHouse	none
Tracker size (gzipped)	~28 KB	~1 KB	~2 KB	~18 KB	2.6 KB
AI assistants as a channel	✗	✓	✓	✓	✓
Crawler reads separated from the humans they send	✗	✗	✗	✓	✓
The query behind every number, in the UI	✗	✗	✗	✗	✓
AI sentences dropped when the number is unprovable	✗	✗	✗	✗	✓
Verified agent identity (Web Bot Auth)	✗	✗	✗	✗	✓
Bot detection beyond the user-agent, in the open-source build	✗	✗	✗	✗	✓
Funnels, journeys and goals	✓	✓ (funnels on paid plans)	✓	✓	✓
Session replay	✗	✗	✓	✓	opt-in, masked by default
Public API with keys	✓	✓	✓	✓	✓ read-only
City-level geography	✓	✓	✓	✓	from proxy headers
Hundreds of millions of events a month	✓	✓	✓	✓	~1M/month per box

Where Vitrus is ahead

You can check every number. Click it and you get the query, its parameters and the rows. No other tool in this table does that.
AI summaries cannot make numbers up. A sentence whose number is not in the evidence is removed.
AI traffic, told apart properly. Visitors that ChatGPT or Perplexity sent you are one thing; the AI crawlers reading your pages are another; agents that sign their requests are verified and named.
Nothing to operate. One process and an embedded database. The others need a database server — Postgres or MySQL, and for two of them ClickHouse as well.
The privacy default is the strict one. The visitor id is re-salted every day, always.

Where others are ahead

Heatmaps — Umami has them; we do not.
Importing your history — we import from Umami only; Plausible imports Google Analytics history, and Rybbit imports Plausible exports too.
Maturity and scale. Replay, autocapture of every button click and hundreds of millions of events a month are all further along in Rybbit and Umami, which run on ClickHouse or Postgres. Our embedded database is what makes the zero-service install possible, and it is also its ceiling (about a million events a month per box).
Ad attribution. If your reporting is tied to Google or Meta ad spend, GA4 closes that loop and we never will.
Cities without a proxy. Everyone else bundles a GeoIP database; we read city and region from Cloudflare, Vercel or CloudFront headers, and show only the country otherwise.

One-page write-ups per tool: vitrus.dev/compare.

Privacy

The visitor id is a one-way hash that cannot follow anyone across days:

The salt rotates daily, the IP is never stored (IPv6 is reduced to its /64 first), and nothing is written to the browser. That is also why the retention page tells you when it cannot compute a cohort instead of showing zeros — call vitrus.identify(user.id) for signed-in users and retention becomes real, with the raw id never touching disk.

Architecture

packages/  core      ingest · classifiers · MetricBundle · numeric guard · digest · agent verifier ·            explore queries (sessions, users, journeys, goals, geo) · replay ingest + player  tracker   the browser script, 2.6 KB gzipped (+ an opt-in replay recorder, under 5 KB)  server    one process: ingest + query API + tracker + evidence dashboard  cli       init · site · start · digest · demo  mcp       read-only MCP module (JSON-RPC over HTTP) for AI agents

packages/  core      ingest · classifiers · MetricBundle · numeric guard · digest · agent verifier ·            explore queries (sessions, users, journeys, goals, geo) · replay ingest + player  tracker   the browser script, 2.6 KB gzipped (+ an opt-in replay recorder, under 5 KB)  server    one process: ingest + query API + tracker + evidence dashboard  cli       init · site · start · digest · demo  mcp       read-only MCP module (JSON-RPC over HTTP) for AI agents

Every package has zero runtime dependencies. The SQL string is the evidence — Store.select takes raw SQL on purpose, because hiding it behind an ORM would remove the one thing this project is for.

A few pieces ship in the core as libraries before the self-hosted server exposes them. Today the server does not yet mount the MCP module, run the scheduled digest delivery, accept server-side forwarded requests (which is how signed agents and non-rendering crawlers are seen — a browser script never sees them), take row filters, or render the sessions, users, journeys, goals and globe views; the building blocks are here and wiring them into vitrus start is on the roadmap.

Running the gates

Type checks, the test suites, two golden-set evals and the build gates:

Gate	What it prevents
`eval:referrer`	the AI-source table going stale unnoticed — 100% required
`eval:insight`	an unprovable number surviving into prose — zero leaks tolerated
`gate:core-purity`	the metric layer ever importing the LLM layer
`gate:no-deps`	a runtime dependency appearing without a deliberate decision
`gate:tracker-size`	the tracker quietly growing past 3 KB
`gate:inline-js`	a bad escape killing the dashboard's script while the page still renders

Cloud

app.vitrus.dev is the hosted version: teams and roles, quotas, EU hosting and digest delivery without running your own mail provider, plus the sessions, users, journeys, goals, real-time and globe views. The analysis engine is the same: every query those views run lives in packages/core in this repository.

Community

Questions and ideas — GitHub Discussions
Bugs — open an issue. A failing case beats a description; the AI referrer table in particular is tested by example.
Security — see SECURITY.md. Please do not open a public issue for a vulnerability.
Contributing — see CONTRIBUTING.md. The most useful first contribution is a new AI-referrer rule with the test case that pins it.

來源：README.md，提交 0d0b145

工具

工具後設資料尚未被收錄。

版本歷史

v0.6.0最新Oct 7, 2026