Macaly Cloud

Fetch one public webpage as markdown (text, headings, links and full image URLs) to reference or recreate it in the selected Macaly app. For normal marketing, docs and content pages; it cannot log in, crawl several pages or extract structured records. For images of a page, use screenshot_webpage. Returns up to the first 40,000 characters; a longer page is marked truncated with totalChars and nextOffset, and calling again with the same url and offset set to nextOffset reads the next part from a copy Macaly keeps for 15 minutes, at no charge. Never pass a preview_app access link. Each new fetch uses the workspace's Macaly credits.

fetch_webpage

Create a new image from a text prompt for the selected Macaly app (hero, mockup, illustration, icon, favicon); the result is saved to the app's media library. Only for the app: for an image the user just wants to look at, use your own image generation. To change an existing image, use edit_image; to make a background transparent, use remove_image_background. Returns imageUrl, a public, permanent link to use in the app's code. You cannot see the image, so never claim it matches the request; share imageUrl with the user. Can take up to about two minutes. Each call uses the workspace's Macaly credits. For image generation inside the finished app, write a Convex action as the ai-image guide shows.

generate_image

Generate an AI music track for the selected Macaly app (background music, a jingle, a song); it is saved to the app's media library. Only for the app. Takes the music-generation guide's prompt, lyrics, style and instrumental; there is no mode, outputFormat or providerOptions: lyrics and style apply whenever given, and the track is MP3. Returns a jobId at once; the track takes about 1 to 3 minutes: call get_media_job with that jobId (each call waits up to waitSeconds), never wait with run_project_command, and never start the same track again while it runs. Its 40,000 credits are reserved when the job starts and charged when the provider finishes generating; a generation that fails or times out is not charged, but if saving the finished file then fails, the credits stay charged (the provider was paid). A repeat call with the same fields while the job runs returns the same job and is not charged again. You cannot listen to it: share audioUrl with the user. For music generation inside the finished app, write a Convex action as the music-generation guide shows.

generate_music

Turn text into speech for the selected Macaly app (voice-over, greeting, narration, pronunciation clips); each clip is saved to the app's media library. Only for the app's audio. Same options as the text-to-voice guide, with its providerOptions as top-level fields: style and languageCode for gemini, pitch and volume for minimax, emotion for both. Pass text for one clip, or items (up to 10) for several in one call; the other top-level fields apply to every item that does not set its own. Returns audioUrl, a public, permanent link to use in the app's code; with items, a result or an error for each item. You cannot listen to the audio, so never claim it sounds right; share audioUrl with the user. Each clip uses the workspace's Macaly credits. For speech inside the finished app, write a Convex action as the text-to-voice guide shows.

generate_speech

Generate a 5- or 10-second AI video for the selected Macaly app, e.g. a hero background; it is saved to the app's media library. Only for the app. Same parameters as the video-generation guide, without providerOptions (generateAudio and cfgScale are fields). Returns a jobId at once; the video takes about 2 to 5 minutes: call get_media_job with that jobId (each call waits up to waitSeconds), never wait with run_project_command, and never start the same video again while it runs. Provider "seedance2" needs the user's agreement to its cost: its first call starts nothing and returns costConfirmationRequired with the exact credits and a costConfirmationId; tell the user the cost, and only after they agree in the conversation call again with chatId and costConfirmationId. Credits from the guide's pricing table (160,000 to 600,000) are reserved when the job starts, so the workspace balance shows them as used, and charged when the provider finishes generating; a generation that fails, is refused or times out is not charged, but if saving the finished file then fails, the credits stay charged (the provider was paid). A repeat call with the same fields while the job runs returns the same job and is not charged again. startImageUrl is a public image URL, e.g. from generate_image or list_media, never a preview_app access link. You cannot watch the video: share videoUrl with the user. For video generation inside the finished app, write a Convex action as the video-generation guide shows.

generate_video

Read how the app's Convex database is being used, to find hot, slow or failing functions and to explain backend cost. Returns two independent parts: history, 7 days of stored daily usage (function calls, documents and bytes read, file egress; Live and Testing combined) plus this month's workspace overage; and functions, a recent snapshot of the busiest functions over the last 15 or 60 minutes (calls, p50/p99 latency, errors, cache hit rate). Either part can be unavailable; then continue with a code review instead of retrying in a loop. The snapshot refreshes at most every 90 seconds, is not billing data, and must never be described as 24-hour or 7-day data.

