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.
- package/README.md +183 -110
- package/dist/index.js +209 -10
- package/package.json +2 -1
package/README.md
CHANGED
|
@@ -1,178 +1,251 @@
|
|
|
1
1
|
# nana800 MCP Server
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/nana800-mcp-server)
|
|
4
|
+
[](LICENSE)
|
|
4
5
|
|
|
5
|
-
|
|
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
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
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
|
-
##
|
|
18
|
+
## 🔑 Get an API key
|
|
14
19
|
|
|
15
|
-
1.
|
|
16
|
-
2.
|
|
17
|
-
3.
|
|
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
|
-
|
|
24
|
+
The key acts as your user: the tools see and change only the projects your account has access to.
|
|
20
25
|
|
|
21
|
-
|
|
26
|
+
## 🚀 Quick start
|
|
22
27
|
|
|
23
|
-
|
|
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": "
|
|
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
|
-
|
|
49
|
+
Restart Claude Desktop after saving.
|
|
42
50
|
|
|
43
|
-
|
|
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": "
|
|
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
|
|
77
|
+
### VS Code
|
|
62
78
|
|
|
63
|
-
Add to
|
|
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
|
-
"
|
|
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": "
|
|
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
|
-
|
|
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
|
|
87
|
-
| `MCP_SCHEME_ID` | No | Default scheme ID
|
|
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
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
| `
|
|
100
|
-
| `
|
|
101
|
-
| `
|
|
102
|
-
| `
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
| `
|
|
110
|
-
| `
|
|
111
|
-
| `
|
|
112
|
-
| `
|
|
113
|
-
| `
|
|
114
|
-
| `
|
|
115
|
-
| `
|
|
116
|
-
| `
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
| `
|
|
124
|
-
| `
|
|
125
|
-
| `
|
|
126
|
-
| `
|
|
127
|
-
| `
|
|
128
|
-
| `
|
|
129
|
-
| `
|
|
130
|
-
| `node_connect` | Connect two nodes
|
|
131
|
-
| `node_disconnect` |
|
|
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
|
-
| `
|
|
134
|
-
|
|
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
|
-
###
|
|
180
|
+
### Payment account
|
|
137
181
|
|
|
138
|
-
| Tool |
|
|
139
|
-
|
|
140
|
-
| `
|
|
141
|
-
| `
|
|
142
|
-
| `
|
|
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
|
-
###
|
|
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
|
-
|
|
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
|
-
|
|
220
|
+
## 💬 Example prompts
|
|
153
221
|
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
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
|
-
##
|
|
231
|
+
## 🔗 Links
|
|
163
232
|
|
|
164
|
-
|
|
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
|
-
|
|
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
|
-
|
|
242
|
+
**nana800-mcp-server** - MCP-сервер для [nana800.io](https://nana800.io), no-code платформы для серверной логики и автоматизации. Через него ИИ-ассистент (Claude, Cursor, VS Code) создаёт проекты и схемы, добавляет и связывает блоки, смотрит историю запусков, данные платёжного аккаунта и выгружает аналитику в CSV или JSON Lines.
|
|
174
243
|
|
|
175
|
-
|
|
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
|
-
|
|
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(`${
|
|
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
|
-
|
|
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
|
|
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/
|
|
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
|
|
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
|
|
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",
|