Справочник MCP Tools
Moira предоставляет возможности выполнения процессов через MCP-инструменты. Каталог ниже — авторитетный справочник имён инструментов, операций, входных схем и корректных примеров входа. Сборка документации напрямую читает тот же чистый типизированный контракт, который используется при MCP-регистрации и в runtime-справке.
Описания инструментов и поддерживаемые варианты для агентов и моделей являются статической частью этого каталога и не переопределяются через настройки базы данных. Системные runtime-инструкции передаются отдельно при MCP-инициализации и никогда не изменяют описание инструмента.
Инструменты MCP
list
Показывает доступные текущему пользователю процессы.
Схема входа
{
"type": "object",
"properties": {
"search": {
"type": "string",
"description": "Search in workflow name and description"
},
"visibility": {
"type": "string",
"enum": [
"public",
"private",
"all"
],
"description": "Filter by visibility (default: all accessible)"
},
"sort": {
"type": "string",
"enum": [
"createdAt",
"name"
],
"description": "Sort field (default: createdAt)"
},
"sortOrder": {
"type": "string",
"enum": [
"asc",
"desc"
],
"description": "Sort order (default: desc)"
},
"limit": {
"type": "number",
"minimum": 1,
"maximum": 100,
"description": "Number of results (default: 20, max: 100)"
},
"offset": {
"type": "number",
"minimum": 0,
"description": "Offset for pagination (default: 0)"
}
},
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}Результат: Страница каталога процессов с явными offset, limit, returnedCount, hasMore и nextOffset.
{
"limit": 20,
"offset": 0
}{
"limit": 20,
"offset": 20
}reconciliation
Показывает и разрешает конфликты сверки встроенных процессов.
Операции: status, get, resolve.
Схема входа
{
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": [
"status",
"get",
"resolve"
]
},
"reference": {
"type": "string"
},
"selection": {
"type": "string",
"enum": [
"current",
"incoming",
"previous"
]
},
"revision": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"rationale": {
"type": "string",
"minLength": 1,
"maxLength": 2000
},
"mergedGraph": {
"type": "object",
"additionalProperties": {}
},
"visibility": {
"type": "string",
"enum": [
"public",
"private"
]
}
},
"required": [
"action"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}Результат: Статус конфликта, кандидат или результат разрешения.
{
"action": "status"
}start
Подготавливает, затем выполняет защищённый от повторов запуск процесса.
Операции: prepare, execute.
Схема входа
{
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": [
"prepare",
"execute"
],
"description": "Start phase: prepare reserves an attempt; execute consumes that attempt"
},
"workflowId": {
"type": "string",
"description": "Workflow ID to prepare (required for prepare; use list() for available workflows)"
},
"note": {
"type": "string",
"maxLength": 500,
"description": "Optional prepare execution note (max 500 chars)"
},
"parentExecutionId": {
"type": "string",
"description": "Required for prepare. Use \"none\" for standalone, or a parent process UUID."
},
"skipNotificationCheck": {
"type": "boolean",
"description": "Prepare only. Skip optional ordinary channel checks; lock PIN delivery remains mandatory"
},
"skipTelegramCheck": {
"type": "boolean",
"description": "Prepare only. Deprecated alias for skipNotificationCheck"
},
"startAttemptId": {
"type": "string",
"format": "uuid",
"description": "Required for execute. Start attempt ID returned by prepare"
}
},
"required": [
"action"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}Результат: Квитанция попытки запуска либо идентификатор выполнения и первая инструкция.
{
"action": "prepare",
"workflowId": "moira/quick-task",
"parentExecutionId": "none"
}{
"action": "execute",
"startAttemptId": "00000000-0000-4000-8000-000000000000"
}step
Продолжает существующее выполнение процесса.
Схема входа
{
"type": "object",
"properties": {
"processId": {
"type": "string",
"description": "Process ID from start() or previous step() response"
},
"attemptId": {
"type": "string",
"description": "Step attempt ID from the current start(), step(), or session current_step response"
},
"input": {
"anyOf": [
{
"type": "string"
},
{
"type": "object",
"additionalProperties": {}
},
{
"type": "array",
"items": {}
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
}
],
"description": "Input data matching the step's inputSchema. Structure depends on current step requirements."
},
"teleportTo": {
"type": "string",
"description": "Optional teleport node ID to jump execution to. Only teleport-type nodes can be targets. When provided, execution jumps to the teleport node instead of following normal flow. Do NOT provide input when teleporting."
}
},
"required": [
"processId",
"attemptId"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}Результат: Следующая инструкция с идентификатором попытки шага или итоговый результат.
{
"processId": "00000000-0000-4000-8000-000000000000",
"attemptId": "11111111-1111-4111-8111-111111111111",
"input": {
"outcome": "completed"
}
}manage
Создаёт, проверяет и изменяет процессы.
Операции: create, edit, get, get-structure, get-node, search-nodes, validate, get-variable, set-variable, list-variables, delete-variable, diff, copy, clone-node, move-node, list-nodes, get-nodes, analyze-variables, set-visibility, create-invite, list-access, list-invites, revoke-access, revoke-invite.
Схема входа
{
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": [
"create",
"edit",
"get",
"get-structure",
"get-node",
"search-nodes",
"validate",
"get-variable",
"set-variable",
"list-variables",
"delete-variable",
"diff",
"copy",
"clone-node",
"move-node",
"list-nodes",
"get-nodes",
"analyze-variables",
"set-visibility",
"create-invite",
"list-access",
"list-invites",
"revoke-access",
"revoke-invite"
],
"description": "Action to perform on workflow"
},
"workflowId": {
"type": "string",
"description": "Target workflow ID (required for most actions except create)"
},
"workflow": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Workflow ID (auto-generated if not provided)"
},
"metadata": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Human-readable workflow name"
},
"version": {
"type": "string",
"description": "Semantic version (e.g., '1.0.0')"
},
"description": {
"type": "string",
"description": "Brief workflow description"
},
"author": {
"type": "string",
"description": "Workflow author"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Workflow tags"
}
},
"required": [
"name",
"version",
"description"
],
"additionalProperties": false
},
"nodes": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": {}
},
"description": "Array of workflow nodes"
},
"variableRegistry": {
"type": "object",
"additionalProperties": {},
"description": "Declared global variables (JSON-Schema-shaped: name -> {type, description, default?}). Required for any variable referenced by bare name in directives/conditions/templates."
},
"runtimePolicy": {
"type": "object",
"properties": {
"externalVariableWrites": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"allowedNodeIds": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
"progress": {
"type": "object",
"properties": {
"title": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"goal": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"facts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"value": {
"type": "string",
"minLength": 1,
"maxLength": 500
},
"tone": {
"type": "string",
"enum": [
"neutral",
"positive",
"warning",
"critical"
]
}
},
"required": [
"label",
"value"
],
"additionalProperties": false
},
"maxItems": 8
},
"nodes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"content": {
"type": "object",
"properties": {
"summary": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"details": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 500
},
"maxItems": 12
},
"outcome": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"next": {
"type": "string",
"minLength": 1,
"maxLength": 500
}
},
"required": [
"summary"
],
"additionalProperties": false
},
"connections": {
"type": "object",
"properties": {
"default": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false
}
},
"required": [
"id",
"label",
"content"
],
"additionalProperties": false
},
"minItems": 1,
"maxItems": 18
}
},
"required": [
"nodes"
],
"additionalProperties": false
},
"visibility": {
"type": "string",
"enum": [
"public",
"private"
],
"description": "Workflow visibility (default: private)"
},
"systemReminder": {
"type": "string",
"description": "System reminder shown to agent on each step"
}
},
"required": [
"metadata",
"nodes"
],
"additionalProperties": false,
"description": "Full workflow object for create action"
},
"overwrite": {
"type": "boolean",
"description": "Overwrite existing workflow with same ID (default: false)"
},
"changes": {
"type": "object",
"properties": {
"metadata": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"version": {
"type": "string"
},
"description": {
"type": "string"
},
"author": {
"type": "string"
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false,
"description": "Metadata fields to update"
},
"variableRegistry": {
"type": "object",
"additionalProperties": {},
"description": "Replace the workflow's declared global variable registry"
},
"runtimePolicy": {
"type": "object",
"properties": {
"externalVariableWrites": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"allowedNodeIds": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
"progress": {
"type": "object",
"properties": {
"title": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"goal": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"facts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"value": {
"type": "string",
"minLength": 1,
"maxLength": 500
},
"tone": {
"type": "string",
"enum": [
"neutral",
"positive",
"warning",
"critical"
]
}
},
"required": [
"label",
"value"
],
"additionalProperties": false
},
"maxItems": 8
},
"nodes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"content": {
"type": "object",
"properties": {
"summary": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"details": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 500
},
"maxItems": 12
},
"outcome": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"next": {
"type": "string",
"minLength": 1,
"maxLength": 500
}
},
"required": [
"summary"
],
"additionalProperties": false
},
"connections": {
"type": "object",
"properties": {
"default": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false
}
},
"required": [
"id",
"label",
"content"
],
"additionalProperties": false
},
"minItems": 1,
"maxItems": 18
}
},
"required": [
"nodes"
],
"additionalProperties": false
},
"addNodes": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": {}
},
"description": "New nodes to add"
},
"removeNodes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Node IDs to remove"
},
"updateNodes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"nodeId": {
"type": "string",
"description": "ID of node to update"
},
"changes": {
"description": "Fields to update on the node"
}
},
"required": [
"nodeId"
],
"additionalProperties": false
},
"description": "Nodes to update with specific changes"
},
"removeConnections": {
"type": "array",
"items": {
"type": "object",
"properties": {
"nodeId": {
"type": "string",
"description": "ID of node with connection to remove"
},
"connectionKey": {
"type": "string",
"description": "Connection key to remove (e.g., 'default', 'true', 'false')"
}
},
"required": [
"nodeId",
"connectionKey"
],
"additionalProperties": false
},
"description": "Connections to remove from nodes"
},
"systemReminder": {
"type": "string",
"description": "New system reminder text"
}
},
"additionalProperties": false,
"description": "Changes to apply for edit action"
},
"expectedRevision": {
"type": "integer",
"minimum": 0,
"description": "edit only: the workflow revision the changes were prepared against (from get); the edit is refused when the stored revision differs"
},
"includeNodes": {
"type": "boolean",
"description": "Include full node definitions in get response"
},
"includeValidation": {
"type": "boolean",
"description": "Include validation results in response"
},
"offset": {
"type": "number",
"description": "Pagination offset for node listing"
},
"limit": {
"type": "number",
"description": "Maximum nodes to return"
},
"nodeId": {
"type": "string",
"description": "Specific node ID for get-node and clone-node actions"
},
"query": {
"type": "string",
"description": "Search query for search-nodes action"
},
"variableName": {
"type": "string",
"description": "Variable name for get/set/delete-variable actions"
},
"variableValue": {
"description": "Variable value for set-variable action"
},
"variableNames": {
"type": "array",
"items": {
"type": "string"
}
},
"variableTypes": {
"type": "array",
"items": {
"type": "string"
}
},
"hasDefault": {
"type": "boolean"
},
"externallyWritable": {
"type": "boolean"
},
"compareWorkflowId": {
"type": "string",
"description": "Second workflow ID for diff action"
},
"newName": {
"type": "string",
"description": "New name for copied workflow (copy action)"
},
"newId": {
"type": "string",
"description": "New ID for cloned node (clone-node action)"
},
"targetIndex": {
"type": "number",
"description": "Target position for node (move-node action)"
},
"afterNodeId": {
"type": "string",
"description": "Place node after this node ID (move-node only, alternative to targetIndex)"
},
"typeFilter": {
"type": "string",
"description": "Filter nodes by type (list-nodes only)"
},
"includePreview": {
"type": "boolean",
"description": "Include directive preview (list-nodes only)"
},
"previewLength": {
"type": "number",
"description": "Length of directive preview (list-nodes only, default 100)"
},
"nodeIds": {
"type": "array",
"items": {
"type": "string"
},
"description": "Array of node IDs to retrieve (get-nodes only)"
},
"includeVariables": {
"type": "boolean",
"description": "Include variables in search (search-nodes only)"
},
"snippetMode": {
"type": "boolean",
"description": "Return only snippets, not full nodes (search-nodes only)"
},
"graph": {
"type": "boolean",
"description": "Return ASCII flow graph (get-structure only)"
},
"detailed": {
"type": "boolean",
"description": "Include directive preview in structure (get-structure only)"
},
"visibility": {
"type": "string",
"enum": [
"public",
"private"
],
"description": "New visibility setting (set-visibility only)"
},
"inviteId": {
"type": "string",
"description": "Invite ID (required for revoke-invite)"
},
"targetUserId": {
"type": "string",
"description": "User ID to revoke access from (revoke-access only)"
},
"ttlMs": {
"type": "number",
"description": "Invite expiration time in milliseconds (create-invite only, default 7 days)"
},
"activeOnly": {
"type": "boolean",
"description": "Filter to active (unused) invites only (list-invites only, default true)"
}
},
"required": [
"action"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}Результат: Данные процесса, зависящие от операции.
{
"action": "get",
"workflowId": "moira/quick-task",
"includeNodes": false,
"includeValidation": false
}{
"action": "list-nodes",
"workflowId": "moira/quick-task",
"includePreview": true
}{
"action": "get-nodes",
"workflowId": "moira/quick-task",
"nodeIds": [
"start",
"end"
]
}{
"action": "analyze-variables",
"workflowId": "moira/quick-task"
}{
"action": "set-visibility",
"workflowId": "my-workflow",
"visibility": "private"
}help
Возвращает документацию и фактический справочник инструментов.
Схема входа
{
"type": "object",
"properties": {
"topic": {
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
],
"description": "Documentation topic(s) to retrieve. Call without a topic to discover the current topics and accepted aliases."
}
},
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}Результат: Документация в Markdown.
{
"topic": "tools"
}settings
Читает или изменяет настройки пользователя.
Операции: get, set, list.
Схема входа
{
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": [
"get",
"set",
"list"
],
"description": "Action: get (one key, one category, or all values), set (update one value), list (definitions by category or all)"
},
"category": {
"type": "string",
"minLength": 1,
"pattern": "\\S",
"description": "Category filter for get and list; do not combine with key for get"
},
"key": {
"type": "string",
"minLength": 1,
"pattern": "\\S",
"description": "Exact setting key for get or set (e.g., 'telegram.bot_token')"
},
"value": {
"description": "New value for set action"
}
},
"required": [
"action"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}Результат: Безопасно скрытые настройки или результат изменения.
{
"action": "get",
"key": "ui.theme"
}{
"action": "get",
"category": "notifications"
}{
"action": "get"
}token
Создаёт временные токены загрузки или скачивания процесса.
Операции: upload, download.
Схема входа
{
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": [
"upload",
"download"
],
"description": "Token type: upload (for creating workflows), download (for retrieving)"
},
"workflowId": {
"type": "string",
"description": "Workflow ID (required for download action)"
},
"ttlMinutes": {
"type": "number",
"default": 60,
"description": "Token expiration time in minutes (default: 60)"
}
},
"required": [
"action"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}Результат: Ссылка и инструкция по использованию.
{
"action": "upload",
"ttlMinutes": 60
}communication
Отправляет сообщение текущему пользователю или создаёт одноразовый grant для авторизованной загрузки вложения.
Операции: send, attachment-token.
Схема входа
{
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": [
"send",
"attachment-token"
]
},
"message": {
"type": "string",
"minLength": 1,
"maxLength": 4096
},
"format": {
"type": "string",
"enum": [
"plain",
"markdown",
"html"
]
},
"silent": {
"type": "boolean"
},
"kind": {
"type": "string",
"enum": [
"image",
"document"
]
},
"filename": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"mimeType": {
"type": "string",
"maxLength": 127,
"pattern": "^[a-z0-9][a-z0-9!#$&^_.+-]*\\/[a-z0-9][a-z0-9!#$&^_.+-]*$"
},
"sizeBytes": {
"type": "integer",
"minimum": 1,
"maximum": 20971520
}
},
"required": [
"action",
"message"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}Результат: Безопасная сводка доставки либо временный grant и адрес загрузки.
{
"action": "send",
"message": "The report is ready."
}{
"action": "attachment-token",
"message": "Report",
"kind": "document",
"filename": "report.pdf",
"mimeType": "application/pdf",
"sizeBytes": 12000
}session
Читает и изменяет состояние выполнения.
Операции: user, executions, execution_context, current_step, diagnose, recover, cancel-execution, update-note, set-parent, add-reminder, reminders, update-reminder, remove-reminder, variables, set-variable, progress, progress-image-token, materialize.
Схема входа
{
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": [
"user",
"executions",
"execution_context",
"current_step",
"diagnose",
"recover",
"cancel-execution",
"update-note",
"set-parent",
"add-reminder",
"reminders",
"update-reminder",
"remove-reminder",
"variables",
"set-variable",
"progress",
"progress-image-token",
"materialize"
],
"description": "Action to perform"
},
"executionId": {
"type": "string",
"description": "Execution ID for execution_context, current_step, diagnose, recover, update-note, or materialize actions"
},
"nodeId": {
"type": "string",
"description": "Node the run must resume from (required for recover)"
},
"variableValues": {
"type": "object",
"additionalProperties": {},
"description": "Variable values written into the execution context while recovering (recover only)"
},
"status": {
"type": "array",
"items": {
"type": "string",
"enum": [
"running",
"waiting",
"completed",
"failed",
"locked"
]
},
"description": "Filter executions by status (array of statuses)"
},
"workflowId": {
"type": "string",
"description": "Filter by workflow ID"
},
"search": {
"type": "string",
"description": "Search in execution notes"
},
"sort": {
"type": "string",
"enum": [
"createdAt",
"updatedAt"
],
"description": "Sort field for executions list"
},
"sortOrder": {
"type": "string",
"enum": [
"asc",
"desc"
],
"description": "Sort order (ascending or descending)"
},
"limit": {
"type": "number",
"minimum": 1,
"maximum": 100,
"description": "Maximum executions to return (1-100)"
},
"offset": {
"type": "number",
"minimum": 0,
"description": "Pagination offset"
},
"note": {
"type": "string",
"maxLength": 500,
"description": "New note text for update-note action (max 500 chars)"
},
"parentExecutionId": {
"type": "string",
"description": "Parent execution UUID or \"none\" for set-parent"
},
"expectedRevision": {
"type": "integer",
"minimum": 0,
"description": "Expected workflow-step revision"
},
"expectedParentRevision": {
"type": "string",
"minLength": 64,
"maxLength": 64,
"description": "Parent target revision returned by execution_context or set-parent"
},
"expectedRemindersRevision": {
"type": "string",
"minLength": 64,
"maxLength": 64,
"description": "Reminder collection revision returned by reminders or a reminder mutation"
},
"expectedContextRevision": {
"type": "string",
"minLength": 64,
"maxLength": 64,
"description": "Context target revision returned by variables, execution_context, or set-variable"
},
"reminderId": {
"type": "string",
"description": "Reminder ID"
},
"reminderText": {
"type": "string",
"description": "Reminder text"
},
"idempotencyKey": {
"type": "string",
"description": "Idempotency key for add-reminder"
},
"reminderStatus": {
"type": "string",
"enum": [
"active",
"cancelled"
],
"description": "Reminder status filter"
},
"names": {
"type": "array",
"items": {
"type": "string"
}
},
"types": {
"type": "array",
"items": {
"type": "string"
}
},
"editable": {
"type": "boolean"
},
"hasValue": {
"type": "boolean"
},
"writePhase": {
"type": "string",
"enum": [
"current",
"other"
]
},
"variableName": {
"type": "string"
},
"variableValue": {},
"theme": {
"type": "string",
"enum": [
"light",
"dark"
]
},
"viewportWidth": {
"type": "integer",
"minimum": 480,
"maximum": 4096
},
"view": {
"type": "string",
"enum": [
"cards",
"process"
],
"description": "progress-image-token: cards (default) draws every block as a content card; process draws the aggregated block view with labelled transitions and loops"
},
"hide": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"maxItems": 100,
"description": "progress-image-token: block ids or authored node ids (resolved to their block) left out of the image; their transitions collapse"
},
"collapse": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"maxItems": 100,
"description": "progress-image-token: block ids or authored node ids drawn as a label-only chip"
},
"at": {
"type": "integer",
"minimum": 0,
"description": "Route cursor for progress: project the run as of this visit sequence number (the route is cut there, variables carry the values written up to it)"
}
},
"required": [
"action"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}Результат: Данные сессии или выполнения для выбранной операции.
{
"action": "executions",
"limit": 20,
"offset": 0
}notes
Хранит и возвращает версионируемые заметки.
Операции: list, get, save, delete, history, stats.
Схема входа
{
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": [
"list",
"get",
"save",
"delete",
"history",
"stats"
],
"description": "Action to perform on notes"
},
"tag": {
"type": "string",
"description": "Filter notes by tag (for list action)"
},
"keySearch": {
"type": "string",
"description": "Search notes by key pattern (for list action)"
},
"limit": {
"type": "number",
"minimum": 1,
"maximum": 100,
"description": "Maximum notes to return (1-100, default 50)"
},
"offset": {
"type": "number",
"minimum": 0,
"description": "Pagination offset (default 0)"
},
"key": {
"type": "string",
"description": "Note key (required for get, save, delete, history actions)"
},
"version": {
"type": "number",
"description": "Specific version number to retrieve (for get action)"
},
"value": {
"type": "string",
"description": "Note content (required for save action)"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Tags for the note (for save action, max 10 tags)"
}
},
"required": [
"action"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}Результат: Данные заметок для выбранной операции.
{
"action": "list",
"limit": 20,
"offset": 0
}playbooks
Хранит именованный переиспользуемый текст поведения для чтения агентом.
Операции: list, get, save, delete, history, compare, restore, visibility.
Схема входа
{
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": [
"list",
"get",
"save",
"delete",
"history",
"compare",
"restore",
"visibility"
],
"description": "Action to perform on playbooks"
},
"name": {
"type": "string",
"description": "Playbook machine name (required for every action except list)"
},
"owner": {
"type": "string",
"description": "Owner handle or id when reading someone else's public playbook; defaults to you"
},
"search": {
"type": "string",
"description": "Search playbooks by name or description (for list)"
},
"limit": {
"type": "number",
"minimum": 1,
"maximum": 100,
"description": "Maximum playbooks to return (1-100, default 50)"
},
"offset": {
"type": "number",
"minimum": 0,
"description": "Pagination offset (default 0)"
},
"content": {
"type": "string",
"description": "Playbook text (required for save)"
},
"title": {
"type": "string",
"description": "Human-readable name (for save)"
},
"description": {
"type": "string",
"description": "What this playbook is for (for save)"
},
"revision": {
"type": "number",
"description": "Revision number to read or restore (for get and restore)"
},
"fromRevision": {
"type": "number",
"description": "Older revision to compare (for compare)"
},
"toRevision": {
"type": "number",
"description": "Newer revision to compare (for compare)"
},
"visibility": {
"type": "string",
"enum": [
"private",
"public"
],
"description": "Who may read the playbook (for visibility)"
}
},
"required": [
"action"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}Результат: Данные playbook для выбранной операции.
{
"action": "list",
"limit": 20,
"offset": 0
}artifacts
Управляет статическими HTML-артефактами.
Операции: upload, update, delete, list, stats, token.
Схема входа
{
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": [
"upload",
"update",
"delete",
"list",
"stats",
"token"
],
"description": "Action to perform on artifacts"
},
"name": {
"type": "string",
"description": "Artifact name (required for upload action)"
},
"content": {
"type": "string",
"description": "HTML content (required for upload and update actions)"
},
"executionId": {
"type": "string",
"description": "Link artifact to workflow execution (optional for upload)"
},
"uuid": {
"type": "string",
"description": "Artifact UUID (required for update and delete actions)"
},
"limit": {
"type": "number",
"minimum": 1,
"maximum": 100,
"description": "Maximum artifacts to return (1-100, default 50)"
},
"offset": {
"type": "number",
"minimum": 0,
"description": "Pagination offset (default 0)"
},
"ttlMinutes": {
"type": "number",
"minimum": 1,
"maximum": 1440,
"description": "Token expiration in minutes (1-1440, default 60)"
}
},
"required": [
"action"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}Результат: Метаданные, квота или токен артефакта.
{
"action": "list",
"limit": 20,
"offset": 0
}lock
Проверяет, создаёт или снимает блокировки выполнения.
Операции: status, list, unlock, lock.
Схема входа
{
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": [
"status",
"list",
"unlock",
"lock"
],
"description": "Action to perform on locks"
},
"executionId": {
"type": "string",
"description": "Execution ID (required for all actions)"
},
"pin": {
"type": "string",
"description": "PIN code to unlock (required for unlock action)"
},
"reason": {
"type": "string",
"description": "Reason for locking the execution (required for lock action)"
}
},
"required": [
"action",
"executionId"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}Результат: Состояние блокировки без секретного PIN-кода.
{
"action": "status",
"executionId": "00000000-0000-4000-8000-000000000000"
}workspace
Работа в постоянном облачном workspace: жизненный цикл, команды и файлы, по action.
Операции: list, create, get, start, stop, delete, exec, stat, search, read, write, apply_patch, upload, download.
Схема входа
{
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": [
"list",
"create",
"get",
"start",
"stop",
"delete",
"exec",
"stat",
"search",
"read",
"write",
"apply_patch",
"upload",
"download"
],
"description": "Workspace operation to perform"
},
"repository_id": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"ref": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"workspace_id": {
"type": "string",
"format": "uuid",
"description": "Persistent workspace ID"
},
"expected_generation": {
"type": "integer",
"minimum": 1
},
"confirm_delete": {
"type": "boolean",
"const": true,
"description": "Required explicit destructive confirmation"
},
"argv": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 16384
},
"minItems": 1,
"maxItems": 128
},
"script": {
"type": "string",
"minLength": 1,
"maxLength": 65536,
"description": "Shell script run inside a session; what it leaves behind is carried forward"
},
"session_end": {
"type": "boolean",
"description": "End the named session after this call, or alone with no command"
},
"cwd": {
"type": "string",
"maxLength": 4096
},
"session": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$",
"description": "Continue the working directory and variables of this named session"
},
"session_start": {
"type": "boolean",
"description": "Open the named session instead of continuing it"
},
"env": {
"type": "object",
"additionalProperties": {
"type": "string",
"maxLength": 4096
},
"propertyNames": {
"pattern": "^[A-Za-z_][A-Za-z0-9_]{0,127}$"
},
"description": "Variables for this command, and for later commands in the same session"
},
"timeout_seconds": {
"type": "integer",
"minimum": 1,
"maximum": 86400
},
"background": {
"type": "boolean",
"description": "Keep the command running past this request; collect it later by operation_id"
},
"max_stdout_bytes": {
"type": "integer",
"minimum": 1,
"maximum": 8388608
},
"max_stderr_bytes": {
"type": "integer",
"minimum": 1,
"maximum": 8388608
},
"stdin_text": {
"type": "string"
},
"stdin_file": {
"type": "object",
"properties": {
"file_id": {
"type": "string",
"maxLength": 512,
"pattern": "^(?:sediment:\\/\\/)?file_[A-Za-z0-9]+$"
},
"download_url": {
"type": "string",
"format": "uri"
},
"file_name": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"mime_type": {
"type": "string",
"maxLength": 127,
"pattern": "^[a-z0-9][a-z0-9!#$&^_.+-]*\\/[a-z0-9][a-z0-9!#$&^_.+-]*$"
},
"size_bytes": {
"type": "integer",
"minimum": 0,
"maximum": 4194304
}
},
"required": [
"file_id",
"download_url"
],
"additionalProperties": false,
"description": "Native ChatGPT file reference; pass the attachment reference without base64"
},
"operation_id": {
"anyOf": [
{
"type": "string",
"format": "uuid",
"description": "Pending operation ID returned by this tool"
},
{
"type": "string",
"format": "uuid",
"description": "Command operation whose retained output is read"
}
]
},
"cancel": {
"type": "boolean"
},
"path": {
"type": "string",
"minLength": 1,
"maxLength": 4096,
"description": "Repository-relative path"
},
"query": {
"type": "string",
"minLength": 1,
"maxLength": 4096
},
"mode": {
"type": "string",
"enum": [
"literal",
"regex"
]
},
"max_matches": {
"type": "integer",
"minimum": 1,
"maximum": 1000
},
"max_bytes": {
"anyOf": [
{
"type": "integer",
"minimum": 1,
"maximum": 1048576
},
{
"type": "integer",
"minimum": 1,
"maximum": 4194304
}
]
},
"offset": {
"type": "integer",
"minimum": 0
},
"length": {
"type": "integer",
"minimum": 1,
"maximum": 4194304
},
"stream": {
"type": "string",
"enum": [
"stdout",
"stderr"
]
},
"text": {
"type": "string"
},
"expected": {
"type": "object",
"properties": {
"exists": {
"type": "boolean",
"description": "Whether the target must already exist"
},
"size_bytes": {
"type": "integer",
"minimum": 0
},
"sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
}
},
"required": [
"exists"
],
"additionalProperties": false
},
"files": {
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string",
"minLength": 1,
"maxLength": 4096,
"description": "Repository-relative path"
},
"expected": {
"type": "object",
"properties": {
"exists": {
"type": "boolean",
"description": "Whether the target must already exist"
},
"size_bytes": {
"type": "integer",
"minimum": 0
},
"sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
}
},
"required": [
"exists"
],
"additionalProperties": false
},
"edits": {
"type": "array",
"items": {
"type": "object",
"properties": {
"start": {
"type": "integer",
"minimum": 0
},
"end": {
"type": "integer",
"minimum": 0
},
"text": {
"type": "string"
}
},
"required": [
"start",
"end",
"text"
],
"additionalProperties": false
},
"minItems": 1,
"maxItems": 4096
}
},
"required": [
"path",
"expected",
"edits"
],
"additionalProperties": false
},
"minItems": 1,
"maxItems": 64
},
"file": {
"type": "object",
"properties": {
"file_id": {
"type": "string",
"maxLength": 512,
"pattern": "^(?:sediment:\\/\\/)?file_[A-Za-z0-9]+$"
},
"download_url": {
"type": "string",
"format": "uri"
},
"file_name": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"mime_type": {
"type": "string",
"maxLength": 127,
"pattern": "^[a-z0-9][a-z0-9!#$&^_.+-]*\\/[a-z0-9][a-z0-9!#$&^_.+-]*$"
},
"size_bytes": {
"type": "integer",
"minimum": 0,
"maximum": 4194304
}
},
"required": [
"file_id",
"download_url"
],
"additionalProperties": false,
"description": "Native ChatGPT file reference; pass the attachment reference without base64"
},
"file_name": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"mime_type": {
"type": "string",
"maxLength": 127,
"pattern": "^[a-z0-9][a-z0-9!#$&^_.+-]*\\/[a-z0-9][a-z0-9!#$&^_.+-]*$"
}
},
"required": [
"action"
],
"additionalProperties": false,
"$schema": "http://json-schema.org/draft-07/schema#"
}Результат: Безопасный результат запрошенного действия: состояние workspace, состояние операции с ограниченным выводом, версии файлов или одноразовая нативная ссылка на скачивание.
{
"action": "list"
}{
"action": "create",
"repository_id": "123456",
"ref": "main"
}{
"action": "get",
"workspace_id": "00000000-0000-4000-8000-000000000000"
}{
"action": "exec",
"workspace_id": "00000000-0000-4000-8000-000000000000",
"argv": [
"git",
"status",
"--short"
],
"cwd": ".",
"timeout_seconds": 60
}{
"action": "read",
"workspace_id": "00000000-0000-4000-8000-000000000000",
"path": "src/index.ts",
"offset": 0,
"length": 65536
}{
"action": "delete",
"workspace_id": "00000000-0000-4000-8000-000000000000",
"expected_generation": 3,
"confirm_delete": true
}{
"action": "search",
"workspace_id": "00000000-0000-4000-8000-000000000000",
"path": ".",
"query": "TODO",
"mode": "literal"
}{
"action": "write",
"workspace_id": "00000000-0000-4000-8000-000000000000",
"path": "notes.txt",
"text": "done\n",
"expected": {
"exists": false
}
}{
"action": "download",
"workspace_id": "00000000-0000-4000-8000-000000000000",
"path": "result.pdf",
"max_bytes": 4194304,
"file_name": "result.pdf",
"mime_type": "application/pdf"
}{
"action": "download",
"workspace_id": "00000000-0000-4000-8000-000000000000",
"operation_id": "11111111-1111-4111-8111-111111111111",
"file_name": "result.pdf",
"mime_type": "application/pdf"
}Поведение инструментов
Заголовок раздела «Поведение инструментов»Типизированный каталог определяет допустимый ввод клиента. Ниже описаны авторизация, изменения состояния и рабочее поведение, которые нельзя выразить в JSON Schema.
Связь с пользователем
Заголовок раздела «Связь с пользователем»communication доставляет сообщения только в активные каналы аутентифицированного пользователя.
Провайдеров и получателей выбирает сервер; вызывающая сторона не может передать пользователя,
провайдера, адресата, credentials, локальный путь, удалённый URL или произвольный HTTP-заголовок.
Операция send принимает непустое сообщение длиной не более 4096 символов и возвращает безопасную
сводку по всем настроенным каналам.
Для изображения или документа вызовите attachment-token с сообщением, видом вложения, именем
файла, MIME-типом и точным размером в байтах. Возвращённый grant действует пять минут и разрешает не
более одной попытки провайдера. Не помещайте grant в URL; отправьте байты с OAuth или постоянным MCP
Bearer credential пользователя, который создал grant:
curl --request POST "$uploadUrl" \ --header "Authorization: Bearer $MOIRA_MCP_TOKEN" \ --header "X-Moira-Communication-Grant: $grant" \ --header "Content-Type: application/pdf" \ --header "Content-Length: $(wc -c < report.pdf)" \ --data-binary @report.pdfОбъявленный размер должен совпадать с Content-Length и фактически полученным числом байтов.
Размер одного вложения ограничен 20 МиБ; изображения принимаются в PNG или JPEG, а документы не
принимают image MIME-типы. До начала доставки провайдером ошибка MIME-типа, размера, сигнатуры
изображения или допуска по числу одновременных загрузок освобождает grant для исправленного запроса
до истечения срока. После любой попытки провайдера результат окончателен, а повтор возвращает тот же
неспецифичный ответ о недействительном grant. Один пользователь может одновременно иметь десять
активных grants и два буфера загрузки общим объёмом не более 40 МиБ; установка принимает одну тысячу
активных grants. Истёкшие и завершённые grants не занимают квоту выдачи.
Поиск и выполнение процессов
Заголовок раздела «Поиск и выполнение процессов»list возвращает только процессы, доступные аутентифицированному пользователю. Фильтры поиска, видимости, сортировки и пагинации применяются совместно; total описывает все совпадения, а не только возвращённую страницу. Каждый ответ содержит фактические offset и limit, а также returnedCount и hasMore. Если есть следующая страница, передайте nextOffset как offset следующего запроса; на последней странице возвращается nextOffset: null.
Все инструменты публикуют входную схему с объектом в корне, чтобы MCP-клиенты видели полный
каталог. Поэтому публичная схема start содержит action непосредственно в корне и перечисляет
поля обеих фаз. Runtime-валидация по-прежнему строго проверяет выбранную фазу: для prepare нужны
workflowId и parentExecutionId, а для execute — startAttemptId; поля только другой фазы и
неизвестные поля отклоняются как MCP-ошибки. Инструмент workspace следует тому же шаблону в
большем масштабе: один плоский объект с action и полями всех действий, где обязателен только
action, а точная форма запрошенного действия проверяется при диспетчеризации (новый запрос либо
возобновление только с workspace_id и operation_id; для exec ровно одно из stdin_text или
stdin_file). Поле, которого нет ни у одного действия, по-прежнему отклоняется как MCP-ошибка; поле
другого действия отклоняется при диспетчеризации как WORKSPACE_REQUEST_INVALID. Значение по
умолчанию, объявленное действием, применяется там же и поэтому отсутствует в публичной схеме. Если два
действия принимают одно и то же поле с разными пределами — max_bytes равен 1 МиБ для search и
4 МиБ для download, — схема показывает обе формы, а какая из них требовалась от вызова, решает
названное действие.
start({ action: "prepare" }) разрешает и проверяет доступный процесс, связывает версию workflow и параметры запроса и возвращает Start attempt ID со сроком 15 минут, не создавая execution. parentExecutionId связывает дочернее выполнение с существующим родителем; для самостоятельного выполнения используется "none". skipNotificationCheck сохраняет политику пропуска только опционального preflight обычных уведомлений во время execute. skipTelegramCheck остаётся устаревшим alias с тем же поведением, а противоречащие значения отклоняются.
start({ action: "execute", startAttemptId }) повторно проверяет изменяемые условия workflow, родителя, учётной записи, lock-delivery и связи до расходования именно этой подготовки. Workflow с user-notification без настроенного канала возвращает общую инструкцию по Settings, а legacy workflow с telegram-notification — инструкцию по настройке Telegram. Для workflow с lock node всегда нужны корректные Telegram bot token и chat ID текущего пользователя; ни один skip-флаг не обходит доверенную доставку PIN. Неуспешная изменяемая проверка сохраняет повторяемый ответ START_PRECONDITION_CHANGED и не создаёт execution. Успех возвращает Process ID, идентификатор попытки первого шага и первую директиву. Повторный execute возвращает точно сохранённый ответ и не может создать ещё одно execution; отдельная подготовка означает намеренный отдельный запуск.
step требует Process ID и идентификатор попытки шага из текущего предъявления, даже если нода принимает пустой ввод. Попытка идентифицирует предъявленный шаг и не является входными данными workflow. Повтор того же вызова с теми же входными данными возвращает долговечно сохранённый результат, не применяя переход второй раз. Одинаковые параллельные вызовы объединяются за одним владельцем: дубликат либо получает сохранённый им ответ за ограниченное время ожидания, либо получает ATTEMPT_PROCESSING; обработчик не выполняется последовательно для каждого дубликата. Другой ввод для завершённой попытки, попытка от другого выполнения и старая попытка после перехода процесса отклоняются.
ATTEMPT_PROCESSING означает, что изменение ещё принадлежит другому вызывающему: повторите ту же попытку с теми же данными. ATTEMPT_STALE отклоняется до работы обработчика: автоматически прочитайте session({ action: "current_step", executionId }) и один раз повторите исходную отправку с возвращённым идентификатором попытки шага. ATTEMPT_CONFLICT отклоняется, потому что эта попытка уже связана с другими входными данными: автоматически прочитайте current_step, отбросьте конфликтующую попытку и продолжите по возвращённой директиве и схеме, не повторяя старый ввод. Если ошибка шага ATTEMPT_INVALID_OR_EXPIRED явно предписывает прочитать current_step, примените то же восстановление и отбросьте недоступную попытку. Для недоступной попытки запуска такое восстановление неприменимо. ATTEMPT_OUTCOME_UNKNOWN означает, что внешний эффект уже мог произойти: изучите возвращённый Process ID и не повторяйте изменение автоматически. Владелец может завершить заблокированное execution на его текущей ревизии через session({ action: "cancel-execution", executionId, expectedRevision }). Каждое последующее приостановленное предъявление получает новый идентификатор попытки. Процесс может предоставлять именованные точки телепортации; телепортация и обычный ввод ноды взаимоисключающие. Зарезервированное поле execution_note во входе обновляет заметку, видимую в списках выполнений. Ошибки инструмента остаются ошибками и не отображаются как успешные шаги.
session работает только с выполнениями текущего пользователя. Он позволяет получить сведения о пользователе, перечислить или исследовать выполнения, повторно показать текущий шаг без продвижения, выяснить, почему приостановленное выполнение не может продолжиться, изменить заметку или родителя, управлять напоминаниями вызывающей стороны, читать и изменять объявленные runtime-переменные согласно политике процесса, читать прогресс или запросить одноразовое скачивание изображения прогресса, а также доставить файлы приостановленной ноды материализации прямо в ответ, когда хост не может выполнить предъявленную команду. После прерывания current_step возвращает авторитетное текущее предъявление и его идентификатор попытки шага. Если у приостановленного выполнения нет сохранённой попытки шага, current_step создаёт привязанное предъявление без исполнения или продвижения ноды. Он также исправляет предъявленную попытку, у которой устарела только привязка к ревизии выполнения. Для живой попытки, привязанной к другой ноде или к поверхности продолжения, которой в текущем определении больше нет, возвращается CURRENT_PRESENTATION_STALE; её старый идентификатор не рекомендуется и не может быть повторён, а сама ошибка указывает на diagnose. diagnose сообщает, может ли приостановленное выполнение продолжиться на текущем определении workflow, и называет каждую причину, по которой не может: ноду, на которой оно стоит, и сохранилась ли она; какие факты его поверхности продолжения изменились; какие ссылки предъявленный шаг не может разрешить из контекста; записанную ошибку выполнения; попытку, принадлежащую другой ноде, без привязки продолжения или не в состоянии предъявления. Каждая причина сообщает, блокирует ли она продолжение: блокирующая означает, что без восстановления выполнение не дойдёт до следующего шага, а неблокирующая объясняет наблюдаемое, пока выполнение остаётся пригодным, — отсутствующее или устаревшее по ревизии предъявление, попытка, которую исполняет другой вызывающий, неразрешённая ссылка, записанная ошибка. Поле continuable истинно, когда не блокирует ни одна причина. Действие ничего не меняет, а здоровое выполнение сообщает о себе как о пригодном к продолжению и не называет ни одной причины. recover возвращает такое выполнение к шагу, с которого оно может продолжиться: передайте nodeId ноды, на которой выполнение может ожидать, — agent-directive, teleport, materialize, lock или subgraph — и variableValues с тем, что этому шагу нужно, — выполнение переносится туда, значения записываются в контекст, нода предъявляется заново, и следующим вызовом становится обычный step(). Действие отклоняется для выполнения, которое уже завершено: завершённое или отменённое выполнение таким и остаётся, потому что восстановление чинит то выполнение, которое пытается продолжиться и не может, а diagnose по-прежнему объясняет, почему оно не может продолжиться. Для ещё идущих выполнений действие отклоняется, если diagnose не называет ни одной блокирующей причины: здоровое выполнение отклоняется намеренно. Любой отказ оставляет выполнение нетронутым и называет следующие вызовы. В аудит записываются оба исхода: и восстановление, и отказ. Поверхность продолжения — это то, от чего ещё зависит приостановленный шаг: всё, что объявляет эта нода, кроме того, как она отображается, плюс записи реестра для объявленных ею на вход глобальных переменных. Поэтому обновлённый workflow оставляет приостановленное выполнение пригодным, пока изменение её не затрагивает: новая версия, новые теги, переписанное описание, правка другой ноды или чисто косметическое изменение самой приостановленной ноды пригодность сохраняют.
Ревизия выполнения увеличивается только тогда, когда исходный вызов step сохраняет состояние workflow. Изменения родителя, напоминаний, заметки и runtime-переменных не увеличивают её и не делают текущую попытку шага недействительной. Для записи родителя, напоминаний и runtime-переменных нужны expectedRevision и соответствующая непрозрачная ревизия из execution_context, reminders, variables или предыдущего изменения (expectedParentRevision, expectedRemindersRevision или expectedContextRevision). Эти ревизии отдельных целей не дают старому снимку метаданных перезаписать более новый в рамках одной генерации шага. Изменение родителя принимает "none" для отсоединения, требует выполняющиеся execution одного владельца и отклоняет циклы. Напоминания не меняют план workflow и не дают полномочий; активные напоминания возвращаются при завершении execution. Запись runtime-переменных по умолчанию запрещена, обязана соответствовать схеме переменной и не продвигает граф.
Когда current_step показывает приостановленную ноду материализации, он возвращает новую команду скачивания архива со сроком пять минут, а не содержимое файлов. Разрешение привязано к текущему пользователю, выполнению, ноде и снимку контекста; повторные загрузки допустимы, только пока выполнение ожидает на этой ноде с тем же контекстом. Выполните или повторите возвращённую команду без изменений, затем завершите ноду значением null или {}; переход выполнения или изменение его контекста делает URL недействительным. Хост, который не может выполнить команду или обратиться к сети, использует вместо этого materialize: тот возвращает те же тела файлов в ответе с теми же привязками и окном, но с меньшим ограничением на суммарный размер, и завершает ноду так же.
Разрешения на изображение прогресса привязаны к владельцу выполнения, версии процесса, ревизии шага, ревизии контекста и нормализованным параметрам рендера. Ошибка рендера или HTTP-доставки не расходует разрешение; успешное завершение ответа расходует его.
Определения процессов и сверка
Заголовок раздела «Определения процессов и сверка»manage разрешает идентификаторы процессов только в пределах доступа вызывающей стороны. Создание и редактирование валидируют итоговое определение до сохранения. Существующий идентификатор перезаписывается только по явному запросу; редактирование отклоняет пустые изменения, отсутствующие или повторные ноды и невалидный итоговый граф.
Операция get возвращает все заданные метаданные процесса, реестр переменных, runtime-политику, представление прогресса, напоминание и структурные сведения. includeNodes: false исключает только определения нод, а includeValidation: false — только результаты валидации. Используйте list-nodes для компактного обзора, get-nodes для выбранного набора, analyze-variables для анализа переменных всего определения и set-visibility для переключения собственного процесса между публичным и приватным режимами.
Поиск нод использует ограниченные RE2-совместимые выражения, если запрос содержит синтаксис регулярного выражения, и переходит к регистронезависимому буквальному поиску для некорректных или неподдерживаемых шаблонов. Клонирование отклоняет отсутствующий источник или повторный целевой идентификатор. Перемещение меняет порядок массива, не переписывая заданные соединения, и отклоняет результат, который перестал проходить валидацию.
Операции с переменными процесса работают с объявленным в определении variableRegistry. Создание, просмотр и отзыв общего доступа и приглашений требуют полномочий владельца. Неуспешная мутация возвращает MCP-ошибку без частичного применения изменения.
reconciliation разрешает конфликты между предыдущей встроенной версией процесса, текущей версией в базе и входящей версией образа. Статус доступен агентам, но полные состояния кандидатов показываются только администраторам; получение кандидата и разрешение конфликта доступны только администратору. Разрешайте конфликт семантически через Workflow Management Flow, а не механическим слиянием JSON графа.
Блокировки
Заголовок раздела «Блокировки»lock принимает только выполнения текущего пользователя. Статус возвращает активную блокировку, список — публичную историю блокировок, а разблокировка проверяет переданный PIN по активной записи. Для создания через MCP нужен выполняющийся процесс без активной блокировки и корректные Telegram-настройки текущего пользователя. Сгенерированный PIN отправляется только в настроенный chat, а несекретные метаданные возвращаются после успешной доставки. При отсутствующих или некорректных настройках и при ошибке отправки эта попытка не оставляет доступной активной блокировки; MCP-ответы и ошибки никогда не содержат PIN.
Отдельный аутентифицированный Web-маршрут создания блокировки один раз показывает PIN человеку — владельцу выполнения. Этот человеческий ответ недоступен через MCP или output workflow node.
Настройки и заметки
Заголовок раздела «Настройки и заметки»settings читает один точный key, одну category или полный доступный набор. Не объединяйте key и category в одном запросе get. Определения включают настройки из базы данных и настройки, объявленные в манифестах установленных расширений. Зашифрованные значения всегда маскируются: для настроек из базы возвращается [encrypted], а для настроек расширений — маска из точек с последними четырьмя символами. Административные значения и определения скрыты от пользователей без прав администратора. Запись требует существующее определение и применяет административные ограничения, объявленный тип, опциональную валидацию по JSON Schema, шифрование и регистрацию Telegram webhook при сохранении токена бота. Структурированное JSON-значение должно проходить сериализацию и чтение без пропуска или преобразования данных. Значение по умолчанию расширения должно пройти ту же проверку типа и схемы до принятия манифеста. Список возвращает доступные сейчас определения, а не сохранённые значения; удаление расширения скрывает его определения, но сохраняет пользовательские значения для последующей переустановки.
notes хранит изолированный по пользователям версионируемый текст. При чтении можно выбрать сохранённую версию; удаление мягкое. Сохранение соблюдает настроенные ограничения размера одной заметки, общего хранилища, числа версий, ключей и тегов. Администраторы могут менять действующие лимиты.
Playbooks
Заголовок раздела «Playbooks»playbooks хранит именованный переиспользуемый текст поведения — стандарт ревью, тон, определение
готовности — в одном месте, а не внутри процессов, которые на него опираются: текст правится один
раз, и агент читает его там, где он нужен.
Имя состоит из строчных букв, цифр и дефисов и уникально внутри аккаунта; запись под именем, которое
занято у другого пользователя, создаёт собственный playbook, а не меняет чужой. Каждое сохранение пишет ревизию, restore пишет новую ревизию с прежним
текстом, а compare показывает разницу двух ревизий построчно. Ревизии хранятся в пределах
настроенного удержания, размер playbook ограничен.
visibility публикует playbook или снова делает его приватным. Опубликованный playbook читает любой
аутентифицированный пользователь, назвав владельца, а менять его может только владелец: публикация
отдаёт текст, а не управление им. Чтобы прочитать чужой опубликованный playbook, владельца нужно
назвать через owner — по handle или по идентификатору пользователя.
Публичные артефакты и файлы процессов
Заголовок раздела «Публичные артефакты и файлы процессов»artifacts управляет публичными статическими HTML-результатами с пользовательскими квотами количества и объёма, ограничением размера файла и сроком хранения. Загрузку можно связать с выполнением; обновление и удаление требуют владения. Операция токена создаёт одноразовое HTTP-разрешение для внешнего клиента загрузки. Администраторы могут менять действующие квоты глобально или для пользователя.
token предназначен только для файлового импорта и экспорта процессов. Разрешение загрузки принимает JSON-файл процесса как multipart-поле workflow; разрешение скачивания требует доступный процесс. Оба имеют короткий срок действия. Для обычного просмотра и изменения процесса используйте manage.
Получив разрешение загрузки от token, отправьте выбранный файл на его uploadUrl:
curl -X POST "${uploadUrl}" -F "workflow=@your-workflow.json"Облачные рабочие пространства
Заголовок раздела «Облачные рабочие пространства»Инструмент workspace даёт агенту постоянное облачное окружение разработки, принадлежащее
пользователю (сейчас — личный GitHub Codespace), без локальной оболочки и файловой системы. Весь
набор операций обслуживает один инструмент: action выбирает операцию — list, create, get,
start, stop, delete, exec, stat, search, read, write, apply_patch, upload или
download, — а остальные поля принадлежат выбранному действию. GitHub подключается только на сайте
Moira; ни одно действие не запускает, не продолжает и не опрашивает авторизацию. Если подключение,
установка приложения или конфигурация сервера отсутствуют, каждое действие возвращает ограниченную
ошибку с settings_url того же origin, чтобы пользователь завершил настройку, и ничего не
создаёт.
Каждый вызов, кроме list и create, указывает workspace_id, полученный из них.
Владение проверяется на сервере, поэтому неизвестный или чужой ID возвращает общий результат
WORKSPACE_NOT_FOUND. Пространство не привязано к чату или сессии: используйте один workspace_id
из любого клиента. list предлагает только пространства, которыми ещё можно
пользоваться: удалённого или отклонённого в списке нет, но get по-прежнему отвечает по
его workspace_id. stop сохраняет данные репозитория (data_preserved: true);
delete разрушителен и требует confirm_delete: true вместе с текущим generation
пространства, поэтому устаревший вызов не удалит изменившееся пространство.
exec выполняет argv как данные (без интерполяции в оболочку) в cwd относительно
репозитория с необязательным таймаутом (timeout_seconds) и необязательными лимитами на каждый
поток вывода и возвращает ограниченные
stdout, stderr и точный exit_code. Эти лимиты ограничивают ответ, а не команду: команда,
напечатавшая больше, продолжает работать, сохраняет собственный код возврата и собственный
stderr, а результат сообщает полный размер каждого потока и был ли ответ усечён. Весь вывод
остаётся в пространстве до очистки операции, и любой его диапазон читается действием read.
Команда останавливается из-за объёма только тогда, когда её сохранённый вывод достигает предела
пространства; это сообщается именно так, а не как собственный сбой команды. Для работы, которая
переживает один запрос, например полной сборки или прогона тестов, передайте background: true:
вызов сразу возвращает выполняющуюся операцию, команда продолжает работать в пространстве под
значительно большим пределом, её вывод читается диапазонами прямо во время работы, а результат
забирается позже по тому же operation_id и остаётся доступным не меньше, чем команде было
позволено выполняться. Если timeout_seconds не указан, обычная команда получает 300 секунд, а
фоновая — весь свой предел.
Последовательные команды могут работать в общем контексте. Откройте сессию через session и
session_start: true, затем называйте ту же session в последующих командах: она запоминает cwd,
указанный вызовом, и переменные, переданные в env, и применяет их к каждой продолжающей команде.
Команда без сессии работает как прежде. Внутри сессии вместо argv можно передать script: он
выполняется оболочкой самого пространства, а каталог, в котором он завершился, и переменные, которые
он добавил, изменил или удалил, переносятся в следующие команды — так переживает активация
инструментария или виртуального окружения. Команда argv никогда не выполняется через оболочку, и
один вызов несёт одну форму работы. Завершить сессию можно параметром session_end: true, отдельно
или вместе с командой; завершение освобождает её место и удаляет сохранённое. Число одновременно открытых сессий в пространстве ограничено: когда предел достигнут, следующий
session_start получает отказ с названным пределом и просьбой завершить одну из сессий, а не
повторять вызов или создавать другое пространство. Сохранённый контекст тоже
ограничен: вызов, который его превысит, получает отказ с названным пределом, а скрипт переносит своё конечное состояние
независимо от того, завершился он успешно или с ошибкой; скрипт, чьё состояние не помещается,
завершивший собственную оболочку через exit или остановленный, сообщает session_capture_dropped,
вместо того чтобы оставить сессию непригодной. Сессия принадлежит текущей жизни пространства: после
остановки и запуска обращение к ней возвращает WORKSPACE_SESSION_UNAVAILABLE, и нужно открыть
новую, как и для сессии, которую никогда не открывали. То, что хранит сессия, остаётся в
пространстве и не возвращается. Остановить любую из них можно вызовом с
workspace_id, operation_id и cancel: true. Команда останавливается вместе со своим
пространством, поэтому длинной команде нужно пространство, чей срок простоя её переживёт. Уснувшее
пространство не нужно запускать заранее: вызов, которому оно понадобилось, сам его запускает и затем
выполняется — в пределах ограниченного ожидания. Если пространство не успевает запуститься, вызов
возвращает WORKSPACE_START_TIMEOUT с названным пределом ожидания и просьбой повторить вызов; а
пространство, которое запустить невозможно, получает отказ по своему фактическому состоянию. Команда,
под которой пространство перезапустилось, сообщается как WORKSPACE_OPERATION_INTERRUPTED с полем
interrupted_by_restart у операции, а не как собственный сбой: уже записанные ею файлы на месте,
результата она не дала, и средство от этого — запустить её снова. Передавайте не более одной формы stdin: stdin_text для
UTF-8-текста или stdin_file для нативной файловой ссылки ChatGPT; байты файла попадают в процесс
без base64 в переписке. Завершившиеся с ошибкой, по таймауту и отменённые команды, а также
отклонённые правки файлов возвращаются как ошибки инструмента, сохраняющие operation_id и
доступный вывод. Быстро завершившаяся команда возвращает терминальный результат тем же вызовом,
который её запустил; всё ещё выполняющаяся возвращает нетерминальный state, который не является
успехом. Вызовите то же действие повторно только с workspace_id и operation_id, чтобы
получить сохранённый итог без повторного запуска команды или мутации.
read возвращает UTF-8-текст с offset и total_size, а для файла репозитория ещё и
sha256; передавайте path для файла либо operation_id и stream для сохранённого stdout или
stderr команды, указывая то пространство, которому эта команда принадлежит. Чтение, начинающееся
на конце потока или за ним, возвращает пустой текст и текущий размер потока. length по умолчанию
равен 64 КиБ, а search по умолчанию возвращает до 100 совпадений в пределах 64 КиБ, так
что вызов только с workspace, путём и запросом полон. Поиск идёт по содержимому репозитория и
пропускает его собственный каталог .git, а также отказывает, если корень поиска указан в этом
каталоге или внутри него; файл в нём по-прежнему читается по точному пути. Нетекстовый диапазон возвращает
WORKSPACE_BINARY_READ_REQUIRES_DOWNLOAD. Вызов, не соответствующий ни одной форме запроса,
возвращает WORKSPACE_REQUEST_INVALID с именами отсутствующих или неверных полей. write атомарно заменяет файл при
предусловии expected (exists, необязательные size_bytes и sha256), а apply_patch
применяет упорядоченные правки по байтовым смещениям для каждого файла с теми же предусловиями и
возвращает старую/новую версии и сводку без содержимого. upload записывает нативную
файловую ссылку по пути; download возвращает файл как MCP resource_link, одноразовая
HTTPS-ссылка которого истекает автоматически и не повторяется в JSON-результате.
Агент действует как обычный пользователь Codespace с репозиторием, сетью и настроенными секретами этого окружения. Moira ограничивает собственную конкурентность, размер ввода/вывода, время и квоты и защищает сервер Moira и других пользователей; она не изолирует пространство от агента, которого авторизовал его владелец. Пользователь может держать несколько пространств одновременно, а отказ в создании называет тот предел, который его остановил: ваш собственный предел активных пространств, предел всего экземпляра или интервал между созданиями. Отказ сообщает настроенное значение этого предела и никогда не называет другого пользователя или его пространства. Когда в создании, запуске, остановке или удалении отказывает сам GitHub, ошибка говорит именно об этом, а не о внутреннем сбое: она различает грант, который нужно переавторизовать, запрос, в котором GitHub откажет и при любом повторе, и недоступность провайдера, которую имеет смысл повторить, — и передаёт собственное объяснение GitHub одной укороченной строкой. Эта строка отбрасывается целиком, оставляя только HTTP-статус, если в ней есть что-либо похожее на учётные данные: токен, помеченный секрет, JWT или URL.
Runtime-справка
Заголовок раздела «Runtime-справка»help обнаруживает файловые темы в установленном корпусе MCP-справки и перечисляет рядом с ними прямую тему tools. Вызовите его без темы, чтобы получить актуальные имена тем и псевдонимы. Несколько запрошенных тем возвращаются вместе с разделителями. Тема tools и её псевдоним tool отображают тот же типизированный каталог непосредственно из реестра.
Связанная документация
Заголовок раздела «Связанная документация»- Руководство MCP-агента — использование MCP-инструментов
- Устранение неполадок — распространённые проблемы