get_database_usage

Get the newest publish attempt of the app, or the one named by deploymentId: status (QUEUED/BUILDING/READY/DELIVERED/ERROR), deployment url and connected domains. liveUrl is the URL of the version that is live now; give the user liveUrl, not url. During a re-publish, liveUrl keeps the previous version until the new one is READY. Poll after publish_app with its id until READY, DELIVERED or ERROR. On ERROR, call get_logs with log_type 'deploy' and the same deploymentId for the build stderr. DELIVERED means partner publishing is complete; no further status check is required. Do not invent a site URL.

get_deployment

Get the SVG markup of one Streamline item, by the hash from search_icons, to embed in the selected Macaly app's code as inline SVG. Same download options as the icon-search guide: size (default 48), responsive (default true), colors (literal HEX codes or CSS color names), backgroundColor, strokeWidth and strokeToFill. Returns svg, the markup, up to 24,000 characters; a larger item is refused. SVG only: for a raster image, embed the SVG instead. The markup is for the app's code only: never upload it to the media library or serve it as a standalone file, and keep its <desc> credit. Uses no Macaly credits.

get_icon

Diagnose the published (live) site. It requests one path on the live URL and returns the HTTP status plus the server runtime log lines recorded for that path during a short listening window, with a note on how to read them. Call it first when the user says the live site is broken, returns 500, or behaves differently from the preview, before guessing a cause or republishing. Quote a matching log line verbatim; credentials in it come back as <redacted>. It never runs browser JavaScript, so a 2xx with no logs does not prove the page renders. Requires a published app. At most 6 calls per 10 minutes per app, shared with Macaly's own agent; each call takes up to about 45 seconds. For build errors of a publish, use get_logs 'deploy'.

get_live_site_logs

Fetch real logs for the project, head/tail-truncated. log_type: 'build' = latest preview build (status, failure reason, build output errors); 'dev_server' = tail of the live sandbox dev-server log (boots the sandbox if needed, ~20s cold); 'deploy' = the newest publish attempt, or the one named by deploymentId, and its build stderr from the hosting provider.

get_logs

Read a video or music job that generate_video or generate_music started, by its jobId; without jobId, list this app's 10 newest jobs (each with a prompt excerpt, provider and duration) without waiting. While a job is queued or running, the call waits up to waitSeconds for it to finish, then returns nextPollAfterSeconds; never wait with run_project_command. Keep calling it in this turn while it runs; if it is still running after about 3 calls, tell the user it is generating and that you can check when they ask, and never start the same generation again because a read is pending. A finished job returns videoUrl or audioUrl, a public, permanent link already in the app's media library, and creditsCharged; a failed one returns error, charged and what to do next. Reading costs nothing.

get_media_job

Project status snapshot: preview build state, preview URL, newest publish status, liveUrl (the URL to give the user for the version that is live now), and active claims. Pass includeBriefing: true to also get the project briefing (stack, boundaries, conventions, workflow and working rules) — create_app already returned it, so leave it off when polling, but pass it once when you continue an existing app in a new conversation. Decide your next action: agentTurnPhase='idle' → write_file/edit_file/delete_file to make changes (each call commits immediately; no need to wait for anything after create_app). agentTurnPhase != 'idle' → Macaly's own agent is working on this app; do NOT write, retry later. activeEditor set → another external editor wrote recently (sameUser: true means another app connected to the same Macaly account, which shares this worktree). After your last write → typecheck with run_project_command ".sandbox/check-errors --strict"; on problems → get_logs. previewUrl serves content once previewBuildStatus='succeeded' (builds run automatically after bootstrap and shortly after your last write). Use publish_app only when the user asks to go live; then poll get_deployment.

get_project

Read the app's conversation history. The first page holds the newest messages and nextCursor pages backward to older ones; within a page, messages are in chronological order (oldest first). Use it to catch up on the chat before making changes — what the user asked for and what was built so far. Returns each message's role, plain text and creation time plus a tool-call count; internal build traces and tool payloads are omitted to keep responses small.

get_messages

Read an SEO audit of the app. Pass the auditId request_seo_audit returned: a publish creates a newer published-site audit, and without auditId you get the newest report of any kind. state is not_requested, building (capturing the files and deploying the temporary preview), auditing, completed, or failed with error. While it is building or auditing, the call waits up to waitSeconds for the state to change, then returns nextPollAfterSeconds; never wait with run_project_command. Make no file writes until it leaves building. If it is still building or auditing after a few calls, tell the user it is running and check back later with get_seo_audit (no auditId needed); never start another run because a read is pending. A completed audit returns score, category scores, findings (failed and warning checks with their affected pages), auditedPaths and page patterns; includeFullReport adds page summaries and performance metrics. Compare auditedPaths with the app's routes before claiming full-site coverage.

get_seo_audit

Read visitor analytics for the app's published site. report 'overview' returns visitors, pageviews, visits, bounceRate and visitDuration, each as total plus diff: the relative change vs the previous period of equal length (1 = +100%, -0.5 = -50%). The other reports rank pages, referrers, countries, browsers, device types or UTM values (pass utmParameter for 'utm'). Start with 'overview', then drill down. Defaults: the last 7 days for 'overview' and 30 days for the rest; the oldest custom domain connected to the app, else its oldest Macaly address, else its generated Macaly address. The result's legend gives the units: tell the user '+50%', not 'diff 0.5', and bounce rate as a percentage. An app that is not published now returns published: false unless you pass domain, which reads an earlier address's past visits; zero or empty results mean the site has had no visitors in that period.

get_site_analytics

Get the one-time code the selected Macaly app just emailed to a reserved test address, to finish an email-code sign-in, email verification or password reset while testing the app in the sandbox browser. Only e2e+<id>@e2e.macaly.dev addresses work: Macaly keeps their codes instead of emailing them, for apps that send codes through Macaly (the auth-otp and email-and-password-auth guides). Submit the address in the app and wait until the code field is visible, then call this tool and type the code with run_project_command (agent-browser fill) in the same browser session. Each code is returned once and then deleted, and expires 5 minutes after it was sent. Status 'pending' means no code is waiting after waitSeconds: not sent yet, already returned, or expired; have the app send a new one. Never use a real person's email or a fixed code.

get_test_otp

Import data into the app's Convex database: a Convex snapshot ZIP, or a CSV, JSON array or JSONL file for one table. On this connector it replaces the deploy-convex-app guide's npx convex import. If convex/schema.ts changed since the last deploy, deploy it with deploy_database first. target must be the database the app currently uses (get_project.database.sandbox.environment: Testing is testing, Live is live); this tool never switches it and refuses a mismatch. A Live import changes the published app's data at once: get the user's explicit go-ahead in the conversation, then pass liveAuthorized true. Choose mode from the user's request: requireEmpty imports only into empty tables; append adds rows; replace replaces the imported tables (with a ZIP, every table in it, including sign-in tables when the export has them); replaceAll, ZIP only, also clears every table the ZIP lacks, including sign-in data, so use it only when the user asked to replace the whole database. Macaly backs up Live before a Live replace or replaceAll. Pass the file as path, a file in the app's sandbox (prefer /tmp/, which is never committed), or as mediaAssetId only for a file the user already put in the media library: upload_file publishes a file at a public URL, so never upload a data file just to import it. Export spreadsheets as CSV first. CSV cells import only as numbers or strings: for booleans, ids, arrays, objects or empty cells, convert the file to JSONL first. table is required for CSV and JSON files and not allowed for a ZIP. A long import returns status in_progress with importId: call again with only chatId and importId to read its state. An identical import within 15 minutes is not run again; to run it once more when the user asks for the same rows again, pass the repeatToken its result returned. Publish never copies Testing data to Live. Read message and follow nextStep.

import_database_data

List the files in the app's media library — everything uploaded by the user or added with upload_file — so you can reference their public URLs from the app's code. Check here before asking the user for an image; they may already have uploaded it. The response also includes an uploadUrl: a link to this app's media library. When the user has a file only on their computer and you cannot send it yourself with upload_file (no local shell, or the upload host is blocked), send them that link, ask them to drag the file in, and call this tool again to pick it up. No tool can accept raw bytes.

list_media

List the Macaly apps of a team, most recently updated first (paginated; pinned apps come back in full on the first page only, and later pages return an empty pinnedProjects). Use it to find the chatId of an existing app to inspect or edit — pass it to get_project, list_files, read_file and the write tools.

list_projects

List the project's source file paths (paginated array of strings). Use read_file to fetch a file's contents.

list_files

List the Macaly teams you can act on. Use this to discover the teamId to pass to create_app when connected via OAuth (API keys are scoped to one team and never need it).

list_teams

