nana800-mcp-server 1.1.0 → 1.2.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 +37 -3
  2. package/dist/index.js +207 -8
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -31,7 +31,8 @@ Add to your `~/.cursor/mcp.json`:
31
31
  "env": {
32
32
  "MCP_API_KEY": "your_api_key_here",
33
33
  "MCP_PROJECT_ID": "your_default_project_id",
34
- "MCP_SCHEME_ID": "your_default_scheme_id"
34
+ "MCP_SCHEME_ID": "your_default_scheme_id",
35
+ "MCP_ANALYTICS_ORG_ID": "your_default_analytics_org_id"
35
36
  }
36
37
  }
37
38
  }
@@ -51,7 +52,8 @@ Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_
51
52
  "env": {
52
53
  "MCP_API_KEY": "your_api_key_here",
53
54
  "MCP_PROJECT_ID": "your_default_project_id",
54
- "MCP_SCHEME_ID": "your_default_scheme_id"
55
+ "MCP_SCHEME_ID": "your_default_scheme_id",
56
+ "MCP_ANALYTICS_ORG_ID": "your_default_analytics_org_id"
55
57
  }
56
58
  }
57
59
  }
@@ -71,7 +73,8 @@ Add to your extension settings:
71
73
  "env": {
72
74
  "MCP_API_KEY": "your_api_key_here",
73
75
  "MCP_PROJECT_ID": "your_default_project_id",
74
- "MCP_SCHEME_ID": "your_default_scheme_id"
76
+ "MCP_SCHEME_ID": "your_default_scheme_id",
77
+ "MCP_ANALYTICS_ORG_ID": "your_default_analytics_org_id"
75
78
  }
76
79
  }
77
80
  }
@@ -86,6 +89,8 @@ Add to your extension settings:
86
89
  | `MCP_PROJECT_ID` | No | Default project ID (can be overridden per tool call) |
87
90
  | `MCP_SCHEME_ID` | No | Default scheme ID (can be overridden per tool call) |
88
91
  | `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
+ | `MCP_ANALYTICS_API_URL` | No | Analytics API origin, `https://api.analytics.nana800.io` by default |
89
94
 
90
95
  Every API request has a 30 second timeout. Requires Node.js 18 or newer.
91
96
 
@@ -159,6 +164,34 @@ Every API request has a 30 second timeout. Requires Node.js 18 or newer.
159
164
  | `payment_account_remove` | Remove payment account |
160
165
  | `payment_account_get_transactions` | Get transaction history |
161
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
+ |------|-------------|
173
+ | `analytics_orgs_list` | List analytics orgs the API key owner is a member of |
174
+ | `analytics_projects_list` | List app projects of an analytics org |
175
+ | `analytics_event_types_list` | List tracked event types of an app project, for export filters |
176
+ | `analytics_export_create` | Start an export of events (`EVENTS`), events of one user (`USER_EVENTS`) or users (`USERS`) to CSV or JSONL |
177
+ | `analytics_export_status` | Get export status (`QUEUED`, `RUNNING`, `DONE`, `FAILED`) and the download link when it is done |
178
+ | `analytics_exports_list` | List the 20 newest exports of an org |
179
+
180
+ Export limits:
181
+
182
+ - Up to 1,000,000 rows per file, `is_truncated` is `true` when more rows matched
183
+ - 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`
185
+ - Poll `analytics_export_status` not more often than once per ~10 seconds
186
+ - The download link is valid for 15 minutes, call `analytics_export_status` again for a fresh one
187
+ - Files are deleted after 7 days
188
+
189
+ The file is served gzipped (`Content-Encoding: gzip`). A browser saves plain CSV or JSONL, from a shell use:
190
+
191
+ ```bash
192
+ curl --compressed -o export.csv "<download_url>"
193
+ ```
194
+
162
195
  ## Usage Examples
163
196
 
164
197
  Once configured, you can ask your AI assistant things like:
@@ -169,6 +202,7 @@ Once configured, you can ask your AI assistant things like:
169
202
  - "Connect the webhook trigger to the email action"
170
203
  - "Export the scheme configuration"
171
204
  - "What processes are currently running?"
205
+ - "Export all purchase events of the last week to CSV and give me the download link"
172
206
 
173
207
  ## API Documentation
174
208
 
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) => {
@@ -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.0";
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,6 @@
1
1
  {
2
2
  "name": "nana800-mcp-server",
3
- "version": "1.1.0",
3
+ "version": "1.2.0",
4
4
  "description": "MCP Server for nana800.io Public API - enables AI IDEs to interact with your no-code projects",
5
5
  "type": "module",
6
6
  "license": "MIT",