@superblocksteam/mcp-server 2.0.101-next.1

package/LICENSE.txt

@@ -0,0 +1,87 @@
+Superblocks Community Software License
+
+This Superblocks Community License Agreement (the “Agreement”) sets forth the terms on which DayZero
+Software, Inc. d/b/a Superblocks (“Superblocks”) makes available certain software made available by Superblocks
+under this Agreement (the “Software”). BY INSTALLING, DOWNLOADING, ACCESSING, USING OR
+DISTRIBUTING ANY OF THE SOFTWARE, YOU AGREE TO THE TERMS AND CONDITIONS OF THIS
+AGREEMENT.IF YOU DO NOT AGREE TO SUCH TERMS AND CONDITIONS, YOU MUST NOT USE THE
+SOFTWARE. IF YOU ARE RECEIVING THE SOFTWARE ON BEHALF OF A LEGAL ENTITY, YOU
+REPRESENT AND WARRANT THAT YOU HAVE THE ACTUAL AUTHORITY TO AGREE TO THE
+TERMS AND CONDITIONS OF THIS AGREEMENT ON BEHALF OF SUCH ENTITY. “Licensee” means you,
+an individual, or the entity on whose behalf you are receiving the Software.
+
+1. LICENSE GRANT AND CONDITIONS.
+
+1.1 License. Subject to the terms and conditions of this Agreement, Superblocks hereby grants to Licensee a
+non-exclusive, royalty-free, worldwide, non-transferable, non-sublicenseable license during the term of this
+Agreement to: (a) use the Software; (b) prepare modifications and derivative works of the Software; (c)
+distribute the Software (including without limitation in source code or object code form); and (d) reproduce
+copies of the Software (the “License”). Licensee is not granted the right to, and Licensee shall not, exercise the
+License for an Excluded Purpose. For purposes of this Agreement, “Excluded Purpose” means making
+available any software-as-a-service, platform-as-a-service, infrastructure-as-a-service or other similar online
+service that competes with Superblocks’ products or services.
+
+1.2 Conditions. In consideration of the License, Licensee’s distribution of the Software is subject to the
+following conditions:
+
+  a. Licensee must cause any Software modified by Licensee to carry prominent notices stating that Licensee
+  modified the Software.
+  b. On each Software copy, Licensee shall reproduce and not remove or alter all Superblocks or third party
+  copyright or other proprietary notices contained in the Software, and Licensee must provide the notice
+  below with each copy.
+
+  “This software is made available by DayZero Software, Inc. d/b/a Superblocks, under the terms of the
+  Superblocks Community License Agreement. © 2022 DayZero Software, Inc.”
+
+1.3 Licensee Modifications. Licensee may add its own copyright notices to modifications made by Licensee
+and may provide additional or different license terms and conditions for use, reproduction, or distribution of
+Licensee’s modifications. While redistributing the Software or modifications thereof, Licensee may choose to
+offer, for a fee or free of charge, support, warranty, indemnity, or other obligations. Licensee, and not
+Superblocks, will be responsible for any such obligations.
+
+1.4 No Sublicensing. The License does not include the right to sublicense the Software, however, each recipient
+to which Licensee provides the Software may exercise the Licenses so long as such recipient agrees to the terms
+and conditions of this Agreement.
+
+2. TERM AND TERMINATION. This Agreement will continue unless and until earlier terminated as set forth
+herein. If Licensee breaches any of its conditions or obligations under this Agreement, this Agreement will
+terminate automatically and the License will terminate automatically and permanently.
+
+3. INTELLECTUAL PROPERTY. As between the parties, Superblocks will retain all right, title, and interest in
+the Software, and all intellectual property rights therein. Superblocks hereby reserves all rights not expressly
+granted to Licensee in this Agreement. Superblocks hereby reserves all rights in its trademarks and service
+marks, and no licenses therein are granted in this Agreement.
+
+4. DISCLAIMER. SUPERBLOCKS HEREBY DISCLAIMS ANY AND ALL WARRANTIES AND
+CONDITIONS, EXPRESS, IMPLIED, STATUTORY, OR OTHERWISE, AND SPECIFICALLY
+DISCLAIMS ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR
+PURPOSE, WITH RESPECT TO THE SOFTWARE.
+
+5. LIMITATION OF LIABILITY. SUPERBLOCKS WILL NOT BE LIABLE FOR ANY DAMAGES OF
+ANY KIND, INCLUDING BUT NOT LIMITED TO, LOST PROFITS OR ANY CONSEQUENTIAL,
+SPECIAL, INCIDENTAL, INDIRECT, OR DIRECT DAMAGES, HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, ARISING OUT OF THIS AGREEMENT. THE FOREGOING SHALL APPLY TO
+THE EXTENT PERMITTED BY APPLICABLE LAW.
+
+6. GENERAL.
+
+6.1  Governing Law. This Agreement will be governed by and interpreted in accordance with the laws of the
+state of California, without reference to its conflict of laws principles. If Licensee is located within the United
+States, all disputes arising out of this Agreement are subject to the exclusive jurisdiction of courts located in San
+Mateo County, California. USA. If Licensee is located outside of the United States, any dispute, controversy or
+claim arising out of or relating to this Agreement will be referred to and finally determined by arbitration in
+accordance with the JAMS International Arbitration Rules. The tribunal will consist of one neutral arbitrator.
+The place of arbitration will be Palo Alto, California. The language to be used in the arbitral proceedings will be
+English. Judgment upon the award rendered by the arbitrator may be entered in any court having jurisdiction
+thereof.
+
+6.2.  Assignment. Licensee may not assign its rights under this Agreement to any third party. Superblocks may
+freely assign its rights under this Agreement to any third party.
+
+6.3.  Other.  This Agreement is the entire agreement between the parties regarding the subject matter hereof.
+No amendment or modification of this Agreement will be valid or binding upon the parties unless made in
+writing and signed by the duly authorized representatives of both parties. In the event that any provision,
+including without limitation any condition, of this Agreement is held to be unenforceable, this Agreement and
+all licenses and rights granted hereunder will immediately terminate. Waiver by Superblocks of a breach of any
+provision of this Agreement or the failure by Superblocks to exercise any right hereunder will not be construed
+as a waiver of any subsequent breach of that right or as a waiver of any other right.

