nana800-mcp-server 1.1.0 → 1.2.1

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 +183 -110
  2. package/dist/index.js +209 -10
  3. package/package.json +2 -1
package/README.md CHANGED
@@ -1,178 +1,251 @@
1
1
  # nana800 MCP Server
2
2
 
3
- MCP (Model Context Protocol) server for [nana800.io](https://nana800.io) Public API. This server enables AI-powered IDEs like Cursor, Claude Desktop, and VS Code to interact with your no-code automation projects.
3
+ [![npm](https://img.shields.io/npm/v/nana800-mcp-server)](https://www.npmjs.com/package/nana800-mcp-server)
4
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
4
5
 
5
- ## Installation
6
+ Model Context Protocol (MCP) server for [nana800.io](https://nana800.io/en/), a no-code platform for backend logic and workflow automation. Workflows (called schemes) are built from trigger and action blocks (called nodes) in a visual editor: webhooks, timers, HTTP requests, Telegram, Google Sheets, GPT and other integrations.
6
7
 
7
- ```bash
8
- npm install -g nana800-mcp-server
9
- # or
10
- npx nana800-mcp-server
11
- ```
8
+ With this server an AI assistant (Claude, Cursor, VS Code and any other MCP client) works with your nana800 account through the Public API:
9
+
10
+ - 🧱 creates projects and schemes, adds trigger and action blocks, configures and connects them
11
+ - 📤 exports and imports schemes as JSON, reads the OpenAPI document of scheme webhooks
12
+ - 🔍 reads the run history of schemes and of single blocks
13
+ - 💳 reads the payment account and its transactions
14
+ - 📊 exports analytics events and users to CSV or JSON Lines files
15
+
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.
12
17
 
13
- ## Getting API Key
18
+ ## 🔑 Get an API key
14
19
 
15
- 1. Go to [https://cloud.nana800.io/settings](https://cloud.nana800.io/settings)
16
- 2. Create or copy your API key
17
- 3. Use it in the configuration below
20
+ 1. Sign in at [cloud.nana800.io](https://cloud.nana800.io)
21
+ 2. Open [cloud.nana800.io/settings](https://cloud.nana800.io/settings) and create or copy an API key
22
+ 3. Put it into `MCP_API_KEY` in the client config below
18
23
 
19
- ## Configuration
24
+ The key acts as your user: the tools see and change only the projects your account has access to.
20
25
 
21
- ### Cursor IDE
26
+ ## 🚀 Quick start
22
27
 
23
- Add to your `~/.cursor/mcp.json`:
28
+ ### Claude Desktop
29
+
30
+ Open Settings -> Developer -> Edit Config, or the file directly:
31
+
32
+ - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
33
+ - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
24
34
 
25
35
  ```json
26
36
  {
27
37
  "mcpServers": {
28
38
  "nana800": {
29
39
  "command": "npx",
30
- "args": ["nana800-mcp-server"],
40
+ "args": ["-y", "nana800-mcp-server"],
31
41
  "env": {
32
- "MCP_API_KEY": "your_api_key_here",
33
- "MCP_PROJECT_ID": "your_default_project_id",
34
- "MCP_SCHEME_ID": "your_default_scheme_id"
42
+ "MCP_API_KEY": "your_api_key"
35
43
  }
36
44
  }
37
45
  }
38
46
  }
39
47
  ```
40
48
 
41
- ### Claude Desktop
49
+ Restart Claude Desktop after saving.
42
50
 
43
- Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
51
+ ### Claude Code
52
+
53
+ ```bash
54
+ claude mcp add nana800 -e MCP_API_KEY=your_api_key -- npx -y nana800-mcp-server
55
+ ```
56
+
57
+ Add `--scope user` to use it in all your projects.
58
+
59
+ ### Cursor
60
+
61
+ Add to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project):
44
62
 
45
63
  ```json
46
64
  {
47
65
  "mcpServers": {
48
66
  "nana800": {
49
67
  "command": "npx",
50
- "args": ["nana800-mcp-server"],
68
+ "args": ["-y", "nana800-mcp-server"],
51
69
  "env": {
52
- "MCP_API_KEY": "your_api_key_here",
53
- "MCP_PROJECT_ID": "your_default_project_id",
54
- "MCP_SCHEME_ID": "your_default_scheme_id"
70
+ "MCP_API_KEY": "your_api_key"
55
71
  }
56
72
  }
57
73
  }
58
74
  }
59
75
  ```
60
76
 
61
- ### VS Code with Cline/Continue
77
+ ### VS Code
62
78
 
63
- Add to your extension settings:
79
+ Add to `.vscode/mcp.json`. VS Code asks for the key on the first start and keeps it in its secret storage:
64
80
 
65
81
  ```json
66
82
  {
67
- "mcpServers": {
83
+ "inputs": [
84
+ {
85
+ "type": "promptString",
86
+ "id": "nana800-api-key",
87
+ "description": "nana800.io API key",
88
+ "password": true
89
+ }
90
+ ],
91
+ "servers": {
68
92
  "nana800": {
93
+ "type": "stdio",
69
94
  "command": "npx",
70
- "args": ["nana800-mcp-server"],
95
+ "args": ["-y", "nana800-mcp-server"],
71
96
  "env": {
72
- "MCP_API_KEY": "your_api_key_here",
73
- "MCP_PROJECT_ID": "your_default_project_id",
74
- "MCP_SCHEME_ID": "your_default_scheme_id"
97
+ "MCP_API_KEY": "${input:nana800-api-key}"
75
98
  }
76
99
  }
77
100
  }
78
101
  }
79
102
  ```
80
103
 
81
- ## Environment Variables
104
+ ### Other clients
105
+
106
+ Any MCP client that starts stdio servers works with the same command:
107
+
108
+ ```bash
109
+ MCP_API_KEY=your_api_key npx -y nana800-mcp-server
110
+ ```
111
+
112
+ ## ⚙️ Environment variables
82
113
 
83
114
  | Variable | Required | Description |
84
115
  |----------|----------|-------------|
85
- | `MCP_API_KEY` | Yes | Your nana800.io API key |
86
- | `MCP_PROJECT_ID` | No | Default project ID (can be overridden per tool call) |
87
- | `MCP_SCHEME_ID` | No | Default scheme ID (can be overridden per tool call) |
116
+ | `MCP_API_KEY` | Yes | Your nana800.io API key from [cloud.nana800.io/settings](https://cloud.nana800.io/settings). The server stops with an error without it |
117
+ | `MCP_PROJECT_ID` | No | Default project ID for tools with an optional `project_id` |
118
+ | `MCP_SCHEME_ID` | No | Default scheme ID for tools with an optional `scheme_id` or `scheme` |
119
+ | `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 |
88
120
  | `MCP_API_URL` | No | API origin, `https://api.nana800.io` by default |
89
-
90
- Every API request has a 30 second timeout. Requires Node.js 18 or newer.
91
-
92
- ## Available Tools
93
-
94
- ### Project Management
95
-
96
- | Tool | Description |
97
- |------|-------------|
98
- | `project_create` | Create a new project |
99
- | `project_get` | Get project details by ID |
100
- | `project_list_by_payment_account` | List projects by payment account |
101
- | `project_update` | Update project properties |
102
- | `project_delete` | Delete a project |
103
-
104
- ### Scheme Management
105
-
106
- | Tool | Description |
107
- |------|-------------|
108
- | `scheme_create` | Create a new scheme (workflow) |
109
- | `scheme_get` | Get scheme details |
110
- | `scheme_list_by_project` | List all schemes in a project |
111
- | `scheme_update` | Update scheme name, description and enable or disable it |
112
- | `scheme_delete` | Delete a scheme |
113
- | `scheme_export` | Export scheme as JSON |
114
- | `scheme_import` | Import nodes into a scheme |
115
- | `scheme_get_context_type` | Get scheme context type |
116
- | `scheme_get_swagger_json` | Get OpenAPI spec for scheme |
117
-
118
- ### Node Management
119
-
120
- | Tool | Description |
121
- |------|-------------|
122
- | `get_nodes_info` | List available trigger and action types with their configuration |
123
- | `node_create_trigger` | Create a trigger node |
124
- | `node_create_action` | Create an action node |
125
- | `node_get` | Get node details |
126
- | `node_list_by_scheme` | List all nodes in a scheme |
127
- | `node_update` | Update node properties |
128
- | `node_update_config` | Update node configuration |
129
- | `node_delete` | Delete a node |
130
- | `node_connect` | Connect two nodes (for condition nodes `connection_index` 0 is the "true" output, 1 is the "false" output) |
131
- | `node_disconnect` | Disconnect two nodes |
121
+ | `MCP_ANALYTICS_API_URL` | No | Analytics API origin, `https://api.analytics.nana800.io` by default |
122
+
123
+ An ID passed in a tool call always wins over the default. Every API request has a 30 second timeout.
124
+
125
+ ## 🧰 Tools
126
+
127
+ ### Projects
128
+
129
+ | Tool | What it does |
130
+ |------|--------------|
131
+ | `project_create` | Create a project, a container for schemes |
132
+ | `project_get` | Get a project by ID |
133
+ | `project_list_by_payment_account` | List projects of a payment account |
134
+ | `project_update` | Change project name or slug |
135
+ | `project_delete` | Delete a project with all its schemes (irreversible) |
136
+
137
+ ### Schemes (workflows)
138
+
139
+ | Tool | What it does |
140
+ |------|--------------|
141
+ | `scheme_create` | Create a scheme in a project |
142
+ | `scheme_get` | Get a scheme by ID |
143
+ | `scheme_list_by_project` | List schemes of a project |
144
+ | `scheme_update` | Change name and description, enable or disable a scheme |
145
+ | `scheme_get_context_type` | Get the data type of the scheme context |
146
+ | `scheme_get_swagger_json` | Get the OpenAPI 3 document of the scheme webhooks: paths, methods, fields the blocks read, answers, and webhooks that get no requests with the reason |
147
+ | `scheme_export` | Export scheme nodes and connections as JSON |
148
+ | `scheme_import` | Import nodes into a scheme from exported JSON |
149
+ | `scheme_delete` | Delete a scheme with all its nodes (irreversible) |
150
+
151
+ ### Nodes (blocks)
152
+
153
+ | Tool | What it does |
154
+ |------|--------------|
155
+ | `get_nodes_info` | List available trigger and action types with their config options, call it before creating nodes |
156
+ | `node_create_trigger` | Create a trigger node (for example `WEBHOOK`, `INTERVAL`) |
157
+ | `node_create_action` | Create an action node (HTTP request, email, integrations) |
158
+ | `node_get` | Get a node by ID |
159
+ | `node_list_by_scheme` | List nodes of a scheme |
160
+ | `node_update` | Change node slug or description |
161
+ | `node_update_config` | Change node configuration |
162
+ | `node_connect` | Connect two nodes, for condition nodes `connection_index` 0 is the "true" output and 1 is the "false" output |
163
+ | `node_disconnect` | Remove a connection between two nodes |
164
+ | `node_get_scheme_edges` | List all connections of a scheme |
165
+ | `node_find_existing_buttons` | List existing outputs of a node |
132
166
  | `node_copy` | Copy a node |
133
- | `node_get_scheme_edges` | Get all connections in a scheme |
134
- | `node_find_existing_buttons` | Find node output buttons |
167
+ | `node_delete` | Delete a node (irreversible) |
168
+
169
+ ### Run history
170
+
171
+ | Tool | What it does |
172
+ |------|--------------|
173
+ | `scheme_process_get` | Get one scheme run |
174
+ | `scheme_process_list_filtered` | List scheme runs by scheme or project, with status filters and pages |
175
+ | `scheme_process_delete` | Delete a scheme run record |
176
+ | `node_process_get` | Get one node run |
177
+ | `node_process_list_filtered` | List node runs by scheme, node or scheme run, with status filters and pages |
178
+ | `node_process_delete` | Delete a node run record |
135
179
 
136
- ### Node Process Management
180
+ ### Payment account
137
181
 
138
- | Tool | Description |
139
- |------|-------------|
140
- | `node_process_get` | Get node process details |
141
- | `node_process_list_filtered` | List node processes, filter by scheme, node or scheme process is required |
142
- | `node_process_delete` | Delete a node process record |
182
+ | Tool | What it does |
183
+ |------|--------------|
184
+ | `payment_account_get_by_user` | Get the payment account of a user |
185
+ | `payment_account_get_by_project` | Get the payment account of a project |
186
+ | `payment_account_update` | Change account name and automatic balance refill |
187
+ | `payment_account_get_transactions` | Get the transaction history |
188
+ | `payment_account_remove` | Remove the payment account from a user |
143
189
 
144
- ### Scheme Process Management
190
+ ### Analytics data export
191
+
192
+ | Tool | What it does |
193
+ |------|--------------|
194
+ | `analytics_orgs_list` | List analytics orgs the API key owner is a member of |
195
+ | `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 |
197
+ | `analytics_export_create` | Start an export of events (`EVENTS`), events of one user (`USER_EVENTS`) or users (`USERS`) to CSV or JSONL |
198
+ | `analytics_export_status` | Get export status (`QUEUED`, `RUNNING`, `DONE`, `FAILED`) and the download link when it is done |
199
+ | `analytics_exports_list` | List the 20 newest exports of an org |
200
+
201
+ The API key user must be a member of the analytics org. Exports run in the background and the tools return only the status and a download link, never the rows.
202
+
203
+ Export limits:
204
+
205
+ - Up to 1,000,000 rows per file, `is_truncated` is `true` when more rows matched
206
+ - One active export per org, 10 exports per org per hour, exports started with an API key: one per 10 minutes per org
207
+ - `time_from` and `time_to` are ISO 8601 date-times with a timezone, for example `2026-10-01T00:00:00.000Z`
208
+ - Poll `analytics_export_status` not more often than once per ~10 seconds
209
+ - The download link is valid for 15 minutes, call `analytics_export_status` again for a fresh one
210
+ - Files are deleted after 7 days
211
+
212
+ The file is served gzipped (`Content-Encoding: gzip`). A browser saves plain CSV or JSONL, from a shell use:
213
+
214
+ ```bash
215
+ curl --compressed -o export.csv "<download_url>"
216
+ ```
145
217
 
146
- | Tool | Description |
147
- |------|-------------|
148
- | `scheme_process_get` | Get scheme process details |
149
- | `scheme_process_list_filtered` | List scheme processes, filter by scheme or project is required |
150
- | `scheme_process_delete` | Delete a scheme process record |
218
+ ⚠️ Delete and remove tools can not be undone. Keep tool call confirmation on in your MCP client for them.
151
219
 
152
- ### Payment Account Management
220
+ ## 💬 Example prompts
153
221
 
154
- | Tool | Description |
155
- |------|-------------|
156
- | `payment_account_get_by_user` | Get payment account by user ID |
157
- | `payment_account_get_by_project` | Get payment account by project ID |
158
- | `payment_account_update` | Update payment account name and automatic balance refill |
159
- | `payment_account_remove` | Remove payment account |
160
- | `payment_account_get_transactions` | Get transaction history |
222
+ - "List the schemes of my project and tell me which ones are disabled"
223
+ - "Create a scheme 'Lead to Telegram': a webhook trigger that sends the request body to my Telegram chat"
224
+ - "Show the nodes of scheme X and how they are connected"
225
+ - "Why did the last runs of scheme X fail? Look at the node runs"
226
+ - "Give me the OpenAPI document of scheme X and list the webhooks that get no requests"
227
+ - "Export scheme X as JSON and import its nodes into scheme Y"
228
+ - "Show the last transactions of my payment account"
229
+ - "Export all purchase events of the last week to CSV and give me the download link"
161
230
 
162
- ## Usage Examples
231
+ ## 🔗 Links
163
232
 
164
- Once configured, you can ask your AI assistant things like:
233
+ - Website: [nana800.io](https://nana800.io/en/)
234
+ - Web app: [cloud.nana800.io](https://cloud.nana800.io)
235
+ - Documentation: [nana800.gitbook.io/doc](https://nana800.gitbook.io/doc)
236
+ - Public API reference: [api.nana800.io/public-api](https://api.nana800.io/public-api)
237
+ - Privacy policy: [nana800_privacy.pdf](https://docs.nana800.io/nana800-files/service_documents/nana800_privacy.pdf)
238
+ - Telegram: [t.me/nana800_io](https://t.me/nana800_io)
165
239
 
166
- - "List all my projects"
167
- - "Create a new scheme called 'Email Notifications' in project X"
168
- - "Show me all nodes in scheme Y"
169
- - "Connect the webhook trigger to the email action"
170
- - "Export the scheme configuration"
171
- - "What processes are currently running?"
240
+ ## 🇷🇺 На русском
172
241
 
173
- ## API Documentation
242
+ **nana800-mcp-server** - MCP-сервер для [nana800.io](https://nana800.io), no-code платформы для серверной логики и автоматизации. Через него ИИ-ассистент (Claude, Cursor, VS Code) создаёт проекты и схемы, добавляет и связывает блоки, смотрит историю запусков, данные платёжного аккаунта и выгружает аналитику в CSV или JSON Lines.
174
243
 
175
- Full API documentation available at: [https://api.nana800.io/public-api](https://api.nana800.io/public-api)
244
+ - 🔑 Ключ API: [cloud.nana800.io/settings](https://cloud.nana800.io/settings), его нужно передать в переменной `MCP_API_KEY`
245
+ - 🚀 Запуск: `npx -y nana800-mcp-server`, готовые настройки для клиентов выше в разделе Quick start
246
+ - 🖥️ Сервер работает на вашем компьютере и ходит в API nana800 от имени владельца ключа
247
+ - ⚠️ Инструменты удаления (`project_delete`, `scheme_delete`, `node_delete` и другие) необратимы
248
+ - 📚 Документация: [nana800.gitbook.io/doc](https://nana800.gitbook.io/doc)
176
249
 
177
250
  ## License
178
251
 
package/dist/index.js CHANGED
@@ -9,11 +9,13 @@ import { z } from "zod";
9
9
 
10
10
  // src/api-client.ts
11
11
  var API_BASE_URL = (process.env.MCP_API_URL || "https://api.nana800.io").replace(/\/+$/, "");
12
+ var ANALYTICS_API_BASE_URL = (process.env.MCP_ANALYTICS_API_URL || "https://api.analytics.nana800.io").replace(/\/+$/, "");
12
13
  var API_KEY_HEADER = "x-nana-api-key";
13
14
  var REQUEST_TIMEOUT_MS = 3e4;
14
15
  var MAX_ERROR_TEXT_LENGTH = 2e3;
15
16
  var DEFAULT_PROJECT_ID = process.env.MCP_PROJECT_ID || "";
16
17
  var DEFAULT_SCHEME_ID = process.env.MCP_SCHEME_ID || "";
18
+ var DEFAULT_ANALYTICS_ORG_ID = process.env.MCP_ANALYTICS_ORG_ID || "";
17
19
  var getProjectId = (providedId) => {
18
20
  const id = providedId || DEFAULT_PROJECT_ID;
19
21
  if (!id) {
@@ -28,6 +30,13 @@ var getSchemeId = (providedId) => {
28
30
  }
29
31
  return id;
30
32
  };
33
+ var getAnalyticsOrgId = (providedId) => {
34
+ const id = providedId || DEFAULT_ANALYTICS_ORG_ID;
35
+ if (!id) {
36
+ throw new Error("org_id is required. Provide it as parameter or set MCP_ANALYTICS_ORG_ID env variable");
37
+ }
38
+ return id;
39
+ };
31
40
  var apiPath = (strings, ...values) => {
32
41
  return strings.reduce((path, part, index) => path + part + (index < values.length ? encodeURIComponent(values[index]) : ""), "");
33
42
  };
@@ -39,8 +48,10 @@ var getErrorMessage = (error) => {
39
48
  };
40
49
  var ApiClient = class {
41
50
  apiKey;
42
- constructor(apiKey) {
51
+ baseUrl;
52
+ constructor(apiKey, baseUrl) {
43
53
  this.apiKey = apiKey;
54
+ this.baseUrl = baseUrl;
44
55
  }
45
56
  get(path, queryParams) {
46
57
  return this.request("GET", path, { query: queryParams });
@@ -56,7 +67,7 @@ var ApiClient = class {
56
67
  }
57
68
  async request(method, path, { query, body }) {
58
69
  try {
59
- const url = new URL(`${API_BASE_URL}${path}`);
70
+ const url = new URL(`${this.baseUrl}${path}`);
60
71
  if (query) {
61
72
  Object.entries(query).forEach(([key, value]) => {
62
73
  if (value !== void 0) {
@@ -91,16 +102,26 @@ var ApiClient = class {
91
102
  }
92
103
  };
93
104
  var apiClientInstance = null;
105
+ var analyticsApiClientInstance = null;
106
+ var getApiKey = () => {
107
+ const apiKey = process.env.MCP_API_KEY;
108
+ if (!apiKey) {
109
+ throw new Error("MCP_API_KEY environment variable is not set");
110
+ }
111
+ return apiKey;
112
+ };
94
113
  var getApiClient = () => {
95
114
  if (!apiClientInstance) {
96
- const apiKey = process.env.MCP_API_KEY;
97
- if (!apiKey) {
98
- throw new Error("MCP_API_KEY environment variable is not set");
99
- }
100
- apiClientInstance = new ApiClient(apiKey);
115
+ apiClientInstance = new ApiClient(getApiKey(), API_BASE_URL);
101
116
  }
102
117
  return apiClientInstance;
103
118
  };
119
+ var getAnalyticsApiClient = () => {
120
+ if (!analyticsApiClientInstance) {
121
+ analyticsApiClientInstance = new ApiClient(getApiKey(), ANALYTICS_API_BASE_URL);
122
+ }
123
+ return analyticsApiClientInstance;
124
+ };
104
125
 
105
126
  // src/tools/project.tools.ts
106
127
  var registerProjectTools = (server) => {
@@ -322,7 +343,7 @@ var registerSchemeTools = (server) => {
322
343
  );
323
344
  server.tool(
324
345
  "scheme_get_swagger_json",
325
- "Get Swagger/OpenAPI JSON specification for a scheme",
346
+ "Get the OpenAPI 3 document of the scheme webhooks, built from the current blocks: the base URL, every webhook path and method, path params, the query, header and body fields the connected blocks read, and the answers of the connected response blocks. Webhooks that get no requests (empty or wrong path, wrong method, taken by an earlier webhook) are listed in x-nana800-broken-webhooks with the reason. Block secrets are masked for project readers",
326
347
  {
327
348
  scheme_id: z2.string().optional().describe("The unique ID of the scheme (uses MCP_SCHEME_ID env if not provided)")
328
349
  },
@@ -330,7 +351,7 @@ var registerSchemeTools = (server) => {
330
351
  try {
331
352
  const resolvedSchemeId = getSchemeId(scheme_id);
332
353
  const client = getApiClient();
333
- const result = await client.get(apiPath`/scheme/swagger_json/${resolvedSchemeId}`);
354
+ const result = await client.get(apiPath`/scheme/openapi/${resolvedSchemeId}`);
334
355
  return {
335
356
  content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
336
357
  };
@@ -904,9 +925,186 @@ var registerPaymentAccountTools = (server) => {
904
925
  );
905
926
  };
906
927
 
928
+ // src/tools/analytics-export.tools.ts
929
+ import { z as z7 } from "zod";
930
+ var MAX_EVENT_TYPE_FILTERS = 20;
931
+ var MAX_CONDITIONS_PER_FILTER = 20;
932
+ var MAX_CONDITION_VALUES = 50;
933
+ var MAX_CONDITION_VALUE_LENGTH = 200;
934
+ var EXPORT_FLOW_HINT = 'The export runs in the background: export_status goes QUEUED -> RUNNING -> DONE or FAILED. Poll analytics_export_status until DONE or FAILED, not more often than once per ~10 seconds. When DONE, download_url is a direct link valid for 15 minutes (call analytics_export_status again for a fresh one). The file is served gzipped with Content-Encoding: gzip: a browser saves plain CSV or JSONL, from a shell use curl --compressed -o file.csv "<download_url>". Files are deleted 7 days after creation. No rows are returned through MCP, only the status and the link.';
935
+ var ISO_DATE_TIME_ERROR = 'must be an ISO 8601 date-time with a timezone, e.g. 2026-10-01T00:00:00.000Z or 2026-10-01T00:00:00+03:00. Relative values like "last 7 days" are not accepted, compute the exact date-time';
936
+ var isoDateTimeSchema = z7.iso.datetime({ offset: true, error: ISO_DATE_TIME_ERROR });
937
+ var conditionSchema = z7.object({
938
+ param_name: z7.string().max(MAX_CONDITION_VALUE_LENGTH).describe("Property name"),
939
+ param_values: z7.array(z7.string().max(MAX_CONDITION_VALUE_LENGTH)).max(MAX_CONDITION_VALUES).describe("Values to compare with. EQUAL and CONTAINS match any of the values, NOT_EQUAL and NOT_CONTAINS match none of them, GREATER_THAN and LESS_THAN use the first value as a number, IS_SET and IS_NOT_SET ignore the values (pass [])"),
940
+ condition: z7.enum(["EQUAL", "NOT_EQUAL", "CONTAINS", "NOT_CONTAINS", "GREATER_THAN", "LESS_THAN", "IS_SET", "IS_NOT_SET"]).optional().describe("Comparison, EQUAL by default")
941
+ });
942
+ var eventTypeFilterSchema = z7.object({
943
+ event_type_id: z7.string().describe("Event type ID from analytics_event_types_list"),
944
+ event_properties: z7.array(conditionSchema).max(MAX_CONDITIONS_PER_FILTER).optional().describe("Conditions on event properties, all of them must match")
945
+ });
946
+ var userFilterSchema = z7.object({
947
+ analytics_user_ids: z7.array(z7.string()).optional().describe("Analytics user IDs (_id or custom_user_id)"),
948
+ user_properties: z7.array(conditionSchema).max(MAX_CONDITIONS_PER_FILTER).optional().describe("Conditions on user properties, all of them must match"),
949
+ user_performed_event_filters: z7.array(eventTypeFilterSchema).max(MAX_EVENT_TYPE_FILTERS).optional().describe("Only users who performed any of these events")
950
+ });
951
+ var pickUserFilter = (userFilter) => {
952
+ const result = {};
953
+ if (userFilter.analytics_user_ids !== void 0) result.analytics_user_ids = userFilter.analytics_user_ids;
954
+ if (userFilter.user_properties !== void 0) result.user_properties = userFilter.user_properties;
955
+ if (userFilter.user_performed_event_filters !== void 0) result.user_performed_event_filters = userFilter.user_performed_event_filters;
956
+ return result;
957
+ };
958
+ var registerAnalyticsExportTools = (server) => {
959
+ server.tool(
960
+ "analytics_orgs_list",
961
+ 'List analytics orgs the API key owner is a member of (_id, org_name). Use the org _id as org_id in the other analytics tools or set it as MCP_ANALYTICS_ORG_ID. In the analytics web app the org ID is the "org" parameter of the page URL',
962
+ {},
963
+ async () => {
964
+ try {
965
+ const mainClient = getApiClient();
966
+ const userResult = await mainClient.get("/user/own");
967
+ if (!userResult.success || !userResult.data?._id) {
968
+ throw new Error(`Failed to get the API key owner: ${userResult.error || "unexpected response"}`);
969
+ }
970
+ const client = getAnalyticsApiClient();
971
+ const result = await client.get(apiPath`/analytics_org_access/get_orgs_of_user/${userResult.data._id}`);
972
+ return {
973
+ content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
974
+ };
975
+ } catch (error) {
976
+ return {
977
+ content: [{ type: "text", text: JSON.stringify({ success: false, error: error instanceof Error ? error.message : "Unknown error" }, null, 2) }]
978
+ };
979
+ }
980
+ }
981
+ );
982
+ server.tool(
983
+ "analytics_projects_list",
984
+ "List app projects of an analytics org (org_id from analytics_orgs_list or MCP_ANALYTICS_ORG_ID). Use the project _id as app_project_id in analytics_event_types_list and analytics_export_create",
985
+ {
986
+ org_id: z7.string().optional().describe("The analytics org ID from analytics_orgs_list (uses MCP_ANALYTICS_ORG_ID env if not provided)")
987
+ },
988
+ async ({ org_id }) => {
989
+ try {
990
+ const resolvedOrgId = getAnalyticsOrgId(org_id);
991
+ const client = getAnalyticsApiClient();
992
+ const result = await client.get(apiPath`/analytics_app_projects/get_projects_by_org/${resolvedOrgId}`);
993
+ return {
994
+ content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
995
+ };
996
+ } catch (error) {
997
+ return {
998
+ content: [{ type: "text", text: JSON.stringify({ success: false, error: error instanceof Error ? error.message : "Unknown error" }, null, 2) }]
999
+ };
1000
+ }
1001
+ }
1002
+ );
1003
+ server.tool(
1004
+ "analytics_event_types_list",
1005
+ "List tracked event types of an analytics app project. Use the event type _id as event_type_id in analytics_export_create filters",
1006
+ {
1007
+ app_project_id: z7.string().describe("The analytics app project ID from analytics_projects_list")
1008
+ },
1009
+ async ({ app_project_id }) => {
1010
+ const client = getAnalyticsApiClient();
1011
+ const result = await client.get(apiPath`/analytics_event_types/get_event_types_by_app_project/${app_project_id}`);
1012
+ return {
1013
+ content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
1014
+ };
1015
+ }
1016
+ );
1017
+ server.tool(
1018
+ "analytics_export_create",
1019
+ "Start a file export of analytics data of an org (org_id from analytics_orgs_list or MCP_ANALYTICS_ORG_ID): EVENTS (events of the org or project), USER_EVENTS (events of one user, user_filter.analytics_user_ids must have exactly one ID) or USERS (users with their properties). Up to 1,000,000 rows per file, is_truncated is true when more rows matched. Limits per org: one active export at a time (HTTP 409 analytics_export_already_running), 10 exports per hour (HTTP 429 analytics_export_hourly_limit), exports started with an API key: one per 10 minutes (HTTP 429 analytics_export_api_key_interval). HTTP 400 analytics_export_invalid_filter means the filter does not fit the export kind, HTTP 403 means the API key user is not a member of the org. " + EXPORT_FLOW_HINT,
1020
+ {
1021
+ org_id: z7.string().optional().describe("The analytics org ID from analytics_orgs_list (uses MCP_ANALYTICS_ORG_ID env if not provided)"),
1022
+ app_project_id: z7.string().optional().describe("The analytics app project ID, all projects of the org if not provided"),
1023
+ export_kind: z7.enum(["EVENTS", "USER_EVENTS", "USERS"]).describe("What to export"),
1024
+ file_format: z7.enum(["CSV", "JSONL"]).optional().describe("File format, CSV by default. JSONL is one JSON object per line"),
1025
+ csv_delimiter: z7.enum([",", ";"]).optional().describe("CSV column delimiter, comma by default"),
1026
+ time_from: isoDateTimeSchema.optional().describe("EVENTS and USER_EVENTS only: events from this time, ISO 8601 date-time with a timezone (e.g. 2026-10-01T00:00:00.000Z)"),
1027
+ time_to: isoDateTimeSchema.optional().describe("EVENTS and USER_EVENTS only: events up to this time, ISO 8601 date-time with a timezone (e.g. 2026-10-08T00:00:00.000Z)"),
1028
+ event_types_filter: z7.array(eventTypeFilterSchema).max(MAX_EVENT_TYPE_FILTERS).optional().describe("EVENTS and USER_EVENTS only: events of any of these types, each type with its own property conditions. All event types if not provided"),
1029
+ user_filter: userFilterSchema.optional().describe("For EVENTS: only events of the matching users. For USER_EVENTS: required, analytics_user_ids with exactly one user ID. For USERS: which users to export, all users if not provided")
1030
+ },
1031
+ async ({ org_id, app_project_id, export_kind, file_format, csv_delimiter, time_from, time_to, event_types_filter, user_filter }) => {
1032
+ try {
1033
+ const resolvedOrgId = getAnalyticsOrgId(org_id);
1034
+ if (export_kind === "USERS" && (time_from || time_to || event_types_filter)) {
1035
+ throw new Error("time_from, time_to and event_types_filter work only for EVENTS and USER_EVENTS exports. For USERS use user_filter.user_performed_event_filters");
1036
+ }
1037
+ if (export_kind === "USER_EVENTS" && user_filter?.analytics_user_ids?.length !== 1) {
1038
+ throw new Error("USER_EVENTS export needs user_filter.analytics_user_ids with exactly one user ID");
1039
+ }
1040
+ const scope = { org_id: resolvedOrgId };
1041
+ if (app_project_id) scope.app_project_id = app_project_id;
1042
+ const body = { ...scope, export_kind };
1043
+ if (file_format) body.file_format = file_format;
1044
+ if (csv_delimiter) body.csv_delimiter = csv_delimiter;
1045
+ if (export_kind === "USERS") {
1046
+ body.users_filter = { ...scope, ...user_filter ? pickUserFilter(user_filter) : {} };
1047
+ } else {
1048
+ const eventsFilter = { ...scope };
1049
+ if (time_from) eventsFilter.time_from = time_from;
1050
+ if (time_to) eventsFilter.time_to = time_to;
1051
+ if (event_types_filter) eventsFilter.event_types_filter = event_types_filter;
1052
+ if (user_filter) eventsFilter.user_filter = { org_id: resolvedOrgId, ...pickUserFilter(user_filter) };
1053
+ body.events_filter = eventsFilter;
1054
+ }
1055
+ const client = getAnalyticsApiClient();
1056
+ const result = await client.post("/analytics_exports/create_export", body);
1057
+ return {
1058
+ content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
1059
+ };
1060
+ } catch (error) {
1061
+ return {
1062
+ content: [{ type: "text", text: JSON.stringify({ success: false, error: error instanceof Error ? error.message : "Unknown error" }, null, 2) }]
1063
+ };
1064
+ }
1065
+ }
1066
+ );
1067
+ server.tool(
1068
+ "analytics_export_status",
1069
+ "Get the status of an analytics export and its download link. Returns export_job (export_status, rows_count, is_truncated, file_name, file_size_bytes, error_text, expires_time), download_url and download_url_expires_time. download_url is null until export_status is DONE. " + EXPORT_FLOW_HINT,
1070
+ {
1071
+ export_id: z7.string().describe("The export ID (_id returned by analytics_export_create)")
1072
+ },
1073
+ async ({ export_id }) => {
1074
+ const client = getAnalyticsApiClient();
1075
+ const result = await client.get(apiPath`/analytics_exports/get_export/${export_id}`);
1076
+ return {
1077
+ content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
1078
+ };
1079
+ }
1080
+ );
1081
+ server.tool(
1082
+ "analytics_exports_list",
1083
+ "List the 20 newest analytics exports of an org (org_id from analytics_orgs_list or MCP_ANALYTICS_ORG_ID), newest first, without download links. Call analytics_export_status with an export _id to get its download link",
1084
+ {
1085
+ org_id: z7.string().optional().describe("The analytics org ID from analytics_orgs_list (uses MCP_ANALYTICS_ORG_ID env if not provided)"),
1086
+ app_project_id: z7.string().optional().describe("Only exports of this analytics app project")
1087
+ },
1088
+ async ({ org_id, app_project_id }) => {
1089
+ try {
1090
+ const resolvedOrgId = getAnalyticsOrgId(org_id);
1091
+ const client = getAnalyticsApiClient();
1092
+ const result = await client.get(apiPath`/analytics_exports/get_exports_list/${resolvedOrgId}`, { app_project_id });
1093
+ return {
1094
+ content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
1095
+ };
1096
+ } catch (error) {
1097
+ return {
1098
+ content: [{ type: "text", text: JSON.stringify({ success: false, error: error instanceof Error ? error.message : "Unknown error" }, null, 2) }]
1099
+ };
1100
+ }
1101
+ }
1102
+ );
1103
+ };
1104
+
907
1105
  // src/index.ts
908
1106
  var SERVER_NAME = "nana800-mcp-server";
909
- var SERVER_VERSION = "1.1.0";
1107
+ var SERVER_VERSION = "1.2.1";
910
1108
  var main = async () => {
911
1109
  const apiKey = process.env.MCP_API_KEY;
912
1110
  if (!apiKey) {
@@ -924,6 +1122,7 @@ var main = async () => {
924
1122
  registerNodeProcessTools(server);
925
1123
  registerSchemeProcessTools(server);
926
1124
  registerPaymentAccountTools(server);
1125
+ registerAnalyticsExportTools(server);
927
1126
  const transport = new StdioServerTransport();
928
1127
  await server.connect(transport);
929
1128
  };
package/package.json CHANGED
@@ -1,6 +1,7 @@
1
1
  {
2
2
  "name": "nana800-mcp-server",
3
- "version": "1.1.0",
3
+ "version": "1.2.1",
4
+ "mcpName": "io.nana800/mcp-server",
4
5
  "description": "MCP Server for nana800.io Public API - enables AI IDEs to interact with your no-code projects",
5
6
  "type": "module",
6
7
  "license": "MIT",