Skip to main content
Glama

project_patch

Edit / change / update / modify / fix / tweak files in a deployed project — edit one or several deployed files in place with a find/replace, an ordered edits array of many find/replaces across files, a full-file rewrite, or a files map of several full-file writes in one atomic patch. Suited to visual-editor iteration and any quick code change. Unchanged files are preserved; only what you send is touched. Static changes reach production in ~1 second; function changes in 2–4 seconds.

For an existing project this touches only the files sent; project_deploy replaces the static file tree, so unchanged static files must be sent again. project_deploy is for the first deploy of a brand-new project.

The source comes from project_export. Its active_release_id is the base_release_id of the patch, including on dry runs. This required release anchor identifies the exact source you edited; base_version is an additional optional conflict check.

Three modes — same tool.

1. Find / replace (token-optimal, preferred for small edits): pass path + find + replace. The platform reads the current file, replaces every occurrence of find with replace, and writes it back. ~200 bytes on the wire instead of re-sending the whole file.

{ "project_id": "my-saas", "base_release_id": "<active_release_id from project_export>", "path": "index.html", "find": "<h1>Pricing</h1>", "replace": "<h1>Plans &amp; pricing</h1>" }

If find doesn't match the file, you get a 400 FIND_NOT_FOUND with a head/tail snippet. When a sufficiently similar region exists, data.closest_match also includes its offset, text and 0–1 confidence; unrelated text may have no close match. A corrected patch uses the exact text from a current project_export and that export's release anchor.

2. Ordered edits (many small changes in one patch): pass edits, an array of { "path", "find", "replace", "expect"? }, instead of top-level path/find/replace. Edits apply in order to the source of base_release_id (a later edit to the same file sees the earlier ones), across any number of files, and publish as ONE patch. If any edit does not match, nothing is published: the error is FIND_NOT_FOUND with zero-based data.edit_index. expect: n requires exactly n non-overlapping matches, else FIND_COUNT_MISMATCH with data.edit_index, data.path, data.expected and data.actual. At most 200 edits per call. A path is edited, written whole (files), or deleted (delete_files) in one patch, never two of these; other paths combine freely.

{ "project_id": "my-saas", "base_release_id": "<active_release_id from project_export>", "edits": [
  { "path": "src/App.tsx", "find": "const TITLE = 'Old'", "replace": "const TITLE = 'New'", "expect": 1 },
  { "path": "src/App.tsx", "find": "<Footer />", "replace": "<Footer year={2026} />" },
  { "path": "styles.css", "find": "color: red", "replace": "color: teal" }
] }

Unified diffs are not a patch format: ordered exact replacements plus whole-file files writes cover the same changes without a second parser. Whole local trees deploy with somewhere deploy; somewhere call project_patch --file args.json sends a large argument object from a file.

3. Full content (rewriting the file): pass path + content. The new bytes replace the file entirely.

{ "project_id": "my-saas", "base_release_id": "<active_release_id from project_export>", "path": "styles.css", "content": "body { background: black }" }

