Skip to main content
Glama
Sign In

kad.dev

by dev.kad
OverviewDiscussionsAdmin

Sync files to a draft

sync_files
DestructiveIdempotent

Edits an app's draft: writes files into a temporary running copy of the app and returns dev_url, WITHOUT a commit or a build. Use it on managed apps with draft runtimes: static, vite, react, vue, svelte, sveltekit, remix, nextjs, astro, nuxt, angular, gatsby, fastapi, flask, django, node, and configured sanic presets. Go, rust and spring-boot require the server rollout flag; dockerfile has no draft runtime. Start can return starting: retry sync_files to check readiness. Startup notes arrive once in note, even after a slow start. data chooses copy (default) or empty on a new draft; a running draft keeps its choice. Where enabled and available, Copy seeds the database and app files at start and reads the bucket live; Empty starts without that data. Writes stay in the draft. The reply reports modes, timestamps and unavailable-copy notes. A change in the draft is not live and not saved: tell the user so, and give dev_url as a preview. New drafts inherit default_public, including drafts with data; the owner can switch public/private on the draft row. Google-login apps stay behind their login and cannot be made public. get_app_status reports the draft public flag. dev_url is private unless the draft is public; do not suggest sharing it unless the owner made it public (plus expires_at and notice when the app is a temporary 72h project). When the user is happy with the result, publish_draft makes everything the draft holds live in ONE commit (deploy_files once with the final files does the same); a commit per small edit fills the timeline and is slow. The result gives unsaved_files, the number of files that exist only in the draft, and next_step. A draft is temporary: it stops after 30 minutes without a sync, and the platform can stop it earlier. When it stops by itself, the files it received are kept for 24 hours; the next sync_files starts a new draft, brings them back and says so in note, so do not resend everything. The owner can stop a draft from the dashboard, which discards its unsaved files; note then says so. The draft does not change deploy_url or canonical_host, and it keeps running after a publish. Each file accepts an optional sha256 (hex) to verify against; on any mismatch the whole call fails before anything is applied, naming the offending file(s), and the response echoes each file's actual sha256 in files[]. Requires a read-write token.

Input Schema

NameRequiredDescriptionDefault
dataNoused only when starting a draft: copy (default) copies managed Postgres and app files at storage_mount_path once at startup (files up to 500 MiB and 50000 entries), and reads the live bucket with separate draft uploads and deletes; empty starts with an empty database, bucket and app-files directory. Omit to inherit the stopped draft's choice on restore. Neither changes production; draft data never publishes
filesNofiles to create or overwrite in the draft (path + full content)
project_idYesthe managed project id (from list_projects)
delete_pathsNopaths to remove from the draft

Output Schema

NameRequiredDescriptionDefault
noteNo
errorNostartup failure, including the dependency install log tail when npm or pip fails
filesNo
stateYes
noticeNo
syncedYes
deletedYes
dev_urlYes
databaseNoresolved managed draft database: copy, empty, or none; absent while the first seed is pending
dev_errorNocompiler diagnostics, missing build manifest, app crash log tail, dependency install failure, or draft database is full (read-only); follow next_step and check this field is gone before claiming the preview is right
next_stepNowhat makes the draft's changes live, or what to do when the dev server is down
restartedYes
data_as_ofNostart of the production database snapshot (RFC 3339, UTC); only present for a copied database
dev_serverNopresets with a dev server: running, starting, restarting, building, build failed (possibly serving the previous build), install_failed, or 'not running: <reason>'
expires_atNo
files_modeNoresolved app-files mode: none, copy, or empty
files_noteNoapp-files copy result, limits, or empty fallback
base_commitNoset only when the owner started this draft from an older commit: its full sha. The draft's files come from that commit, not from the newest code
files_as_ofNoUTC time the production app-files copy began; absent for none or empty
unsaved_filesYeshow many files (changed or deleted) exist only in the draft: they are not live and not saved as a commit
dev_config_errorNolog lines when edited dev-server config or Python/Node source failed to load. The watcher can remain running while the app is down or serving old code; fix the file before saying the preview works

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already flag destructiveHint=true and idempotentHint=true, but the description adds substantial context the annotations cannot convey: writes stay in the draft and are not live or saved, drafts stop after 30 minutes of inactivity and keep files 24 hours, an owner-initiated stop discards unsaved files, dev_url is private unless the draft is public, and a read-write token is required. The sha256 fail-before-apply contract is also stated explicitly.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded correctly, but the remainder is one dense paragraph covering draft lifecycle, visibility defaults, Google-login edge cases, 72h projects, publish guidance and sha256 behavior. Nearly every sentence carries operational value, yet the lack of structure makes it hard to scan and several advisories arguably belong with publish_draft or get_app_status.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, stateful mutation on a temporary runtime, the definition covers start/stop/restore behavior, failure modes, token requirements and next steps; with an output schema present it does not need to explain return values. An agent has enough to call this correctly on the first attempt.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds a little on the `data` parameter (copy vs empty, a running draft keeps its earlier choice, copy seeds DB/app files and reads the bucket live) and on per-file sha256 verification, but that largely restates what the schema descriptions already say.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence gives a specific verb and resource ('Edits an app's draft: writes files into a temporary running copy') and immediately delimits it against deploy/build semantics ('WITHOUT a commit or a build'). An agent can distinguish it from deploy_files, publish_draft and start_commit from the first line alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It enumerates the runtimes where the tool applies (static, vite, react ... configured sanic presets), the exceptions requiring flags (go, rust, spring-boot), the runtimes with no draft runtime (dockerfile), and the retry path ('Start can return starting: retry sync_files'). It also routes the agent to publish_draft once the user is satisfied, explaining why ('a commit per small edit fills the timeline').

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All kad.dev toolsInspect
Try in Browser
Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources