dev/page MCP tool
update_page
Append and publish an immutable guarded revision at the same public URL.
When to use it
After get_page, when the user wants to replace a known page's source or title, or change its task state alongside that update. Inspect list_folders and set folderId when the update changes where the page belongs.
Behavior
Replaces complete page source and can update its folder placement and task status atomically. Omit status to preserve it; use todo for an unfinished task, done when it is complete, or neutral when it is no longer a task. In Markdown, preserve or produce valid GFM tables with the header, delimiter, and every data row on separate lines; never serialize an entire table onto one line. A folderId explicitly locks the placement; null re-enables automatic classification; omission preserves an explicit placement and reclassifies an automatic one from the updated title and content.
- Required scopes
- pages:write
- Idempotency
- required
- Side effects
- Appends and publishes one immutable revision and may change task status; the public URL is unchanged.
- Cost
- One guarded database transaction.
- Recovery
- On revision conflict, read the current page, merge intentionally, and retry with a new key.
- Stable errors
- page_not_found, revision_conflict, idempotency_conflict, workspace_not_found, workspace_access_revoked, rate_limited, service_not_ready
Exact input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"content": {
"type": "string",
"minLength": 1
},
"expectedLatestRevisionId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$"
},
"page": {
"type": "string",
"minLength": 1,
"maxLength": 2048
},
"folderId": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"enum": [
"neutral",
"todo",
"done"
]
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"workspace": {
"type": "string",
"minLength": 1,
"maxLength": 80,
"pattern": "^[a-z0-9]+(?:[_-][a-z0-9]+)*$"
}
},
"required": [
"content",
"expectedLatestRevisionId",
"idempotencyKey",
"page"
],
"additionalProperties": false
}Exact success schema
Every successful MCP response uses this validated { contractVersion, requestId, data } envelope.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"contractVersion": {
"type": "string",
"const": "9"
},
"data": {
"type": "object",
"properties": {
"contentSha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"contentType": {
"type": "string",
"enum": [
"markdown",
"html"
]
},
"createdAt": {
"type": "string"
},
"folder": {
"anyOf": [
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"name": {
"type": "string"
},
"path": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"id",
"name",
"path"
],
"additionalProperties": false
},
{
"type": "null"
}
]
},
"latestRevisionId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"pageId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"publicUrl": {
"type": "string",
"format": "uri"
},
"publishedRevisionId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"status": {
"type": "string",
"enum": [
"neutral",
"todo",
"done"
]
},
"title": {
"type": "string"
},
"updatedAt": {
"type": "string"
},
"workspace": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"isDefault": {
"type": "boolean"
},
"name": {
"type": "string"
},
"role": {
"type": "string",
"enum": [
"owner",
"editor"
]
},
"slug": {
"type": "string",
"minLength": 1,
"maxLength": 80,
"pattern": "^[a-z0-9]+(?:[_-][a-z0-9]+)*$"
}
},
"required": [
"id",
"isDefault",
"name",
"role",
"slug"
],
"additionalProperties": false
}
},
"required": [
"contentSha256",
"contentType",
"createdAt",
"folder",
"latestRevisionId",
"pageId",
"publicUrl",
"publishedRevisionId",
"status",
"title",
"updatedAt",
"workspace"
],
"additionalProperties": false
},
"requestId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"required": [
"contractVersion",
"data",
"requestId"
],
"additionalProperties": false
}