nana800-mcp-server 1.2.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 +160 -121
  2. package/dist/index.js +3 -3
  3. package/package.json +2 -1
package/README.md CHANGED
@@ -1,175 +1,196 @@
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.
25
+
26
+ ## 🚀 Quick start
27
+
28
+ ### Claude Desktop
20
29
 
21
- ### Cursor IDE
30
+ Open Settings -> Developer -> Edit Config, or the file directly:
22
31
 
23
- Add to your `~/.cursor/mcp.json`:
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",
35
- "MCP_ANALYTICS_ORG_ID": "your_default_analytics_org_id"
42
+ "MCP_API_KEY": "your_api_key"
36
43
  }
37
44
  }
38
45
  }
39
46
  }
40
47
  ```
41
48
 
42
- ### Claude Desktop
49
+ Restart Claude Desktop after saving.
50
+
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
43
60
 
44
- Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
61
+ Add to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project):
45
62
 
46
63
  ```json
47
64
  {
48
65
  "mcpServers": {
49
66
  "nana800": {
50
67
  "command": "npx",
51
- "args": ["nana800-mcp-server"],
68
+ "args": ["-y", "nana800-mcp-server"],
52
69
  "env": {
53
- "MCP_API_KEY": "your_api_key_here",
54
- "MCP_PROJECT_ID": "your_default_project_id",
55
- "MCP_SCHEME_ID": "your_default_scheme_id",
56
- "MCP_ANALYTICS_ORG_ID": "your_default_analytics_org_id"
70
+ "MCP_API_KEY": "your_api_key"
57
71
  }
58
72
  }
59
73
  }
60
74
  }
61
75
  ```
62
76
 
63
- ### VS Code with Cline/Continue
77
+ ### VS Code
64
78
 
65
- 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:
66
80
 
67
81
  ```json
68
82
  {
69
- "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": {
70
92
  "nana800": {
93
+ "type": "stdio",
71
94
  "command": "npx",
72
- "args": ["nana800-mcp-server"],
95
+ "args": ["-y", "nana800-mcp-server"],
73
96
  "env": {
74
- "MCP_API_KEY": "your_api_key_here",
75
- "MCP_PROJECT_ID": "your_default_project_id",
76
- "MCP_SCHEME_ID": "your_default_scheme_id",
77
- "MCP_ANALYTICS_ORG_ID": "your_default_analytics_org_id"
97
+ "MCP_API_KEY": "${input:nana800-api-key}"
78
98
  }
79
99
  }
80
100
  }
81
101
  }
82
102
  ```
83
103
 
84
- ## 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
85
113
 
86
114
  | Variable | Required | Description |
87
115
  |----------|----------|-------------|
88
- | `MCP_API_KEY` | Yes | Your nana800.io API key |
89
- | `MCP_PROJECT_ID` | No | Default project ID (can be overridden per tool call) |
90
- | `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 |
91
120
  | `MCP_API_URL` | No | API origin, `https://api.nana800.io` by default |
92
- | `MCP_ANALYTICS_ORG_ID` | No | Default analytics org ID (can be overridden per tool call), get it with `analytics_orgs_list` or from the `org` parameter in the analytics page URL |
93
121
  | `MCP_ANALYTICS_API_URL` | No | Analytics API origin, `https://api.analytics.nana800.io` by default |
94
122
 
95
- Every API request has a 30 second timeout. Requires Node.js 18 or newer.
96
-
97
- ## Available Tools
98
-
99
- ### Project Management
100
-
101
- | Tool | Description |
102
- |------|-------------|
103
- | `project_create` | Create a new project |
104
- | `project_get` | Get project details by ID |
105
- | `project_list_by_payment_account` | List projects by payment account |
106
- | `project_update` | Update project properties |
107
- | `project_delete` | Delete a project |
108
-
109
- ### Scheme Management
110
-
111
- | Tool | Description |
112
- |------|-------------|
113
- | `scheme_create` | Create a new scheme (workflow) |
114
- | `scheme_get` | Get scheme details |
115
- | `scheme_list_by_project` | List all schemes in a project |
116
- | `scheme_update` | Update scheme name, description and enable or disable it |
117
- | `scheme_delete` | Delete a scheme |
118
- | `scheme_export` | Export scheme as JSON |
119
- | `scheme_import` | Import nodes into a scheme |
120
- | `scheme_get_context_type` | Get scheme context type |
121
- | `scheme_get_swagger_json` | Get OpenAPI spec for scheme |
122
-
123
- ### Node Management
124
-
125
- | Tool | Description |
126
- |------|-------------|
127
- | `get_nodes_info` | List available trigger and action types with their configuration |
128
- | `node_create_trigger` | Create a trigger node |
129
- | `node_create_action` | Create an action node |
130
- | `node_get` | Get node details |
131
- | `node_list_by_scheme` | List all nodes in a scheme |
132
- | `node_update` | Update node properties |
133
- | `node_update_config` | Update node configuration |
134
- | `node_delete` | Delete a node |
135
- | `node_connect` | Connect two nodes (for condition nodes `connection_index` 0 is the "true" output, 1 is the "false" output) |
136
- | `node_disconnect` | Disconnect two nodes |
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 |
137
166
  | `node_copy` | Copy a node |
138
- | `node_get_scheme_edges` | Get all connections in a scheme |
139
- | `node_find_existing_buttons` | Find node output buttons |
167
+ | `node_delete` | Delete a node (irreversible) |
140
168
 
141
- ### Node Process Management
169
+ ### Run history
142
170
 
143
- | Tool | Description |
144
- |------|-------------|
145
- | `node_process_get` | Get node process details |
146
- | `node_process_list_filtered` | List node processes, filter by scheme, node or scheme process is required |
147
- | `node_process_delete` | Delete a node process record |
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 |
148
179
 
