Reference
MCP tools
The 12 tools of /mcp, as tools/list describes them. A tool checks its scopes when it runs: a token without them gets a 403 that names what is missing.
approve_review
writecontent:publishPublishes the revision a review asked for, in your name, after the contracts run again as publish runs them. The warnings the request acknowledged count as acknowledged; a new one answers needs_acknowledgement, and you approve again with it in acknowledgeWarnings.
Input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^rvw_[0-9A-HJKMNP-TV-Z]{26}$",
"description": "The id of a review (rvw_…), as publish and list_reviews return it."
},
"acknowledgeWarnings": {
"default": [],
"description": "Warnings you accept besides those the request acknowledged.",
"type": "array",
"items": {
"type": "object",
"properties": {
"contract": {
"type": "string"
},
"path": {
"type": "string"
}
},
"required": [
"contract",
"path"
]
}
}
},
"required": [
"id"
],
"additionalProperties": false
}create_draft
writecontent:writeCreates an entry from a Markdown file and saves it as a draft at version 1. Contract errors do not stop the draft: it is saved, and the verdict says what to fix before publishing. It is refused only when it cannot be stored: the file is too large, its frontmatter or syntax does not parse, or the slug or translation is taken.
Input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"collection": {
"type": "string",
"minLength": 1,
"description": "A collection of the site, as describe_site lists it."
},
"locale": {
"type": "string",
"minLength": 1,
"description": "A locale of the site, as describe_site lists it."
},
"slug": {
"type": "string",
"maxLength": 200,
"pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
"description": "The entry's path segment: lowercase letters and digits joined by hyphens, such as edge-caching-guide."
},
"markdown": {
"type": "string",
"description": "The whole Markdown file: the YAML frontmatter between two --- lines, then the body. The collection schema in describe_site says what the frontmatter needs."
}
},
"required": [
"collection",
"locale",
"slug",
"markdown"
],
"additionalProperties": false
}describe_site
readcontent:readDescribes the site: its locales, and for each collection the JSON Schema of the frontmatter, the components the body may use, the contracts that writes and publishes are checked against, and the style guides. Read it before writing.
Input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {},
"additionalProperties": false
}get_entry
readcontent:readGets an entry by collection, locale and slug, with its latest revision: the Markdown, the frontmatter, the verdict of its contracts and its last publication.
Input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"collection": {
"type": "string",
"minLength": 1,
"description": "A collection of the site, as describe_site lists it."
},
"locale": {
"type": "string",
"minLength": 1,
"description": "A locale of the site, as describe_site lists it."
},
"slug": {
"type": "string",
"maxLength": 200,
"pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
"description": "The entry's path segment: lowercase letters and digits joined by hyphens, such as edge-caching-guide."
},
"formats": {
"default": [
"markdown"
],
"description": "What to return of the revision: markdown, the Comark document, or html.",
"minItems": 1,
"type": "array",
"items": {
"type": "string",
"enum": [
"markdown",
"document",
"html"
]
}
},
"published": {
"default": false,
"description": "Read the revision that is live instead of the latest one: not_found when the entry is not published.",
"type": "boolean"
}
},
"required": [
"collection",
"locale",
"slug"
],
"additionalProperties": false
}get_translations
readcontent:readGets the entries of a translation group of a collection, one per locale. The group is the value of the field that describe_site names as translationGroupField.
Input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"collection": {
"type": "string",
"minLength": 1,
"description": "A collection of the site, as describe_site lists it."
},
"translationGroup": {
"type": "string",
"minLength": 1
}
},
"required": [
"collection",
"translationGroup"
],
"additionalProperties": false
}list_entries
readcontent:readLists the entries of a collection, newest first, filtered by locale, tag or status. Pass the nextCursor of an answer as cursor to get the next page.
Input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"collection": {
"type": "string",
"minLength": 1,
"description": "A collection of the site, as describe_site lists it."
},
"locale": {
"type": "string",
"minLength": 1,
"description": "A locale of the site, as describe_site lists it."
},
"tag": {
"type": "string",
"minLength": 1
},
"status": {
"type": "string",
"enum": [
"draft",
"scheduled",
"published"
]
},
"limit": {
"default": 20,
"type": "integer",
"minimum": 1,
"maximum": 100
},
"cursor": {
"type": "string",
"minLength": 1
}
},
"required": [
"collection"
],
"additionalProperties": false
}list_reviews
readcontent:readLists the requests to publish, newest first, with the entry each one is for: the pending ones unless you name another status.
Input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"status": {
"default": "pending",
"type": "string",
"enum": [
"pending",
"approved",
"changes_requested",
"cancelled"
]
},
"limit": {
"default": 50,
"type": "integer",
"minimum": 1,
"maximum": 100
}
},
"additionalProperties": false
}publish
writecontent:writePublishes the latest revision of an entry, if the entry is still at the version you read, and with group, other entries in the same step. It is blocked while the contracts report errors. Warnings have to be acknowledged: an answer of needs_acknowledgement lists them, and publish again with them in acknowledgeWarnings. Publish entries that link to each other as one group. Without content:publish, the same checks run and the answer is pending_review: a person who may publish approves the revision or asks for changes, and a new revision of the entry cancels the request. A review is for one entry, now: never with group or publishAt.
Input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^ent_[0-9A-HJKMNP-TV-Z]{26}$",
"description": "The id of an entry (ent_…), as the other operations return it."
},
"version": {
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991,
"description": "The version of the entry you read. A change against an older version answers conflict."
},
"acknowledgeWarnings": {
"default": [],
"description": "The warnings you accept, as needs_acknowledgement listed them.",
"type": "array",
"items": {
"type": "object",
"properties": {
"contract": {
"type": "string"
},
"path": {
"type": "string"
}
},
"required": [
"contract",
"path"
]
}
},
"group": {
"default": [],
"description": "Other entries to publish in the same step, each with the version you read: all of them are published, or none. A link between two of them counts as published, and an acknowledged warning holds for every entry that reports it.",
"maxItems": 99,
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^ent_[0-9A-HJKMNP-TV-Z]{26}$",
"description": "The id of an entry (ent_…), as the other operations return it."
},
"version": {
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991,
"description": "The version of the entry you read. A change against an older version answers conflict."
}
},
"required": [
"id",
"version"
],
"additionalProperties": false
}
},
"publishAt": {
"description": "Publish at this time instead of now, as an ISO 8601 date and time: the entry is checked now and waits as scheduled, and it is published within a minute of the time, if nobody changes it before. One entry at a time, never with group.",
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
}
},
"required": [
"id",
"version"
],
"additionalProperties": false
}request_changes
editcontent:publishCloses a pending review without publishing, with a note that says what to change. The author saves a new revision and asks again.
Input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^rvw_[0-9A-HJKMNP-TV-Z]{26}$",
"description": "The id of a review (rvw_…), as publish and list_reviews return it."
},
"note": {
"type": "string",
"minLength": 1,
"maxLength": 4000,
"description": "What to change, for the author."
}
},
"required": [
"id",
"note"
],
"additionalProperties": false
}unpublish
destructivecontent:publishTakes an entry off the public site and keeps it, with its revisions, as a draft. An entry that is not published stays as it is.
Input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^ent_[0-9A-HJKMNP-TV-Z]{26}$",
"description": "The id of an entry (ent_…), as the other operations return it."
}
},
"required": [
"id"
],
"additionalProperties": false
}update_draft
editcontent:writeSaves a new revision of an entry from the whole Markdown file, if the entry is still at the version you read; otherwise it answers conflict with the current version, and nothing is saved. A file identical to the latest revision answers unchanged. Contract errors do not stop the save; the verdict says what to fix.
Input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^ent_[0-9A-HJKMNP-TV-Z]{26}$",
"description": "The id of an entry (ent_…), as the other operations return it."
},
"version": {
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991,
"description": "The version of the entry you read. A change against an older version answers conflict."
},
"markdown": {
"type": "string",
"description": "The whole Markdown file: the YAML frontmatter between two --- lines, then the body. The collection schema in describe_site says what the frontmatter needs."
}
},
"required": [
"id",
"version",
"markdown"
],
"additionalProperties": false
}validate
readcontent:readChecks a Markdown file against every contract of the collection, as publish would, without saving anything: the verdict lists each problem with its fix.
Input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"collection": {
"type": "string",
"minLength": 1,
"description": "A collection of the site, as describe_site lists it."
},
"locale": {
"type": "string",
"minLength": 1,
"description": "A locale of the site, as describe_site lists it."
},
"slug": {
"type": "string",
"maxLength": 200,
"pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
"description": "The entry's path segment: lowercase letters and digits joined by hyphens, such as edge-caching-guide."
},
"markdown": {
"type": "string",
"description": "The whole Markdown file: the YAML frontmatter between two --- lines, then the body. The collection schema in describe_site says what the frontmatter needs."
}
},
"required": [
"collection",
"locale",
"slug",
"markdown"
],
"additionalProperties": false
}