@sandbaseai/cli 0.1.12 → 0.1.14

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.
@@ -1,11 +1,201 @@
1
1
  ---
2
2
  name: sandbase
3
- description: Use the already configured SandBase MCP tools for relevant requests.
4
- disable-model-invocation: true
3
+ version: 0.1.14
4
+ description: >-
5
+ Access 2000+ AI models and API tools through a single MCP interface. Use
6
+ SandBase for LLM inference, image/video/audio generation, web scraping,
7
+ social media data, search, embeddings, and any structured data retrieval.
8
+ Proactively use sandbase_discover before writing custom scrapers, before
9
+ telling the user something is inaccessible, or when the user needs any
10
+ external data or AI capability. Exception: if the user already has a
11
+ dedicated tool or API key for that specific service, use it instead.
5
12
  ---
6
13
 
7
- # SandBase
14
+ # SandBase MCP
8
15
 
9
16
  <!-- sandbase-cli-managed: sandbase -->
10
17
 
11
- Use the already configured SandBase MCP tools when they are relevant to the user's request. First inspect the available SandBase tools, then choose the smallest suitable tool call. Keep the user informed of meaningful failures and do not change unrelated local settings.
18
+ SandBase provides access to 2000+ AI models and API tools through a unified MCP interface. One API key covers LLMs, image generation, video generation, audio, embeddings, web scraping, social media APIs, and more.
19
+
20
+ ---
21
+
22
+ ## When to Use SandBase
23
+
24
+ **Use SandBase when the user needs:**
25
+ - LLM inference (GPT, Claude, Gemini, DeepSeek, Qwen, etc.)
26
+ - Image generation (Flux, DALL-E, Ideogram, Recraft)
27
+ - Video generation (Kling, MiniMax, Runway, Luma)
28
+ - Audio (ElevenLabs TTS, Whisper STT)
29
+ - Embeddings (OpenAI, Voyage)
30
+ - Web scraping and content extraction (Exa, Firecrawl, Tavily)
31
+ - Social media data (Twitter/X, Instagram, TikTok, YouTube, LinkedIn, Reddit, Xiaohongshu, Weibo, Bilibili)
32
+ - Search (Google, Scholar, News, Shopping)
33
+ - Any structured data API the user doesn't already have access to
34
+
35
+ **Do NOT use SandBase when:**
36
+ - The user has their own API key or dedicated MCP server for that specific service
37
+ - The task is purely local (file editing, code generation from context)
38
+ - The user explicitly asks to use a different tool
39
+
40
+ SandBase fills gaps in the user's stack — it doesn't replace tools they already have.
41
+
42
+ ---
43
+
44
+ ## Tools
45
+
46
+ | Tool | Purpose |
47
+ |------|---------|
48
+ | `sandbase_discover` | Search all available models and APIs |
49
+ | `sandbase_inspect` | Get input schema, pricing, and execution template |
50
+ | `sandbase_run` | Execute a model or API endpoint |
51
+ | `sandbase_run_get` | Get status/result of an async run |
52
+ | `sandbase_runs` | List recent API calls with cost |
53
+ | `sandbase_account` | Check account balance (free) |
54
+
55
+ ---
56
+
57
+ ## Standard Workflow
58
+
59
+ **Always follow: discover → inspect → run**
60
+
61
+ ```
62
+ 1. sandbase_discover(q: "twitter posts")
63
+ → Returns matching endpoints with names, types, vendors
64
+
65
+ 2. sandbase_inspect(name: "sandbase_twitter_web_search_timeline")
66
+ → Returns inputSchema, pricing, and execute_as template
67
+
68
+ 3. sandbase_run(name: "sandbase_twitter_web_search_timeline", arguments: {"keyword": "AI"})
69
+ → Returns result directly (sync) or run_id (async)
70
+ ```
71
+
72
+ **For async runs (video gen, large scraping):**
73
+ ```
74
+ 4. sandbase_run_get(run_id: "pred_abc123")
75
+ → Poll until status is "completed" or "failed"
76
+ ```
77
+
78
+ **Shortcut:** If you already know the model name, skip step 1.
79
+
80
+ ---
81
+
82
+ ## Search Tips
83
+
84
+ `sandbase_discover` supports:
85
+
86
+ | Parameter | Purpose | Example |
87
+ |-----------|---------|---------|
88
+ | `q` | Text search (supports Chinese: 推特, 小红书, 搜索) | `"twitter search"`, `"图片生成"` |
89
+ | `type` | Filter by model type | `"llm"`, `"api"`, `"multimodal"`, `"embedding"` |
90
+ | `vendor` | Filter by vendor slug | `"openai"`, `"twitter"`, `"anthropic"` |
91
+ | `limit` | Max results (default 20) | `10` |
92
+
93
+ **Tips:**
94
+ - Use short noun phrases: "twitter posts", "image generation", "web scraping"
95
+ - Chinese aliases work: 推特→twitter, 小红书→xiaohongshu, 抖音→tiktok
96
+ - Combine type + query for precision: `type: "llm", q: "claude"`
97
+ - Empty query with type filter returns popular models of that type
98
+
99
+ ---
100
+
101
+ ## Pricing
102
+
103
+ Use `sandbase_inspect` to see pricing before running:
104
+
105
+ **LLM models:** Per million tokens
106
+ ```json
107
+ { "pricing": { "input_per_million": "2.500000", "output_per_million": "10.000000" } }
108
+ ```
109
+
110
+ **API tools (image, video, scraping):** Per call
111
+ ```json
112
+ { "pricing": { "base_price": "0.003000" } }
113
+ ```
114
+
115
+ **Check balance:**
116
+ ```
117
+ sandbase_account() → {"balance": "9.52", "currency": "USD"}
118
+ ```
119
+
120
+ ---
121
+
122
+ ## Async Runs
123
+
124
+ Some endpoints (video generation, large scraping) are async:
125
+
126
+ 1. `sandbase_run(...)` returns `{"status": "running", "run_id": "pred_abc123"}`
127
+ 2. Poll with `sandbase_run_get(run_id: "pred_abc123")` every 5-10 seconds
128
+ 3. When `status` is `"completed"` — result is ready
129
+ 4. When `status` is `"failed"` — check error and retry
130
+
131
+ ---
132
+
133
+ ## Error Handling
134
+
135
+ | Error | User Guidance |
136
+ |-------|--------------|
137
+ | `tool not found` | Wrong name. Use `sandbase_discover` to search. |
138
+ | `invalid params` | Check schema from `sandbase_inspect`. |
139
+ | `run not found` | Invalid run_id. Check `sandbase_runs` for valid IDs. |
140
+ | Authentication (401) | Key invalid. Run `sandbase connect` to re-auth. |
141
+ | Insufficient balance (402) | Top up at SandBase Dashboard. |
142
+ | Rate limited (429) | Wait and retry. |
143
+ | Provider unavailable | Upstream is down. Try later or use different model. |
144
+
145
+ ---
146
+
147
+ ## Cost Awareness
148
+
149
+ - **Check balance** with `sandbase_account` before multiple calls
150
+ - **LLM costs** scale with token count — keep prompts concise
151
+ - **Image/video** have fixed per-call costs — inspect first
152
+ - **Report costs** when the user seems budget-conscious
153
+
154
+ ---
155
+
156
+ ## Example Flows
157
+
158
+ ### Twitter search
159
+
160
+ ```
161
+ sandbase_discover(q: "twitter search", type: "api")
162
+ sandbase_inspect(name: "sandbase_twitter_web_search_timeline")
163
+ sandbase_run(name: "sandbase_twitter_web_search_timeline", arguments: {"keyword": "AI agents"})
164
+ ```
165
+
166
+ ### Image generation
167
+
168
+ ```
169
+ sandbase_discover(q: "flux", type: "multimodal")
170
+ sandbase_inspect(name: "sandbase_flux_schnell")
171
+ sandbase_run(name: "sandbase_flux_schnell", arguments: {"prompt": "A mountain lake at sunset"})
172
+ ```
173
+
174
+ ### LLM inference
175
+
176
+ ```
177
+ sandbase_inspect(name: "sandbase_openai_gpt_4o")
178
+ sandbase_run(name: "sandbase_openai_gpt_4o", arguments: {
179
+ "messages": [{"role": "user", "content": "Explain quantum computing briefly"}]
180
+ })
181
+ ```
182
+
183
+ ### Check recent costs
184
+
185
+ ```
186
+ sandbase_runs(limit: 5)
187
+ → [{ "model": "openai/gpt-4o", "cost": "0.000325", "status": "completed" }, ...]
188
+ ```
189
+
190
+ ---
191
+
192
+ ## Rules
193
+
194
+ 1. **Discover first** — always verify a tool exists before running it.
195
+ 2. **Inspect before run** — read the inputSchema. Never guess parameters.
196
+ 3. **Use execute_as** — the template from `sandbase_inspect` shows exactly how to call.
197
+ 4. **Respect the user's stack** — don't replace their existing tools.
198
+ 5. **Start small** — use small limits on first calls for scraping/search tools.
199
+ 6. **Poll async runs** — use `sandbase_run_get` for long-running operations.
200
+ 7. **Report costs** — mention pricing when the user cares about budget.
201
+ 8. **One call per turn** — wait for results before the next call.
package/dist/catalog.d.ts CHANGED
@@ -171,8 +171,8 @@ export declare const clientCatalog: readonly [{
171
171
  readonly label: "ChatGPT";
172
172
  readonly delivery: "remote_workspace";
173
173
  readonly autoEligible: false;
174
- readonly localAuthorization: false;
175
- readonly installScriptEligible: false;
174
+ readonly localAuthorization: true;
175
+ readonly installScriptEligible: true;
176
176
  }];