Path auto-routes: api/*, _lib/*, and root [id].ts paths go to functions; everything else (HTML, CSS, SVG, JSON, etc.) to static. Binary assets (images, fonts) use the matching binary surface — content and find/replace do not carry raw bytes.

Delete: delete_files is an array of paths. Works for static files and functions; missing paths are silently ignored. A rename or atomic replace combines one path + content write (or the one-entry files alias) with delete_files in the same call: the new file and removals publish as one patch transaction.

Conflict check (optional, recommended for shared projects): pass base_version from your last deploy/export response. If another deployer landed changes since, returns 409 STALE_BASE with data.changed_files, data.last_change_source, and data.last_change_at instead of overwriting. On STALE_BASE, project_diff_versions shows the change, and force:true overwrites the remote changes. The older expected_version strict CAS still works and returns VERSION_CONFLICT when the production version differs.

Preview first (optional): pass dry_run: true to get a per-file unified diff of what the patch WOULD change (data.diffs), plus added/modified/removed lists — nothing is written and the version doesn't change. The same call without dry_run applies it.

Safety net — what IS and is NOT checked. A patch that touches page-rendering files (HTML/JS/CSS) is blank-page health-checked after it goes live: if it blanked a previously-rendering page, the patch is automatically rolled back and you get a 400 DEPLOY_BLANK_PAGE with data.rolled_back. Pages that were already blank before the patch are never blocked.

A function-only patch (api/*, _lib/*, root [id].ts) is NOT blank-page-checked, and it does NOT get "the same protection as a full deploy." After a function patch the response carries a best-effort function_health field — { checked, status, ok } from one GET of a patched route. function_health.ok === false means the route returned a 5xx (e.g. a missing import → 500): your edit shipped but is broken in production. If function_health.checked === false the route couldn't be probed (no concrete route, browser unavailable) — it was NOT verified, so confirm it yourself. A clean build is NOT a working function; only function_health.ok === true (or your own request to the route) confirms it runs.

For a risky edit, dry_run:true and project_check come first, then one patch, verified on the public production URL. project_rollback restores the previous production version if needed.

Patches reach production immediately at https://{subdomain}.somewhere.site. The success response includes the new version, a next_step, function_errors (build failures) and, for function patches, function_health (runtime 5xx). Preview is advanced and must not be selected unless the user explicitly says the account is enabled.

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_patch"
  }
}

Input Schema

NameRequiredDescriptionDefault
findNoFind/replace mode exact substring, paired with `path` and `replace`. All occurrences are replaced. Mutually exclusive with `content`.
pathNoFile path relative to project root (e.g. "api/hello.ts" or "index.html"). Required for both content and find/replace modes.
editsNoOrdered find/replace edits across one or more files, applied in order to the base_release_id source and published as one patch. Any edit that does not match fails the whole patch (FIND_NOT_FOUND with data.edit_index) and nothing is published. Exclusive with top-level path/find/replace/content; a path in edits may not also appear in files or delete_files.
filesNoFull-file content writes as a {"path": "content"} map or an array of {path, content} items. One entry is the same as path+content; several entries are written together in one atomic patch, anchored to base_release_id, and every unlisted file is kept. Paths under api/, _lib/ and root [param] routes go to functions, everything else to static files, exactly as a single path is routed. May accompany delete_files in the same transaction. Find/replace uses top-level path+find+replace, not files items.
forceNoBypasses a STALE_BASE refusal and overwrites the remote changes it reported; project_diff_versions lists those changes.
contentNoFull file content paired with `path`; it replaces the file entirely. `find` and `replace` provide the smaller-edit alternative.
dry_runNoNon-writing preview that returns per-file unified diffs plus added, modified, and removed lists. The version stays unchanged; a subsequent call without dry_run applies the patch.
messageNoOptional user-supplied note for this version (max 200 characters). Required with note_version.
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) patches production.
replaceNoFind/replace substitution paired with `path` and `find`.
draft_idNoAlias for preview_session_id.
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 version from the preceding deploy or export response. A 409 STALE_BASE indicates a remote change and requires reviewing project_diff_versions before a forced retry.
delete_filesNoPaths to remove. Works for static files and functions. Paths not present are ignored.
note_versionNoChange the note on this version. Send only project_id, note_version and message.
base_release_idNoRequired for a project with a production release. It is the `active_release_id` from the same project read or export that supplied the edited source. A missing base fails closed; a stale base returns STALE_RELEASE_BASE without applying the patch.
expected_versionNoOptional optimistic-concurrency version from the preceding deploy or patch response. A concurrent project change returns 409 VERSION_CONFLICT with `data.current_version` instead of overwriting.
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. Changed2 schema fields changed
    • changedInput schema / properties / message / description
      Previous value: -"Optional user-supplied note for this version (max 200 characters)."New value: +"Optional user-supplied note for this version (max 200 characters). Required with note_version."
    • addedInput schema / properties / note_version
      Added value: +{
      +  "description": "Change the note on this version. Send only project_id, note_version and message.",
      +  "minimum": 1,
      +  "type": "integer"
      +}
  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?

Beyond annotations declaring non-read-only, non-idempotent, and non-destructive behavior, it discloses atomic publish semantics, blank-page health-check rollback, function-only patch limitations, function_health caveats, conflict handling, and timing. These are substantial behavioral details an agent needs before invoking a mutation tool.

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

Conciseness4/5

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

The description is long but front-loads purpose and modes, uses headings and concrete JSON examples, and keeps each section task-oriented. Some repetition around base_release_id, health checks, and preview slightly reduces conciseness, though the complexity justifies the length.

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?

Given a 22-parameter mutation tool with no output schema, the description covers source anchoring, conflict checks, previews, error names, response fields such as version and function_health, and recovery paths. An agent has enough information to select and invoke it safely.

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

Parameters4/5

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

Schema coverage is already 100%, but the description adds meaning beyond the schema: mode exclusivity, ordered edit semantics, path routing, base_release_id anchoring, force behavior, dry_run preview behavior, expect-count failures, and delete_files transactions. It repeats some schema-level facts, but the added invocation semantics are material.

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 description states a specific verb and resource — editing deployed project files in place — and distinguishes the tool from project_deploy by explaining that deploy replaces the static tree while patch touches only sent files. The three supported modes and path auto-routing make the tool’s purpose concrete.

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 explicitly says when to use project_patch versus project_deploy, recommends project_export for source, project_check and dry_run for risky edits, project_diff_versions on STALE_BASE, and project_rollback for recovery. It also states the preferred mode for small edits and warns not to select preview unless the user says the account is enabled.

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