Beautiful Open-Source Form Builder
fix(mcp): keep previews stable and guide next steps
Julien Nahum96c1320172da
diff --git a/api/app/Mcp/Apps/FormDraftPreviewApp.php b/api/app/Mcp/Apps/FormDraftPreviewApp.phpindex 0f718dad1..348f5539c 100644--- a/api/app/Mcp/Apps/FormDraftPreviewApp.php+++ b/api/app/Mcp/Apps/FormDraftPreviewApp.php@@ -14,7 +14,7 @@ use Laravel\Mcp\Server\Ui\Csp;#[Name('form_draft_preview')]#[Description('Interactive preview of a temporary guest OpnForm draft with an optional editor handoff.')]-#[Uri('ui://opnform/form-draft-preview-v4')]+#[Uri('ui://opnform/form-draft-preview-v5')]class FormDraftPreviewApp extends AppResource{public function shouldRegister(McpAvailability $availability): booldiff --git a/api/app/Mcp/Servers/OpnFormServer.php b/api/app/Mcp/Servers/OpnFormServer.phpindex 29d1991c1..4afc42bd9 100644--- a/api/app/Mcp/Servers/OpnFormServer.php+++ b/api/app/Mcp/Servers/OpnFormServer.php@@ -33,7 +33,7 @@ use Laravel\Mcp\Server\Attributes\Version;#[Name('OpnForm')]#[Version('1.0.0')]-#[Instructions('Default every request to create a new form to the guest draft workflow unless the user explicitly asks to save it in their connected OpnForm account or a workspace. A natural request such as "create a contact form" needs no login or preview wording: validate, then create_form_draft, which renders the interactive preview. Every patch_form_draft renders the updated preview too. Follow the catalog authoring guidelines: human labels, useful placeholders, appropriate fields/layout, a contextual submit label, and a useful completion message. Correct relevant quality_warnings while preserving intentional choices. For a long answer, use type text with multi_lines true; textarea is not a valid field type. If validation fails, correct and revalidate the definition before creating a draft. Never ask the user to connect when guest draft tools can satisfy the request. OAuth is required only for connected-account operations. Enabling or selecting the plugin is not OAuth authentication. Use preview_form_draft only to re-render an existing draft. If an account-scoped tool challenges, ask the user to authenticate the OpnForm MCP server in the host; do not repeatedly retry from the guest workflow. In local Codex, start a new conversation after OAuth so the MCP client loads the stored credential. If guest draft tools are unexpectedly missing, do not substitute an authenticated tool unless the user requested account persistence; ask the user to start a new conversation with OpnForm selected before the first message. Use OpnForm MCP tools directly. Never invoke Codex or ChatGPT recursively, run `codex exec`, use shell or raw HTTP, inspect repositories or caches, or switch connectors. Read the schema and field catalog again before changing presentation, fields, layout, or media, then validate before saving. Focused presentation creates one step per block automatically: use full-width blocks, no page breaks or standalone media blocks, and attach optional media through the block image property. Use only durable public HTTPS asset URLs, never localhost or temporary tunnel URLs.')]+#[Instructions('Default every request to create a new form to the guest draft workflow unless the user explicitly asks to save it in their connected OpnForm account or a workspace. A natural request such as "create a contact form" needs no login or preview wording: validate, then create_form_draft, which renders the interactive preview. Every patch_form_draft renders the updated preview too. Follow the catalog authoring guidelines: human labels, useful placeholders, appropriate fields/layout, a contextual submit label, and a useful completion message. Correct relevant quality_warnings while preserving intentional choices. For a long answer, use type text with multi_lines true; textarea is not a valid field type. If validation fails, correct and revalidate the definition before creating a draft. Never ask the user to connect when guest draft tools can satisfy the request. OAuth is required only for connected-account operations. Enabling or selecting the plugin is not OAuth authentication. Use preview_form_draft only to re-render an existing draft. After each guest create or patch, briefly summarize the result and ask whether the user wants another change or wants to save the form to their OpnForm account. Never call a temporary guest draft saved. Once an account-owned form is saved as an unpublished draft, say so and ask whether the user wants it published; asking is not confirmation, so publish only after an explicit affirmative response. If an account-scoped tool challenges, ask the user to authenticate the OpnForm MCP server in the host; do not repeatedly retry from the guest workflow. In local Codex, start a new conversation after OAuth so the MCP client loads the stored credential. If guest draft tools are unexpectedly missing, do not substitute an authenticated tool unless the user requested account persistence; ask the user to start a new conversation with OpnForm selected before the first message. Use OpnForm MCP tools directly. Never invoke Codex or ChatGPT recursively, run `codex exec`, use shell or raw HTTP, inspect repositories or caches, or switch connectors. Read the schema and field catalog again before changing presentation, fields, layout, or media, then validate before saving. Focused presentation creates one step per block automatically: use full-width blocks, no page breaks or standalone media blocks, and attach optional media through the block image property. Use only durable public HTTPS asset URLs, never localhost or temporary tunnel URLs.')]class OpnFormServer extends Server{public int $maxPaginationLength = 100;diff --git a/api/app/Mcp/Tools/CreateFormDraftTool.php b/api/app/Mcp/Tools/CreateFormDraftTool.phpindex ba68bc73e..778f9bb1d 100644--- a/api/app/Mcp/Tools/CreateFormDraftTool.php+++ b/api/app/Mcp/Tools/CreateFormDraftTool.php@@ -51,6 +51,7 @@ class CreateFormDraftTool extends GuestDraftMcpTool'Pass draft_handle unchanged to guest draft tools. Do not display this internal handle to the user.','Use patch_form_draft with expected_version for changes.','The interactive preview is included in this result; present it before any text summary.',+ 'After the preview, ask whether the user wants another change or wants to save the form to their OpnForm account.',],]);}diff --git a/api/app/Mcp/Tools/PatchFormDraftTool.php b/api/app/Mcp/Tools/PatchFormDraftTool.phpindex 324c91292..cebb7cd52 100644--- a/api/app/Mcp/Tools/PatchFormDraftTool.php+++ b/api/app/Mcp/Tools/PatchFormDraftTool.php@@ -46,7 +46,7 @@ class PatchFormDraftTool extends GuestDraftMcpTool'draft_handle' => $validated['draft_handle'],'draft' => $drafts->serialize($draft),'preview_url' => $drafts->previewUrl($draft),- 'next_step' => 'The refreshed interactive preview is included in this result; present it before any text summary.',+ 'next_step' => 'Present the refreshed interactive preview, briefly summarize the change, then ask whether the user wants another change or wants to save the form to their OpnForm account.',]);}diff --git a/api/app/Service/Forms/McpFormManagementService.php b/api/app/Service/Forms/McpFormManagementService.phpindex dd0096bb5..170728dee 100644--- a/api/app/Service/Forms/McpFormManagementService.php+++ b/api/app/Service/Forms/McpFormManagementService.php@@ -132,7 +132,7 @@ class McpFormManagementService'message' => 'Form created as an unpublished draft.','form' => $this->serializeForm($created['form']->load('workspace')),'disabled_features' => $created['cleanings'],- 'next_step' => 'Open edit_url to review or refine the unpublished form. Ask the user before calling publish_form.',+ 'next_step' => 'Tell the user the form is saved as an unpublished draft, then ask whether they want to publish it. Call publish_form only after explicit confirmation.',];}diff --git a/api/resources/views/mcp/form-draft-preview-app.blade.php b/api/resources/views/mcp/form-draft-preview-app.blade.phpindex ac907cff4..b542f8a78 100644--- a/api/resources/views/mcp/form-draft-preview-app.blade.php+++ b/api/resources/views/mcp/form-draft-preview-app.blade.php@@ -54,6 +54,7 @@let presentationStyle = 'classic';let resizeScriptPromise;let draftHandle = null;+ let currentPreviewUrl = null;let rendered = false;const initialOpenButtonText = openButton.textContent;const loadingFallback = window.setTimeout(() => {@@ -143,7 +144,11 @@if (payload.preview_url) {const previewUrl = new URL(payload.preview_url);previewUrl.searchParams.set('embedded', '1');- preview.src = previewUrl.toString();+ const nextPreviewUrl = previewUrl.toString();+ if (currentPreviewUrl !== nextPreviewUrl) {+ currentPreviewUrl = nextPreviewUrl;+ preview.src = nextPreviewUrl;+ }preview.hidden = false;previewViewport.hidden = false;applyPreviewLayout();@@ -188,15 +193,6 @@app.onToolInput(applyToolInput);app.onToolResult(renderToolResult);- applyToolInput(window.openai?.toolInput);- renderToolResult(window.openai?.toolOutput);-- window.addEventListener('openai:set_globals', (event) => {- const globals = event.detail?.globals ?? {};- applyToolInput(globals.toolInput ?? window.openai?.toolInput);- renderToolResult(globals.toolOutput ?? window.openai?.toolOutput);- });-openButton.onclick = async () => {if (!draftHandle) return;diff --git a/api/tests/Feature/Mcp/AgentDraftEditorTest.php b/api/tests/Feature/Mcp/AgentDraftEditorTest.phpindex 2158fc689..8ed2e8db3 100644--- a/api/tests/Feature/Mcp/AgentDraftEditorTest.php+++ b/api/tests/Feature/Mcp/AgentDraftEditorTest.php@@ -45,8 +45,9 @@ it('renders a read-only MCP App preview and creates an editor link only on deman->assertOk()->assertSee('Open in OpnForm')->assertSee("app.callServerTool('open_form_draft_in_editor'")- ->assertSee('window.openai?.toolOutput')- ->assertSee("openai:set_globals")+ ->assertSee('currentPreviewUrl !== nextPreviewUrl')+ ->assertDontSee('window.openai')+ ->assertDontSee("openai:set_globals")->assertSee('<iframe');OpnFormServer::tool(OpenFormDraftInEditorTool::class, [@@ -72,7 +73,7 @@ it('publishes standard and ChatGPT-compatible CSP metadata with the full fronten->content()->toResource($previewApp);- expect($previewApp->uri())->toBe('ui://opnform/form-draft-preview-v4')+ expect($previewApp->uri())->toBe('ui://opnform/form-draft-preview-v5')->and($previewApp->resolvedAppMeta()['csp']['resourceDomains'])->toBe(['http://127.0.0.1:33676'])->and($previewApp->resolvedAppMeta()['csp']['frameDomains'])diff --git a/api/tests/Feature/Mcp/AgentPluginPackageTest.php b/api/tests/Feature/Mcp/AgentPluginPackageTest.phpindex 22124285b..141dffa63 100644--- a/api/tests/Feature/Mcp/AgentPluginPackageTest.php+++ b/api/tests/Feature/Mcp/AgentPluginPackageTest.php@@ -249,6 +249,25 @@ it('renders a guest preview automatically after creation and every draft change'->toContain('RendersApp(resource: FormDraftPreviewApp::class)');});+it('guides the agent from guest preview to account save and explicit publication', function () {+ $skill = file_get_contents(opnformPluginPath('skills/opnform/SKILL.md'));+ $server = file_get_contents(app_path('Mcp/Servers/OpnFormServer.php'));+ $createTool = file_get_contents(app_path('Mcp/Tools/CreateFormDraftTool.php'));+ $patchTool = file_get_contents(app_path('Mcp/Tools/PatchFormDraftTool.php'));++ expect($skill)+ ->toContain('whether the user wants another change or wants to save the form')+ ->toContain('saved as a draft and ask whether the user wants to publish it')+ ->toContain('Asking is not confirmation')+ ->and($server)+ ->toContain('Never call a temporary guest draft saved')+ ->toContain('publish only after an explicit affirmative response')+ ->and($createTool)+ ->toContain('wants another change or wants to save the form')+ ->and($patchTool)+ ->toContain('wants another change or wants to save the form');+});+it('renders a flattened and hardened form preview frame', function () {$view = file_get_contents(resource_path('views/mcp/form-draft-preview-app.blade.php'));@@ -266,13 +285,14 @@ it('renders a flattened and hardened form preview frame', function () {->toContain('new ResizeObserver(applyPreviewLayout).observe(previewViewport)')->toContain("sizeHeight: presentationStyle !== 'focused'")->toContain("app.callServerTool('open_form_draft_in_editor'")- ->toContain('window.openai?.toolOutput')- ->toContain("openai:set_globals")+ ->toContain('currentPreviewUrl !== nextPreviewUrl')->toContain('Ask ChatGPT to refresh this preview.')->toContain('aria-label="Preview zoom"')->toContain('sandbox="allow-forms allow-modals allow-popups allow-scripts allow-same-origin"')->toContain('referrerpolicy="no-referrer"')->not->toContain('class="card"')->not->toContain('border-radius: 10px')+ ->not->toContain('window.openai')+ ->not->toContain('openai:set_globals')->not->toContain('allow-top-navigation');});diff --git a/api/tests/Feature/Mcp/AuthenticatedFormToolsTest.php b/api/tests/Feature/Mcp/AuthenticatedFormToolsTest.phpindex db39ff9c3..bc52c54d3 100644--- a/api/tests/Feature/Mcp/AuthenticatedFormToolsTest.php+++ b/api/tests/Feature/Mcp/AuthenticatedFormToolsTest.php@@ -168,7 +168,7 @@ it('hides guest draft capabilities but keeps validation and OAuth tools on self-expect($resourceUris)->toContain('opnform://schemas/agent-form-definition/v1', 'opnform://reference/form-fields/v1')- ->not->toContain('ui://opnform/form-draft-preview-v4');+ ->not->toContain('ui://opnform/form-draft-preview-v5');$this->postJson('/mcp', ['jsonrpc' => '2.0',diff --git a/api/tests/Feature/Mcp/GuestDraftToolsTest.php b/api/tests/Feature/Mcp/GuestDraftToolsTest.phpindex e69ac2fe9..c23559340 100644--- a/api/tests/Feature/Mcp/GuestDraftToolsTest.php+++ b/api/tests/Feature/Mcp/GuestDraftToolsTest.php@@ -34,9 +34,9 @@ it('publishes a neutral draft handle contract and accurate preview annotations',expect($create['outputSchema']['properties'])->toHaveKey('draft_handle')->and($create['outputSchema']['properties'])->toHaveKey('preview_url')->and($create['outputSchema']['properties'])->not->toHaveKey('draft_token')- ->and($create['_meta']['ui']['resourceUri'])->toBe('ui://opnform/form-draft-preview-v4')+ ->and($create['_meta']['ui']['resourceUri'])->toBe('ui://opnform/form-draft-preview-v5')->and(app(PatchFormDraftTool::class)->toArray()['_meta']['ui']['resourceUri'])- ->toBe('ui://opnform/form-draft-preview-v4')+ ->toBe('ui://opnform/form-draft-preview-v5')->and($preview['inputSchema']['properties'])->toHaveKey('draft_handle')->and($preview['outputSchema']['properties'])->not->toHaveKeys(['editor_url',diff --git a/plugins/opnform/.codex-plugin/plugin.json b/plugins/opnform/.codex-plugin/plugin.jsonindex c70e8dd3a..ae9762cf5 100644--- a/plugins/opnform/.codex-plugin/plugin.json+++ b/plugins/opnform/.codex-plugin/plugin.json@@ -1,6 +1,6 @@{"name": "opnform",- "version": "1.0.1",+ "version": "1.0.2","description": "Build private form drafts without signing in, then connect OpnForm to manage forms and read submissions.","author": {"name": "OpnForm",diff --git a/plugins/opnform/plugin.json b/plugins/opnform/plugin.jsonindex 06c2d2a72..83b098ebd 100644--- a/plugins/opnform/plugin.json+++ b/plugins/opnform/plugin.json@@ -1,7 +1,7 @@{"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json","name": "opnform",- "version": "1.0.1",+ "version": "1.0.2","description": "Create, preview, and manage OpnForm forms and read their submissions with an AI agent.","author": {"name": "OpnForm",diff --git a/plugins/opnform/skills/opnform/SKILL.md b/plugins/opnform/skills/opnform/SKILL.mdindex bc742a64e..11c856ac7 100644--- a/plugins/opnform/skills/opnform/SKILL.md+++ b/plugins/opnform/skills/opnform/SKILL.md@@ -30,10 +30,18 @@ This is the default workflow for new-form requests, including when the user does6. Apply requested changes with `patch_form_draft`, passing the latest `expected_version`. Validate the changed definition before persistence when needed. Its result renders the refreshed interactive preview automatically; present it before replying so the user never needs to ask to see an update.7. If the version conflicts or the current state is uncertain, call `get_form_draft`, reconcile the user's requested changes, validate again, and retry with the new version. Never overwrite blindly.8. If a patch returns a validation error, correct the invalid operation and retry once with the same latest version. Report the returned validation problem accurately; do not turn a recoverable enum or field error into a generic “server error”.-9. Offer to open the draft in OpnForm. Call `open_form_draft_in_editor` only after the user chooses the preview's **Open in OpnForm** action or explicitly asks to continue in the editor. The returned handoff URL is reusable until the seven-day guest draft expires; generating another URL does not revoke earlier ones.+9. After the preview, briefly summarize the result and ask one concise next-step question: whether the user wants another change or wants to save the form to their OpnForm account. Use the user's language. Do not end with only “the draft is ready”, and do not claim that a temporary guest draft is saved to an account.+10. Call `open_form_draft_in_editor` only after the user chooses the preview's **Open in OpnForm** action or explicitly asks to continue in the editor. The returned handoff URL is reusable until the seven-day guest draft expires; generating another URL does not revoke earlier ones.The browser editor keeps the guest draft available through an HttpOnly session. The user can preview and edit before signing in. Authentication and workspace selection happen only when the user chooses to save the draft into an OpnForm account.+### Guide the next decision++- After every successful guest creation or revision, keep the interactive preview visible, mention the meaningful result or change in one sentence, and offer the two relevant choices: continue modifying the form or save it to the user's OpnForm account.+- When the user chooses to save, that is an explicit request for account persistence. Enter the authenticated workflow, preserve the latest validated definition, and connect only if needed. If the user prefers the visual editor, use the editor handoff instead.+- After a form is saved to an account and remains unpublished, clearly say that it is saved as a draft and ask whether the user wants to publish it. Asking is not confirmation: call `publish_form` only after an explicit affirmative response.+- If the user already gave the next instruction, follow it instead of repeating a menu. Keep suggestions contextual and limited to one immediate decision; do not pile on unrelated account or submission actions.+### Produce a polished first draft- Infer the form's purpose, audience, language, and tone. Make conservative assumptions and show a useful first draft instead of blocking on non-essential questions.@@ -72,7 +80,7 @@ For new forms, enter this authenticated workflow only when the user explicitly aAfter authentication, use the account context to choose a workspace. If exactly one writable workspace is available, select it without asking. If several are available, call `list_workspaces` and ask the user which one to use. Workspace access is read-only through MCP; do not attempt workspace administration.- Use form listing and lookup tools to identify the target before changing it.-- `create_form_in_account` creates an account-owned draft. After creation, ask whether the user wants it published.+- `create_form_in_account` creates an account-owned draft. State that it is saved but unpublished, then ask whether the user wants it published.- Before `update_form`, `publish_form`, or `trash_form`, fetch the form and pass its current `revision` as `expected_revision`. On conflict, fetch, reconcile, and retry instead of overwriting newer changes.- Call `publish_form` only after the user explicitly confirms publication, then pass the confirmed form's `expected_revision` and `confirm_publish: true`.- Call `trash_form` only after the user explicitly confirms moving the form to trash, then pass the confirmed form's `expected_revision` and `confirm_trash: true`. MCP does not expose form restoration or permanent deletion.