package/README.md

@@ -0,0 +1,264 @@
+# Superblocks MCP Server
+
+A [Model Context Protocol](https://modelcontextprotocol.io/) server that connects AI assistants (Claude, ChatGPT, Cursor, and other MCP clients) to the Superblocks platform. It lets AI agents inspect, create, and manage Superblocks applications on your behalf.
+
+## Quick Start
+
+For a beginner-friendly walkthrough, see [`QUICKSTART.md`](./QUICKSTART.md).
+
+### Via the Superblocks CLI (recommended)
+
+```bash
+# Install the Superblocks CLI
+npm install -g @superblocksteam/cli
+
+# Authenticate
+superblocks login
+
+# Start the MCP server (stdio, for Cursor / Claude Desktop)
+superblocks mcp serve
+
+# Generate configuration for your MCP client
+superblocks mcp setup --client cursor
+superblocks mcp setup --client claude
+```
+
+### Standalone (development)
+
+```bash
+# From the superblocks repo root
+pnpm install
+pnpm turbo run build --filter @superblocksteam/mcp-server...
+
+# Run directly
+node packages/cli/packages/mcp-server/dist/index.js
+```
+
+## Client Configuration
+
+### Cursor
+
+Add to `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "superblocks": {
+      "command": "superblocks",
+      "args": ["mcp", "serve"]
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add to `~/.claude/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "superblocks": {
+      "command": "superblocks",
+      "args": ["mcp", "serve"]
+    }
+  }
+}
+```
+
+### ChatGPT (HTTP transport)
+
+ChatGPT requires an HTTPS endpoint. Start the server with the HTTP transport:
+
+```bash
+superblocks mcp serve --transport http --port 8484 --http-token <token>
+```
+
+Then expose it via a tunnel (e.g., ngrok) and configure it as a ChatGPT connector pointing to `https://<your-tunnel>/mcp`, sending `Authorization: Bearer <token>`.
+
+## Authentication
+
+The MCP server uses the same authentication as the Superblocks CLI. After running `superblocks login`, the MCP server can access the same environment automatically.
+
+For multiple environments, you can add tokens directly:
+
+```bash
+superblocks-mcp auth add --base-url https://staging.superblocks.com --token <api-key>
+superblocks-mcp auth list
+```
+
+Auth resolution order:
+
+1. CLI auth (`~/.superblocks/auth.json`) -- checked first
+2. MCP auth store (`~/.superblocks/mcp-auth.json`) -- multi-environment extension
+
+## Available Tools
+
+### `get_auth_status`
+
+Check whether you are authenticated for a Superblocks environment.
+
+### `get_current_user`
+
+Get the currently authenticated user for a given `base_url`.
+
+### `get_application_summary`
+
+Fetch application metadata: ID, name, organization, app mode (1.0 / 2.0), deployed commit, environment.
+
+### `get_application_commit_history`
+
+Paginated, reverse-chronological commit history with committer details and DBFS hashes.
+
+### `get_audit_events`
+
+Fetch v2 audit events in OCSF format with cursor pagination. Supports filters for class, status, severity, actor, resource, and full-text search.
+
+### Audit tool guidance
+
+- **Use `get_audit_events` by default** for new integrations and investigations.
+- `get_audit_logs` and `get_audit_entities` are **legacy-compatible** helpers for older audit-log workflows.
+- `get_audit_events` is the newer audit model and covers a broader set of operations than legacy audit logs, including:
+  - Applications
+  - APIs / Workflows
+  - Folders
+  - Integrations
+  - Users & Groups
+  - RBAC
+  - SCIM
+  - Tokens
+  - Billing
+  - OAuth
+  - Organization settings
+  - Files
+  - Profiles
+  - Repositories
+  - Knowledge
+  - Credentials
+
+### `get_integration_access`
+
+List all users and groups that have access to an integration, including assigned roles and effective permissions.
+
+### `get_application_structure`
+
+Lightweight application view. For 1.0 apps: page and API summary. For 2.0 apps: directory tree and checkout metadata (`checkout_path` is null when a temporary checkout is used and cleaned up).
+
+### `checkout_application`
+
+Materialize an application to disk. Supports historical snapshots via `commit_id`.
+
+### `create_application`
+
+Create a new Superblocks application. Returns the application ID and editor URL.
+
+### Deployment
+
+- `deploy_application` - deploy an application using either `app_url` or `application_id` + `base_url` (optionally with `commit_id`)
+
+### Integration Management
+
+- `get_integration` - fetch an integration by ID
+- `create_integration` - create an integration from API payload
+- `update_integration` - update an integration by ID
+- `delete_integration` - delete an integration by ID
+- `get_integration_access` - list users/groups with integration access
+
+### Folder Management
+
+- `list_folders` - list folders
+- `create_folder` - create a folder
+- `update_folder` - rename a folder
+- `delete_folder` - delete a folder
+
+### RBAC Assignment Management
+
+- `get_workflow_access` - list users/groups with access to a workflow
+- `get_job_access` - list users/groups with access to a scheduled job
+- `list_rbac_assignments` - list RBAC assignments for a specific resource
+- `grant_resource_access` - create RBAC assignments
+- `update_resource_access` - update a specific assignment
+- `revoke_resource_access` - delete a specific assignment
+
+### Billing Management
+
+- `list_builder_seats` - list builder seat assignments
+- `assign_builder_seat` - assign a seat to a user
+- `unassign_builder_seat` - remove a seat from a user
+- `update_subscription` - update subscription settings (payload passthrough)
+- `create_checkout_session` - create a checkout session (payload passthrough)
+- `create_billing_intent` - initialize a billing/payment intent
+- `submit_payment` - submit payment details (payload passthrough)
+- `check_promo` - validate a promo code
+- `downgrade_plan` - downgrade to free plan
+- `contact_sales` - submit a sales-contact request (payload passthrough)
+
+### Agent + Git Helpers
+
+- `list_organization_agents` - list organization agents
+- `get_git_fresh_token` - get a fresh Git credential token for app + host
+
+### Derived Analytics and Search
+
+- `get_app_activity_report` - summarize app activity from audit logs in a time window
+- `find_apps_by_package` - scan code-mode (2.0) `package.json` files for dependency usage
+
+### App Mode Coverage Notes
+
+- **Multi-page (1.0)** apps expose structured page/API metadata directly.
+- **Code-mode (2.0)** apps are file-based and usually require checkout + file scanning.
+- Some derived tools currently support only one mode:
+  - `find_apps_by_package`: code-mode (2.0) only
+- Tool responses include scan counters and mode-skipped counts to make this explicit.
+
+## Tool Annotations
+
+All tools include [MCP tool annotations](https://spec.modelcontextprotocol.io/) so clients can make informed decisions about auto-approval:
+
+- Read-only tools (`get_auth_status`, `get_application_summary`, etc.) are marked with `readOnlyHint: true`
+- `checkout_application` writes to disk but is non-destructive (`destructiveHint: false`)
+- `create_application` is non-destructive and non-idempotent
+
+## Transports
+
+| Transport           | Use case                                  | Command                                                                   |
+| ------------------- | ----------------------------------------- | ------------------------------------------------------------------------- |
+| **stdio** (default) | Cursor, Claude Desktop, local MCP clients | `superblocks mcp serve`                                                   |
+| **HTTP**            | ChatGPT, remote clients                   | `superblocks mcp serve --transport http --port 8484 --http-token <token>` |
+
+The HTTP transport binds to `127.0.0.1` by default.
+For security, HTTP transport requires an authentication token. Provide it via `--http-token` or `SUPERBLOCKS_MCP_HTTP_TOKEN`.
+
+## Environment Hints
+
+The server recognizes these Superblocks environments from URLs:
+
+- `app.superblocks.com` / `app.superblockshq.com` → `prod`
+- `eu.superblocks.com` / `prod-eu.superblocks.com` → `prod-eu`
+- `staging.superblocks.com` → `staging`
+- `dev.superblocks.com` → `dev`
+- `pr-*.superblocks.dev` → `ephemeral`
+- `localhost` / `127.0.0.1` → `local`
+
+Unknown URLs still work as long as auth is configured for that base URL.
+
+## Troubleshooting
+
+### "Not authenticated" errors
+
+```bash
+# Check which environments are configured
+superblocks-mcp auth list
+
+# Re-authenticate via CLI
+superblocks login
+
+# Or add a token for a specific environment
+superblocks-mcp auth add --base-url <url> --token <api-key>
+```
+
+### Server won't start
+
+- Ensure `node` is on your PATH (Node.js >= 24)
+- Rebuild: `pnpm turbo run build --filter @superblocksteam/mcp-server...`
+- Test standalone: `superblocks mcp serve --help`

package/dist/application/commit-history.d.ts

@@ -0,0 +1,27 @@
+import type { GetApplicationCommitsResponseBody } from "@superblocksteam/shared";
+export type ApplicationCommitHistoryItem = {
+    autosave_type: string | null;
+    branch: string | null;
+    commit_id: string;
+    commit_message: string;
+    commit_type: "autosave" | "commit";
+    committed_at: string;
+    committer_email: string;
+    committer_name: string | null;
+    directory_contents_hash: string | null;
+    external_commit_id: string | null;
+    external_committed_at: string | null;
+};
+type SummarizeApplicationCommitHistoryPageParams = {
+    offset: number;
+    pageLimit: number;
+    response: GetApplicationCommitsResponseBody;
+};
+export declare function summarizeApplicationCommitHistoryPage({ offset, pageLimit, response, }: SummarizeApplicationCommitHistoryPageParams): {
+    commits: ApplicationCommitHistoryItem[];
+    has_more: boolean;
+    next_offset: number | null;
+    returned_count: number;
+};
+export {};
+//# sourceMappingURL=commit-history.d.ts.map

package/dist/application/commit-history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commit-history.d.ts","sourceRoot":"","sources":["../../src/application/commit-history.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,iCAAiC,EAClC,MAAM,yBAAyB,CAAC;AAEjC,MAAM,MAAM,4BAA4B,GAAG;IACzC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,UAAU,GAAG,QAAQ,CAAC;IACnC,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,uBAAuB,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,qBAAqB,EAAE,MAAM,GAAG,IAAI,CAAC;CACtC,CAAC;AAEF,KAAK,2CAA2C,GAAG;IACjD,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,iCAAiC,CAAC;CAC7C,CAAC;AA6BF,wBAAgB,qCAAqC,CAAC,EACpD,MAAM,EACN,SAAS,EACT,QAAQ,GACT,EAAE,2CAA2C;;;;;EAa7C"}

package/dist/application/commit-history.js

@@ -0,0 +1,36 @@
+function compareCommits(left, right) {
+    const commitDateDifference = right.commitDate - left.commitDate;
+    if (commitDateDifference !== 0) {
+        return commitDateDifference;
+    }
+    return right.commitId.localeCompare(left.commitId);
+}
+function summarizeCommit(commit) {
+    return {
+        autosave_type: commit.autosaveType ?? null,
+        branch: commit.branch ?? null,
+        commit_id: commit.commitId,
+        commit_message: commit.commitMessage,
+        commit_type: commit.autosave ? "autosave" : "commit",
+        committed_at: new Date(commit.commitDate).toISOString(),
+        committer_email: commit.committer.email,
+        committer_name: commit.committer.name ?? null,
+        directory_contents_hash: commit.directoryContentsHash ?? null,
+        external_commit_id: commit.externalCommitId ?? null,
+        external_committed_at: commit.externalCommitDate
+            ? new Date(commit.externalCommitDate).toISOString()
+            : null,
+    };
+}
+export function summarizeApplicationCommitHistoryPage({ offset, pageLimit, response, }) {
+    const orderedCommits = [...response.autosaves, ...response.commits].sort(compareCommits);
+    const hasMore = orderedCommits.length > pageLimit;
+    const pageItems = orderedCommits.slice(0, pageLimit).map(summarizeCommit);
+    return {
+        commits: pageItems,
+        has_more: hasMore,
+        next_offset: hasMore ? offset + pageLimit : null,
+        returned_count: pageItems.length,
+    };
+}
+//# sourceMappingURL=commit-history.js.map

package/dist/application/commit-history.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commit-history.js","sourceRoot":"","sources":["../../src/application/commit-history.ts"],"names":[],"mappings":"AAyBA,SAAS,cAAc,CAAC,IAAe,EAAE,KAAgB;IACvD,MAAM,oBAAoB,GAAG,KAAK,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;IAChE,IAAI,oBAAoB,KAAK,CAAC,EAAE,CAAC;QAC/B,OAAO,oBAAoB,CAAC;IAC9B,CAAC;IAED,OAAO,KAAK,CAAC,QAAQ,CAAC,aAAa,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;AACrD,CAAC;AAED,SAAS,eAAe,CAAC,MAAiB;IACxC,OAAO;QACL,aAAa,EAAE,MAAM,CAAC,YAAY,IAAI,IAAI;QAC1C,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,IAAI;QAC7B,SAAS,EAAE,MAAM,CAAC,QAAQ;QAC1B,cAAc,EAAE,MAAM,CAAC,aAAa;QACpC,WAAW,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,QAAQ;QACpD,YAAY,EAAE,IAAI,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,WAAW,EAAE;QACvD,eAAe,EAAE,MAAM,CAAC,SAAS,CAAC,KAAK;QACvC,cAAc,EAAE,MAAM,CAAC,SAAS,CAAC,IAAI,IAAI,IAAI;QAC7C,uBAAuB,EAAE,MAAM,CAAC,qBAAqB,IAAI,IAAI;QAC7D,kBAAkB,EAAE,MAAM,CAAC,gBAAgB,IAAI,IAAI;QACnD,qBAAqB,EAAE,MAAM,CAAC,kBAAkB;YAC9C,CAAC,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC,WAAW,EAAE;YACnD,CAAC,CAAC,IAAI;KACT,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,qCAAqC,CAAC,EACpD,MAAM,EACN,SAAS,EACT,QAAQ,GACoC;IAC5C,MAAM,cAAc,GAAG,CAAC,GAAG,QAAQ,CAAC,SAAS,EAAE,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC,IAAI,CACtE,cAAc,CACf,CAAC;IACF,MAAM,OAAO,GAAG,cAAc,CAAC,MAAM,GAAG,SAAS,CAAC;IAClD,MAAM,SAAS,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IAE1E,OAAO;QACL,OAAO,EAAE,SAAS;QAClB,QAAQ,EAAE,OAAO;QACjB,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC,IAAI;QAChD,cAAc,EAAE,SAAS,CAAC,MAAM;KACjC,CAAC;AACJ,CAAC"}

package/dist/application/directory-tree.d.ts

@@ -0,0 +1,11 @@
+export type DirectoryTreeSummary = {
+    entries: string[];
+    truncated: boolean;
+};
+type BuildDirectoryTreeSummaryOptions = {
+    exclude?: Set<string>;
+    maxEntries: number;
+};
+export declare function buildDirectoryTreeSummary(rootPath: string, options: BuildDirectoryTreeSummaryOptions): Promise<DirectoryTreeSummary>;
+export {};
+//# sourceMappingURL=directory-tree.d.ts.map

package/dist/application/directory-tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"directory-tree.d.ts","sourceRoot":"","sources":["../../src/application/directory-tree.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,oBAAoB,GAAG;IACjC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,SAAS,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,KAAK,gCAAgC,GAAG;IACtC,OAAO,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,wBAAsB,yBAAyB,CAC7C,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,gCAAgC,GACxC,OAAO,CAAC,oBAAoB,CAAC,CA+C/B"}

package/dist/application/directory-tree.js

@@ -0,0 +1,37 @@
+import path from "node:path";
+import fs from "fs-extra";
+export async function buildDirectoryTreeSummary(rootPath, options) {
+    const entries = [];
+    let truncated = false;
+    async function visit(currentPath, relativePath = "") {
+        if (entries.length >= options.maxEntries) {
+            truncated = true;
+            return;
+        }
+        const directoryEntries = (await fs.readdir(currentPath, { withFileTypes: true })).sort((left, right) => left.name.localeCompare(right.name));
+        for (const directoryEntry of directoryEntries) {
+            if (entries.length >= options.maxEntries) {
+                truncated = true;
+                return;
+            }
+            if (options.exclude?.has(directoryEntry.name)) {
+                continue;
+            }
+            const entryRelativePath = relativePath
+                ? path.posix.join(relativePath, directoryEntry.name)
+                : directoryEntry.name;
+            if (directoryEntry.isDirectory()) {
+                entries.push(`${entryRelativePath}/`);
+                await visit(path.join(currentPath, directoryEntry.name), entryRelativePath);
+                continue;
+            }
+            entries.push(entryRelativePath);
+        }
+    }
+    await visit(rootPath);
+    return {
+        entries,
+        truncated,
+    };
+}
+//# sourceMappingURL=directory-tree.js.map

package/dist/application/directory-tree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"directory-tree.js","sourceRoot":"","sources":["../../src/application/directory-tree.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,MAAM,UAAU,CAAC;AAY1B,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,QAAgB,EAChB,OAAyC;IAEzC,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,IAAI,SAAS,GAAG,KAAK,CAAC;IAEtB,KAAK,UAAU,KAAK,CAAC,WAAmB,EAAE,YAAY,GAAG,EAAE;QACzD,IAAI,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;YACzC,SAAS,GAAG,IAAI,CAAC;YACjB,OAAO;QACT,CAAC;QAED,MAAM,gBAAgB,GAAG,CACvB,MAAM,EAAE,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CACvD,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;QAE7D,KAAK,MAAM,cAAc,IAAI,gBAAgB,EAAE,CAAC;YAC9C,IAAI,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;gBACzC,SAAS,GAAG,IAAI,CAAC;gBACjB,OAAO;YACT,CAAC;YAED,IAAI,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC9C,SAAS;YACX,CAAC;YAED,MAAM,iBAAiB,GAAG,YAAY;gBACpC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,YAAY,EAAE,cAAc,CAAC,IAAI,CAAC;gBACpD,CAAC,CAAC,cAAc,CAAC,IAAI,CAAC;YAExB,IAAI,cAAc,CAAC,WAAW,EAAE,EAAE,CAAC;gBACjC,OAAO,CAAC,IAAI,CAAC,GAAG,iBAAiB,GAAG,CAAC,CAAC;gBACtC,MAAM,KAAK,CACT,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,cAAc,CAAC,IAAI,CAAC,EAC3C,iBAAiB,CAClB,CAAC;gBACF,SAAS;YACX,CAAC;YAED,OAAO,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;QAClC,CAAC;IACH,CAAC;IAED,MAAM,KAAK,CAAC,QAAQ,CAAC,CAAC;IAEtB,OAAO;QACL,OAAO;QACP,SAAS;KACV,CAAC;AACJ,CAAC"}

package/dist/application/materialize-application.d.ts

@@ -0,0 +1,16 @@
+import { type CodeModeApplicationWrapper, type MultiPageApplicationWrapperWithComponents, type SuperblocksSdk } from "@superblocksteam/sdk";
+type MaterializeApplicationParams = {
+    sdk: SuperblocksSdk;
+    application: CodeModeApplicationWrapper | MultiPageApplicationWrapperWithComponents;
+    branch: string;
+    directoryContentsHash?: string;
+    destinationPath?: string;
+};
+export type MaterializedApplication = {
+    checkoutPath: string;
+    isTemporary: boolean;
+    temporaryRootPath?: string;
+};
+export declare function materializeApplication({ sdk, application, branch, directoryContentsHash, destinationPath, }: MaterializeApplicationParams): Promise<MaterializedApplication>;
+export {};
+//# sourceMappingURL=materialize-application.d.ts.map

package/dist/application/materialize-application.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"materialize-application.d.ts","sourceRoot":"","sources":["../../src/application/materialize-application.ts"],"names":[],"mappings":"AAKA,OAAO,EAEL,KAAK,0BAA0B,EAC/B,KAAK,yCAAyC,EAC9C,KAAK,cAAc,EACpB,MAAM,sBAAsB,CAAC;AAE9B,KAAK,4BAA4B,GAAG;IAClC,GAAG,EAAE,cAAc,CAAC;IACpB,WAAW,EACP,0BAA0B,GAC1B,yCAAyC,CAAC;IAC9C,MAAM,EAAE,MAAM,CAAC;IACf,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;IACrB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEF,wBAAsB,sBAAsB,CAAC,EAC3C,GAAG,EACH,WAAW,EACX,MAAM,EACN,qBAAqB,EACrB,eAAe,GAChB,EAAE,4BAA4B,GAAG,OAAO,CAAC,uBAAuB,CAAC,CA+CjE"}

package/dist/application/materialize-application.js

@@ -0,0 +1,47 @@
+import os from "node:os";
+import path from "node:path";
+import fs from "fs-extra";
+import { writeApplicationToDisk, } from "@superblocksteam/sdk";
+export async function materializeApplication({ sdk, application, branch, directoryContentsHash, destinationPath, }) {
+    const resolvedDestinationPath = destinationPath
+        ? path.resolve(destinationPath)
+        : undefined;
+    if (resolvedDestinationPath &&
+        resolvedDestinationPath === path.parse(resolvedDestinationPath).root) {
+        throw new Error(`destination_path must not resolve to a filesystem root: ${resolvedDestinationPath}`);
+    }
+    const featureFlags = await sdk.getFeatureFlagsForCurrentUser();
+    const projectRootFolder = resolvedDestinationPath
+        ? path.dirname(resolvedDestinationPath)
+        : await fs.mkdtemp(path.join(os.tmpdir(), "superblocks-mcp-"));
+    const appRelativePath = resolvedDestinationPath
+        ? path.basename(resolvedDestinationPath)
+        : undefined;
+    let resourceConfig;
+    try {
+        resourceConfig = await writeApplicationToDisk({
+            sdk,
+            resource: application,
+            projectRootFolder,
+            appRelativePath,
+            directoryContentsHash,
+            featureFlags,
+            branch,
+        });
+    }
+    catch (error) {
+        if (!resolvedDestinationPath) {
+            // Best-effort cleanup for temporary materialization roots.
+            await fs.remove(projectRootFolder);
+        }
+        throw error;
+    }
+    return {
+        checkoutPath: path.resolve(projectRootFolder, resourceConfig.location),
+        isTemporary: !resolvedDestinationPath,
+        ...(resolvedDestinationPath
+            ? {}
+            : { temporaryRootPath: projectRootFolder }),
+    };
+}
+//# sourceMappingURL=materialize-application.js.map

