Skip to main content
Glama

project_deploy

Deploy / ship / host / push / release your app — upload raw source (HTML, CSS, JS, server functions) to a project and put it in production at https://{subdomain}.somewhere.site. The platform compiles your code; you deploy source, not a build.

If you can run a shell, LEAD WITH the CLI: somewhere deploy reads files straight from disk (no inline JSON payload) and is the faster path. The CLI installs with npm i -g @somewhere-cloud/cli && somewhere auth login (shares MCP auth). This MCP tool is the inline fallback — for agents without shell access, small projects, or when the CLI isn't available.

For UPDATES to an existing project, project_patch with find/replace ships surgical edits in ~200 bytes instead of resending every file. project_deploy is for the FIRST deploy of a new project, or for replacing the whole tree.

Large or binary files are referenced, not pasted. Instead of being inlined into files, a big asset (or base64 bytes) goes to project file storage first with fs_write and is referenced by storage path via file_refs (text files) or binary_file_refs (images, fonts, other binaries). The platform resolves the referenced content server-side at deploy time, so a big tree ships without a giant inline payload. Inline files/functions keep working and can be mixed with refs in the same deploy.

Deploys your app. The result lands at https://{subdomain}.somewhere.site and on any verified custom domain — every deploy reaches production.

⚠️ Omitted items are NOT all treated the same. Static files are full-replacement: anything you omit from files is deleted (scope:"functions" leaves static untouched). functions are merge-preserved by default: a function already in production but omitted from this call is KEPT, not deleted — so you can ship a backend-only change without resending the frontend, and project_patch-only functions survive a later full deploy. replace_functions:true makes a deploy delete functions it no longer ships. (Env vars, database, and uploaded fs files are never affected.) Use dry_run:true to inspect exactly what will be added / removed / modified before anything is written. project_patch with a files map changes several files of an existing project without resending the rest: files not listed are kept.

