Skip to content

Beautiful Open-Source Form Builder

9.0 KB
Raw Blame
<?php

namespace App\Mcp\Tools;

use App\Mcp\Support\McpOutputSchema;
use App\Models\Forms\Form;
use App\Rules\PropertyValidators\LogicPropertyValidator;
use App\Service\Forms\AgentFormFieldCatalog;
use App\Service\Forms\AgentFormDraftService;
use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\ResponseFactory;
use Laravel\Mcp\Server\Attributes\Description;
use Laravel\Mcp\Server\Attributes\Name;
use Laravel\Mcp\Server\Tools\Annotations\IsDestructive;
use Laravel\Mcp\Server\Tools\Annotations\IsOpenWorld;
use Laravel\Mcp\Server\Tools\Annotations\IsReadOnly;

#[Name('patch_form_draft')]
#[Description('Apply semantic operations to the current guest draft. This tool is data-only and never renders a widget. Requires the latest expected_version and rejects conflicts without overwriting newer work. On success, call preview_form_draft exactly once with the returned draft_handle so the user sees one updated preview. Do not retry after success. Correct validation errors and retry with the same current version; after a version conflict, fetch the draft before retrying. Supported ops: set_form_values, add_block, update_block, remove_block, move_block.')]
#[IsReadOnly(false)]
#[IsDestructive]
#[IsOpenWorld(false)]
class PatchFormDraftTool extends GuestDraftMcpTool
{
    public function handle(Request $request, AgentFormDraftService $drafts): ResponseFactory
    {
        $validated = $request->validate([
            'draft_handle' => ['required', 'string', 'size:43'],
            'expected_version' => ['required', 'integer', 'min:1'],
            'operations' => ['required', 'array', 'min:1', 'max:100'],
            'operations.*' => ['required', 'array'],
            'operations.*.op' => ['required', 'string'],
        ]);

        $draft = $drafts->patch(
            $validated['draft_handle'],
            $validated['expected_version'],
            $validated['operations'],
        );

        return Response::structured([
            'draft_handle' => $validated['draft_handle'],
            'draft' => $drafts->serialize($draft),
        ]);
    }

    public function schema(JsonSchema $schema): array
    {
        return [
            'draft_handle' => $schema->string()
                ->description('Opaque reference returned by create_form_draft. Pass it unchanged.')
                ->min(43)
                ->max(43)
                ->required(),
            'expected_version' => $schema->integer()
                ->description('Version returned by the most recent create, get, or patch call.')
                ->min(1)
                ->required(),
            'operations' => $schema->array()
                ->description('Ordered semantic patch operations. Select blocks by block_id when possible; index is supported. See the tool description and schema resource for operation fields.')
                ->items($schema->object([
                    'op' => $schema->string()
                        ->enum(['set_form_values', 'add_block', 'update_block', 'remove_block', 'move_block'])
                        ->required(),
                    'values' => $schema->object([
                        'title' => $schema->string()->description('Form title.'),
                        'presentation_style' => $schema->string()->enum(Form::PRESENTATION_STYLES),
                        'width' => $schema->string()->enum(Form::WIDTHS),
                        'size' => $schema->string()->enum(Form::SIZES),
                        'theme' => $schema->string()->enum(Form::THEMES),
                        'border_radius' => $schema->string()->enum(Form::BORDER_RADIUS),
                        'color' => $schema->string()->description('Form accent color, preferably a hex color.'),
                        'uppercase_labels' => $schema->boolean(),
                        'show_progress_bar' => $schema->boolean(),
                        'submit_button_text' => $schema->string(),
                        'settings' => $schema->object(),
                        'computed_variables' => $schema->array()
                            ->items($schema->object([
                                'id' => $schema->string()->description('Unique technical ID beginning with cv_.')->required(),
                                'name' => $schema->string()->description('Unique human-readable variable name.')->required(),
                                'formula' => $schema->string()->description('Formula using brace references such as {budget} * 1.2.')->required(),
                                'result_type' => $schema->string()->enum(['number', 'text', 'auto']),
                            ]))
                            ->max(500)
                            ->description('Complete replacement list of computed variables. Use [] to remove all variables.'),
                    ])->description('Top-level form values for set_form_values, including computed_variables. Do not put properties here.'),
                    'block' => $schema->object([
                        'name' => $schema->string()->required(),
                        'type' => $schema->string()->enum(AgentFormFieldCatalog::types())->required(),
                        'content' => $schema->string()->description('For nf-text blocks: sanitized HTML, never Markdown.'),
                        'placeholder' => $schema->string()->nullable(),
                        'help' => $schema->string()->nullable(),
                        'hidden' => $schema->boolean(),
                        'required' => $schema->boolean(),
                        'width' => $schema->string()->enum(['full', '1/2', '1/3', '2/3', '1/4', '3/4']),
                        'logic' => $this->logicSchema($schema)->nullable(),
                    ])->description('Complete block for add_block. Use type nf-page-break only in classic mode.'),
                    'patch' => $schema->object([
                        'name' => $schema->string(),
                        'type' => $schema->string()->enum(AgentFormFieldCatalog::types()),
                        'content' => $schema->string()->description('For nf-text blocks: sanitized HTML, never Markdown.'),
                        'placeholder' => $schema->string()->nullable(),
                        'help' => $schema->string()->nullable(),
                        'hidden' => $schema->boolean(),
                        'required' => $schema->boolean(),
                        'width' => $schema->string()->enum(['full', '1/2', '1/3', '2/3', '1/4', '3/4']),
                        'logic' => $this->logicSchema($schema)->nullable(),
                    ])->description('Fields to merge into the selected block for update_block. Block id cannot change.'),
                    'block_id' => $schema->string()->description('Stable block id from the latest draft.'),
                    'index' => $schema->integer()->description('Zero-based block index. For add_block, insertion at the final count is allowed.')->min(0),
                    'to_index' => $schema->integer()->description('Zero-based destination for move_block.')->min(0),
                ]))
                ->min(1)
                ->max(100)
                ->required(),
        ];
    }

    private function logicSchema(JsonSchema $schema): mixed
    {
        return $schema->object([
            'conditions' => $schema->object([
                'operatorIdentifier' => $schema->string()->enum(['and', 'or']),
                'children' => $schema->array()->items($schema->object()),
                'identifier' => $schema->string()->description('Referenced field or computed-variable ID.'),
                'value' => $schema->object([
                    'operator' => $schema->string()->enum(AgentFormFieldCatalog::logicOperators()),
                    'property_meta' => $schema->object([
                        'id' => $schema->string()->description('Referenced field or computed-variable ID.'),
                        'type' => $schema->string()
                            ->enum(array_keys(AgentFormFieldCatalog::logicOperatorsByReferenceType()))
                            ->description('Use computed for a computed-variable reference.'),
                    ]),
                    'value' => $schema->union(['string', 'number', 'boolean', 'object', 'array', 'null'])
                        ->description('Comparison value. Omit it for operators that do not take a value, such as is_empty or is_checked.'),
                ]),
            ])->description('A condition leaf or a nested and/or group. See opnform://schemas/agent-form-definition/v1 for the recursive shape.'),
            'actions' => $schema->array()
                ->items($schema->string()->enum(LogicPropertyValidator::ACTIONS_VALUES))
                ->min(1),
        ])->description('Conditional behavior for the target block. Empty or safely invalid logic is removed during normalization.');
    }

    public function outputSchema(JsonSchema $schema): array
    {
        return [
            'draft_handle' => $schema->string()->min(43)->max(43)->required(),
            'draft' => McpOutputSchema::draft($schema)->required(),
        ];
    }
}