package/dist/application/materialize-application.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"materialize-application.js","sourceRoot":"","sources":["../../src/application/materialize-application.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,MAAM,UAAU,CAAC;AAE1B,OAAO,EACL,sBAAsB,GAIvB,MAAM,sBAAsB,CAAC;AAkB9B,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,EAC3C,GAAG,EACH,WAAW,EACX,MAAM,EACN,qBAAqB,EACrB,eAAe,GACc;IAC7B,MAAM,uBAAuB,GAAG,eAAe;QAC7C,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,eAAe,CAAC;QAC/B,CAAC,CAAC,SAAS,CAAC;IACd,IACE,uBAAuB;QACvB,uBAAuB,KAAK,IAAI,CAAC,KAAK,CAAC,uBAAuB,CAAC,CAAC,IAAI,EACpE,CAAC;QACD,MAAM,IAAI,KAAK,CACb,2DAA2D,uBAAuB,EAAE,CACrF,CAAC;IACJ,CAAC;IAED,MAAM,YAAY,GAAG,MAAM,GAAG,CAAC,6BAA6B,EAAE,CAAC;IAC/D,MAAM,iBAAiB,GAAG,uBAAuB;QAC/C,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,uBAAuB,CAAC;QACvC,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,kBAAkB,CAAC,CAAC,CAAC;IACjE,MAAM,eAAe,GAAG,uBAAuB;QAC7C,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,uBAAuB,CAAC;QACxC,CAAC,CAAC,SAAS,CAAC;IAEd,IAAI,cAAoC,CAAC;IACzC,IAAI,CAAC;QACH,cAAc,GAAG,MAAM,sBAAsB,CAAC;YAC5C,GAAG;YACH,QAAQ,EAAE,WAAW;YACrB,iBAAiB;YACjB,eAAe;YACf,qBAAqB;YACrB,YAAY;YACZ,MAAM;SACP,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC,uBAAuB,EAAE,CAAC;YAC7B,2DAA2D;YAC3D,MAAM,EAAE,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC;QACrC,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;IAED,OAAO;QACL,YAAY,EAAE,IAAI,CAAC,OAAO,CAAC,iBAAiB,EAAE,cAAc,CAAC,QAAQ,CAAC;QACtE,WAAW,EAAE,CAAC,uBAAuB;QACrC,GAAG,CAAC,uBAAuB;YACzB,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,CAAC;KAC9C,CAAC;AACJ,CAAC"}