Server-side functions are the core — handler code goes in the functions map (keyed by path, e.g. "api/hello.ts") and becomes routable at /api/... on your production URL. The files map is for STATIC assets only (HTML, CSS, client-side JS, images). Handler code (api/*, _lib/*, root [id].ts routes) belongs in functions, not files — a static asset never routes, so /api/* would just serve the app's HTML. (A handler-shaped path found in files is moved into functions with a warning.)

For a JSON route in api/, use export default sw.endpoint({ auth, handler }) and set auth explicitly. TypeScript infers the handler inputs and sw context. Use auth: 'none' only for a deliberately public route.

export default sw.endpoint({ auth: 'none', handler: async () => ({ ok: true }) });

Declare application tables in db/schema.ts. Read them with sw.db.from for caller-scoped access or sw.db.server.from after authorizing the caller for server access. Write them with the corresponding structured methods, such as sw.db.server.insert. Raw query and batch use the separate raw SQL database on current projects.

Functions run directly on the platform with access to sw.db (database), sw.fs (file storage), sw.email (send email), sw.ai (AI models), sw.env (environment variables), sw.jobs (background jobs), sw.queue, and sw.logs. sw.db uses the function's authenticated project binding, so application code does not send a developer API key or construct a platform HTTP request. First-use activation, placement, transport, scheduling, and engine work can still contribute to latency. sw.db.batch([{sql, params}, ...]) runs multiple statements as one atomic transaction; any failure rolls every statement back. (ctx is an alias — same object, both names work.)

Source base (required on every live deploy). Pass base_release_id: the active_release_id from the project_export read your source came from, or null when the project has no source yet. The base is the one that came with the edited source; a newer id read just before deploying is not a valid base. A missing base returns 400 BASE_REQUIRED and nothing changes; a base that is no longer live returns 409 STALE_RELEASE_BASE with data.changed_files. Recovery is a re-export, the change re-applied to the new source, and a deploy with the new base. force:true deliberately replaces the live source; it still fails if another deploy lands while yours builds.

Projects without releases use base_version from your last deploy/export response instead. If the project changed elsewhere, deploy returns 409 STALE_BASE with data.changed_files, data.last_change_source, and data.last_change_at; review project_diff_versions before choosing force:true.

Version counter check (optional, separate from the source base). expected_version compares the project's deploy counter: a number returns 409 VERSION_CONFLICT with data.current_version when it differs; omitting it (or "latest") skips only this extra check. Omitting it never replaces base_release_id.

The success response always includes the new version. When available, it may also include _runtime_key_summary, a plain-language note on whether the runtime key for this deploy was narrowed to least-privilege scopes or fell back to blanket access.

Example:

{
  "project_id": "my-saas",
  "files": {
    "index.html": "<!DOCTYPE html><html><body><h1>Hello</h1></body></html>"
  },
  "functions": {
    "api/hello.ts": "export default sw.endpoint({ auth: 'none', handler: async () => ({ ok: true }) });"
  }
}

Handler code goes in functions; static assets (here, index.html) go in files.

The default workflow has one environment: read production source, check, deploy once, then verify the public production URL. somewhere preview is an optional advanced capability; preview inputs apply when a preview is explicitly requested and the account has hosted preview access (every plan includes it for signed-in accounts).

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "project_id": "<project_id>"
    },
    "name": "project_deploy"
  }
}

Input Schema

NameRequiredDescriptionDefault
draftNoAlias for preview; preview is the canonical name.
filesNoMap of STATIC file paths to content, e.g. {"index.html": "<html>..."}. A native object or an array of {path, content} is accepted. Static assets include HTML, CSS, and client-side JS. Handler code (api/*, _lib/*, root [id].ts routes) belongs in `functions` for routing; a handler-shaped path here is auto-routed with a warning. Full deploys require this field; scope:'functions' may omit it when only functions are supplied.
forceNoBypasses a STALE_BASE refusal and overwrites the remote changes it reported; project_diff_versions lists those changes.
scopeNoOptional partial-deploy guard. "all" (default) deploys static files and functions. "functions" leaves static files untouched; "static" leaves functions untouched. Omitted functions remain merge-preserved by default.
dry_runNoOptional non-writing diff of added, modified, and removed files, function changes, and version conflict. It exposes every deletion before a real deploy and returns { dry_run, static_files, functions, warnings, version_conflict }.
messageNoOptional user-supplied note for this version (max 200 characters).
previewNoAdvanced `somewhere preview` flag requiring hosted preview access for signed-in accounts on every plan; otherwise CLOUD_DEV_NOT_ENABLED is returned before resource creation. False (default) deploys directly to production.
draft_idNoAlias for preview_session_id.
file_refsNoOptional map of deploy path → project file-storage path for TEXT files otherwise supplied inline, e.g. {"index.html": "/staged/index.html"}. The platform reads referenced content from file storage at deploy time, so a large tree avoids a giant inline payload. Referenced source must already exist through `fs_write`. Inline `files` may be mixed in.
functionsNoMap of function paths to ES-module source. Prefer an object; an array of {path, content} or a JSON-stringified object also works. Files under api/ become routes. For a JSON route in api/, use export default sw.endpoint({ auth, handler }) and set auth explicitly. TypeScript infers the handler inputs and sw context. Use auth: 'none' only for a deliberately public route. A direct request handler is also supported for streaming and webhooks. Read config from sw.env inside the handler (docs topic sw.env).
project_idYesProject ID (UUID), subdomain, or slug — resolved server-side, no UUID lookup needed. 'default' also works when the account has exactly one project; multi-project accounts must name one (the error lists them).
base_versionNoOptional stale-base guard containing the version from the preceding deploy or export response. A 409 STALE_BASE indicates a remote project change and requires reviewing project_diff_versions before a forced retry.
binary_filesNoOptional map of binary asset paths to base64 content. Exact preview snapshots require the complete map.
base_release_idNoRelease id the deployed source was prepared from: the active_release_id returned with that project_export, or null when the project had no source. Required on every live deploy and on the first preview snapshot. A missing base returns 400 BASE_REQUIRED; a base that is no longer live returns 409 STALE_RELEASE_BASE with data.changed_files, and nothing changes.
binary_file_refsNoOptional binary counterpart to `file_refs` for images, fonts, and other non-text assets, e.g. {"public/logo.png": "/uploads/logo.png"}. Binary data is referenced from file storage rather than base64-encoded in `files`.
expected_versionNoOptional extra check on the deploy counter, separate from the required base_release_id. A number returns 409 VERSION_CONFLICT when the counter differs; "latest" or omission skips only this extra check.
replace_functionsNoOptional authoritative-function flag. When true, functions absent from the payload are deleted; false (default) merge-preserves omitted functions. The true value is for intentional removal of functions no longer shipped.
draft_operation_idNoAlias for preview_operation_id.
preview_session_idNoStable editing-session id for this preview lineage. Required with preview:true.
expected_preview_idNoExact current preview id, or null for the first preview.
preview_operation_idNoStable idempotency id for this exact preview build/retry.
expected_candidate_release_idNoAlias for expected_preview_id.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / functions / description
      Previous value: -"Map of function paths to ES-module source code. A native object is preferred; an array of {path, content} is also accepted. Files under api/ become routable at /api/.... Each file can default-export a single handler or export method-named (GET, POST, ...) handlers. The handler receives `(request, sw)`; `sw.env` carries env vars set with the `env` tool, which take effect on the NEXT deploy (existing running functions keep their deployed values). (`ctx` is an alias for `sw` — same object, both names work.) Object value preferred; a JSON-stringified object is also accepted."New value: +"Map of function paths to ES-module source. Prefer an object; an array of {path, content} or a JSON-stringified object also works. Files under api/ become routes. For a JSON route in api/, use export default sw.endpoint({ auth, handler }) and set auth explicitly. TypeScript infers the handler inputs and sw context. Use auth: 'none' only for a deliberately public route. A direct request handler is also supported for streaming and webhooks. Read config from sw.env inside the handler (docs topic sw.env)."
  2. Changed1 schema field changed
    • addedInput schema / properties / message
      Added value: +{
      +  "description": "Optional user-supplied note for this version (max 200 characters).",
      +  "type": "string"
      +}
  3. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Goes far beyond the annotations: it discloses that omitted static files are deleted while omitted functions are merge-preserved by default, that replace_functions:true makes the deploy authoritative, that env vars/database/fs files are never affected, and it documents the base_release_id requirement with the exact 400 BASE_REQUIRED and 409 STALE_RELEASE_BASE codes and the recovery path. Latency caveats and the _runtime_key_summary return note add further operational context. The only wrinkle is that destructiveHint:false understates the static-file deletion, but the description surfaces that deletion explicitly so the agent is not misled.

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?

Front-loaded well (CLI advice, then project_patch, then file/function split), but the text runs long for a tool description and repeats the same point three times: handler code belongs in functions, not files, appears in prose twice and again in the example caption. The closing paragraph on preview is loosely attached and adds little beyond the preview parameter's own schema description.

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 22-parameter mutation tool with no output schema, the definition covers what an agent needs: required base on every live deploy, what gets deleted vs preserved, partial-deploy scope, dry-run inspection, error codes with recovery, and the shape of the success response (new version plus optional _runtime_key_summary). Nothing material is left to inference.

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

Parameters5/5

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

Even at 100% schema coverage, the description adds real meaning the schema does not: it separates base_release_id (source base, required) from base_version (projects without releases) and from expected_version (a separate deploy-counter check that 'never replaces base_release_id'), and it explains why big assets go through fs_write plus file_refs/binary_file_refs instead of inline payloads. It also clarifies the files-vs-functions routing rule that the schema only hints at.

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 line gives a specific verb and resource ('upload raw source ... to a project and put it in production') and immediately disambiguates scope with 'The platform compiles your code; you deploy source, not a build.' It also names the sibling it is not (project_patch for updates) and the CLI alternative, so an agent can place the tool without opening the schema.

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?

Explicit routing: lead with the CLI when a shell is available, use project_patch for updates, use project_deploy for the FIRST deploy of a new project or for replacing the whole tree. It also states the fallback condition ('agents without shell access, small projects, or when the CLI isn't available') and when to prefer dry_run before writing.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources