nana800-mcp-server 1.2.1 → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +83 -4
  2. package/dist/index.js +1026 -29
  3. package/package.json +9 -1
package/README.md CHANGED
@@ -11,9 +11,10 @@ With this server an AI assistant (Claude, Cursor, VS Code and any other MCP clie
11
11
  - 📤 exports and imports schemes as JSON, reads the OpenAPI document of scheme webhooks
12
12
  - 🔍 reads the run history of schemes and of single blocks
13
13
  - 💳 reads the payment account and its transactions
14
+ - 📈 builds analytics charts and dashboards from a request in words: lines, bars, funnels, retention, splits by a property, filters, public dashboard links
14
15
  - 📊 exports analytics events and users to CSV or JSON Lines files
15
16
 
16
- The server runs on your machine over stdio and calls `https://api.nana800.io` and `https://api.analytics.nana800.io` with your API key. 44 tools, Node.js 18 or newer.
17
+ The server runs on your machine over stdio and calls `https://api.nana800.io` and `https://api.analytics.nana800.io` with your API key. 59 tools, Node.js 18 or newer.
17
18
 
18
19
  ## 🔑 Get an API key
19
20
 
@@ -119,9 +120,14 @@ MCP_API_KEY=your_api_key npx -y nana800-mcp-server
119
120
  | `MCP_ANALYTICS_ORG_ID` | No | Default analytics org ID for tools with an optional `org_id`. Get it with `analytics_orgs_list` or from the `org` parameter of the analytics page URL |
120
121
  | `MCP_API_URL` | No | API origin, `https://api.nana800.io` by default |
121
122
  | `MCP_ANALYTICS_API_URL` | No | Analytics API origin, `https://api.analytics.nana800.io` by default |
123
+ | `MCP_CABINET_URL` | No | Web app origin used in chart and dashboard links, `https://cloud.nana800.io` by default |
122
124
 
123
125
  An ID passed in a tool call always wins over the default. Every API request has a 30 second timeout.
124
126
 
127
+ ### 🏷️ What the server tells nana800 about requests
128
+
129
+ Every request carries `x-nana-client: mcp`, `x-nana-client-version` (the package version), the name and version of the AI client from the MCP connection (`x-nana-ai-client`, `x-nana-ai-client-version`, for example `claude-ai`, `cursor-vscode`), the tool that made the request (`x-nana-mcp-tool`) and the User-Agent `nana800-mcp-server/<version>`. nana800 uses them only to count how people work with the platform through MCP, the web app and the API. No prompts or tool results are sent.
130
+
125
131
  ## 🧰 Tools
126
132
 
127
133
  ### Projects
@@ -187,13 +193,81 @@ An ID passed in a tool call always wins over the default. Every API request has
187
193
  | `payment_account_get_transactions` | Get the transaction history |
188
194
  | `payment_account_remove` | Remove the payment account from a user |
189
195
 
190
- ### Analytics data export
196
+ ### Analytics: orgs, projects, events
191
197
 
192
198
  | Tool | What it does |
193
199
  |------|--------------|
194
200
  | `analytics_orgs_list` | List analytics orgs the API key owner is a member of |
195
201
  | `analytics_projects_list` | List app projects of an analytics org |
196
- | `analytics_event_types_list` | List tracked event types of an app project, for export filters |
202
+ | `analytics_event_types_list` | List tracked event types of an app project, for chart series and export filters |
203
+ | `analytics_event_properties_list` | List property keys of an event type, the most used first, for chart conditions and splits |
204
+
205
+ ### Analytics charts
206
+
207
+ | Tool | What it does |
208
+ |------|--------------|
209
+ | `analytics_chart_preview` | Calculate a chart without saving it and return its numbers: totals per series, values per period, funnel steps, retention. Also takes `chart_id` of a saved chart |
210
+ | `analytics_chart_create` | Save a chart (`LINES_CHART`, `BARS`, `FUNNEL`, `RETENTION`) and return `chart_url`; `add_to_dashboard` puts it onto a dashboard in the same call |
211
+ | `analytics_chart_get` | Get a saved chart as an editable definition and its link |
212
+ | `analytics_chart_update` | Change a saved chart: name, series, period, metric, chart type, display settings |
213
+ | `analytics_chart_delete` | Delete a chart and remove it from every dashboard (irreversible) |
214
+
215
+ A chart is described the same way in `analytics_chart_preview`, `analytics_chart_create` and `analytics_chart_update`:
216
+
217
+ | Field | Meaning |
218
+ |-------|---------|
219
+ | `app_project_id` | Analytics project whose events are counted |
220
+ | `chart_variant` | `LINES_CHART` trend, `BARS` bars per period or one total bar per series, `FUNNEL` ordered steps, `RETENTION` start event + return event |
221
+ | `series` | `event_type_id`, `title` (label or funnel step name), `conditions` on event properties, `breakdown_property_key` to split by property values (lines and bars) |
222
+ | `common_conditions` | Conditions added to every series, for example to drop test traffic |
223
+ | `user_conditions` | Conditions on user properties for the whole chart |
224
+ | `metric` | `UNIQ_USERS` (default) or `TOTAL_EVENTS` |
225
+ | `period` | `time_scale` (`HOURLY`, `DAILY`, `WEEKLY`, `MONTHLY`) and `last_periods_count` for a live period (default last 30), or `from_time` + `to_time` for fixed dates |
226
+ | `funnel_conversion_window_seconds` | Funnel: all steps within this time from the first step |
227
+ | `retention_periods_count` | Retention: periods after the start period to track returns |
228
+ | `timezone_offset_minutes` | Day boundaries, minutes east of UTC (Moscow 180) |
229
+ | `display_settings` | `bars_mode` (`GROUPED`, `STACKED`, `TOTAL`), `value_mode`, renamed or colored series, up to 5 formulas like conversion = A / B |
230
+
231
+ The server writes the series where the web chart builder expects them, so every chart made through MCP opens and can be edited in the web app like a chart made by hand.
232
+
233
+ Example: "build a funnel from a view to a purchase for the last 30 days" becomes
234
+
235
+ ```json
236
+ {
237
+ "chart_name": "Funnel: view → purchase",
238
+ "app_project_id": "<project id>",
239
+ "chart_variant": "FUNNEL",
240
+ "series": [
241
+ { "event_type_id": "<id of page_viewed>", "title": "View" },
242
+ { "event_type_id": "<id of checkout_started>", "title": "Checkout" },
243
+ { "event_type_id": "<id of purchase_completed>", "title": "Purchase" }
244
+ ],
245
+ "period": { "time_scale": "DAILY", "last_periods_count": 30 },
246
+ "funnel_conversion_window_seconds": 604800,
247
+ "add_to_dashboard": { "dashboard_id": "<dashboard id>", "width_size": 2 }
248
+ }
249
+ ```
250
+
251
+ ### Analytics dashboards
252
+
253
+ | Tool | What it does |
254
+ |------|--------------|
255
+ | `analytics_dashboards_list` | List dashboards of an org with web app and public links |
256
+ | `analytics_dashboard_get` | Get a dashboard with its charts in order, widths and links |
257
+ | `analytics_dashboard_create` | Create an empty dashboard |
258
+ | `analytics_dashboard_update` | Rename a dashboard or change its description |
259
+ | `analytics_dashboard_add_chart` | Put a saved chart onto a dashboard at a position with a width, the charts below move down |
260
+ | `analytics_dashboard_set_chart_position` | Move a chart or change its width |
261
+ | `analytics_dashboard_remove_chart` | Take a chart off a dashboard, the chart stays saved |
262
+ | `analytics_dashboard_share_link` | Turn the public link on, reissue it (the old link stops working at once) or turn it off |
263
+ | `analytics_dashboard_delete` | Delete a dashboard, with `delete_charts` also its charts that are not on other dashboards (irreversible) |
264
+
265
+ A dashboard is a grid of 3 columns: `width_size` 1 is a third of a row, 2 is two thirds, 3 is the full row. Keep the sum of widths in a row equal to 3. The public link `https://cloud.nana800.io/share/dashboard/<token>` shows the charts without login, read only; turning it on needs the owner or editor role in the org.
266
+
267
+ ### Analytics data export
268
+
269
+ | Tool | What it does |
270
+ |------|--------------|
197
271
  | `analytics_export_create` | Start an export of events (`EVENTS`), events of one user (`USER_EVENTS`) or users (`USERS`) to CSV or JSONL |
198
272
  | `analytics_export_status` | Get export status (`QUEUED`, `RUNNING`, `DONE`, `FAILED`) and the download link when it is done |
199
273
  | `analytics_exports_list` | List the 20 newest exports of an org |
@@ -227,6 +301,9 @@ curl --compressed -o export.csv "<download_url>"
227
301
  - "Export scheme X as JSON and import its nodes into scheme Y"
228
302
  - "Show the last transactions of my payment account"
229
303
  - "Export all purchase events of the last week to CSV and give me the download link"
304
+ - "Build a funnel from a view to a purchase for the last 30 days"
305
+ - "Make a dashboard for my site: visitors per day, traffic channels and a funnel from a visit to a call, turn on the public link"
306
+ - "Which pages bring the most calls? Show it as total bars split by page"
230
307
 
231
308
  ## 🔗 Links
232
309
 
@@ -239,11 +316,13 @@ curl --compressed -o export.csv "<download_url>"
239
316
 
240
317
  ## 🇷🇺 На русском
241
318
 
242
- **nana800-mcp-server** - MCP-сервер для [nana800.io](https://nana800.io), no-code платформы для серверной логики и автоматизации. Через него ИИ-ассистент (Claude, Cursor, VS Code) создаёт проекты и схемы, добавляет и связывает блоки, смотрит историю запусков, данные платёжного аккаунта и выгружает аналитику в CSV или JSON Lines.
319
+ **nana800-mcp-server** - MCP-сервер для [nana800.io](https://nana800.io), no-code платформы для серверной логики и автоматизации. Через него ИИ-ассистент (Claude, Cursor, VS Code) создаёт проекты и схемы, добавляет и связывает блоки, смотрит историю запусков, данные платёжного аккаунта, строит графики и дашборды аналитики по просьбе словами и выгружает аналитику в CSV или JSON Lines.
243
320
 
244
321
  - 🔑 Ключ API: [cloud.nana800.io/settings](https://cloud.nana800.io/settings), его нужно передать в переменной `MCP_API_KEY`
245
322
  - 🚀 Запуск: `npx -y nana800-mcp-server`, готовые настройки для клиентов выше в разделе Quick start
246
323
  - 🖥️ Сервер работает на вашем компьютере и ходит в API nana800 от имени владельца ключа
324
+ - 🏷️ Каждый запрос помечен как сделанный через MCP: версия пакета, имя ИИ-клиента (Claude, Cursor и другие) и имя инструмента. По этим меткам nana800 считает, сколько работают через MCP, кабинет и API. Тексты запросов к ИИ и ответы инструментов не передаются
325
+ - 📈 Графики и дашборды: попросите, например, «построй воронку от просмотра до покупки за 30 дней» или «собери дашборд сайта из трёх графиков и включи публичную ссылку». Ассистент сам найдёт события, проверит цифры предпросмотром, сохранит графики, разложит их на дашборде и пришлёт ссылки на кабинет и публичную страницу
247
326
  - ⚠️ Инструменты удаления (`project_delete`, `scheme_delete`, `node_delete` и другие) необратимы
248
327
  - 📚 Документация: [nana800.gitbook.io/doc](https://nana800.gitbook.io/doc)
249
328