package/dist/application/summary.d.ts

@@ -0,0 +1,25 @@
+import type { MultiPageApplicationWrapper, MultiPageApplicationWrapperWithComponents } from "@superblocksteam/sdk";
+export type ApplicationMode = "1.0" | "2.0";
+export type ApplicationModeLabel = "Legacy Low Code Apps" | "Clark AI Apps";
+export declare function inferApplicationMode(application: Record<string, any>): ApplicationMode;
+export declare function applicationModeLabel(mode: ApplicationMode): ApplicationModeLabel;
+export declare function applicationModeNote(mode: ApplicationMode): string;
+export declare function summarizeApplication(applicationWrapper: MultiPageApplicationWrapper): {
+    application_id: any;
+    application_mode: ApplicationMode;
+    deployed_commit_id: string | null;
+    name: any;
+    organization_id: any;
+};
+export declare function summarizeMultiPageApplicationStructure(applicationWrapper: MultiPageApplicationWrapperWithComponents): {
+    application_mode: "1.0";
+    app_api_count: number;
+    app_api_names: string[];
+    page_count: number;
+    pages: {
+        id: string;
+        name: string;
+        api_names: string[];
+    }[];
+};
+//# sourceMappingURL=summary.d.ts.map

package/dist/application/summary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"summary.d.ts","sourceRoot":"","sources":["../../src/application/summary.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,2BAA2B,EAC3B,yCAAyC,EAC1C,MAAM,sBAAsB,CAAC;AAE9B,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,KAAK,CAAC;AAC5C,MAAM,MAAM,oBAAoB,GAAG,sBAAsB,GAAG,eAAe,CAAC;AAc5E,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC/B,eAAe,CAEjB;AAED,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,eAAe,GACpB,oBAAoB,CAEtB;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,CAIjE;AAED,wBAAgB,oBAAoB,CAClC,kBAAkB,EAAE,2BAA2B;;;;;;EAUhD;AAED,wBAAgB,sCAAsC,CACpD,kBAAkB,EAAE,yCAAyC;;;;;;;;;;EAqB9D"}