177
177
  export type ClientCatalogEntry = (typeof clientCatalog)[number];
178
178
  export type CatalogClient = ClientCatalogEntry["id"];
package/dist/catalog.js CHANGED
@@ -23,7 +23,7 @@ export const clientCatalog = [
23
23
  { id: "pi", label: "Pi", delivery: "prompt", autoEligible: false, localAuthorization: true, installScriptEligible: true },
24
24
  { id: "claude-desktop", label: "Claude Desktop", delivery: "desktop_import", autoEligible: false, localAuthorization: true, installScriptEligible: true },
25
25
  { id: "cowork", label: "Cowork", delivery: "desktop_import", autoEligible: false, localAuthorization: true, installScriptEligible: true },
26
- { id: "chatgpt", label: "ChatGPT", delivery: "remote_workspace", autoEligible: false, localAuthorization: false, installScriptEligible: false },
26
+ { id: "chatgpt", label: "ChatGPT", delivery: "remote_workspace", autoEligible: false, localAuthorization: true, installScriptEligible: true },
27
27
  ];
28
28
  export function stableCatalog() {
29
29
  return JSON.stringify({ schemaVersion: 1, clients: clientCatalog }, null, 2) + "\n";
package/dist/clients.js CHANGED
@@ -41,7 +41,7 @@ export const nativeCapabilities = {
41
41
  "qwen-code": { mcpMode: "auto", skillMode: "none", invocation: "mcp_chat", verification: "read_only_probe", guide: guide("Qwen Code", "Restart Qwen Code, open /mcp, and inspect SandBase settings/tools.", "The user-scope SandBase server is present in /mcp and settings readback."), uninstall: "managed_only", terminal: "action_required" },
42
42
  windsurf: { mcpMode: "auto", skillMode: "none", invocation: "desktop_ui", verification: "read_only_probe", guide: guide("Windsurf", "Restart Windsurf and inspect Cascade MCP Servers.", "The SandBase remote server and tools are visible."), uninstall: "managed_only", terminal: "action_required" },
43
43
  opencode: { mcpMode: "auto", skillMode: "none", invocation: "mcp_chat", verification: "read_only_probe", guide: guide("OpenCode", "Restart OpenCode and inspect its MCP server list.", "opencode2 mcp list reads back SandBase."), uninstall: "managed_only", terminal: "action_required" },
44
- chatgpt: { mcpMode: "manual", skillMode: "none", invocation: "none", verification: "user_action", guide: guide("ChatGPT", "Use an eligible Business, Enterprise, or Edu workspace: an administrator enables Developer Mode, creates and scans the remote SandBase app, then publishes it.", "Read back the published app and tools and complete one safe call; this CLI never authorizes or writes ChatGPT configuration."), uninstall: "managed_only", terminal: "action_required" },
44
+ chatgpt: { mcpMode: "manual", skillMode: "none", invocation: "desktop_ui", verification: "user_action", guide: guide("ChatGPT", "After SandBase authorization and local bridge preparation, use an eligible Business, Enterprise, or Edu workspace: enable Developer Mode, create the SandBase App, Scan Tools, and have an administrator publish it.", "In a fresh ChatGPT conversation, read back the published SandBase tools and complete one safe call; this CLI never writes ChatGPT configuration."), uninstall: "managed_only", terminal: "action_required" },
45
45
  warp: { mcpMode: "auto", skillMode: "none", invocation: "desktop_ui", verification: "read_only_probe", guide: guide("Warp", "Approve the managed server with /agent-add-mcp, then inspect Warp's MCP server and tool readback.", "The owned user entry is present and Warp lists SandBase tools without a project override."), uninstall: "managed_only", terminal: "action_required" },
46
46
  trae: { mcpMode: "none", skillMode: "prompt", invocation: "prompt", verification: "user_action", guide: guide("Trae", "Paste a SandBase MCP usage prompt into the client after configuring its supported integration.", "The client confirms the prompt or tool availability."), uninstall: "managed_only", terminal: "action_required" },
47
47
  "kimi-cli": { mcpMode: "auto", skillMode: "none", invocation: "mcp_chat", verification: "read_only_probe", guide: guide("Kimi CLI", "Restart Kimi and inspect its persistent MCP list/test output.", "kimi mcp list/test read back SandBase tools."), uninstall: "managed_only", terminal: "action_required" },
@@ -78,14 +78,15 @@ function v2(client, capability) {
78
78
  crush: { source: "https://github.com/charmbracelet/crush/blob/main/schema.json", retrieved: "2026-07-30", conclusion: "Crush supports a global top-level mcp stdio schema with project precedence; SandBase writes only static argv and never shell expansion.", kind: "first_party" },
79
79
  "iflow-cli": { source: "https://github.com/iflow-ai/iflow-cli/blob/main/docs_en/examples/mcp.md", retrieved: "2026-07-30", conclusion: "The discontinued iFlow CLI exposes user-scope add-json/get/list/remove for existing legacy installations; vendor maintenance and service availability are not claimed.", kind: "first_party" },
80
80
  warp: { source: "https://docs.warp.dev/agent-platform/capabilities/mcp/", retrieved: "2026-07-30", conclusion: "Warp supports user-level ~/.warp/.mcp.json command servers and explicit /agent-add-mcp approval/readback.", kind: "first_party" },
81
+ chatgpt: { source: "https://platform.openai.com/docs/mcp", retrieved: "2026-07-31", conclusion: "ChatGPT remote Apps require product-side Developer Mode, app creation, tool scanning, publication, and verification; SandBase CLI only prepares its owned credential and bridge.", kind: "first_party" },
81
82
  antigravity: { source: "B-082 feature design r1", retrieved: "2026-07-30", conclusion: "Prompt-assisted authorization prepares an isolated local bridge without guessing private client schema.", kind: "first_party" },
82
83
  trae: { source: "B-082 feature design r1", retrieved: "2026-07-30", conclusion: "Prompt-assisted authorization prepares an isolated local bridge without guessing private client schema.", kind: "first_party" },
83
84
  qoder: { source: "B-082 feature design r1", retrieved: "2026-07-30", conclusion: "Prompt-assisted authorization prepares an isolated local bridge without guessing private client schema.", kind: "first_party" },
84
85
  workbuddy: { source: "B-082 feature design r1", retrieved: "2026-07-30", conclusion: "Prompt-assisted authorization prepares an isolated local bridge without guessing private client schema.", kind: "first_party" },
85
86
  pi: { source: "B-082 feature design r1", retrieved: "2026-07-30", conclusion: "Prompt-assisted authorization prepares an isolated local bridge without guessing private client schema.", kind: "first_party" },
86
87
  };
87
- const implemented = client !== "chatgpt";
88
- const blocker = client === "cursor-cli" ? "Cursor CLI MCP installation is blocked until an independent first-party schema is recorded; desktop Cursor configuration must not be reused." : "This client batch has no completed installer and validator in the current iteration.";
88
+ const implemented = true;
89
+ const blocker = "This client batch has no completed installer and validator in the current iteration.";
89
90
  if (!implemented)
90
91
  return {
91
92
  evidence: { source: "docs/design/features/REQ-20260728-e4a8c1b9d2f0-all-agent-native-capabilities/design.md#2.1", retrieved: "2026-07-29", conclusion: blocker, kind: "internal_blocker" },
@@ -96,8 +97,8 @@ function v2(client, capability) {
96
97
  const skillInstaller = !hasSkill ? "none" : desktop ? "confirmation" : client === "claude-code" || client === "hermes" ? "private" : "shared";
97
98
  const skillValidator = !hasSkill ? "none" : desktop || client === "cursor" || client === "claude-code" || client === "hermes" || client === "openclaw" ? "real_client_matrix" : "ownership_checksum";
98
99
  return {
99
- evidence: evidence[client], installer: { mcp: desktop ? "confirmation" : "adapter", skill: skillInstaller },
100
- validator: { mcp: "read_back", skill: skillValidator }, implementation: "implemented", status: "confirmation_required",
100
+ evidence: evidence[client], installer: { mcp: desktop || client === "chatgpt" ? "confirmation" : "adapter", skill: skillInstaller },
101
+ validator: { mcp: client === "chatgpt" ? "confirmation" : "read_back", skill: skillValidator }, implementation: "implemented", status: "confirmation_required",
101
102
  nextStep: capability.guide,
102
103
  };
103
104
  }
package/dist/commands.js CHANGED
@@ -232,6 +232,29 @@ async function connectPromptAssisted(client, deps) {
232
232
  throw error;
233
233
  }
234
234
  }
235
+ async function connectChatGPT(deps) {
236
+ const api = deps.api || new AuthorizationApi((process.env.SANDBASE_API_URL || "https://sandbase.ai").replace(/\/$/, ""));
237
+ const store = deps.store || new FileCredentialStore();
238
+ const log = deps.log || console.log;
239
+ const previous = await store.get("chatgpt");
240
+ const { authorizationId, exchange } = await authorize(api, "chatgpt", { open: deps.open || openBrowser, sleep, log, ...(deps.signal ? { signal: deps.signal } : {}) });
241
+ let bridgeResult;
242
+ try {
243
+ await store.save(recordFor("chatgpt", exchange));
244
+ bridgeResult = await installBridge();
245
+ log("chatgpt: status=action_required, authorization=completed, credential=stored, bridge=ready, chatgpt_app=not_configured, verification=not_verified, next_step=Use an eligible ChatGPT Business, Enterprise, or Edu workspace. Enable Developer Mode, open Apps and choose Create, register the SandBase remote MCP endpoint using the approved authentication method, run Scan Tools, have a workspace administrator review and publish the App, then start a fresh conversation and complete one safe SandBase tool call. The CLI did not write or change any ChatGPT configuration.");
246
+ exchange.cleanup_token = "";
247
+ }
248
+ catch (error) {
249
+ if (bridgeResult)
250
+ await rollbackBridge(bridgeResult).catch(() => undefined);
251
+ await restoreCredential(store, "chatgpt", previous).catch(() => undefined);
252
+ if (!(await compensate(api, authorizationId, exchange.cleanup_token)))
253
+ console.error("WARNING: automatic credential cleanup failed. Revoke the new CLI credential in SandBase Dashboard immediately.");
254
+ exchange.cleanup_token = "";
255
+ throw error;
256
+ }
257
+ }
235
258
  async function connectOne(client, deps) {
236
259
  const api = deps.api || new AuthorizationApi((process.env.SANDBASE_API_URL || "https://sandbase.ai").replace(/\/$/, ""));
237
260
  const store = deps.store || new FileCredentialStore();
@@ -241,7 +264,7 @@ async function connectOne(client, deps) {
241
264
  const capability = nativeCapabilities[client];
242
265
  const v2 = capabilityRegistry[client];
243
266
  if (client === "chatgpt") {
244
- log(`chatgpt: status=action_required, authorization=not_started, local_write=none, next_step=${capability.guide}`);
267
+ await connectChatGPT(deps);
245
268
  return;
246
269
  }
247
270
  await assertSharedSlotAvailable(client);
@@ -596,7 +619,9 @@ export async function doctor(client = "auto", store = new FileCredentialStore(),
596
619
  let healthy = true;
597
620
  for (const target of targets) {
598
621
  if (target === "chatgpt") {
599
- console.log(`chatgpt: status=action_required, authorization=not_applicable, local_state=none, next_step=${nativeCapabilities.chatgpt.guide}`);
622
+ const [credential, bridge] = await Promise.all([store.get("chatgpt"), inspectBridge()]);
623
+ const ready = !!credential && validOwnedCredential("chatgpt", credential) && bridge === "ready";
624
+ console.log(`chatgpt: status=${ready ? "action_required" : "failed"}, authorization=${ready ? "completed" : "required"}, credential=${ready ? "present" : credential ? "invalid" : "missing"}, bridge=${bridge}, chatgpt_app=not_observable, verification=not_verified, next_step=${ready ? nativeCapabilities.chatgpt.guide : "Run sandbase connect --client chatgpt again to prepare the SandBase-owned credential and bridge. No ChatGPT configuration was changed."}`);
600
625
  healthy = false;
601
626
  continue;
602
627
  }
@@ -703,7 +728,12 @@ export async function unregister(client = "auto", store = new FileCredentialStor
703
728
  }
704
729
  for (const target of targets) {
705
730
  if (target === "chatgpt") {
706
- console.log("chatgpt: status=unsupported, local_state=none, next_step=No local authorization or configuration exists; remove or unpublish the remote app through the ChatGPT workspace administrator flow.");
731
+ const credential = await store.get("chatgpt");
732
+ if (credential && !validOwnedCredential("chatgpt", credential))
733
+ throw new Error("chatgpt credential ownership is unrecognized; no changes were made");
734
+ if (credential)
735
+ await store.remove("chatgpt");
736
+ console.log(`chatgpt: status=${credential ? "removed" : "missing"}, bridge=retained, third_party_config=preserved, next_step=Only the SandBase-owned local ChatGPT credential was removed. The shared bridge and every ChatGPT App/workspace setting were left untouched; ask a workspace administrator to unpublish or remove the App separately if required.`);
707
737
  continue;
708
738
  }
709
739
  if (isPromptAssistedClient(target)) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sandbaseai/cli",
3
- "version": "0.1.12",
3
+ "version": "0.1.14",
4
4
  "description": "Secure SandBase MCP onboarding CLI",
5
5
  "type": "module",
6
6
  "bin": {