# MCP tools

> Reference of the 79 tools served by each project's MCP server and HTTP API, with inputs, permissions and plans, generated from the registry.

Every operation in Galerne is one tool. The same 79 tools are served by the MCP server of each project, by the HTTP API (`POST /p/<project>/v1/tools/<name>` and the routes listed below) and by the CLI. Each tool checks the caller's role, token scope and agent rules before it runs, and every write runs the same validation as the studio.

This page is generated from the tool registry, so it matches the server. `GET /p/<project>/v1/tools` returns the tools your token may call, with their JSON Schemas.

## Summary

| Tool | Kind | What it does |
|---|---|---|
| [`get_schema`](#get_schema) | read | The content model: document types, fields (as JSON Schema), blocks and languages. |
| [`get_guidelines`](#get_guidelines) | read | The project's voice, audience, glossary, banned words and rules. |
| [`query`](#query) | read | Find documents with a JSON filter. |
| [`get_doc`](#get_doc) | read | One document with its current values (rich text as Markdown), status, revision and studio link. |
| [`list_docs`](#list_docs) | read | Documents of a type (or all), most recently changed first, with status and last author. |
| [`search`](#search) | read | Full text search over titles and text fields. |
| [`get_history`](#get_history) | read | Who changed a document and when (people and agents). |
| [`list_branches`](#list_branches) | read | Content branches with their status (open, in_review, approved, merged) and number of changed docs. |
| [`get_references`](#get_references) | read | Documents that reference this one ("used by"), and the documents it references. |
| [`check`](#check) | read | Validation and content checks (broken references and links, missing alt text, heading order, missing or outdated translations, duplicates) for one doc, a type, or a whole branch. |
| [`create_branch`](#create_branch) | write | A branch for a unit of work ("translate to German", "alt text pass"). |
| [`create_doc`](#create_doc) | write | Creates a document on a branch. |
| [`patch_doc`](#patch_doc) | write | Changes fields by path: set `{ "title": "…", "seo.description": "…", "body": "Markdown…", "content[<key>].heading": "…", "role.fr": "…" }`, unset ["path"], insert items into lists. |
| [`publish_doc`](#publish_doc) | write | Makes the current draft the published version on this branch. |
| [`unpublish_doc`](#unpublish_doc) | write | Removes the published version; the draft stays. |
| [`delete_doc`](#delete_doc) | write | Deletes a document on a branch. |
| [`restore_version`](#restore_version) | write | Restores a past version (seq from get_history), whole or only some field paths, as a new change. |
| [`upload_media`](#upload_media) | write | Adds an image or file from a public https URL or base64 data. |
| [`list_media`](#list_media) | read | Media library with search, tag and type filters; unused=true finds files no doc uses. |
| [`get_media`](#get_media) | read | One media file: details, URL and the docs that use it. |
| [`update_media`](#update_media) | write | Sets alt text, title, caption, credits, license, tags or expiry of a media file. |
| [`branch_changes`](#branch_changes) | read | What a branch changes: docs created, edited or deleted, field-level diffs, conflicts with main, validation errors, the schema deployed on the branch (what promotion deploys on main), review events and content checks. |
| [`request_review`](#request_review) | flow | Asks people to review a branch. |
| [`approve`](#approve) | flow | Approves a branch under review, or asks for changes with a note. |
| [`comment`](#comment) | flow | Comments on a doc (optionally a field path) or a branch. |
| [`list_comments`](#list_comments) | read | Comments and tasks on a doc or branch. |
| [`promote`](#promote) | flow | Merges a branch into main (text merges by character; fields both sides changed are conflicts). |
| [`update_from_main`](#update_from_main) | write | Brings changes made on main since the branch started into the branch. |
| [`close_branch`](#close_branch) | write | Closes a branch without promoting it. |
| [`schedule`](#schedule) | write | Publishes or unpublishes a doc at a time (ISO 8601 with offset). |
| [`list_schedules`](#list_schedules) | read | Lists the pending scheduled publishes, unpublishes and releases, soonest first. |
| [`cancel_schedule`](#cancel_schedule) | write | Cancels a pending scheduled publish or unpublish. |
| [`propose_schema_change`](#propose_schema_change) | read | Checks a full schema config (galerne.config.ts as JSON) against the one deployed on main and returns the diff and problems. |
| [`deploy_schema`](#deploy_schema) | admin | Deploys a schema config. |
| [`get_audit_log`](#get_audit_log) | read | Who (person, agent or token) did what on this project, newest first. |
| [`accessibility_report`](#accessibility_report) | read | Accessibility issues in content (European Accessibility Act): images without alt text, skipped heading levels, vague link text. |
| [`update_branch`](#update_branch) | write | Changes a branch title or description, or makes it a release with a publish time (publishAt null removes the time). |
| [`rollback_promotion`](#rollback_promotion) | write | Puts the docs a promotion (or release) changed on main back to their state before it, as new changes. |
| [`update_comment`](#update_comment) | flow | Edits your comment, resolves or reopens a thread, marks a task done, or changes its assignee or due date. |
| [`delete_comment`](#delete_comment) | flow | Deletes a comment and its replies. |
| [`delete_media`](#delete_media) | write | Deletes a media file. |
| [`replace_media`](#replace_media) | write | Replaces the bytes of a media file in place: same id, so every doc using it shows the new file. |
| [`get_cache_settings`](#get_cache_settings) | read | Per type: how long sites cache answers that depend on it (life: seconds, minutes, hours, days, weeks, max), and which other types a publish of it also purges (purges). |
| [`set_cache_settings`](#set_cache_settings) | admin | Sets the cache settings of some types (expert mode). |
| [`import_from`](#import_from) | write | Copies content from Sanity, Contentful, Storyblok, WordPress, Payload or Markdown files into a branch (default import/<cms>-<date>): schema inferred, docs with references, rich text, translations, drafts and assets, ids kept. |
| [`export_to`](#export_to) | read | Writes a branch in another CMS format (schema, content, assets): sanity, contentful, storyblok, wordpress, payload, markdown, or galerne (the plain export). |
| [`get_analytics`](#get_analytics) | read | Page views of a published doc over the last 30 days (site analytics), per day, with the trend of the last 7 days against the 7 before. |
| [`create_site`](#create_site) | admin | Creates the project's site: a git repo from a template on Galerne's Forgejo, a site on Tramontane (EU hosting) built from it, its environment (API URL, project, read and preview tokens, preview and webhook secrets) and the revalidation webhook. |
| [`delete_site`](#delete_site) | admin | Deletes the project's managed site: the hosted site on Tramontane, the git repo and its mirrors settings, git access, the site's tokens and its revalidation webhook. |
| [`refresh_site`](#refresh_site) | admin | Reads the hosted site again, stores its URL, wires the revalidation webhook once the URL is known (then rebuilds production), and gives the site the current API URL and preview secrets again (after a rotation; branch builds get their own secret and draft token if they have none yet). |
| [`list_files`](#list_files) | read | Files of the site repo on a branch, optionally under a folder. |
| [`read_file`](#read_file) | read | One file of the site repo on a branch: text as UTF-8, other files as base64 (1 MB at most). |
| [`write_files`](#write_files) | write | Creates, updates or deletes files of the site repo in one commit on a branch (created from main when new, with the content branch of the same name). |
| [`code_branches`](#code_branches) | read | Branches of the site repo with their last commit, the content branch of the same name, and the preview URL when built. |
| [`code_changes`](#code_changes) | read | Commits and files a branch changes compared to main: what a review of the branch covers on the code side. |
| [`build_status`](#build_status) | read | Latest builds of the site on Tramontane, for one branch or all. |
| [`build_logs`](#build_logs) | read | Log lines of one build, by page: pass `next` back as `after` until it is null. |
| [`preview_url`](#preview_url) | read | Where to see a branch: its own build when its code changed (code and content of the branch), else the production site in draft mode on that content branch. |
| [`request_code_review`](#request_code_review) | flow | Asks people to review a branch: its code changes (compared to main) and its content changes, together under one name. |
| [`promote_code`](#promote_code) | flow | Merges a code branch into main (a merge commit); Tramontane then rebuilds production. |
| [`set_mirror`](#set_mirror) | admin | Copies the site repo to your own GitHub or GitLab repository on every change (a push mirror). |
| [`list_mirrors`](#list_mirrors) | read | Where the site repo is mirrored, with the last push and its error if any. |
| [`git_access`](#git_access) | write | Credentials to clone the site repo and push branches with plain git (for agents with a shell). |
| [`update_theme`](#update_theme) | write | Changes design tokens in theme/tokens.json on a branch, in one commit. |
| [`list_components`](#list_components) | read | Lists the site's components from its design manifest: atoms, components and blocks, with their props, controls, variants and, for blocks, the CMS fields. |
| [`update_site_settings`](#update_site_settings) | admin | Where content is published: the public site URL, the path pattern per type (routes, e.g. |
| [`site_env`](#site_env) | admin | Returns a .env.local for running the site on your machine: API URL, project, studio URL, the preview secret and a new read token made for it (shown once; revoke it in settings, API tokens). |
| [`site_analytics`](#site_analytics) | read | Visitors and page views of the managed site in production over a range (24h, 7d, 30d, 90d), with the range before it, and the top pages, routes, referrers, countries, devices, browsers and custom events. |
| [`set_site_analytics`](#set_site_analytics) | admin | Turns web analytics of the managed site on or off. |
| [`list_sources`](#list_sources) | read | External APIs that fill docs: their type, schedule, target and last run. |
| [`source_runs`](#source_runs) | read | The run log: counts (created, updated, unchanged, removed, failed), errors per item, duration. |
| [`get_source`](#get_source) | read | One source with its mapping, secret names (values are never returned) and recent runs. |
| [`create_source`](#create_source) | admin | Adds an external API that fills docs of one type. |
| [`update_source`](#update_source) | admin | Changes a source: its definition (studio sources only; config sources change in galerne.config.ts), secrets (null removes one), enabled, or a new hook secret. |
| [`delete_source`](#delete_source) | admin | Removes a studio source and its run log. |
| [`sync_source`](#sync_source) | write | Fetches the API and writes the changes now: new and changed items, removed items unpublished. |
| [`test_source`](#test_source) | admin | Dry run: fetches the API and maps the first items with a saved source or a draft definition. |
| [`set_override`](#set_override) | write | Keeps the current values of fields a data source owns: syncs stop writing them. |
| [`reset_override`](#reset_override) | write | The source owns these fields again (all overridden ones without paths). |

## Read tools

### get_schema

**Get schema.** The content model: document types, fields (as JSON Schema), blocks and languages. Call this first.

- Roles: admin, editor, contributor, viewer. Token scope: `read:published` or higher.
- REST: `GET /p/<project>/v1/schema`, or `POST /p/<project>/v1/tools/get_schema`.
- Read only.

| Input | Type | Required | Notes |
|---|---|---|---|
| `type` | string |  | one type only |
| `config` | boolean |  | also return the deployed galerne.config.ts as JSON (to propose a change); default `false` |
| `branch` | string |  | the schema a branch uses: its own when one was deployed there with deploy_schema, else main's; max 100 chars |

### get_guidelines

**Get writing guidelines.** The project's voice, audience, glossary, banned words and rules. Follow them in everything you write.

- Roles: admin, editor, contributor, viewer. Token scope: `read` or higher.
- REST: `GET /p/<project>/v1/guidelines`, or `POST /p/<project>/v1/tools/get_guidelines`.
- Read only.

No input.

### query

**Query documents.** Find documents with a JSON filter. where: `{ field: value }` or { field: `{ eq, ne, gt, gte, lt, lte, in, nin, contains, includes, exists }` }, combined with and / or / not. System fields: _id, _type, _lang, _updatedAt, _createdAt, _publishedAt. order: "-publishedAt,title". expand follows references: a depth, or `{ type: [fields] }` to keep only some fields of the referenced docs. The answer lists cache tags (type:<type>, doc:<id>, all) that publish webhooks purge.

- Roles: admin, editor, contributor, viewer. Token scope: `read:published` or higher.
- REST: `POST /p/<project>/v1/query`, or `POST /p/<project>/v1/tools/query`.
- Read only.

| Input | Type | Required | Notes |
|---|---|---|---|
| `branch` | string |  | content branch; "main" is live content; max 100 chars; default `"main"` |
| `perspective` | "drafts" \| "published" |  | published (default): what sites see; drafts: latest edits, needs the read scope; default `"published"` |
| `type` | string or string[] |  |  |
| `ids` | string[] |  | max 1000 items |
| `where` | object |  |  |
| `search` | string |  | full text; max 200 chars |
| `order` | string or { field, dir }[] |  |  |
| `limit` | integer |  | 1 to 1000; default `50` |
| `offset` | integer |  | 0 to 9007199254740991; default `0` |
| `select` | string[] |  | fields to return; dotted paths reach into expanded references |
| `expand` | integer or object |  | follow references: a depth (up to 3), or the fields to keep per referenced type, e.g. `{ "project": ["title", "slug"], "*": ["title"] }`. _id, _type and _lang always come |
| `lang` | string |  |  |
| `fallback` | boolean |  |  |
| `format` | "markdown" \| "json" \| "html" |  | default `"markdown"` |

### get_doc

**Get a document.** One document with its current values (rich text as Markdown), status, revision and studio link. Pass rev to patch_doc to avoid overwriting newer edits.

- Roles: admin, editor, contributor, viewer. Token scope: `read` or higher.
- REST: `GET /p/<project>/v1/docs/{id}`, or `POST /p/<project>/v1/tools/get_doc`.
- Read only.

| Input | Type | Required | Notes |
|---|---|---|---|
| `id` | string | yes | document id; max 128 chars |
| `branch` | string |  | content branch; "main" is live content; max 100 chars; default `"main"` |
| `format` | "markdown" \| "json" |  | rich text as Markdown (default) or ProseMirror JSON; default `"markdown"` |
| `published` | boolean |  | also return the published values; default `false` |

### list_docs

**List documents.** Documents of a type (or all), most recently changed first, with status and last author.

- Roles: admin, editor, contributor, viewer. Token scope: `read` or higher.
- REST: `GET /p/<project>/v1/docs`, or `POST /p/<project>/v1/tools/list_docs`.
- Read only.

| Input | Type | Required | Notes |
|---|---|---|---|
| `branch` | string |  | content branch; "main" is live content; max 100 chars; default `"main"` |
| `type` | string |  |  |
| `search` | string |  | max 200 chars |
| `status` | "draft" \| "published" \| "changed" |  |  |
| `changedOnly` | boolean |  | only docs changed on this branch; default `false` |
| `limit` | integer |  | 1 to 500; default `50` |
| `offset` | integer |  | 0 to 9007199254740991; default `0` |

### search

**Search.** Full text search over titles and text fields. With semantic=true (Business plan), finds published docs by meaning. Returns ids, types and titles; use get_doc for content.

- Roles: admin, editor, contributor, viewer. Token scope: `read` or higher.
- REST: `GET /p/<project>/v1/search`, or `POST /p/<project>/v1/tools/search`.
- Plan: `semantic search` is part of Business. On other plans, a call that uses it gets a `402` with code `feature`.
- Read only.

| Input | Type | Required | Notes |
|---|---|---|---|
| `text` | string | yes | max 500 chars |
| `branch` | string |  | content branch; "main" is live content; max 100 chars; default `"main"` |
| `type` | string |  |  |
| `semantic` | boolean |  | search by meaning in published content on main; default `false` |
| `limit` | integer |  | 1 to 100; default `20` |

### get_history

**Document history.** Who changed a document and when (people and agents). Pass two seq values to get the field-level diff between versions.

- Roles: admin, editor, contributor, viewer. Token scope: `read` or higher.
- REST: `GET /p/<project>/v1/docs/{id}/history`, or `POST /p/<project>/v1/tools/get_history`.
- Read only.

| Input | Type | Required | Notes |
|---|---|---|---|
| `id` | string | yes | document id; max 128 chars |
| `branch` | string |  | content branch; "main" is live content; max 100 chars; default `"main"` |
| `limit` | integer |  | 1 to 200; default `50` |
| `diff` | { from, to } |  | version seq values; "to" defaults to the current draft |
| `diff.from` | integer | yes | -9007199254740991 to 9007199254740991 |
| `diff.to` | integer |  | -9007199254740991 to 9007199254740991 |

### list_branches

**List branches.** Content branches with their status (open, in_review, approved, merged) and number of changed docs.

- Roles: admin, editor, contributor, viewer. Token scope: `read` or higher.
- REST: `GET /p/<project>/v1/branches`, or `POST /p/<project>/v1/tools/list_branches`.
- Read only.

| Input | Type | Required | Notes |
|---|---|---|---|
| `includeClosed` | boolean |  | default `false` |

### get_references

**References.** Documents that reference this one ("used by"), and the documents it references.

- Roles: admin, editor, contributor, viewer. Token scope: `read` or higher.
- REST: `GET /p/<project>/v1/docs/{id}/references`, or `POST /p/<project>/v1/tools/get_references`.
- Read only.

| Input | Type | Required | Notes |
|---|---|---|---|
| `id` | string | yes | document id; max 128 chars |
| `branch` | string |  | content branch; "main" is live content; max 100 chars; default `"main"` |

### check

**Check content.** Validation and content checks (broken references and links, missing alt text, heading order, missing or outdated translations, duplicates) for one doc, a type, or a whole branch. Use the result as a to-do list.

- Roles: admin, editor, contributor, viewer. Token scope: `read` or higher.
- REST: `POST /p/<project>/v1/check`, or `POST /p/<project>/v1/tools/check`.
- Read only.

| Input | Type | Required | Notes |
|---|---|---|---|
| `branch` | string |  | content branch; "main" is live content; max 100 chars; default `"main"` |
| `ids` | string[] |  |  |
| `type` | string |  |  |
| `changedOnly` | boolean |  | default `false` |
| `unusedMedia` | boolean |  | default `false` |

### list_media

**List media.** Media library with search, tag and type filters; unused=true finds files no doc uses.

- Roles: admin, editor, contributor, viewer. Token scope: `read` or higher.
- REST: `GET /p/<project>/v1/media`, or `POST /p/<project>/v1/tools/list_media`.
- Read only.

| Input | Type | Required | Notes |
|---|---|---|---|
| `search` | string |  |  |
| `tag` | string |  |  |
| `mime` | string |  | e.g. "image/" |
| `unused` | boolean |  | default `false` |
| `limit` | integer |  | 1 to 500; default `50` |
| `offset` | integer |  | 0 to 9007199254740991; default `0` |

### get_media

**Get media.** One media file: details, URL and the docs that use it.

- Roles: admin, editor, contributor, viewer. Token scope: `read` or higher.
- REST: `GET /p/<project>/v1/media/{id}/info`, or `POST /p/<project>/v1/tools/get_media`.
- Read only.

| Input | Type | Required | Notes |
|---|---|---|---|
| `id` | string | yes |  |

### branch_changes

**Branch review.** What a branch changes: docs created, edited or deleted, field-level diffs, conflicts with main, validation errors, the schema deployed on the branch (what promotion deploys on main), review events and content checks.

- Roles: admin, editor, contributor, viewer. Token scope: `read` or higher.
- REST: `GET /p/<project>/v1/branches/{branch}/changes`, or `POST /p/<project>/v1/tools/branch_changes`.
- Read only.

| Input | Type | Required | Notes |
|---|---|---|---|
| `branch` | string | yes | content branch to write on; agents work on their own branch and call request_review; max 100 chars |

### list_comments

**List comments.** Comments and tasks on a doc or branch.

- Roles: admin, editor, contributor, viewer. Token scope: `read` or higher.
- REST: `GET /p/<project>/v1/comments`, or `POST /p/<project>/v1/tools/list_comments`.
- Read only.

| Input | Type | Required | Notes |
|---|---|---|---|
| `branch` | string |  |  |
| `id` | string |  |  |
| `includeResolved` | boolean |  | default `false` |
| `openTasks` | boolean |  | default `false` |

### list_schedules

**Scheduled publishing.** Lists the pending scheduled publishes, unpublishes and releases, soonest first. Filter by branch or doc.

- Roles: admin, editor, contributor, viewer. Token scope: `read` or higher.
- REST: `GET /p/<project>/v1/schedules`, or `POST /p/<project>/v1/tools/list_schedules`.
- Read only.

| Input | Type | Required | Notes |
|---|---|---|---|
| `branch` | string |  | max 100 chars |
| `id` | string |  | document id; max 128 chars |

### propose_schema_change

**Propose a schema change.** Checks a full schema config (galerne.config.ts as JSON) against the one deployed on main and returns the diff and problems. Nothing is deployed; deploy_schema with a branch makes it apply to that branch.

- Roles: admin, editor, contributor, viewer. Token scope: `read` or higher.
- REST: `POST /p/<project>/v1/schema/diff`, or `POST /p/<project>/v1/tools/propose_schema_change`.
- Read only.

| Input | Type | Required | Notes |
|---|---|---|---|
| `config` | { languages, types, blocks, structure, sources } | yes |  |
| `config.languages` | string[] |  |  |
| `config.types` | object | yes |  |
| `config.blocks` | object |  |  |
| `config.structure` | any[] |  |  |
| `config.sources` | object |  |  |

### get_audit_log

**Audit log.** Who (person, agent or token) did what on this project, newest first. Business plan.

- Roles: admin. Token scope: `admin` or higher.
- REST: `GET /p/<project>/v1/audit`, or `POST /p/<project>/v1/tools/get_audit_log`.
- Plan: `audit log` is part of Business. On other plans, a call that uses it gets a `402` with code `feature`.
- Read only.

| Input | Type | Required | Notes |
|---|---|---|---|
| `limit` | integer |  | 1 to 1000; default `100` |
| `before` | integer |  | -9007199254740991 to 9007199254740991 |
| `actor` | string |  |  |
| `action` | string |  |  |

### accessibility_report

**Accessibility report.** Accessibility issues in content (European Accessibility Act): images without alt text, skipped heading levels, vague link text. Counts per type and the list to fix.

- Roles: admin, editor, contributor, viewer. Token scope: `read` or higher.
- REST: `GET /p/<project>/v1/accessibility`, or `POST /p/<project>/v1/tools/accessibility_report`.
- Read only.

| Input | Type | Required | Notes |
|---|---|---|---|
| `branch` | string |  | content branch; "main" is live content; max 100 chars; default `"main"` |
| `type` | string |  |  |

### get_cache_settings

**Cache settings.** Per type: how long sites cache answers that depend on it (life: seconds, minutes, hours, days, weeks, max), and which other types a publish of it also purges (purges).

- Roles: admin, editor, contributor, viewer. Token scope: `read` or higher.
- REST: `GET /p/<project>/v1/cache`, or `POST /p/<project>/v1/tools/get_cache_settings`.
- Read only.

No input.

### export_to

**Export to another CMS.** Writes a branch in another CMS format (schema, content, assets): sanity, contentful, storyblok, wordpress, payload, markdown, or galerne (the plain export). Returns the text files inline and the media as URLs; set includeMedia to get them as base64 (up to 20 MB).

- Roles: admin, editor, contributor, viewer. Token scope: `read` or higher.
- REST: `POST /p/<project>/v1/export/to`, or `POST /p/<project>/v1/tools/export_to`.
- Read only.

| Input | Type | Required | Notes |
|---|---|---|---|
| `cms` | "sanity" \| "contentful" \| "storyblok" \| "wordpress" \| "payload" \| "markdown" \| "galerne" \| "strapi" \| "hygraph" \| "prismic" \| "directus" | yes |  |
| `branch` | string |  | max 100 chars; default `"main"` |
| `options` | object |  | target options, e.g. sanity `{ dataset }`; default `{}` |
| `includeMedia` | boolean |  | default `false` |

### get_analytics

**Page views.** Page views of a published doc over the last 30 days (site analytics), per day, with the trend of the last 7 days against the 7 before. Needs the site URL and routes in project settings. Business plan.

- Roles: admin, editor, contributor, viewer. Token scope: `read` or higher.
- REST: `GET /p/<project>/v1/docs/{id}/analytics`, or `POST /p/<project>/v1/tools/get_analytics`.
- Plan: `analytics` is part of Business. On other plans, a call that uses it gets a `402` with code `feature`.
- Read only.

| Input | Type | Required | Notes |
|---|---|---|---|
| `id` | string | yes |  |

### list_files

**List code files.** Files of the site repo on a branch, optionally under a folder. Sizes in bytes.

- Roles: admin, editor, contributor, viewer. Token scope: `read` or higher.
- REST: `GET /p/<project>/v1/code/files`, or `POST /p/<project>/v1/tools/list_files`.
- Read only.

| Input | Type | Required | Notes |
|---|---|---|---|
| `branch` | string |  | git branch, the same name as the content branch; agents work on their own branch and call request_code_review; max 100 chars; default `"main"` |
| `path` | string |  | folder, e.g. "app/blocks"; max 300 chars |

### read_file

**Read a code file.** One file of the site repo on a branch: text as UTF-8, other files as base64 (1 MB at most).

- Roles: admin, editor, contributor, viewer. Token scope: `read` or higher.
- REST: `GET /p/<project>/v1/code/file`, or `POST /p/<project>/v1/tools/read_file`.
- Read only.

| Input | Type | Required | Notes |
|---|---|---|---|
| `branch` | string |  | git branch, the same name as the content branch; agents work on their own branch and call request_code_review; max 100 chars; default `"main"` |
| `path` | string | yes | max 300 chars |

### code_branches

**Code branches.** Branches of the site repo with their last commit, the content branch of the same name, and the preview URL when built.

- Roles: admin, editor, contributor, viewer. Token scope: `read` or higher.
- REST: `GET /p/<project>/v1/code/branches`, or `POST /p/<project>/v1/tools/code_branches`.
- Read only.

No input.

### code_changes

**Code changes of a branch.** Commits and files a branch changes compared to main: what a review of the branch covers on the code side.

- Roles: admin, editor, contributor, viewer. Token scope: `read` or higher.
- REST: `GET /p/<project>/v1/code/changes`, or `POST /p/<project>/v1/tools/code_changes`.
- Read only.

| Input | Type | Required | Notes |
|---|---|---|---|
| `branch` | string | yes | git branch, the same name as the content branch; agents work on their own branch and call request_code_review; max 100 chars |

### build_status

**Build status.** Latest builds of the site on Tramontane, for one branch or all. Status: queued, building, deploying, ready, error, canceled.

- Roles: admin, editor, contributor, viewer. Token scope: `read` or higher.
- REST: `GET /p/<project>/v1/site/builds`, or `POST /p/<project>/v1/tools/build_status`.
- Read only.

| Input | Type | Required | Notes |
|---|---|---|---|
| `branch` | string |  | git branch, the same name as the content branch; agents work on their own branch and call request_code_review; max 100 chars |
| `limit` | integer |  | 1 to 50; default `10` |

### build_logs

**Build logs.** Log lines of one build, by page: pass `next` back as `after` until it is null.

- Roles: admin, editor, contributor, viewer. Token scope: `read` or higher.
- REST: `GET /p/<project>/v1/site/builds/{deploymentId}/logs`, or `POST /p/<project>/v1/tools/build_logs`.
- Read only.

| Input | Type | Required | Notes |
|---|---|---|---|
| `deploymentId` | string | yes | max 40 chars |
| `after` | integer |  | 0 to 9007199254740991; default `0` |
| `limit` | integer |  | 1 to 2000; default `500` |

### preview_url

**Preview URL.** Where to see a branch: its own build when its code changed (code and content of the branch), else the production site in draft mode on that content branch. `open` turns on draft mode and goes to `path`.

- Roles: admin, editor, contributor, viewer. Token scope: `read` or higher.
- REST: `GET /p/<project>/v1/site/preview`, or `POST /p/<project>/v1/tools/preview_url`.
- Read only.

| Input | Type | Required | Notes |
|---|---|---|---|
| `branch` | string |  | git branch, the same name as the content branch; agents work on their own branch and call request_code_review; max 100 chars; default `"main"` |
| `path` | string |  | max 500 chars; default `"/"` |

### list_mirrors

**Mirrors.** Where the site repo is mirrored, with the last push and its error if any.

- Roles: admin, editor, contributor, viewer. Token scope: `read` or higher.
- REST: `GET /p/<project>/v1/code/mirrors`, or `POST /p/<project>/v1/tools/list_mirrors`.
- Read only.

No input.

### list_components

**List site components.** Lists the site's components from its design manifest: atoms, components and blocks, with their props, controls, variants and, for blocks, the CMS fields. Give `id` for one component with the args of every variant. Read from the site repo on `branch` when Galerne manages the code, else from the site at <preview URL>/_design/manifest.json. See a component at <preview URL>/_design/<id>, one variant alone at /_design/frame/<id>?variant=<name> (draft mode: open preview_url with path /_design).

- Roles: admin, editor, contributor, viewer. Token scope: `read` or higher.
- REST: `GET /p/<project>/v1/site/components`, or `POST /p/<project>/v1/tools/list_components`.
- Read only.

| Input | Type | Required | Notes |
|---|---|---|---|
| `branch` | string |  | code branch to read the manifest from (managed sites); max 100 chars; default `"main"` |
| `group` | string |  | only this group: atoms, components or blocks; max 40 chars |
| `id` | string |  | one component, e.g. blocks/hero, with the args of its variants; max 120 chars |

### site_analytics

**Site analytics.** Visitors and page views of the managed site in production over a range (24h, 7d, 30d, 90d), with the range before it, and the top pages, routes, referrers, countries, devices, browsers and custom events.

- Roles: admin, editor, contributor, viewer. Token scope: `read` or higher.
- REST: `GET /p/<project>/v1/site/analytics`, or `POST /p/<project>/v1/tools/site_analytics`.
- Read only.

| Input | Type | Required | Notes |
|---|---|---|---|
| `range` | "24h" \| "7d" \| "30d" \| "90d" |  | default `"30d"` |

### list_sources

**List data sources.** External APIs that fill docs: their type, schedule, target and last run.

- Roles: admin, editor, contributor, viewer. Token scope: `read` or higher.
- REST: `GET /p/<project>/v1/sources`, or `POST /p/<project>/v1/tools/list_sources`.
- Read only.

No input.

### source_runs

**Data source runs.** The run log: counts (created, updated, unchanged, removed, failed), errors per item, duration. Newest first.

- Roles: admin, editor, contributor, viewer. Token scope: `read` or higher.
- REST: `GET /p/<project>/v1/sources/runs`, or `POST /p/<project>/v1/tools/source_runs`.
- Read only.

| Input | Type | Required | Notes |
|---|---|---|---|
| `name` | string |  | source name: lowercase letters, digits and "-"; max 48 chars |
| `limit` | integer |  | 1 to 100; default `20` |

### get_source

**Get a data source.** One source with its mapping, secret names (values are never returned) and recent runs.

- Roles: admin, editor, contributor, viewer. Token scope: `read` or higher.
- REST: `GET /p/<project>/v1/sources/{name}`, or `POST /p/<project>/v1/tools/get_source`.
- Read only.

| Input | Type | Required | Notes |
|---|---|---|---|
| `name` | string | yes | source name: lowercase letters, digits and "-"; max 48 chars |

## Write tools

### create_branch

**Create a branch.** A branch for a unit of work ("translate to German", "alt text pass"). Docs read through to main until changed on the branch.

- Roles: admin, editor, contributor. Token scope: `write` or higher.
- REST: `POST /p/<project>/v1/branches`, or `POST /p/<project>/v1/tools/create_branch`.
- Plan: `releases` is part of Pro, Business. On other plans, a call that uses it gets a `402` with code `feature`.

| Input | Type | Required | Notes |
|---|---|---|---|
| `name` | string | yes | lowercase, e.g. "agent/translate-de"; max 100 chars |
| `title` | string |  | max 200 chars |
| `description` | string |  | max 2000 chars |
| `release` | boolean |  | a release publishes all its changes together; default `false` |
| `publishAt` | datetime |  | releases: publish at this time |

### create_doc

**Create a document.** Creates a document on a branch. Values follow get_schema; rich text as Markdown. Incomplete drafts are saved with warnings; invalid values are rejected with the field path and rule.

- Roles: admin, editor, contributor. Token scope: `write` or higher.
- REST: `POST /p/<project>/v1/docs`, or `POST /p/<project>/v1/tools/create_doc`.

| Input | Type | Required | Notes |
|---|---|---|---|
| `branch` | string | yes | content branch to write on; agents work on their own branch and call request_review; max 100 chars |
| `type` | string | yes |  |
| `id` | string |  | optional; generated when omitted (singletons use the type name); max 128 chars |
| `values` | object | yes | field values; rich text fields accept Markdown strings |
| `lang` | string |  | doc-level i18n: the language of this doc |
| `translationOf` | string |  | doc-level i18n: id of the source doc |

### patch_doc

**Edit a document.** Changes fields by path: set `{ "title": "…", "seo.description": "…", "body": "Markdown…", "content[<key>].heading": "…", "role.fr": "…" }`, unset ["path"], insert items into lists. Pass rev (from get_doc) so edits made meanwhile are not overwritten.

- Roles: admin, editor, contributor. Token scope: `write` or higher.
- REST: `PATCH /p/<project>/v1/docs/{id}`, or `POST /p/<project>/v1/tools/patch_doc`.

| Input | Type | Required | Notes |
|---|---|---|---|
| `branch` | string | yes | content branch to write on; agents work on their own branch and call request_review; max 100 chars |
| `id` | string | yes | document id; max 128 chars |
| `set` | object |  |  |
| `unset` | string[] |  |  |
| `insert` | { path, items, position, at }[] |  |  |
| `insert[].path` | string | yes |  |
| `insert[].items` | any[] | yes |  |
| `insert[].position` | "before" \| "after" \| "start" \| "end" |  |  |
| `insert[].at` | string |  | _key or index for before/after |
| `rev` | integer |  | -9007199254740991 to 9007199254740991 |

### publish_doc

**Publish a document.** Makes the current draft the published version on this branch. On main, sites see it at once. Fails with field errors when the draft is incomplete.

- Roles: admin, editor. Token scope: `write` or higher.
- REST: `POST /p/<project>/v1/docs/{id}/publish`, or `POST /p/<project>/v1/tools/publish_doc`.

| Input | Type | Required | Notes |
|---|---|---|---|
| `branch` | string | yes | content branch to write on; agents work on their own branch and call request_review; max 100 chars |
| `id` | string | yes | document id; max 128 chars |

### unpublish_doc

**Unpublish a document.** Removes the published version; the draft stays.

- Roles: admin, editor. Token scope: `write` or higher.
- REST: `POST /p/<project>/v1/docs/{id}/unpublish`, or `POST /p/<project>/v1/tools/unpublish_doc`.
- Marked destructive for MCP clients, which usually ask before calling it.

| Input | Type | Required | Notes |
|---|---|---|---|
| `branch` | string | yes | content branch to write on; agents work on their own branch and call request_review; max 100 chars |
| `id` | string | yes | document id; max 128 chars |

### delete_doc

**Delete a document.** Deletes a document on a branch. Refused while other docs reference it (the error lists them).

- Roles: admin, editor. Token scope: `write` or higher.
- REST: `DELETE /p/<project>/v1/docs/{id}`, or `POST /p/<project>/v1/tools/delete_doc`.
- Marked destructive for MCP clients, which usually ask before calling it.

| Input | Type | Required | Notes |
|---|---|---|---|
| `branch` | string | yes | content branch to write on; agents work on their own branch and call request_review; max 100 chars |
| `id` | string | yes | document id; max 128 chars |

### restore_version

**Restore a version.** Restores a past version (seq from get_history), whole or only some field paths, as a new change.

- Roles: admin, editor, contributor. Token scope: `write` or higher.
- REST: `POST /p/<project>/v1/docs/{id}/restore`, or `POST /p/<project>/v1/tools/restore_version`.

| Input | Type | Required | Notes |
|---|---|---|---|
| `branch` | string | yes | content branch to write on; agents work on their own branch and call request_review; max 100 chars |
| `id` | string | yes | document id; max 128 chars |
| `seq` | integer | yes | -9007199254740991 to 9007199254740991 |
| `paths` | string[] |  |  |

### upload_media

**Upload media.** Adds an image or file from a public https URL or base64 data. Returns the media id to use as `{ "asset": id }` or `![alt](media:id)`. Same bytes return the existing id.

- Roles: admin, editor, contributor. Token scope: `write` or higher.
- REST: `POST /p/<project>/v1/media/import`, or `POST /p/<project>/v1/tools/upload_media`.

| Input | Type | Required | Notes |
|---|---|---|---|
| `url` | url |  |  |
| `base64` | string |  |  |
| `filename` | string |  | max 255 chars |
| `mimeType` | string |  |  |
| `alt` | string |  | max 1000 chars |
| `title` | string |  | max 300 chars |
| `credits` | string |  | max 300 chars |
| `tags` | string[] |  | max 30 items |

### update_media

**Update media details.** Sets alt text, title, caption, credits, license, tags or expiry of a media file. Use it for alt text passes.

- Roles: admin, editor, contributor. Token scope: `write` or higher.
- REST: `PATCH /p/<project>/v1/media/{id}`, or `POST /p/<project>/v1/tools/update_media`.

| Input | Type | Required | Notes |
|---|---|---|---|
| `id` | string | yes |  |
| `alt` | string or null |  |  |
| `title` | string or null |  |  |
| `caption` | string or null |  |  |
| `credits` | string or null |  |  |
| `license` | string or null |  |  |
| `tags` | string[] |  | max 30 items |
| `expiresAt` | datetime or null |  |  |

### update_from_main

**Update branch from main.** Brings changes made on main since the branch started into the branch. Branch values win on conflicting fields; the result lists them.

- Roles: admin, editor, contributor. Token scope: `write` or higher.
- REST: `POST /p/<project>/v1/branches/{branch}/update`, or `POST /p/<project>/v1/tools/update_from_main`.

| Input | Type | Required | Notes |
|---|---|---|---|
| `branch` | string | yes | content branch to write on; agents work on their own branch and call request_review; max 100 chars |

### close_branch

**Close a branch.** Closes a branch without promoting it. Its changes stay in history.

- Roles: admin, editor, contributor. Token scope: `write` or higher.
- REST: `DELETE /p/<project>/v1/branches/{branch}`, or `POST /p/<project>/v1/tools/close_branch`.
- Marked destructive for MCP clients, which usually ask before calling it.

| Input | Type | Required | Notes |
|---|---|---|---|
| `branch` | string | yes | content branch to write on; agents work on their own branch and call request_review; max 100 chars |

### schedule

**Schedule publishing.** Publishes or unpublishes a doc at a time (ISO 8601 with offset).

- Roles: admin, editor. Token scope: `write` or higher.
- REST: `POST /p/<project>/v1/docs/{id}/schedule`, or `POST /p/<project>/v1/tools/schedule`.
- Plan: `scheduling` is part of Pro, Business. On other plans, a call that uses it gets a `402` with code `feature`.

| Input | Type | Required | Notes |
|---|---|---|---|
| `branch` | string | yes | content branch to write on; agents work on their own branch and call request_review; max 100 chars |
| `id` | string | yes | document id; max 128 chars |
| `action` | "publish" \| "unpublish" | yes |  |
| `at` | datetime | yes |  |

### cancel_schedule

**Cancel a scheduled publish.** Cancels a pending scheduled publish or unpublish. A release is canceled with update_branch and publishAt null.

- Roles: admin, editor. Token scope: `write` or higher.
- REST: `DELETE /p/<project>/v1/schedules/{schedule}`, or `POST /p/<project>/v1/tools/cancel_schedule`.

| Input | Type | Required | Notes |
|---|---|---|---|
| `schedule` | string | yes | schedule id, from list_schedules or schedule; max 64 chars |

### update_branch

**Update a branch.** Changes a branch title or description, or makes it a release with a publish time (publishAt null removes the time).

- Roles: admin, editor, contributor. Token scope: `write` or higher.
- REST: `PATCH /p/<project>/v1/branches/{branch}`, or `POST /p/<project>/v1/tools/update_branch`.
- Plan: `releases` is part of Pro, Business. On other plans, a call that uses it gets a `402` with code `feature`.

| Input | Type | Required | Notes |
|---|---|---|---|
| `branch` | string | yes | content branch to write on; agents work on their own branch and call request_review; max 100 chars |
| `title` | string |  | max 200 chars |
| `description` | string |  | max 2000 chars |
| `publishAt` | datetime or null |  | releases: publish at this time; null removes it |

### rollback_promotion

**Roll back a promotion.** Puts the docs a promotion (or release) changed on main back to their state before it, as new changes.

- Roles: admin, editor. Token scope: `write` or higher.
- REST: `POST /p/<project>/v1/promotions/{promotionId}/rollback`, or `POST /p/<project>/v1/tools/rollback_promotion`.
- Marked destructive for MCP clients, which usually ask before calling it.

| Input | Type | Required | Notes |
|---|---|---|---|
| `promotionId` | integer | yes | -9007199254740991 to 9007199254740991 |

### delete_media

**Delete media.** Deletes a media file. Refused while docs use it (the error lists them).

- Roles: admin, editor. Token scope: `write` or higher.
- REST: `DELETE /p/<project>/v1/media/{id}`, or `POST /p/<project>/v1/tools/delete_media`.
- Marked destructive for MCP clients, which usually ask before calling it.

| Input | Type | Required | Notes |
|---|---|---|---|
| `id` | string | yes |  |

### replace_media

**Replace a media file.** Replaces the bytes of a media file in place: same id, so every doc using it shows the new file.

- Roles: admin, editor, contributor. Token scope: `write` or higher.
- REST: `PUT /p/<project>/v1/media/{id}`, or `POST /p/<project>/v1/tools/replace_media`.

| Input | Type | Required | Notes |
|---|---|---|---|
| `id` | string | yes |  |
| `base64` | string |  |  |
| `url` | url |  |  |
| `filename` | string |  | max 255 chars |
| `mimeType` | string |  |  |

### import_from

**Import from another CMS.** Copies content from Sanity, Contentful, Storyblok, WordPress, Payload or Markdown files into a branch (default import/<cms>-<date>): schema inferred, docs with references, rich text, translations, drafts and assets, ids kept. Re-runnable: a second run changes nothing. Credentials go in options for this call only and are never stored. Use dryRun first to read the report and the inferred galerne.config.ts.

- Roles: admin, editor. Token scope: `write` or higher.
- REST: `POST /p/<project>/v1/import/from`, or `POST /p/<project>/v1/tools/import_from`.

| Input | Type | Required | Notes |
|---|---|---|---|
| `cms` | "sanity" \| "contentful" \| "storyblok" \| "wordpress" \| "payload" \| "markdown" \| "galerne" \| "strapi" \| "hygraph" \| "prismic" \| "directus" | yes |  |
| `options` | object |  | source options, never stored: sanity `{ projectId, dataset, token? }` or `{ data: NDJSON }`; contentful `{ url \| data: export JSON }`; storyblok `{ token, managementToken?, space? }`; wordpress `{ url \| data: WXR XML }`; payload `{ url, collections, token? }`; markdown { files: [`{ path, content }`] }; default `{}` |
| `branch` | string |  | target branch; created when missing; max 100 chars |
| `dryRun` | boolean |  | default `false` |
| `allMedia` | boolean |  | also import assets no doc uses; default `false` |

### write_files

**Write code files.** Creates, updates or deletes files of the site repo in one commit on a branch (created from main when new, with the content branch of the same name). Up to 200 files, 1 MB each, 8 MB in all. Secrets files (.env, keys) are refused: the site gets its secrets from its environment. Agents write on their own branch; the push builds a preview (preview_url, build_status).

- Roles: admin, editor, contributor. Token scope: `write` or higher.
- REST: `POST /p/<project>/v1/code/commits`, or `POST /p/<project>/v1/tools/write_files`.

| Input | Type | Required | Notes |
|---|---|---|---|
| `branch` | string | yes | git branch, the same name as the content branch; agents work on their own branch and call request_code_review; max 100 chars |
| `message` | string | yes | commit message; max 500 chars |
| `files` | { path, content, encoding, delete }[] | yes | max 200 items |
| `files[].path` | string | yes | max 300 chars |
| `files[].content` | string |  | the whole new content; omit with delete |
| `files[].encoding` | "utf8" \| "base64" |  | default `"utf8"` |
| `files[].delete` | boolean |  | default `false` |

### git_access

**Git access.** Credentials to clone the site repo and push branches with plain git (for agents with a shell). main only changes through promotion. Each call replaces your previous token; with revoke, removes it. Tokens are revoked 30 days after they are made.

- Roles: admin, editor, contributor. Token scope: `write` or higher.
- REST: `POST /p/<project>/v1/code/git-access`, or `POST /p/<project>/v1/tools/git_access`.

| Input | Type | Required | Notes |
|---|---|---|---|
| `revoke` | boolean |  | default `false` |

### update_theme

**Update the theme.** Changes design tokens in theme/tokens.json on a branch, in one commit. Give only what changes, nested like the file (e.g. { "colors": `{ "accent": "#0b5f59" }` }); null removes a token. The result is checked against theme/tokens.schema.json when the repo has it, and values that could break the CSS are refused. Web fonts go in the fonts group ({ "fonts": { "serif": { "family", "fallback", "files": [`{ "path": "/fonts/name.woff2", "weight": 400 }`] } } }) and are used as var(--fonts-<key>); commit the files under public/fonts with write_files first, the paths must exist on the branch. The branch preview rebuilds, then the change goes through review.

- Roles: admin, editor, contributor. Token scope: `write` or higher.
- REST: `POST /p/<project>/v1/code/theme`, or `POST /p/<project>/v1/tools/update_theme`.

| Input | Type | Required | Notes |
|---|---|---|---|
| `branch` | string | yes | git branch, the same name as the content branch; agents work on their own branch and call request_code_review; max 100 chars |
| `tokens` | object | yes |  |
| `message` | string |  | max 500 chars |

### sync_source

**Run a data source.** Fetches the API and writes the changes now: new and changed items, removed items unpublished. Unchanged items are skipped. An empty or malformed answer stops the run and keeps the data. wait=false queues the run for the worker.

- Roles: admin, editor. Token scope: `write` or higher.
- REST: `POST /p/<project>/v1/sources/{name}/sync`, or `POST /p/<project>/v1/tools/sync_source`.

| Input | Type | Required | Notes |
|---|---|---|---|
| `name` | string | yes | source name: lowercase letters, digits and "-"; max 48 chars |
| `wait` | boolean |  | default `true` |

### set_override

**Override synced fields.** Keeps the current values of fields a data source owns: syncs stop writing them. Editing such a field does the same on its own.

- Roles: admin, editor, contributor. Token scope: `write` or higher.
- REST: `POST /p/<project>/v1/tools/set_override`.

| Input | Type | Required | Notes |
|---|---|---|---|
| `branch` | string |  | content branch; max 100 chars; default `"main"` |
| `id` | string | yes | max 128 chars |
| `paths` | string[] | yes | max 100 items |

### reset_override

**Reset to source.** The source owns these fields again (all overridden ones without paths). The last fetched values come back now; publish to put them online.

- Roles: admin, editor, contributor. Token scope: `write` or higher.
- REST: `POST /p/<project>/v1/tools/reset_override`.

| Input | Type | Required | Notes |
|---|---|---|---|
| `branch` | string |  | content branch; max 100 chars; default `"main"` |
| `id` | string | yes | max 128 chars |
| `paths` | string[] |  | max 100 items |

## Review and flow tools

### request_review

**Request review.** Asks people to review a branch. Summarize what you changed and why in the note; reviewers see it with the diff.

- Roles: admin, editor, contributor. Token scope: `write` or higher.
- REST: `POST /p/<project>/v1/branches/{branch}/review`, or `POST /p/<project>/v1/tools/request_review`.
- Plan: `review` is part of Pro, Business. On other plans, a call that uses it gets a `402` with code `feature`.

| Input | Type | Required | Notes |
|---|---|---|---|
| `branch` | string | yes | content branch to write on; agents work on their own branch and call request_review; max 100 chars |
| `note` | string |  | max 5000 chars |

### approve

**Approve or request changes.** Approves a branch under review, or asks for changes with a note.

- Roles: admin, editor. Token scope: `write` or higher.
- REST: `POST /p/<project>/v1/branches/{branch}/decision`, or `POST /p/<project>/v1/tools/approve`.
- Plan: `review` is part of Pro, Business. On other plans, a call that uses it gets a `402` with code `feature`.
- People only: agents get a `403`.

| Input | Type | Required | Notes |
|---|---|---|---|
| `branch` | string | yes | content branch to write on; agents work on their own branch and call request_review; max 100 chars |
| `decision` | "approved" \| "changes_requested" | yes |  |
| `note` | string |  | max 5000 chars |

### comment

**Comment.** Comments on a doc (optionally a field path) or a branch. Mention people with @email or @[Name]. With assignee, the comment is a task.

- Roles: admin, editor, contributor, viewer. Token scope: `write` or higher.
- REST: `POST /p/<project>/v1/comments`, or `POST /p/<project>/v1/tools/comment`.

| Input | Type | Required | Notes |
|---|---|---|---|
| `branch` | string |  | content branch; "main" is live content; max 100 chars; default `"main"` |
| `id` | string |  | doc id; omit to comment on the branch |
| `path` | string |  |  |
| `parentId` | string |  | reply to this comment |
| `body` | string | yes | max 10000 chars |
| `assignee` | string |  | member id; makes the comment a task |
| `dueAt` | datetime |  |  |

### promote

**Promote a branch.** Merges a branch into main (text merges by character; fields both sides changed are conflicts). A schema deployed on the branch is deployed on main first. With publish, the merged docs go live. Agents need the promote right; most should call request_review instead. With a site, the code branch of the same name is merged into main too, and production rebuilds.

- Roles: admin, editor. Token scope: `write` or higher.
- REST: `POST /p/<project>/v1/branches/{branch}/promote`, or `POST /p/<project>/v1/tools/promote`.
- Marked destructive for MCP clients, which usually ask before calling it.

| Input | Type | Required | Notes |
|---|---|---|---|
| `branch` | string | yes | content branch to write on; agents work on their own branch and call request_review; max 100 chars |
| `publish` | boolean |  | default `false` |
| `onConflict` | "branch" \| "main" |  | which side wins on conflicting fields; without it, conflicts stop the promotion |
| `docs` | string[] |  | promote only these docs |

### update_comment

**Update a comment.** Edits your comment, resolves or reopens a thread, marks a task done, or changes its assignee or due date.

- Roles: admin, editor, contributor, viewer. Token scope: `write` or higher.
- REST: `PATCH /p/<project>/v1/comments/{id}`, or `POST /p/<project>/v1/tools/update_comment`.

| Input | Type | Required | Notes |
|---|---|---|---|
| `id` | string | yes |  |
| `body` | string |  | max 10000 chars |
| `resolved` | boolean |  |  |
| `done` | boolean |  |  |
| `assignee` | string or null |  |  |
| `dueAt` | datetime or null |  |  |

### delete_comment

**Delete a comment.** Deletes a comment and its replies. Authors delete their own; admins any.

- Roles: admin, editor, contributor, viewer. Token scope: `write` or higher.
- REST: `DELETE /p/<project>/v1/comments/{id}`, or `POST /p/<project>/v1/tools/delete_comment`.
- Marked destructive for MCP clients, which usually ask before calling it.

| Input | Type | Required | Notes |
|---|---|---|---|
| `id` | string | yes |  |

### request_code_review

**Request review of code and content.** Asks people to review a branch: its code changes (compared to main) and its content changes, together under one name. Summarize what you changed and why in the note. People then promote the branch: content and code reach main together.

- Roles: admin, editor, contributor. Token scope: `write` or higher.
- REST: `POST /p/<project>/v1/code/review`, or `POST /p/<project>/v1/tools/request_code_review`.

| Input | Type | Required | Notes |
|---|---|---|---|
| `branch` | string | yes | git branch, the same name as the content branch; agents work on their own branch and call request_code_review; max 100 chars |
| `note` | string |  | max 5000 chars |

### promote_code

**Promote code.** Merges a code branch into main (a merge commit); Tramontane then rebuilds production. promote does it too, after the content of the branch of the same name. With dryRun, only says whether the merge would go through. Needs the promote right.

- Roles: admin, editor. Token scope: `write` or higher.
- REST: `POST /p/<project>/v1/code/promote`, or `POST /p/<project>/v1/tools/promote_code`.
- Marked destructive for MCP clients, which usually ask before calling it.

| Input | Type | Required | Notes |
|---|---|---|---|
| `branch` | string | yes | git branch, the same name as the content branch; agents work on their own branch and call request_code_review; max 100 chars |
| `dryRun` | boolean |  | default `false` |

## Schema and admin tools

### deploy_schema

**Deploy schema.** Deploys a schema config. With a branch, the schema applies to that branch only (its docs can use the new types and fields) and is deployed on main when the branch is promoted. Breaking changes need force. Admin rights (galerne schema deploy uses it).

- Roles: admin. Token scope: `admin` or higher.
- REST: `PUT /p/<project>/v1/schema`, or `POST /p/<project>/v1/tools/deploy_schema`.

| Input | Type | Required | Notes |
|---|---|---|---|
| `config` | { languages, types, blocks, structure, sources } | yes |  |
| `config.languages` | string[] |  |  |
| `config.types` | object | yes |  |
| `config.blocks` | object |  |  |
| `config.structure` | any[] |  |  |
| `config.sources` | object |  |  |
| `branch` | string |  | deploy on this branch only, with the site code that needs it; omit for main; max 100 chars |
| `force` | boolean |  | default `false` |
| `dryRun` | boolean |  | default `false` |
| `note` | string |  | max 500 chars |

### set_cache_settings

**Set cache settings.** Sets the cache settings of some types (expert mode). life: how long sites keep answers; purges: other types whose cached answers a publish of this type also refreshes (e.g. post purges home). null clears a type.

- Roles: admin. Token scope: `admin` or higher.
- REST: `PUT /p/<project>/v1/cache`, or `POST /p/<project>/v1/tools/set_cache_settings`.

| Input | Type | Required | Notes |
|---|---|---|---|
| `types` | object | yes |  |

### create_site

**Create the site.** Creates the project's site: a git repo from a template on Galerne's Forgejo, a site on Tramontane (EU hosting) built from it, its environment (API URL, project, read and preview tokens, preview and webhook secrets) and the revalidation webhook. Templates: "starter" brings its own sample model (page, post, person, settings, strings and 16 blocks) for a new project; "bare" is for a project that already has content types (imported, or modelled before): the kit wiring, previews, the design browser and tokens, galerne.config.ts written from the deployed schema, and one page that renders any routed doc with its blocks shown as plain fields until you build their components. Pick "bare" when get_schema lists types of your own. Without template, bare is used when the deployed schema has types the starter does not define, else starter. Runs again safely: steps already done are kept. Then agents change the code on branches with write_files (AGENTS.md in the repo says how).

- Roles: admin. Token scope: `admin` or higher.
- REST: `POST /p/<project>/v1/site`, or `POST /p/<project>/v1/tools/create_site`.

| Input | Type | Required | Notes |
|---|---|---|---|
| `template` | "starter" \| "bare" |  | starter for a new project, bare for a project with its own content model; default: bare when the deployed schema has types the starter does not define |
| `name` | string |  | site name on Tramontane; defaults to the project name; max 80 chars |

### delete_site

**Delete the site.** Deletes the project's managed site: the hosted site on Tramontane, the git repo and its mirrors settings, git access, the site's tokens and its revalidation webhook. Content stays. People only; `confirm` must be the project slug. Mirrors elsewhere (GitHub, GitLab) keep their copy.

- Roles: admin. Token scope: `admin` or higher.
- REST: `DELETE /p/<project>/v1/site`, or `POST /p/<project>/v1/tools/delete_site`.
- Marked destructive for MCP clients, which usually ask before calling it.

| Input | Type | Required | Notes |
|---|---|---|---|
| `confirm` | string | yes |  |

### refresh_site

**Refresh the site.** Reads the hosted site again, stores its URL, wires the revalidation webhook once the URL is known (then rebuilds production), and gives the site the current API URL and preview secrets again (after a rotation; branch builds get their own secret and draft token if they have none yet). With rebuild, production builds again so new values apply.

- Roles: admin. Token scope: `admin` or higher.
- REST: `POST /p/<project>/v1/site/refresh`, or `POST /p/<project>/v1/tools/refresh_site`.

| Input | Type | Required | Notes |
|---|---|---|---|
| `rebuild` | boolean |  | default `false` |

### set_mirror

**Mirror the code.** Copies the site repo to your own GitHub or GitLab repository on every change (a push mirror). Give an empty repository URL and a token that may push to it. The token is kept by Forgejo only. With remove, stops the mirror to that URL.

- Roles: admin. Token scope: `admin` or higher.
- REST: `POST /p/<project>/v1/code/mirrors`, or `POST /p/<project>/v1/tools/set_mirror`.

| Input | Type | Required | Notes |
|---|---|---|---|
| `provider` | "github" \| "gitlab" | yes |  |
| `url` | url | yes | https://github.com/acme/site.git; max 500 chars |
| `token` | string |  | access token with push rights; not needed with remove; max 500 chars |
| `remove` | boolean |  | default `false` |

### update_site_settings

**Update site settings.** Where content is published: the public site URL, the path pattern per type (routes, e.g. { "post": "/`{lang}`/blog/`{slug}`" }, null removes one), the preview URL the studio frames (a site running @galerne/next; null removes it), and llms (serve /p/<project>/llms.txt for agents).

- Roles: admin. Token scope: `admin` or higher.
- REST: `PATCH /p/<project>/v1/site/settings`, or `POST /p/<project>/v1/tools/update_site_settings`.

| Input | Type | Required | Notes |
|---|---|---|---|
| `url` | string or null |  |  |
| `routes` | object |  |  |
| `previewUrl` | string or null |  |  |
| `llms` | boolean |  |  |

### site_env

**Site env for local development.** Returns a .env.local for running the site on your machine: API URL, project, studio URL, the preview secret and a new read token made for it (shown once; revoke it in settings, API tokens). Set the preview URL to the local site (update_site_settings) to see it in the studio.

- Roles: admin. Token scope: `admin` or higher.
- REST: `POST /p/<project>/v1/site/env`, or `POST /p/<project>/v1/tools/site_env`.

| Input | Type | Required | Notes |
|---|---|---|---|
| `name` | string |  | max 60 chars; default `"local development"` |

### set_site_analytics

**Turn site analytics on or off.** Turns web analytics of the managed site on or off. On, Tramontane counts visitors without cookies from the next visit; off, it keeps nothing new.

- Roles: admin. Token scope: `admin` or higher.
- REST: `PUT /p/<project>/v1/site/analytics`, or `POST /p/<project>/v1/tools/set_site_analytics`.

| Input | Type | Required | Notes |
|---|---|---|---|
| `enabled` | boolean | yes |  |

### create_source

**Create a data source.** Adds an external API that fills docs of one type. Map fields with JSON paths and transforms; run test_source first. Docs get deterministic ids, the source owns the mapped fields, and edits by people become overrides the sync leaves alone. With webhook, the answer holds the hook secret once.

- Roles: admin. Token scope: `admin` or higher.
- REST: `POST /p/<project>/v1/sources`, or `POST /p/<project>/v1/tools/create_source`.

| Input | Type | Required | Notes |
|---|---|---|---|
| `name` | string | yes | source name: lowercase letters, digits and "-"; max 48 chars |
| `definition` | { title, description, type, fetch, key, id, fields, languages, schedule, target, webhook } | yes |  |
| `definition.title` | string |  | max 120 chars |
| `definition.description` | string |  | max 1000 chars |
| `definition.type` | string | yes | the doc type the items fill |
| `definition.fetch` | { url, method, headers, body, items, pagination } | yes |  |
| `definition.fetch.url` | string | yes | https URL; templates {`{lang}`}, {`{page}`}, {`{cursor}`}, {`{secret.NAME}`}; max 2000 chars |
| `definition.fetch.method` | "GET" \| "POST" |  |  |
| `definition.fetch.headers` | object |  | literal values of auth headers are moved to the encrypted secrets |
| `definition.fetch.body` | string |  | max 100000 chars |
| `definition.fetch.items` | string |  | JSON path of the items list in the response; empty when the response is the list; max 500 chars |
| `definition.fetch.pagination` | any |  |  |
| `definition.key` | string |  | JSON path of the item id (default "id"); max 500 chars |
| `definition.id` | string |  | doc id template (default "<source>-{`{key}`}", plus "-{`{lang}`}" for doc-level i18n); max 200 chars |
| `definition.fields` | object | yes | target field path → mapping; the source owns these paths |
| `definition.languages` | { mode, values } or { mode, path } |  | doc-level i18n: one request per language, or the item language at a path |
| `definition.schedule` | { every } |  |  |
| `definition.schedule.every` | integer | yes | minutes, 15 at least; -9007199254740991 to 9007199254740991 |
| `definition.target` | "main" \| "review" |  | main publishes each run; review writes a branch and requests a review |
| `definition.webhook` | boolean |  | accept POST /v1/sources/<name>/hook to start a run |
| `secrets` | object |  | named secrets used as {`{secret.NAME}`}; stored encrypted, never returned |
| `enabled` | boolean |  |  |

### update_source

**Update a data source.** Changes a source: its definition (studio sources only; config sources change in galerne.config.ts), secrets (null removes one), enabled, or a new hook secret.

- Roles: admin. Token scope: `admin` or higher.
- REST: `PATCH /p/<project>/v1/sources/{name}`, or `POST /p/<project>/v1/tools/update_source`.

| Input | Type | Required | Notes |
|---|---|---|---|
| `name` | string | yes | source name: lowercase letters, digits and "-"; max 48 chars |
| `definition` | { title, description, type, fetch, key, id, fields, languages, schedule, target, webhook } |  |  |
| `definition.title` | string |  | max 120 chars |
| `definition.description` | string |  | max 1000 chars |
| `definition.type` | string | yes | the doc type the items fill |
| `definition.fetch` | { url, method, headers, body, items, pagination } | yes |  |
| `definition.fetch.url` | string | yes | https URL; templates {`{lang}`}, {`{page}`}, {`{cursor}`}, {`{secret.NAME}`}; max 2000 chars |
| `definition.fetch.method` | "GET" \| "POST" |  |  |
| `definition.fetch.headers` | object |  | literal values of auth headers are moved to the encrypted secrets |
| `definition.fetch.body` | string |  | max 100000 chars |
| `definition.fetch.items` | string |  | JSON path of the items list in the response; empty when the response is the list; max 500 chars |
| `definition.fetch.pagination` | any |  |  |
| `definition.key` | string |  | JSON path of the item id (default "id"); max 500 chars |
| `definition.id` | string |  | doc id template (default "<source>-{`{key}`}", plus "-{`{lang}`}" for doc-level i18n); max 200 chars |
| `definition.fields` | object | yes | target field path → mapping; the source owns these paths |
| `definition.languages` | { mode, values } or { mode, path } |  | doc-level i18n: one request per language, or the item language at a path |
| `definition.schedule` | { every } |  |  |
| `definition.schedule.every` | integer | yes | minutes, 15 at least; -9007199254740991 to 9007199254740991 |
| `definition.target` | "main" \| "review" |  | main publishes each run; review writes a branch and requests a review |
| `definition.webhook` | boolean |  | accept POST /v1/sources/<name>/hook to start a run |
| `secrets` | object |  |  |
| `enabled` | boolean |  |  |
| `rotateHookSecret` | boolean |  |  |

### delete_source

**Delete a data source.** Removes a studio source and its run log. The docs it filled stay as they are.

- Roles: admin. Token scope: `admin` or higher.
- REST: `DELETE /p/<project>/v1/sources/{name}`, or `POST /p/<project>/v1/tools/delete_source`.
- Marked destructive for MCP clients, which usually ask before calling it.

| Input | Type | Required | Notes |
|---|---|---|---|
| `name` | string | yes | source name: lowercase letters, digits and "-"; max 48 chars |

### test_source

**Test a data source.** Dry run: fetches the API and maps the first items with a saved source or a draft definition. Shows the docs it would write and the problems. Writes nothing. A draft on the saved source's host uses its saved secrets.

- Roles: admin. Token scope: `admin` or higher.
- REST: `POST /p/<project>/v1/tools/test_source`.

| Input | Type | Required | Notes |
|---|---|---|---|
| `name` | string |  | a saved source, or the name of the draft; max 48 chars |
| `definition` | { title, description, type, fetch, key, id, fields, languages, schedule, target, webhook } |  | a draft definition; secrets of the saved source with this name are used when the host is the same |
| `definition.title` | string |  | max 120 chars |
| `definition.description` | string |  | max 1000 chars |
| `definition.type` | string | yes | the doc type the items fill |
| `definition.fetch` | { url, method, headers, body, items, pagination } | yes |  |
| `definition.fetch.url` | string | yes | https URL; templates {`{lang}`}, {`{page}`}, {`{cursor}`}, {`{secret.NAME}`}; max 2000 chars |
| `definition.fetch.method` | "GET" \| "POST" |  |  |
| `definition.fetch.headers` | object |  | literal values of auth headers are moved to the encrypted secrets |
| `definition.fetch.body` | string |  | max 100000 chars |
| `definition.fetch.items` | string |  | JSON path of the items list in the response; empty when the response is the list; max 500 chars |
| `definition.fetch.pagination` | any |  |  |
| `definition.key` | string |  | JSON path of the item id (default "id"); max 500 chars |
| `definition.id` | string |  | doc id template (default "<source>-{`{key}`}", plus "-{`{lang}`}" for doc-level i18n); max 200 chars |
| `definition.fields` | object | yes | target field path → mapping; the source owns these paths |
| `definition.languages` | { mode, values } or { mode, path } |  | doc-level i18n: one request per language, or the item language at a path |
| `definition.schedule` | { every } |  |  |
| `definition.schedule.every` | integer | yes | minutes, 15 at least; -9007199254740991 to 9007199254740991 |
| `definition.target` | "main" \| "review" |  | main publishes each run; review writes a branch and requests a review |
| `definition.webhook` | boolean |  | accept POST /v1/sources/<name>/hook to start a run |
| `secrets` | object |  | named secrets used as {`{secret.NAME}`}; stored encrypted, never returned |
| `limit` | integer |  | 1 to 50; default `5` |

## Prompts

The MCP server also ships prompts. Your MCP client lists them (in Claude, under the + menu or as slash commands). The prompt only holds instructions: your agent runs it with its own model, and Galerne runs no model.

### translate_doc

**Translate a document.** Translate a document (and the docs it references, if asked) into another language on a branch, for review.

| Argument | Type | Required | Notes |
|---|---|---|---|
| `id` | string | yes | document id |
| `language` | string | yes | target language code, e.g. de |
| `branch` | string |  |  |

### alt_text

**Write alt text.** Find images without alt text and write it, on a branch, for review.

| Argument | Type | Required | Notes |
|---|---|---|---|
| `type` | string |  | only this document type |
| `language` | string |  |  |

### seo_pass

**SEO pass.** Review titles, descriptions and slugs of documents and propose improvements on a branch.

| Argument | Type | Required | Notes |
|---|---|---|---|
| `type` | string | yes | document type |
| `limit` | string |  | how many docs, default 20 |

Each prompt tells the agent to read the schema and the guidelines first, work on its own branch, run `check`, and finish with `request_review`.