package/dist/application/summary.js

@@ -0,0 +1,42 @@
+function getApiName(api) {
+    return api.apiPb?.metadata?.name ?? "Unnamed API";
+}
+export function inferApplicationMode(application) {
+    return application.devEnvEnabled ? "2.0" : "1.0";
+}
+export function applicationModeLabel(mode) {
+    return mode === "1.0" ? "Legacy Low Code Apps" : "Clark AI Apps";
+}
+export function applicationModeNote(mode) {
+    return mode === "1.0"
+        ? "Legacy Low Code Apps are the legacy multi-page app model (1.0)."
+        : "Clark AI Apps are the code-mode app model (2.0).";
+}
+export function summarizeApplication(applicationWrapper) {
+    const application = applicationWrapper.application;
+    return {
+        application_id: application.id,
+        application_mode: inferApplicationMode(application),
+        deployed_commit_id: applicationWrapper.deployedCommitId ?? null,
+        name: application.name,
+        organization_id: application.organizationId,
+    };
+}
+export function summarizeMultiPageApplicationStructure(applicationWrapper) {
+    const pages = applicationWrapper.pages.map((page) => ({
+        id: page.id,
+        name: page.name,
+        api_names: [...page.apis.map((api) => getApiName(api))].sort((left, right) => left.localeCompare(right)),
+    }));
+    const appApiNames = [
+        ...applicationWrapper.apis.map((api) => getApiName(api)),
+    ].sort((left, right) => left.localeCompare(right));
+    return {
+        application_mode: "1.0",
+        app_api_count: applicationWrapper.apis.length,
+        app_api_names: appApiNames,
+        page_count: applicationWrapper.pages.length,
+        pages,
+    };
+}
+//# sourceMappingURL=summary.js.map