149
- ### Scheme Process Management
180
+ ### Payment account
150
181
 
151
- | Tool | Description |
152
- |------|-------------|
153
- | `scheme_process_get` | Get scheme process details |
154
- | `scheme_process_list_filtered` | List scheme processes, filter by scheme or project is required |
155
- | `scheme_process_delete` | Delete a scheme 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 |
156
189
 
157
- ### Payment Account Management
190
+ ### Analytics data export
158
191
 
159
- | Tool | Description |
160
- |------|-------------|
161
- | `payment_account_get_by_user` | Get payment account by user ID |
162
- | `payment_account_get_by_project` | Get payment account by project ID |
163
- | `payment_account_update` | Update payment account name and automatic balance refill |
164
- | `payment_account_remove` | Remove payment account |
165
- | `payment_account_get_transactions` | Get transaction history |
166
-
167
- ### Analytics Data Export
168
-
169
- The API key user must be a member of the analytics org. The org ID (`org_id`) comes from `analytics_orgs_list`, the `MCP_ANALYTICS_ORG_ID` env variable or the `org` parameter in the analytics page URL. Exports run in the background and the tools return only the status and a download link, never the rows.
170
-
171
- | Tool | Description |
172
- |------|-------------|
192
+ | Tool | What it does |
193
+ |------|--------------|
173
194
  | `analytics_orgs_list` | List analytics orgs the API key owner is a member of |
174
195
  | `analytics_projects_list` | List app projects of an analytics org |
175
196
  | `analytics_event_types_list` | List tracked event types of an app project, for export filters |
@@ -177,11 +198,13 @@ The API key user must be a member of the analytics org. The org ID (`org_id`) co
177
198
  | `analytics_export_status` | Get export status (`QUEUED`, `RUNNING`, `DONE`, `FAILED`) and the download link when it is done |
178
199
  | `analytics_exports_list` | List the 20 newest exports of an org |
179
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
+
180
203
  Export limits:
181
204
 
182
205
  - Up to 1,000,000 rows per file, `is_truncated` is `true` when more rows matched
183
206
  - One active export per org, 10 exports per org per hour, exports started with an API key: one per 10 minutes per org
184
- - `time_from` and `time_to` are ISO 8601 date-times with a timezone, e.g. `2026-10-01T00:00:00.000Z`
207
+ - `time_from` and `time_to` are ISO 8601 date-times with a timezone, for example `2026-10-01T00:00:00.000Z`
185
208
  - Poll `analytics_export_status` not more often than once per ~10 seconds
186
209
  - The download link is valid for 15 minutes, call `analytics_export_status` again for a fresh one
187
210
  - Files are deleted after 7 days
@@ -192,21 +215,37 @@ The file is served gzipped (`Content-Encoding: gzip`). A browser saves plain CSV
192
215
  curl --compressed -o export.csv "<download_url>"
193
216
  ```
194
217
 
195
- ## Usage Examples
218
+ ⚠️ Delete and remove tools can not be undone. Keep tool call confirmation on in your MCP client for them.
196
219
 
197
- Once configured, you can ask your AI assistant things like:
220
+ ## 💬 Example prompts
198
221
 
199
- - "List all my projects"
200
- - "Create a new scheme called 'Email Notifications' in project X"
201
- - "Show me all nodes in scheme Y"
202
- - "Connect the webhook trigger to the email action"
203
- - "Export the scheme configuration"
204
- - "What processes are currently running?"
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"
205
229
  - "Export all purchase events of the last week to CSV and give me the download link"
206
230
 
207
- ## API Documentation
231
+ ## 🔗 Links
232
+
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)
239
+
240
+ ## 🇷🇺 На русском
241
+
242
+ **nana800-mcp-server** - MCP-сервер для [nana800.io](https://nana800.io), no-code платформы для серверной логики и автоматизации. Через него ИИ-ассистент (Claude, Cursor, VS Code) создаёт проекты и схемы, добавляет и связывает блоки, смотрит историю запусков, данные платёжного аккаунта и выгружает аналитику в CSV или JSON Lines.
208
243
 
209
- 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)
210
249
 
211
250
  ## License
212
251
 
package/dist/index.js CHANGED
@@ -343,7 +343,7 @@ var registerSchemeTools = (server) => {
343
343
  );
344
344
  server.tool(
345
345
  "scheme_get_swagger_json",
346
- "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",
347
347
  {
348
348
  scheme_id: z2.string().optional().describe("The unique ID of the scheme (uses MCP_SCHEME_ID env if not provided)")
349
349
  },
@@ -351,7 +351,7 @@ var registerSchemeTools = (server) => {
351
351
  try {
352
352
  const resolvedSchemeId = getSchemeId(scheme_id);
353
353
  const client = getApiClient();
354
- const result = await client.get(apiPath`/scheme/swagger_json/${resolvedSchemeId}`);
354
+ const result = await client.get(apiPath`/scheme/openapi/${resolvedSchemeId}`);
355
355
  return {
356
356
  content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
357
357
  };
@@ -1104,7 +1104,7 @@ var registerAnalyticsExportTools = (server) => {
1104
1104
 
1105
1105
  // src/index.ts
1106
1106
  var SERVER_NAME = "nana800-mcp-server";
1107
- var SERVER_VERSION = "1.2.0";
1107
+ var SERVER_VERSION = "1.2.1";
1108
1108
  var main = async () => {
1109
1109
  const apiKey = process.env.MCP_API_KEY;
1110
1110
  if (!apiKey) {
package/package.json CHANGED
@@ -1,6 +1,7 @@
1
1
  {
2
2
  "name": "nana800-mcp-server",
3
- "version": "1.2.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",