List the app's variants: alternative versions with their own code and chat, sharing the app's data, uploads and live URL. Returns each variant's id, name, branch, saved headCommitHash and macalyUrl, plus activeId (the active variant, the one this connector's tools edit), revision and lastPublishedId (the variant the live site serves; null if never published). Inspect saved code with git through run_project_command (git show '<commit>:<path>', git diff '<a>' '<b>'); saved commits leave out uncommitted edits. Creating, switching, renaming and deleting variants happen in Macaly, not here: share macalyUrl, or a variant's macalyUrl to open that variant there; switching changes which variant this connector edits. Not available for scratchpads.

list_variants

Open the Macaly live preview panel. Without chatId it lists the apps of a team (teamId, or your first team); with chatId it creates a temporary preview access link for that app. The user opens this panel from the conversation or from the Macaly app in the ChatGPT sidebar; use preview_app to show an app yourself.

open_preview_panel

Search the user's Macaly apps by title for @-mentions in the composer. Returns resource links whose description carries the chatId to pass to other tools. Type "<app>/<file>" (for example "bakery/page") to mention a source file or media item of the matching apps instead; those links also carry the file path or the media's public URL.

mention_projects

Get the app's LIVE preview URL to share with the user. Call it at the end of every turn that changed the app, after the preview rebuild succeeds (get_project reports previewBuildStatus), even when an earlier link is still valid: the call tells Macaly that your turn is finished. Pass path to open a subpage directly (e.g. "/pricing") and give the user that link instead of telling them where to navigate. It never triggers a build; it creates a temporary, exact-app access link valid for three hours.

preview_app

Read the preview build status of a Macaly app, whether the live preview panel may publish it, and its live URL. The live preview panel calls this tool.

get_preview_status

Publish the app to production (make it publicly live at its macaly.app URL). Only call this when the user explicitly asks to go live. Requires at least one committed edit. Asynchronous — poll get_deployment with deploymentId set to the id this tool returns until status is READY or DELIVERED (or ERROR, then check get_logs with log_type 'deploy' and the same deploymentId). Then give the user liveUrl from get_deployment. DELIVERED means partner publishing is complete; report the project as published without inventing a site URL.

publish_app

Read one project file by path. Pass `path` exactly as list_files returned it. A missing path is a NOT_FOUND error. Pass startLine and endLine (1-based, inclusive) to read only part of a large file; every response reports totalLines. Responses are capped at 100000 characters: a cut response has truncated: true and nextStartLine, the line to read next.

read_file

Make the background of one image transparent for the selected Macaly app, e.g. a logo, product photo or portrait for a colored section. The result is saved to the app's media library as a new image; the input image is not changed. The default provider redraws the image with AI, which can change details and size; for an exact cut-out of a logo, photo or product, pass provider "nanobanana". Input images are public URLs, e.g. from list_media, upload_file or generate_image; never a preview_app access link. Returns imageUrl, a public, permanent link to use in the app's code. You cannot see the image, so never claim it matches the request; share imageUrl with the user. Each call uses the workspace's Macaly credits.

remove_image_background

Rename a Macaly app. This changes the title shown in the user's project list and dashboard. Use it when the user asks for a new name, or when the auto-generated title no longer matches what the project has become. Use a short, concrete product name (2-6 words) and leave a title that is still accurate alone. This does not change the app's URL; use rename_subdomain for that.

rename_app

Change the app's free Macaly address, e.g. to better-name.macaly.app. Pass only the label ('better-name'); the app must already be published, and the old Macaly URL stops working immediately. Visitor analytics start fresh under the new address. If another app holds that address, nothing changes and the response returns moveConfirmationRequired: explain that the address will be removed from that app at once, and retry with moveFromChatId only after the user explicitly agrees. For a domain the user owns, use connect_domain instead.

rename_subdomain

Restore the platform-managed connection variables in the app's Convex deployment with a freshly issued token: MACALY_API_TOKEN, MACALY_BASE_URL, MACALY_CHAT_ID, MACALY_DATABASE_ENVIRONMENT and MACALY_APP_FILES_PROTOCOL (plus a preview bypass header where one is needed). Use it when a Convex function gets 401 or 403 from Macaly platform APIs, including '403 Missing required scope', or when those variables are missing or wrong; set_env_vars cannot set them. It repairs the deployment the app currently targets (Live or Testing), revokes the token it replaces, and checks the other deployment in the background. Requires an existing database. Never ask the user for these values.