package/dist/application/summary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"summary.js","sourceRoot":"","sources":["../../src/application/summary.ts"],"names":[],"mappings":"AAgBA,SAAS,UAAU,CAAC,GAAa;IAC/B,OAAO,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,IAAI,IAAI,aAAa,CAAC;AACpD,CAAC;AAED,MAAM,UAAU,oBAAoB,CAClC,WAAgC;IAEhC,OAAO,WAAW,CAAC,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC;AACnD,CAAC;AAED,MAAM,UAAU,oBAAoB,CAClC,IAAqB;IAErB,OAAO,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,sBAAsB,CAAC,CAAC,CAAC,eAAe,CAAC;AACnE,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,IAAqB;IACvD,OAAO,IAAI,KAAK,KAAK;QACnB,CAAC,CAAC,iEAAiE;QACnE,CAAC,CAAC,kDAAkD,CAAC;AACzD,CAAC;AAED,MAAM,UAAU,oBAAoB,CAClC,kBAA+C;IAE/C,MAAM,WAAW,GAAG,kBAAkB,CAAC,WAAW,CAAC;IACnD,OAAO;QACL,cAAc,EAAE,WAAW,CAAC,EAAE;QAC9B,gBAAgB,EAAE,oBAAoB,CAAC,WAAW,CAAC;QACnD,kBAAkB,EAAE,kBAAkB,CAAC,gBAAgB,IAAI,IAAI;QAC/D,IAAI,EAAE,WAAW,CAAC,IAAI;QACtB,eAAe,EAAE,WAAW,CAAC,cAAc;KAC5C,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,sCAAsC,CACpD,kBAA6D;IAE7D,MAAM,KAAK,GAAG,kBAAkB,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACpD,EAAE,EAAE,IAAI,CAAC,EAAE;QACX,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,SAAS,EAAE,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAC1D,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAC3C;KACF,CAAC,CAAC,CAAC;IAEJ,MAAM,WAAW,GAAG;QAClB,GAAG,kBAAkB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;KACzD,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC;IAEnD,OAAO;QACL,gBAAgB,EAAE,KAAc;QAChC,aAAa,EAAE,kBAAkB,CAAC,IAAI,CAAC,MAAM;QAC7C,aAAa,EAAE,WAAW;QAC1B,UAAU,EAAE,kBAAkB,CAAC,KAAK,CAAC,MAAM;QAC3C,KAAK;KACN,CAAC;AACJ,CAAC"}

package/dist/auth/commands.d.ts

@@ -0,0 +1,3 @@
+export declare function maybeRunAuthCommand(args: string[]): Promise<boolean>;
+export declare function getMcpUsageText(): string;
+//# sourceMappingURL=commands.d.ts.map

package/dist/auth/commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../src/auth/commands.ts"],"names":[],"mappings":"AAwFA,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAyB1E;AAED,wBAAgB,eAAe,IAAI,MAAM,CAExC"}