@superglue/cli 1.1.30 → 1.1.32
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/.claude-plugin/plugin.json +1 -1
- package/README.md +17 -5
- package/dist/cli.js +319 -209
- package/dist/skills/superglue/SKILL.md +73 -50
- package/dist/skills/superglue/references/http.md +11 -10
- package/dist/skills/superglue/references/mongodb.md +136 -0
- package/dist/skills/superglue/references/superglue-info.md +30 -10
- package/package.json +1 -1
- package/skills/superglue/SKILL.md +73 -50
- package/skills/superglue/references/http.md +11 -10
- package/skills/superglue/references/mongodb.md +136 -0
- package/skills/superglue/references/superglue-info.md +30 -10
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: superglue
|
|
3
|
-
description: "Build, test, deploy and integrate superglue tools via the sg CLI and superglue SDKs. IMPORTANT — you MUST invoke this skill and read the full reference BEFORE running ANY sg command or writing ANY superglue SDK/REST/webhook integration code. Before using the sg CLI, first check that it is installed (run sg --version; if not found, install with npm install -g @superglue/cli), then verify it is configured
|
|
3
|
+
description: "Build, test, deploy and integrate superglue tools via the sg CLI and superglue SDKs. IMPORTANT — you MUST invoke this skill and read the full reference BEFORE running ANY sg command or writing ANY superglue SDK/REST/webhook integration code. Before using the sg CLI, first check that it is installed (run sg --version; if not found, install with npm install -g @superglue/cli), then verify either that it is configured with sg login or, for headless/API-key auth, that SUPERGLUE_API_KEY and SUPERGLUE_API_ENDPOINT environment variables are set. If not, guide the user through setup first. After reading SKILL.md, also run `sg skill <topic>` for the specific protocols and topics involved."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# superglue CLI (`sg`) — Agent Reference
|
|
7
7
|
|
|
8
|
-
This file is the entry point for operating superglue via the `sg` CLI. It covers setup, tool building, tool editing, system management, running tools, and deployment via SDK/REST/webhooks.
|
|
8
|
+
This file is the entry point for operating superglue via the `sg` CLI. It covers setup, tool building, tool editing, system management, running tools, schedules, and deployment via SDK/REST/webhooks.
|
|
9
9
|
|
|
10
10
|
For protocol-specific details (HTTP, databases, Redis, file servers, GraphQL), file handling, access rules, SDK integration, and general superglue information, run `sg skill <topic>` (linked throughout and listed at the bottom).
|
|
11
11
|
|
|
@@ -23,6 +23,7 @@ Read these on demand — they are authoritative for their topic and kept in sync
|
|
|
23
23
|
| `sg skill mssql` | MSSQL / Azure SQL connection URLs, schema introspection, parameterized queries |
|
|
24
24
|
| `sg skill odbc` | ODBC connections (SAP ASE / Sybase via FreeTDS), driver config, positional `?` params |
|
|
25
25
|
| `sg skill redis` | Redis command syntax, connection URLs, key type handling |
|
|
26
|
+
| `sg skill mongodb` | MongoDB connection URLs (mongodb:// / mongodb+srv://), CRUD operations, Extended JSON, aggregation |
|
|
26
27
|
| `sg skill sftp-smb` | SFTP, FTP, and SMB operations, file upload/download semantics, path handling |
|
|
27
28
|
| `sg skill file-handling` | File detection, parsing, `file::` reference syntax, lazy base64 access, transform-produced files |
|
|
28
29
|
| `sg skill access-rules` | RBAC roles, resource grants, and tool/system permissions (enterprise only) |
|
|
@@ -33,7 +34,7 @@ Read these on demand — they are authoritative for their topic and kept in sync
|
|
|
33
34
|
|
|
34
35
|
1. **Check CLI exists**: Run `sg --version`. If it fails with `command not found`, install: `npm install -g @superglue/cli`.
|
|
35
36
|
2. **Keep CLI and SDK up to date**: Always use the latest versions. Run `sg update` to update the CLI. For the SDK, run `npm install @superglue/client@latest` (JS) or `pip install --upgrade superglue-client` (Python).
|
|
36
|
-
3. **Verify configuration**: Run `sg system list`. If it fails with `fetch failed` or auth errors, the CLI needs configuration via `sg
|
|
37
|
+
3. **Verify configuration**: Run `sg whoami` or `sg system list`. If it fails with `fetch failed` or auth errors, the CLI needs configuration via `sg login` (see Setup below). For custom/self-hosted instances, the CLI must know the instance API endpoint; browser login also needs the web app endpoint when it differs from the API URL. Use API-key auth only for headless/legacy environments.
|
|
37
38
|
|
|
38
39
|
**Calling systems and running tools**
|
|
39
40
|
|
|
@@ -67,26 +68,22 @@ npm install -g @superglue/cli
|
|
|
67
68
|
|
|
68
69
|
After installation the `sg` command is available globally.
|
|
69
70
|
|
|
70
|
-
###
|
|
71
|
+
### Authentication
|
|
71
72
|
|
|
72
|
-
The CLI
|
|
73
|
+
The preferred CLI setup is browser OAuth via `sg login`. Headless/API-key auth is available for CI and legacy automation. The API endpoint defaults to `https://api.superglue.cloud`.
|
|
73
74
|
|
|
74
|
-
**
|
|
75
|
+
**Browser login (humans):**
|
|
75
76
|
|
|
76
77
|
```bash
|
|
77
|
-
sg
|
|
78
|
+
sg login
|
|
79
|
+
sg --endpoint "https://custom-api.example.com" login --web-endpoint "https://custom-app.example.com" --save-config
|
|
78
80
|
```
|
|
79
81
|
|
|
80
|
-
|
|
82
|
+
Opens the browser, completes OAuth login, and stores the OAuth session in `~/.superglue/auth.json`. This file is separate from `config.json`. Use `--save-config` to persist non-secret endpoint settings in `config.json`, and `sg logout` to remove the OAuth session.
|
|
81
83
|
|
|
82
|
-
**
|
|
84
|
+
**Headless/API-key auth (CI, agents, backwards-compatible):**
|
|
83
85
|
|
|
84
|
-
|
|
85
|
-
sg init --api-key "your-api-key" --global
|
|
86
|
-
sg init --api-key "your-api-key" --endpoint "https://custom.endpoint.com" --global
|
|
87
|
-
```
|
|
88
|
-
|
|
89
|
-
`--api-key` and `--endpoint` are global flags and work on all subcommands.
|
|
86
|
+
Use environment variables, global flags, or an existing `.superglue/config.json`. `sg init` remains available as a legacy hidden command for scripts that already use it, but new setup should prefer `sg login` for humans and env vars/config files for headless API-key auth.
|
|
90
87
|
|
|
91
88
|
**Environment variables (no config file):**
|
|
92
89
|
|
|
@@ -95,19 +92,19 @@ export SUPERGLUE_API_KEY="your-api-key"
|
|
|
95
92
|
export SUPERGLUE_API_ENDPOINT="https://api.superglue.cloud" # optional, this is the default
|
|
96
93
|
```
|
|
97
94
|
|
|
98
|
-
**Config resolution order:** CLI flags > environment variables > local `.superglue/config.json` > global `~/.superglue/config.json`.
|
|
95
|
+
**Config resolution order:** CLI flags > environment variables > local `.superglue/config.json` > global `~/.superglue/config.json`. For authentication, API keys from flags/env/config take precedence; if no API key is configured, the CLI uses the matching OAuth session from `~/.superglue/auth.json`.
|
|
99
96
|
|
|
100
|
-
Verify with `sg system list` — should return
|
|
97
|
+
Verify with `sg whoami` or `sg system list` — should return authenticated context without errors.
|
|
101
98
|
|
|
102
99
|
### Capability Presets
|
|
103
100
|
|
|
104
|
-
Set
|
|
101
|
+
Set via `SUPERGLUE_CLI_PRESET` env var or `config.json` as `"preset"`. Legacy `sg init --preset` still writes this value for existing scripts.
|
|
105
102
|
|
|
106
|
-
| Preset | Description
|
|
107
|
-
| --------- |
|
|
108
|
-
| `runner` | Run saved tools by ID only. Read-only lookups. No building/editing
|
|
109
|
-
| `builder` | Runner + build/edit/save tools, call systems, manage MCP servers. No system CRUD |
|
|
110
|
-
| `admin` | Full access (default)
|
|
103
|
+
| Preset | Description |
|
|
104
|
+
| --------- | ---------------------------------------------------------------------------------------------- |
|
|
105
|
+
| `runner` | Run saved tools by ID only. Read-only lookups. No building/editing |
|
|
106
|
+
| `builder` | Runner + build/edit/save tools, call systems, manage MCP servers and schedules. No system CRUD |
|
|
107
|
+
| `admin` | Full access (default) |
|
|
111
108
|
|
|
112
109
|
Blocked commands print a clear error showing the current preset and how to change it.
|
|
113
110
|
|
|
@@ -148,7 +145,7 @@ Blocked commands print a clear error showing the current preset and how to chang
|
|
|
148
145
|
1. Search for an existing system first: `sg system find <query>`
|
|
149
146
|
2. If creating: `sg system create --name "..." --url "..." --credentials '{...}'`. Prefer `--template <id>` when one exists — it auto-fills URL and OAuth config
|
|
150
147
|
3. For OAuth: `sg system oauth --system-id <id> [--scopes "..."]` opens a browser flow. User approves → tokens saved automatically
|
|
151
|
-
4. For
|
|
148
|
+
4. For non-OAuth credentials: `sg system credentials set --system-id <id> --credentials '{...}'`
|
|
152
149
|
5. Verify connectivity with `sg system call`
|
|
153
150
|
6. For updates: `sg system edit --id <id>` with the fields to change
|
|
154
151
|
|
|
@@ -185,6 +182,26 @@ Auth modes:
|
|
|
185
182
|
|
|
186
183
|
If `sg mcp ...` returns "MCP server management is not available", the target instance or plan does not support named MCP server management. The default all-tools MCP endpoint may still be usable at `<api-endpoint>/mcp`.
|
|
187
184
|
|
|
185
|
+
### Creating/Editing Tool Schedules
|
|
186
|
+
|
|
187
|
+
Schedules run saved tools on cron expressions. Use 5-field cron syntax and an IANA timezone.
|
|
188
|
+
|
|
189
|
+
```bash
|
|
190
|
+
sg schedule list
|
|
191
|
+
sg schedule list --tool <toolId>
|
|
192
|
+
sg schedule create --tool daily_report --cron "0 9 * * 1-5" --timezone UTC
|
|
193
|
+
sg schedule edit --tool daily_report --id <scheduleId> --disabled
|
|
194
|
+
sg schedule edit --tool daily_report --id <scheduleId> --cron "0 8 * * *" --timezone UTC
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
Optional flags:
|
|
198
|
+
|
|
199
|
+
- `--payload '{"key":"value"}'` or `--payload-file payload.json` sets the scheduled run payload.
|
|
200
|
+
- `--webhook-url <url>` posts results to a webhook after success.
|
|
201
|
+
- `--tool-chain <toolId>` runs another saved tool after success.
|
|
202
|
+
- `--retries <n>` and `--timeout <ms>` set request options.
|
|
203
|
+
- `--clear-webhook` removes the webhook/tool-chain success action during edit.
|
|
204
|
+
|
|
188
205
|
---
|
|
189
206
|
|
|
190
207
|
## Reference
|
|
@@ -193,31 +210,37 @@ If `sg mcp ...` returns "MCP server management is not available", the target ins
|
|
|
193
210
|
|
|
194
211
|
Agents familiar with the web tool names can map them directly to CLI commands:
|
|
195
212
|
|
|
196
|
-
| Web agent tool | CLI command
|
|
197
|
-
| ------------------------------------------------ |
|
|
198
|
-
| `build_tool` | `sg tool build --config '{...}'`
|
|
199
|
-
| `edit_tool` | `sg tool edit --tool <id> --patches '[...]'`
|
|
200
|
-
| `run_tool` | `sg tool run --tool <id>` / `--draft <id>`
|
|
201
|
-
| `save_tool` | `sg tool save --draft <draftId>`
|
|
202
|
-
| `run_command` with `vfs` for `/org/tools/` | `sg tool find --id <id>` / `sg tool find <q>`
|
|
203
|
-
| `create_system` | `sg system create --name "..." --url "..."`
|
|
204
|
-
| `edit_system` | `sg system edit --id <id> ...`
|
|
205
|
-
| `run_command` with `vfs` for `/org/systems/` | `sg system find <query>` / `--id <id>`
|
|
206
|
-
| Credentials VFS /
|
|
207
|
-
| `call_system` | `sg system call --url "..." --system-id <id>`
|
|
208
|
-
| `run_command search` | `sg system search-docs --system-id <id> -k`
|
|
209
|
-
| `authenticate_oauth` | `sg system oauth --system-id <id> [--scopes]`
|
|
210
|
-
| `run_command` with `vfs` for `/org/runs/` | `sg run list` / `sg run get <runId>`
|
|
211
|
-
| `run_command` with `vfs` for `/org/mcp-servers/` | `sg mcp list` / `sg mcp find --id <id>`
|
|
212
|
-
| `create_mcp_server` | `sg mcp create --name <n> --tool <id>`
|
|
213
|
-
| `edit_mcp_server` | `sg mcp edit --id <id> ...`
|
|
214
|
-
|
|
|
215
|
-
|
|
216
|
-
|
|
213
|
+
| Web agent tool | CLI command | Notes |
|
|
214
|
+
| ------------------------------------------------ | ---------------------------------------------- | ------------------------------------------------------------------ |
|
|
215
|
+
| `build_tool` | `sg tool build --config '{...}'` | CLI is not AI-powered — you provide the full JSON config |
|
|
216
|
+
| `edit_tool` | `sg tool edit --tool <id> --patches '[...]'` | JSON Patch (RFC 6902). Use `--draft <id>` for drafts |
|
|
217
|
+
| `run_tool` | `sg tool run --tool <id>` / `--draft <id>` | Add `--include-step-results` to inspect per-step data |
|
|
218
|
+
| `save_tool` | `sg tool save --draft <draftId>` | Persists a draft to the database |
|
|
219
|
+
| `run_command` with `vfs` for `/org/tools/` | `sg tool find --id <id>` / `sg tool find <q>` | Full config with `--id`, compact search with a query string |
|
|
220
|
+
| `create_system` | `sg system create --name "..." --url "..."` | Use `--template <id>` when available |
|
|
221
|
+
| `edit_system` | `sg system edit --id <id> ...` | Supports `--env dev\|prod` |
|
|
222
|
+
| `run_command` with `vfs` for `/org/systems/` | `sg system find <query>` / `--id <id>` | Returns `storedCredentials` and system URL |
|
|
223
|
+
| Credentials VFS / saved credentials | `sg system credentials get/set/clear` | Manage the current user's credentials for a system |
|
|
224
|
+
| `call_system` | `sg system call --url "..." --system-id <id>` | Authenticated ad-hoc calls for testing / schema introspection |
|
|
225
|
+
| `run_command search` | `sg system search-docs --system-id <id> -k` | Targeted keyword search over ingested system docs |
|
|
226
|
+
| `authenticate_oauth` | `sg system oauth --system-id <id> [--scopes]` | Opens browser flow. Supports `--grant-type client_credentials` too |
|
|
227
|
+
| `run_command` with `vfs` for `/org/runs/` | `sg run list` / `sg run get <runId>` | Filter `list` by `--tool`, `--status`, `--source`, `--limit` |
|
|
228
|
+
| `run_command` with `vfs` for `/org/mcp-servers/` | `sg mcp list` / `sg mcp find --id <id>` | Returns endpoint, auth mode, selected tool IDs, and client config |
|
|
229
|
+
| `create_mcp_server` | `sg mcp create --name <n> --tool <id>` | Creates a named MCP endpoint for selected saved tools |
|
|
230
|
+
| `edit_mcp_server` | `sg mcp edit --id <id> ...` | Edits name, auth mode, description, or selected tool IDs |
|
|
231
|
+
| `create_schedule` | `sg schedule create --tool <id> --cron <expr>` | Creates a cron schedule for a saved tool |
|
|
232
|
+
| `edit_schedule` | `sg schedule edit --tool <id> --id <schedule>` | Updates, enables, or disables an existing schedule |
|
|
233
|
+
| (no direct equivalent) | `sg login`, `sg update`, `sg skill` | CLI-specific setup, updater, and this reference system |
|
|
234
|
+
|
|
235
|
+
Web-agent-only concepts with no CLI equivalent: `run_command`'s virtual filesystem (CLI uses concrete `sg` subcommands), `authenticate_oauth`'s dedicated MCP `authenticate` tool (CLI uses `sg system oauth`).
|
|
217
236
|
|
|
218
237
|
### Command Reference
|
|
219
238
|
|
|
220
|
-
**`sg
|
|
239
|
+
**`sg login`** — Browser OAuth setup. Stores the OAuth session in `~/.superglue/auth.json`. Flags: `--web-endpoint`, `--no-browser`, `--save-config`, `--global`. Use global `--endpoint` for custom/self-hosted API URLs.
|
|
240
|
+
|
|
241
|
+
**`sg logout`** — Removes the stored OAuth session from `~/.superglue/auth.json`.
|
|
242
|
+
|
|
243
|
+
**`sg whoami`** — Shows the authenticated superglue user and organization.
|
|
221
244
|
|
|
222
245
|
**Tool commands:**
|
|
223
246
|
|
|
@@ -313,7 +336,7 @@ Attach files with repeatable `--file key=path`. Reference in payloads with `file
|
|
|
313
336
|
}
|
|
314
337
|
```
|
|
315
338
|
|
|
316
|
-
**Request step fields** (HTTP, Postgres, MSSQL, Redis, FTP/SFTP, SMB) — see protocol-specific references for full details:
|
|
339
|
+
**Request step fields** (HTTP, Postgres, MSSQL, Redis, MongoDB, FTP/SFTP, SMB) — see protocol-specific references for full details:
|
|
317
340
|
|
|
318
341
|
| Field | Type | Description |
|
|
319
342
|
| ------------- | ------ | ------------------------------------------------------------------------ |
|
|
@@ -495,7 +518,7 @@ Basic auth auto-encodes: if the value after `Basic ` isn't already base64, the e
|
|
|
495
518
|
**Credential lifecycle:**
|
|
496
519
|
|
|
497
520
|
- Pass ALL credentials (including secrets) via `--credentials '{"api_key":"...","client_secret":"..."}'` on create/edit
|
|
498
|
-
-
|
|
521
|
+
- Use `sg system credentials set --system-id <id> --credentials '{...}'` to save credentials for the current API-key user
|
|
499
522
|
- Use `sg system credentials get --system-id <id>` to inspect current-user credential keys; values are masked unless `--reveal` is passed
|
|
500
523
|
- OAuth tokens (`access_token`, `refresh_token`) auto-refresh before each step execution
|
|
501
524
|
- Non-sensitive fields (`client_id`, `auth_url`, `token_url`) are stored alongside secrets in the same `--credentials` JSON
|
|
@@ -564,7 +587,7 @@ Drafts live under the active CLI config directory: local `.superglue/drafts/` wh
|
|
|
564
587
|
|
|
565
588
|
After building and saving, tools can be invoked from code via REST API, SDK, or webhook. See `sg skill integration` for complete SDK (TypeScript/Python), REST API, and webhook examples including retry patterns.
|
|
566
589
|
|
|
567
|
-
**IP whitelisting:** if a customer's system requires IP whitelisting
|
|
590
|
+
**IP whitelisting:** if a customer's system requires IP whitelisting for firewall rules, security groups, or vendor access controls, superglue Cloud outbound requests come from `34.234.12.178` and `18.198.191.215`. These IPs apply to superglue Cloud only; self-hosted and enterprise deployments use deployment-specific networking.
|
|
568
591
|
|
|
569
592
|
Quick reference:
|
|
570
593
|
|
|
@@ -607,7 +630,7 @@ curl -X POST "https://api.superglue.cloud/v1/hooks/{toolId}?token=$SUPERGLUE_API
|
|
|
607
630
|
|
|
608
631
|
## Error Recovery
|
|
609
632
|
|
|
610
|
-
For protocol-specific error recovery (HTTP, Postgres, MSSQL, Redis, GraphQL, SFTP/SMB), run `sg skill <protocol>`. General strategies below.
|
|
633
|
+
For protocol-specific error recovery (HTTP, Postgres, MSSQL, Redis, MongoDB, GraphQL, SFTP/SMB), run `sg skill <protocol>`. General strategies below.
|
|
611
634
|
|
|
612
635
|
### Tool build fails validation
|
|
613
636
|
|
|
@@ -19,15 +19,15 @@ All fields support `<<variable>>` and `<<(sourceData) => ...>>` expressions.
|
|
|
19
19
|
|
|
20
20
|
### Fields
|
|
21
21
|
|
|
22
|
-
| Field | Required | Notes
|
|
23
|
-
| ------------- | -------- |
|
|
24
|
-
| `url` | yes |
|
|
25
|
-
| `method` | yes | `GET`, `POST`, `PUT`, `DELETE`, `PATCH`
|
|
26
|
-
| `headers` | no | Auth headers, content type, custom headers
|
|
27
|
-
| `queryParams` | no | Key-value pairs appended to URL
|
|
28
|
-
| `body` | no | Stripped for GET/HEAD/DELETE/OPTIONS
|
|
29
|
-
| `pagination` | no | See Pagination section
|
|
30
|
-
| `systemId` | no | Links system credentials and URL. Omit for public APIs
|
|
22
|
+
| Field | Required | Notes |
|
|
23
|
+
| ------------- | -------- | ------------------------------------------------------------------------------------------------------------ |
|
|
24
|
+
| `url` | yes | Use `<<systemId_url>>` for the base; join with exactly one `/` (the system's `url` may or may not end in `/` |
|
|
25
|
+
| `method` | yes | `GET`, `POST`, `PUT`, `DELETE`, `PATCH` |
|
|
26
|
+
| `headers` | no | Auth headers, content type, custom headers |
|
|
27
|
+
| `queryParams` | no | Key-value pairs appended to URL |
|
|
28
|
+
| `body` | no | Stripped for GET/HEAD/DELETE/OPTIONS |
|
|
29
|
+
| `pagination` | no | See Pagination section |
|
|
30
|
+
| `systemId` | no | Links system credentials and URL. Omit for public APIs |
|
|
31
31
|
|
|
32
32
|
For APIs that require the same query key multiple times, use an array value:
|
|
33
33
|
`{ metadataHeaders: ["From", "Subject"] }` -> `?metadataHeaders=From&metadataHeaders=Subject`.
|
|
@@ -237,7 +237,8 @@ When an HTTP step downloads a file (PDF, CSV, binary response), set `outputFile:
|
|
|
237
237
|
|
|
238
238
|
## Common Pitfalls
|
|
239
239
|
|
|
240
|
-
- Hardcoding base URLs
|
|
240
|
+
- Hardcoding base URLs instead of using `<<systemId_url>>`.
|
|
241
|
+
- Wrong slash at the `<<systemId_url>>` join. The placeholder resolves to the system's `url` exactly as stored, which may or may not end in `/`. Read the `url` shown by `sg system find` and write the path so there is exactly one `/` between base and path: against a base with no trailing slash, `<<systemId_url>>crm/v3/...` becomes a broken host (`https://api.hubapi.comcrm/...`) that silently hits the wrong server; against a base ending in `/`, a leading `/` produces `//`.
|
|
241
242
|
- Forgetting auth headers entirely — nothing is injected automatically, including for OAuth systems (only token refresh is automatic)
|
|
242
243
|
- Forgetting `outputFile: true` on steps that download files the user wants
|
|
243
244
|
- Putting pagination variables in the config but not setting a `pagination` block, or vice versa
|
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
# MongoDB
|
|
2
|
+
|
|
3
|
+
## Step Configuration
|
|
4
|
+
|
|
5
|
+
```typescript
|
|
6
|
+
{
|
|
7
|
+
type: "request",
|
|
8
|
+
systemId: "my_mongo",
|
|
9
|
+
url: "mongodb://<<my_mongo_username>>:<<my_mongo_password>>@<<my_mongo_host>>:<<my_mongo_port>>/<<my_mongo_database>>?authSource=admin",
|
|
10
|
+
body: '{"collection": "users", "operation": "find", "filter": {"status": "active"}, "options": {"limit": 50, "sort": {"createdAt": -1}}}'
|
|
11
|
+
}
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
Configure the connection URL based on which credentials are stored in the system — use `sg system find` to check `storedCredentials` and reference them accordingly.
|
|
15
|
+
|
|
16
|
+
`method`, `headers`, `queryParams`, and `pagination` are HTTP-only fields — omit them for MongoDB steps.
|
|
17
|
+
|
|
18
|
+
### Fields
|
|
19
|
+
|
|
20
|
+
| Field | Required | Notes |
|
|
21
|
+
| ---------- | -------- | -------------------------------------------------------------- |
|
|
22
|
+
| `url` | yes | Connection string with `<<credential>>` placeholders |
|
|
23
|
+
| `body` | yes | JSON: single operation object or array of operations |
|
|
24
|
+
| `systemId` | no | Links system credentials for `<<systemId_credKey>>` resolution |
|
|
25
|
+
|
|
26
|
+
### URL Format
|
|
27
|
+
|
|
28
|
+
```
|
|
29
|
+
mongodb://user:password@host:port/database?authSource=admin
|
|
30
|
+
mongodb+srv://user:password@cluster.example.mongodb.net/database (SRV seedlist, e.g. Atlas)
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
- `mongodb://` for a standard host:port connection.
|
|
34
|
+
- `mongodb+srv://` for DNS SRV seedlists (MongoDB Atlas). The driver resolves the seedlist and enables TLS automatically; do not add a port.
|
|
35
|
+
- The default database comes from the URL path; override per operation with a `database` field in the body.
|
|
36
|
+
- Common query params: `authSource` (auth database, usually `admin` for root users), `replicaSet`, `tls`, `retryWrites`.
|
|
37
|
+
- Special characters in the username or password are URL-encoded automatically before the driver parses the string.
|
|
38
|
+
|
|
39
|
+
### Body Format
|
|
40
|
+
|
|
41
|
+
JSON string with `operation` (required) and `collection` (required for all operations except `listCollections`). Bodies are parsed as MongoDB Extended JSON, so `{ "$oid": "..." }` becomes an `ObjectId` and `{ "$date": "..." }` becomes a `Date`:
|
|
42
|
+
|
|
43
|
+
```json
|
|
44
|
+
{
|
|
45
|
+
"collection": "orders",
|
|
46
|
+
"operation": "find",
|
|
47
|
+
"filter": { "_id": { "$oid": "652c1f77bcf86cd799439011" } }
|
|
48
|
+
}
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
For several operations in one step, pass an array (executed in order, results returned as an array):
|
|
52
|
+
|
|
53
|
+
```json
|
|
54
|
+
[
|
|
55
|
+
{ "collection": "orders", "operation": "countDocuments", "filter": { "status": "paid" } },
|
|
56
|
+
{
|
|
57
|
+
"collection": "orders",
|
|
58
|
+
"operation": "find",
|
|
59
|
+
"filter": { "status": "paid" },
|
|
60
|
+
"options": { "limit": 10 }
|
|
61
|
+
}
|
|
62
|
+
]
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
### Supported Operations
|
|
66
|
+
|
|
67
|
+
| Operation | Required fields | Returns |
|
|
68
|
+
| ------------------------------------------------------------- | ------------------------------------------------- | ---------------------------------------------- |
|
|
69
|
+
| `find` | `collection` | array of documents |
|
|
70
|
+
| `findOne` | `collection` | a document or `null` |
|
|
71
|
+
| `aggregate` | `collection`, `pipeline` | array of documents |
|
|
72
|
+
| `countDocuments` | `collection` | number |
|
|
73
|
+
| `estimatedDocumentCount` | `collection` | number |
|
|
74
|
+
| `distinct` | `collection`, `field` | array of values |
|
|
75
|
+
| `listCollections` | — | array of collection info |
|
|
76
|
+
| `insertOne` | `collection`, `document` | `{ acknowledged, insertedId }` |
|
|
77
|
+
| `insertMany` | `collection`, `documents` | `{ acknowledged, insertedCount, insertedIds }` |
|
|
78
|
+
| `updateOne` / `updateMany` | `collection`, `filter`, `update` | `{ matchedCount, modifiedCount, upsertedId }` |
|
|
79
|
+
| `replaceOne` | `collection`, `filter`, `replacement` | update result |
|
|
80
|
+
| `deleteOne` / `deleteMany` | `collection`, `filter` | `{ acknowledged, deletedCount }` |
|
|
81
|
+
| `findOneAndUpdate` / `findOneAndReplace` / `findOneAndDelete` | `collection`, `filter` (+ `update`/`replacement`) | the affected document |
|
|
82
|
+
| `bulkWrite` | `collection`, `operations` | bulk write result |
|
|
83
|
+
|
|
84
|
+
`filter`, `pipeline`, `document`, `update`, `replacement`, and driver `options` (e.g. `limit`, `skip`, `sort`, `projection`, `upsert`) are passed straight through to the driver.
|
|
85
|
+
|
|
86
|
+
Dynamic values with variables:
|
|
87
|
+
|
|
88
|
+
```json
|
|
89
|
+
{
|
|
90
|
+
"collection": "users",
|
|
91
|
+
"operation": "find",
|
|
92
|
+
"filter": { "orgId": "<<(sourceData) => sourceData.orgId>>" }
|
|
93
|
+
}
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
## Authentication
|
|
97
|
+
|
|
98
|
+
Credentials are embedded directly in the connection URL using `<<systemId_credentialKey>>` placeholders. Nothing is injected automatically. Root/admin users almost always need `?authSource=admin`.
|
|
99
|
+
|
|
100
|
+
```
|
|
101
|
+
mongodb://<<my_mongo_username>>:<<my_mongo_password>>@<<my_mongo_host>>:<<my_mongo_port>>/<<my_mongo_database>>?authSource=admin
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
## MongoDB Runtime Details
|
|
105
|
+
|
|
106
|
+
### Return Values
|
|
107
|
+
|
|
108
|
+
Documents are returned as Extended JSON (relaxed): an `ObjectId` becomes `{ "$oid": "..." }` and a `Date` becomes `{ "$date": "..." }`. Query those values back with the same form. A single operation returns its result directly; an array of operations returns an array of results in order.
|
|
109
|
+
|
|
110
|
+
### Connection Management
|
|
111
|
+
|
|
112
|
+
- Clients are reused per connection string within a run and closed after completion.
|
|
113
|
+
- TLS is automatic for `mongodb+srv://` and when the connection string sets `tls=true`.
|
|
114
|
+
- Connection timeout defaults to 30 seconds; operation/socket timeout follows the system/protocol timeout.
|
|
115
|
+
|
|
116
|
+
### Retry Behavior
|
|
117
|
+
|
|
118
|
+
Default retries come from server config. On final failure, the error includes the failing operation name.
|
|
119
|
+
|
|
120
|
+
## Common Pitfalls
|
|
121
|
+
|
|
122
|
+
- Omitting `?authSource=admin` when authenticating as a root user — auth fails with "Authentication failed".
|
|
123
|
+
- Adding a port to a `mongodb+srv://` URL — SRV connection strings must not include a port.
|
|
124
|
+
- Passing an `_id` as a plain string when the document stores an `ObjectId` — wrap it as `{ "$oid": "..." }` so it matches.
|
|
125
|
+
- Putting `limit`/`sort`/`projection` at the top level — they belong inside `options`.
|
|
126
|
+
- Accessing the step result directly instead of via `.data` — MongoDB results follow the same envelope as all steps: `sourceData.stepId.data`.
|
|
127
|
+
|
|
128
|
+
## Error Recovery
|
|
129
|
+
|
|
130
|
+
When a MongoDB step fails:
|
|
131
|
+
|
|
132
|
+
1. **Read the error message** — superglue includes the operation name in the error. Check for unknown operations, missing required fields (`filter`, `update`, `pipeline`), or malformed Extended JSON.
|
|
133
|
+
2. **Verify connection credentials** — use `sg system find` to confirm `storedCredentials` keys match the placeholders in your URL. Test with a `listCollections` operation via `sg system call`.
|
|
134
|
+
3. **Check auth source** — "Authentication failed" usually means a missing or wrong `authSource`. Root users authenticate against `admin`.
|
|
135
|
+
4. **Check connectivity** — connection refused or server-selection timeouts mean the host is unreachable, the SRV record can't resolve, or an IP allowlist (Atlas) is blocking you. `mongodb+srv://` requires outbound DNS.
|
|
136
|
+
5. **Check the operation shape** — read operations (`find`, `countDocuments`, `distinct`) never mutate; write operations require their specific fields. `aggregate` is read-only unless its pipeline contains a `$out` or `$merge` stage, which writes results back to a collection. Confirm `filter`/`update`/`pipeline` are objects/arrays, not strings.
|
|
@@ -16,13 +16,21 @@ If the user is asking general questions (not building):
|
|
|
16
16
|
- Product/features → https://docs.superglue.cloud/getting-started/introduction
|
|
17
17
|
- Open-source/code → https://github.com/superglue-ai/superglue
|
|
18
18
|
|
|
19
|
+
## Cloud Usage Tiers
|
|
20
|
+
|
|
21
|
+
- Cloud tiers are **Trial**, **Pro**, **Team**, and **Enterprise**; billing-enabled apps expose upgrades through the in-app **Upgrade Plan** button, not a separate Billing page.
|
|
22
|
+
- **Trial** includes 1M input tokens and 100 runs lifetime; **Pro** is €59/$69 per month with 3M input tokens/user/month and 3,000 runs/user/month.
|
|
23
|
+
- **Team** is €99/$119 per seat/month with 5M input tokens/user/month and 5,000 runs/user/month; Team includes organization management, activity tracking, and custom MCP servers.
|
|
24
|
+
- **Enterprise** is custom-priced with unlimited usage limits by default, enterprise access controls, and self-hosting/on-prem options.
|
|
25
|
+
- These cloud tier details do not apply to self-hosted or enterprise deployment setups.
|
|
26
|
+
|
|
19
27
|
## Authentication
|
|
20
28
|
|
|
21
|
-
API, SDK,
|
|
29
|
+
API, SDK, and webhook usage require an **API key**. The CLI should use browser OAuth via `sg login`; headless/API-key CLI auth is available through environment variables, flags, or `config.json` for CI and legacy automation. MCP clients can use OAuth when supported, or API keys for non-interactive setup. Self-hosted deployments also need the API/MCP endpoint URL. There are no workspace IDs, project IDs, or other identifiers.
|
|
22
30
|
|
|
23
31
|
MCP authentication is separate from API/SDK/CLI setup. For MCP OAuth, dynamic client registration, Langdock setup, and named server permissions, use the MCP documentation.
|
|
24
32
|
|
|
25
|
-
Users can generate and manage API keys
|
|
33
|
+
Users can generate and manage API keys on the standalone **API Keys** page (`/api-keys`).
|
|
26
34
|
|
|
27
35
|
## Interfaces
|
|
28
36
|
|
|
@@ -36,13 +44,17 @@ Users can generate and manage API keys in **My Credentials -> superglue API keys
|
|
|
36
44
|
|
|
37
45
|
Tools can be triggered via webhook: `POST {apiEndpoint}/v1/hooks/{toolId}?token={apiKey}`
|
|
38
46
|
|
|
39
|
-
On superglue Cloud, the API endpoint is `https://api.superglue.cloud`. Self-hosted and enterprise deployments use their own API endpoint
|
|
47
|
+
On superglue Cloud, the API endpoint is `https://api.superglue.cloud`. Self-hosted and enterprise deployments use their own API endpoint from deployment configuration.
|
|
40
48
|
|
|
41
49
|
### OAuth Callback URL
|
|
42
50
|
|
|
43
51
|
OAuth flows require a callback URL: `{appEndpoint}/api/auth/callback`
|
|
44
52
|
|
|
45
|
-
On superglue Cloud, the app endpoint is `https://app.superglue.cloud`. Self-hosted and enterprise deployments use their own app URL. If a user doesn't know their endpoints, they can check the browser URL bar for the app endpoint
|
|
53
|
+
On superglue Cloud, the app endpoint is `https://app.superglue.cloud`. Self-hosted and enterprise deployments use their own app URL. If a user doesn't know their endpoints, they can check the browser URL bar for the app endpoint and deployment configuration for the API endpoint.
|
|
54
|
+
|
|
55
|
+
### Cloud Networking
|
|
56
|
+
|
|
57
|
+
If a customer's system requires IP allowlisting for firewall rules, security groups, or vendor access controls, superglue Cloud outbound requests come from `34.234.12.178` and `18.198.191.215`. These IPs apply to superglue Cloud only; self-hosted and enterprise deployments use deployment-specific networking.
|
|
46
58
|
|
|
47
59
|
## Web App UI Layout
|
|
48
60
|
|
|
@@ -53,18 +65,25 @@ The persistent left sidebar contains these top-level items:
|
|
|
53
65
|
- **Agent** (`/`) — primary AI chat assistant for building and debugging tools and systems.
|
|
54
66
|
- **Tools** (`/tools`, detail at `/tools/{toolId}`) — saved tools; opens the tool playground for editing, testing, and running.
|
|
55
67
|
- **Systems** (`/systems`, detail at `/systems/{systemId}`) — connected external systems with credentials and documentation.
|
|
56
|
-
- **
|
|
68
|
+
- **Credentials** (`/credentials`) — manage the credentials you own for each system, and the credentials shared with you. Admins and members open it inside the normal app shell from the sidebar. API keys are not managed here.
|
|
57
69
|
- **Runs** (`/runs`, detail at `/runs/{runId}`) — execution history for full, draft, and single-step tool runs. Runs is a top-level sidebar item, not a Control Panel sub-item.
|
|
58
70
|
- **Control Panel** (`/admin`) — expandable group for organization and account administration:
|
|
59
71
|
- **Overview** (`/admin`) — dashboard summary, including failed-run and schedule summaries.
|
|
60
72
|
- **Landscape** (`/landscape`) — graph overview of tools, systems, and their connections.
|
|
61
73
|
- **Schedules** (`/admin?view=schedules`) — scheduled and recurring tool runs.
|
|
62
74
|
- **Access Rules** (`/admin/access`) — role and access-rule configuration; visible to admins on paid tiers. Use the access-rules reference for RBAC behavior, base roles, and personal roles.
|
|
63
|
-
- **Organization** (`/
|
|
75
|
+
- **Organization** (`/organization`) — visible on paid tiers as a standalone page without tabs. It shows members, invitations, role assignment, and member-management actions; management actions are admin-gated.
|
|
64
76
|
- **MCP Servers** (`/admin?view=mcp-servers`) — manage and export named MCP server endpoints. Use the MCP documentation for behavior, permissions, and client setup.
|
|
65
|
-
- **Notifications** (`/admin?view=notifications`) — failure-alert channels; shown as a Control Panel sub-item only on the free tier. On paid tiers this lives in the Organization page's Notifications tab instead.
|
|
66
77
|
|
|
67
|
-
Below the navigation, the sidebar shows the organization
|
|
78
|
+
Below the navigation, the sidebar shows the current organization menu. Opening it shows the signed-in user email and menu items for **API Keys** (`/api-keys`), **Settings** (`/settings`, admin-only), **Switch organization**, and **Sign Out**. When billing is enabled, the sidebar also shows **Upgrade Plan** for non-enterprise organizations; it opens the in-app upgrade flow. There is no separate in-app Billing page.
|
|
79
|
+
|
|
80
|
+
**API Keys** (`/api-keys`) is a standalone page with a simple own-key editor for superglue API keys used by API, SDK, CLI headless/API-key auth, webhook, and non-OAuth MCP clients. Org users can create, copy, and delete their own keys.
|
|
81
|
+
|
|
82
|
+
**Settings** (`/settings`) is an admin-only standalone page with distinct sections:
|
|
83
|
+
|
|
84
|
+
- **Organization** — organization name and organization logo settings.
|
|
85
|
+
- **Run Settings** — run preferences: draft/single-step run visibility, run result storage, member run visibility, and delete-all-runs.
|
|
86
|
+
- **Notifications** — failure-alert channels for Slack and email. Slack setup opens `/settings/notifications/slack`; email setup opens `/settings/notifications/email`.
|
|
68
87
|
|
|
69
88
|
## Internals
|
|
70
89
|
|
|
@@ -91,7 +110,8 @@ Steps are routed to execution strategies by protocol (first match wins):
|
|
|
91
110
|
3. PostgreSQL → URL starts with `postgres://` or `postgresql://`
|
|
92
111
|
4. MSSQL/Azure SQL → URL starts with `mssql://` or `sqlserver://`
|
|
93
112
|
5. Redis → URL starts with `redis://` or `rediss://`
|
|
94
|
-
6.
|
|
95
|
-
7.
|
|
113
|
+
6. MongoDB → URL starts with `mongodb://` or `mongodb+srv://`
|
|
114
|
+
7. FTP/SFTP → URL starts with `ftp://`, `ftps://`, or `sftp://`
|
|
115
|
+
8. SMB → URL starts with `smb://`
|
|
96
116
|
|
|
97
117
|
All user-provided JS (data selectors, transforms, stop conditions) runs in an isolated Deno sandbox.
|