repair_platform_env

Request an SEO audit of the app's current code, including uncommitted edits. Macaly captures the sandbox's files, deploys them to a temporary noindex preview, audits it, saves the findings and removes the preview; it never publishes the app or touches its domain, so never publish just to get a report. Finish your file edits first. Returns an auditId with state 'building'. Make no file writes until get_seo_audit says it left building: edits before that, by you or Macaly's agent, fail the audit, and you can request it again. Then read the report with get_seo_audit and this auditId. One audit runs per app at a time, and a run still pending after 20 minutes is reported as failed. Not available for scratchpads.

request_seo_audit

Research what building or debugging the selected Macaly app needs: library and API documentation, install steps, reference content. Only for that work; answer general questions with your own browsing instead. Returns an answer with citations, search_results (title, url, snippet, date) and images. Set deepResearch for detailed library or API documentation with exact install steps; it is slower (often 20 to 60 seconds) and costs more. Each search uses the workspace's Macaly credits. For search inside the finished app, write a Convex action that calls the endpoint as the internet-search guide shows; this tool is for your own research.

search_web

Use this for development commands for this app that file tools cannot perform: installing packages, builds, tests, framework CLIs, migrations, git, and validation. Macaly platform capabilities have their own tools. It runs a full shell from the selected Macaly app's project root inside an isolated cloud sandbox; it cannot access the user's device or other Macaly projects. The command can modify or delete files in the selected project and can contact external internet services. Execution is authorized, time-limited, rate-limited, and audited. Prefer write_file/edit_file/delete_file for source edits: they create Git history, and protected paths are checked before command-made changes are persisted with the next write_file, edit_file or delete_file. Run '.sandbox/check-errors' after the last source change.

run_project_command

Capture a screenshot of the selected Macaly app or of a public webpage, as images to share with the user or to keep as a design reference. You cannot see the images, so never claim from them that a page looks right. target "preview" captures the app's preview as the user sees it (pass path for a subpage); it needs a successful preview build (get_project.previewBuildStatus). "sandbox" captures the live dev server in the app's sandbox, with the latest files before the preview rebuilds, and may start the sandbox. "external" captures a public url. Without target, a url means external and no url means preview. Same parameters as the webpage-screenshot guide. Returns imageUrls: public, permanent image links, also for the private preview; a tall page comes in several parts, top to bottom. Never pass a preview_app access link as url. Each screenshot uses the workspace's Macaly credits.

screenshot_webpage

Search Streamline icons, illustrations, emojis and design elements for the selected Macaly app, e.g. to replace emoji or default icons on a landing page. Same parameters as the icon-search guide: query, productType (default "icons"), offset, limit (default 20), productTier and style. Returns results with hash, name, imagePreviewUrl, isFree, family and category, and pagination with nextOffset. You cannot see imagePreviewUrl: choose by name and family, or share the previews with the user; never reference them from the app. Pass a result's hash to get_icon for its SVG markup. Uses no Macaly credits.

search_icons

Search the documentation for the selected app's workspace to answer how-to questions about the platform: publishing, domains, database, settings. Returns results with title, link and content. Describe only what the results support, and give the user the returned link exactly; never build documentation URLs yourself. For platform API access, tell the user to contact support.

search_platform_docs

Search Pexels stock photos for the selected Macaly app (hero, backgrounds, section imagery). Only for building the app; for photos the user just wants to see, use your own search. Same parameters as the stock-photo-search guide: query, orientation, size, color (a color name or a hex code such as "#FF0000"), page and per_page (default 4, at most 80). Returns photos with the Pexels page url, photographer credit, average color, src links (medium, large, large2x) and alt text, and next to pass back as given for more. You cannot see the photos: choose by alt and share the links with the user. Credit photographers as "Photo by NAME on Pexels". Uses no Macaly credits.

search_stock_photos

Save API keys, URLs and other settings that the app or its Convex functions read from process.env. Values are merged into the project's .env.local (other variables are kept), committed, and synced to every attached Live and Testing Convex deployment, so Convex functions see them right away; app code reads its values after the next preview build or publish. It cannot delete a variable; an empty string is stored as a value. Platform-managed names (MACALY_*, CONVEX_*, SITE_URL, auth keys and similar) are refused and listed in blockedVars; use repair_platform_env for MACALY_* problems. Never give a secret a VITE_ or NEXT_PUBLIC_ name, because those reach the browser.

set_env_vars