Skip to content

Beautiful Open-Source Form Builder

fix(mcp): make guest draft previews reliable

Julien Nahume4bb538a2ed9
diff --git a/api/.env.example b/api/.env.example
index bfb967312..c90a9f69d 100644
--- a/api/.env.example
+++ b/api/.env.example
@@ -136,6 +136,9 @@ MCP_RATE_LIMIT_PER_MINUTE=120
MCP_RATE_LIMIT_PER_HOUR=3000
MCP_DRAFT_CREATES_PER_MINUTE=20
MCP_DRAFT_CREATES_PER_HOUR=200
+MCP_DRAFT_HANDOFFS_PER_MINUTE=120
+MCP_DRAFT_EDITOR_REQUESTS_PER_MINUTE=240
+MCP_DRAFT_PROXY_POOL_PER_MINUTE=6000
MCP_SUBMISSION_EXPORTS_PER_MINUTE=5
MCP_SUBMISSION_EXPORTS_PER_HOUR=30
# Comma-separated OAuth callback origins. Keep this allowlist explicit.
diff --git a/api/app/Mcp/Servers/OpnFormServer.php b/api/app/Mcp/Servers/OpnFormServer.php
index 0f1afff00..29d1991c1 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: read the schema and field catalog, validate, create_form_draft, then preview_form_draft. Follow the catalog authoring guidelines: use human labels, helpful example placeholders, appropriate fields and layout, a contextual submit label, and a useful completion message. Correct relevant non-blocking quality_warnings while preserving intentional choices. For a message or other 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. 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. 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.php
index 62a3818d7..ba68bc73e 100644
--- a/api/app/Mcp/Tools/CreateFormDraftTool.php
+++ b/api/app/Mcp/Tools/CreateFormDraftTool.php
@@ -2,6 +2,7 @@
namespace App\Mcp\Tools;
+use App\Mcp\Apps\FormDraftPreviewApp;
use App\Mcp\Support\McpOutputSchema;
use App\Service\Forms\AgentFormDraftRateLimiter;
use App\Service\Forms\AgentFormDraftService;
@@ -11,6 +12,7 @@ use Laravel\Mcp\Response;
use Laravel\Mcp\ResponseFactory;
use Laravel\Mcp\Server\Attributes\Description;
use Laravel\Mcp\Server\Attributes\Name;
+use Laravel\Mcp\Server\Attributes\RendersApp;
use Laravel\Mcp\Server\Attributes\Title;
use Laravel\Mcp\Server\Tools\Annotations\IsDestructive;
use Laravel\Mcp\Server\Tools\Annotations\IsOpenWorld;
@@ -18,7 +20,8 @@ use Laravel\Mcp\Server\Tools\Annotations\IsReadOnly;
#[Name('create_form_draft')]
#[Title('Create a Guest Form Draft')]
-#[Description('Use this as the default creation tool whenever the user asks to create, build, or preview a new form without explicitly asking to save it in an OpnForm account or workspace. It works immediately without login; never request authentication or use create_form_in_account instead for this guest-first workflow. Creates a temporary unpublished draft that expires after seven days and returns an opaque draft handle for get_form_draft, patch_form_draft, and preview_form_draft.')]
+#[Description('Use this as the default creation tool when the user asks to create or build a new form without explicitly asking to save it in an OpnForm account or workspace. A natural request such as "create a contact form" is sufficient; the user does not need to mention guest mode, login, a draft, or a preview. It works immediately without login and returns a temporary unpublished seven-day draft with its interactive preview; never request authentication or use create_form_in_account for this guest-first workflow.')]
+#[RendersApp(resource: FormDraftPreviewApp::class)]
#[IsReadOnly(false)]
#[IsDestructive(false)]
#[IsOpenWorld(false)]
@@ -43,10 +46,11 @@ class CreateFormDraftTool extends GuestDraftMcpTool
return Response::structured([
'draft_handle' => $created['token'],
'draft' => $drafts->serialize($created['draft']),
+ 'preview_url' => $drafts->previewUrl($created['draft']),
'next_steps' => [
'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.',
- 'Render a preview before asking the user to claim or publish the form.',
+ 'The interactive preview is included in this result; present it before any text summary.',
],
]);
}
@@ -69,6 +73,7 @@ class CreateFormDraftTool extends GuestDraftMcpTool
->max(43)
->required(),
'draft' => McpOutputSchema::draft($schema)->required(),
+ 'preview_url' => $schema->string()->format('uri')->required(),
'next_steps' => $schema->array()->items($schema->string())->required(),
];
}
diff --git a/api/app/Mcp/Tools/PatchFormDraftTool.php b/api/app/Mcp/Tools/PatchFormDraftTool.php
index 623cc0097..324c91292 100644
--- a/api/app/Mcp/Tools/PatchFormDraftTool.php
+++ b/api/app/Mcp/Tools/PatchFormDraftTool.php
@@ -2,6 +2,7 @@
namespace App\Mcp\Tools;
+use App\Mcp\Apps\FormDraftPreviewApp;
use App\Mcp\Support\McpOutputSchema;
use App\Models\Forms\Form;
use App\Service\Forms\AgentFormFieldCatalog;
@@ -12,12 +13,14 @@ use Laravel\Mcp\Response;
use Laravel\Mcp\ResponseFactory;
use Laravel\Mcp\Server\Attributes\Description;
use Laravel\Mcp\Server\Attributes\Name;
+use Laravel\Mcp\Server\Attributes\RendersApp;
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 validated semantic operations to a private draft. Operations can replace or remove draft content. Requires expected_version, so concurrent agent or editor changes cannot be silently overwritten. Supported ops: set_form_values, add_block, update_block, remove_block, move_block. Before changing presentation_style, fields, layout, or media, read opnform://reference/form-fields/v1. Style values are strict: border_radius is none, small, or full; width is centered or full; size is sm, md, or lg; theme is default, simple, notion, minimal, or transparent. Classic mode uses nf-page-break for explicit pagination; focused mode derives one step per block and must not use page breaks.')]
+#[Description('Use this when the user asks to change the current guest form draft. Apply validated semantic operations and return the updated interactive preview automatically. Requires expected_version, so concurrent agent or editor changes cannot be silently overwritten. Supported ops: set_form_values, add_block, update_block, remove_block, move_block. Before changing presentation_style, fields, layout, or media, read opnform://reference/form-fields/v1. Style values are strict: border_radius is none, small, or full; width is centered or full; size is sm, md, or lg; theme is default, simple, notion, minimal, or transparent. Classic mode uses nf-page-break for explicit pagination; focused mode derives one step per block and must not use page breaks.')]
+#[RendersApp(resource: FormDraftPreviewApp::class)]
#[IsReadOnly(false)]
#[IsDestructive]
#[IsOpenWorld(false)]
@@ -40,8 +43,10 @@ class PatchFormDraftTool extends GuestDraftMcpTool
);
return Response::structured([
+ 'draft_handle' => $validated['draft_handle'],
'draft' => $drafts->serialize($draft),
- 'next_step' => 'Render or refresh the preview before presenting the result to the user.',
+ 'preview_url' => $drafts->previewUrl($draft),
+ 'next_step' => 'The refreshed interactive preview is included in this result; present it before any text summary.',
]);
}
@@ -105,7 +110,9 @@ class PatchFormDraftTool extends GuestDraftMcpTool
public function outputSchema(JsonSchema $schema): array
{
return [
+ 'draft_handle' => $schema->string()->min(43)->max(43)->required(),
'draft' => McpOutputSchema::draft($schema)->required(),
+ 'preview_url' => $schema->string()->format('uri')->required(),
'next_step' => $schema->string()->required(),
];
}
diff --git a/api/app/Mcp/Tools/PreviewFormDraftTool.php b/api/app/Mcp/Tools/PreviewFormDraftTool.php
index 949d82025..c3f55c403 100644
--- a/api/app/Mcp/Tools/PreviewFormDraftTool.php
+++ b/api/app/Mcp/Tools/PreviewFormDraftTool.php
@@ -17,7 +17,7 @@ use Laravel\Mcp\Server\Tools\Annotations\IsOpenWorld;
use Laravel\Mcp\Server\Tools\Annotations\IsReadOnly;
#[Name('preview_form_draft')]
-#[Description('Render the current guest draft and return a browser preview valid for one hour. This read-only tool does not create an editor link. Call open_form_draft_in_editor only when the user chooses to continue editing in OpnForm.')]
+#[Description('Use this when an existing guest draft preview needs to be shown or re-rendered without changing the draft. Create_form_draft and patch_form_draft already render their previews automatically. The returned browser preview is valid for one hour. This read-only tool does not create an editor link. Call open_form_draft_in_editor only when the user chooses to continue editing in OpnForm.')]
#[RendersApp(resource: FormDraftPreviewApp::class)]
#[IsReadOnly]
#[IsDestructive(false)]
diff --git a/api/app/Providers/RouteServiceProvider.php b/api/app/Providers/RouteServiceProvider.php
index 401f9e10e..46e25f624 100644
--- a/api/app/Providers/RouteServiceProvider.php
+++ b/api/app/Providers/RouteServiceProvider.php
@@ -121,6 +121,35 @@ class RouteServiceProvider extends ServiceProvider
RateLimiter::for('mcp-oauth-registration', function (Request $request) {
return Limit::perHour(20)->by('mcp-oauth-registration:'.$request->ip());
});
+
+ RateLimiter::for('agent-draft-handoff', function (Request $request) {
+ $token = (string) $request->input('handoff_token');
+ $identifier = strlen($token) === 43
+ ? 'token:'.hash('sha256', $token)
+ : 'invalid:'.$request->ip();
+
+ return [
+ Limit::perMinute(max(1, config('opnform.mcp.rate_limit.draft_handoffs_per_minute', 120)))
+ ->by('agent-draft-handoff:'.$identifier),
+ Limit::perMinute(max(1, config('opnform.mcp.rate_limit.draft_proxy_pool_per_minute', 6000)))
+ ->by('agent-draft-handoff:proxy:'.$request->ip()),
+ ];
+ });
+
+ RateLimiter::for('agent-draft-editor', function (Request $request) {
+ $session = (string) $request->header('x-agent-draft-session');
+ $identifier = strlen($session) === 43
+ ? 'session:'.hash('sha256', $session)
+ : 'missing:'.$request->ip();
+ $route = $request->route()?->getName() ?? $request->path();
+
+ return [
+ Limit::perMinute(max(1, config('opnform.mcp.rate_limit.draft_editor_requests_per_minute', 240)))
+ ->by('agent-draft-editor:'.$route.':'.$identifier),
+ Limit::perMinute(max(1, config('opnform.mcp.rate_limit.draft_proxy_pool_per_minute', 6000)))
+ ->by('agent-draft-editor:proxy:'.$request->ip()),
+ ];
+ });
}
protected function registerGlobalRouteParamConstraints()
diff --git a/api/config/opnform.php b/api/config/opnform.php
index bd9fe6ae4..29d5fb62f 100644
--- a/api/config/opnform.php
+++ b/api/config/opnform.php
@@ -25,6 +25,9 @@ return [
'per_hour' => (int) env('MCP_RATE_LIMIT_PER_HOUR', 3000),
'draft_creates_per_minute' => (int) env('MCP_DRAFT_CREATES_PER_MINUTE', 20),
'draft_creates_per_hour' => (int) env('MCP_DRAFT_CREATES_PER_HOUR', 200),
+ 'draft_handoffs_per_minute' => (int) env('MCP_DRAFT_HANDOFFS_PER_MINUTE', 120),
+ 'draft_editor_requests_per_minute' => (int) env('MCP_DRAFT_EDITOR_REQUESTS_PER_MINUTE', 240),
+ 'draft_proxy_pool_per_minute' => (int) env('MCP_DRAFT_PROXY_POOL_PER_MINUTE', 6000),
'submission_exports_per_minute' => (int) env('MCP_SUBMISSION_EXPORTS_PER_MINUTE', 5),
'submission_exports_per_hour' => (int) env('MCP_SUBMISSION_EXPORTS_PER_HOUR', 30),
],
diff --git a/api/routes/api.php b/api/routes/api.php
index 2a7990ac7..e3b268e33 100644
--- a/api/routes/api.php
+++ b/api/routes/api.php
@@ -61,15 +61,19 @@ Route::middleware('mcp.enabled')->group(function () {
->middleware(['signed', 'throttle:60,1'])
->name('preview');
Route::post('/handoff/consume', [AgentFormDraftController::class, 'consume'])
- ->middleware('throttle:30,1')
+ ->withoutMiddleware('throttle:100,1')
+ ->middleware('throttle:agent-draft-handoff')
->name('handoff.consume');
Route::get('/editor/current', [AgentFormDraftController::class, 'current'])
- ->middleware('throttle:120,1')
+ ->withoutMiddleware('throttle:100,1')
+ ->middleware('throttle:agent-draft-editor')
->name('editor.current');
Route::put('/editor/current', [AgentFormDraftController::class, 'replace'])
- ->middleware('throttle:120,1')
+ ->withoutMiddleware('throttle:100,1')
+ ->middleware('throttle:agent-draft-editor')
->name('editor.replace');
Route::post('/editor/claim', [AgentFormDraftController::class, 'claim'])
+ ->withoutMiddleware('throttle:100,1')
->middleware(['auth.multi', 'throttle:30,1'])
->name('editor.claim');
});
diff --git a/api/tests/Feature/Mcp/AgentDraftEditorTest.php b/api/tests/Feature/Mcp/AgentDraftEditorTest.php
index 6ecd882bd..2158fc689 100644
--- a/api/tests/Feature/Mcp/AgentDraftEditorTest.php
+++ b/api/tests/Feature/Mcp/AgentDraftEditorTest.php
@@ -8,6 +8,7 @@ use App\Models\Forms\AgentFormDraft;
use App\Models\OAuthProvider;
use App\Models\User;
use App\Service\Forms\AgentFormDraftService;
+use Illuminate\Routing\Middleware\ThrottleRequests;
use Illuminate\Support\Facades\URL;
function editorDraftDefinition(array $overrides = []): array
@@ -181,6 +182,73 @@ it('keeps every guest editor link reusable until the draft expires', function ()
->assertJsonValidationErrors('handoff_token');
});
+it('rate limits editor handoffs by capability instead of the shared frontend proxy', function () {
+ $this->withMiddleware(ThrottleRequests::class);
+ config()->set('opnform.mcp.rate_limit.draft_handoffs_per_minute', 2);
+ config()->set('opnform.mcp.rate_limit.draft_proxy_pool_per_minute', 1000);
+ $drafts = app(AgentFormDraftService::class);
+ $created = $drafts->create(editorDraftDefinition());
+
+ // Exceed the API group's generic 100/minute budget to prove that unrelated
+ // visitors sharing the trusted frontend proxy no longer consume one pool.
+ foreach (range(1, 101) as $_) {
+ $handoff = $drafts->issueEditorHandoff($created['token']);
+
+ $this->withHeader('x-api-secret', 'test-front-secret')
+ ->postJson(route('agent-drafts.handoff.consume'), [
+ 'handoff_token' => $handoff['handoff_token'],
+ ])
+ ->assertOk();
+ }
+
+ $reused = $drafts->issueEditorHandoff($created['token']);
+ foreach (range(1, 2) as $_) {
+ $this->withHeader('x-api-secret', 'test-front-secret')
+ ->postJson(route('agent-drafts.handoff.consume'), [
+ 'handoff_token' => $reused['handoff_token'],
+ ])
+ ->assertOk();
+ }
+
+ $this->withHeader('x-api-secret', 'test-front-secret')
+ ->postJson(route('agent-drafts.handoff.consume'), [
+ 'handoff_token' => $reused['handoff_token'],
+ ])
+ ->assertTooManyRequests();
+});
+
+it('rate limits editor requests by session instead of the shared frontend proxy', function () {
+ $this->withMiddleware(ThrottleRequests::class);
+ config()->set('opnform.mcp.rate_limit.draft_editor_requests_per_minute', 2);
+ config()->set('opnform.mcp.rate_limit.draft_proxy_pool_per_minute', 100);
+ $drafts = app(AgentFormDraftService::class);
+
+ $sessions = collect(range(1, 2))->map(function () use ($drafts): string {
+ $created = $drafts->create(editorDraftDefinition());
+
+ return $drafts->consumeEditorHandoff(
+ $drafts->issueEditorHandoff($created['token'])['handoff_token'],
+ )['editor_session'];
+ });
+
+ foreach (range(1, 2) as $_) {
+ $this->withHeaders([
+ 'x-api-secret' => 'test-front-secret',
+ AgentFormDraftController::SESSION_HEADER => $sessions[0],
+ ])->getJson(route('agent-drafts.editor.current'))->assertOk();
+ }
+
+ $this->withHeaders([
+ 'x-api-secret' => 'test-front-secret',
+ AgentFormDraftController::SESSION_HEADER => $sessions[0],
+ ])->getJson(route('agent-drafts.editor.current'))->assertTooManyRequests();
+
+ $this->withHeaders([
+ 'x-api-secret' => 'test-front-secret',
+ AgentFormDraftController::SESSION_HEADER => $sessions[1],
+ ])->getJson(route('agent-drafts.editor.current'))->assertOk();
+});
+
it('requires the trusted frontend secret for editor endpoints', function () {
$drafts = app(AgentFormDraftService::class);
$created = $drafts->create(editorDraftDefinition());
diff --git a/api/tests/Feature/Mcp/AgentPluginPackageTest.php b/api/tests/Feature/Mcp/AgentPluginPackageTest.php
index b132fddde..22124285b 100644
--- a/api/tests/Feature/Mcp/AgentPluginPackageTest.php
+++ b/api/tests/Feature/Mcp/AgentPluginPackageTest.php
@@ -231,6 +231,24 @@ it('teaches agents how to change presentation and media without repository inspe
->toContain('Never persist localhost, private addresses, temporary tunnel domains');
});
+it('renders a guest preview automatically after creation and every draft change', 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('renders the interactive MCP preview automatically')
+ ->toContain('renders the refreshed interactive preview automatically')
+ ->and($server)
+ ->toContain('needs no login or preview wording')
+ ->toContain('Every patch_form_draft renders the updated preview too')
+ ->and($createTool)
+ ->toContain('RendersApp(resource: FormDraftPreviewApp::class)')
+ ->and($patchTool)
+ ->toContain('RendersApp(resource: FormDraftPreviewApp::class)');
+});
+
it('renders a flattened and hardened form preview frame', function () {
$view = file_get_contents(resource_path('views/mcp/form-draft-preview-app.blade.php'));
diff --git a/api/tests/Feature/Mcp/GuestDraftToolsTest.php b/api/tests/Feature/Mcp/GuestDraftToolsTest.php
index 445884978..e69ac2fe9 100644
--- a/api/tests/Feature/Mcp/GuestDraftToolsTest.php
+++ b/api/tests/Feature/Mcp/GuestDraftToolsTest.php
@@ -32,7 +32,11 @@ it('publishes a neutral draft handle contract and accurate preview annotations',
$open = app(OpenFormDraftInEditorTool::class)->toArray();
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(app(PatchFormDraftTool::class)->toArray()['_meta']['ui']['resourceUri'])
+ ->toBe('ui://opnform/form-draft-preview-v4')
->and($preview['inputSchema']['properties'])->toHaveKey('draft_handle')
->and($preview['outputSchema']['properties'])->not->toHaveKeys([
'editor_url',
@@ -50,6 +54,7 @@ it('creates a seven-day server-side guest draft and returns an opaque handle', f
'definition' => guestDraftDefinition(['visibility' => 'public']),
])->assertOk()
->assertSee('draft_handle')
+ ->assertSee('preview_url')
->assertDontSee('capability secret')
->assertSee('Customer intake')
->assertSee('expected_version');
@@ -110,6 +115,7 @@ it('patches form values and blocks with optimistic versioning', function () {
$response->assertOk()
->assertSee('Qualified lead')
->assertSee('Full legal name')
+ ->assertSee('preview_url')
->assertSee('version');
$updated = $created['draft']->refresh();
diff --git a/plugins/opnform/skills/opnform/SKILL.md b/plugins/opnform/skills/opnform/SKILL.md
index 44effd756..bc742a64e 100644
--- a/plugins/opnform/skills/opnform/SKILL.md
+++ b/plugins/opnform/skills/opnform/SKILL.md
@@ -24,10 +24,10 @@ This is the default workflow for new-form requests, including when the user does
1. Read `opnform://schemas/agent-form-definition/v1` and `opnform://reference/form-fields/v1` before generating a definition. Follow the field reference's `authoring_guidelines`. Re-read the field reference before changing presentation style, fields, layout, or media later in the conversation. Do not inspect the OpnForm source tree or guess product behavior when the MCP resources describe it.
2. Perform the respondent-facing quality pass below, then call `validate_form_definition`. Resolve every validation error. Treat `quality_warnings` as non-blocking editorial guidance: correct relevant warnings before creating or saving while preserving intentional user choices.
-3. Call `create_form_draft` with the validated definition.
+3. Call `create_form_draft` with the validated definition. Its result renders the interactive MCP preview automatically; present that preview even when the user did not ask to see one, and do not finish a create turn with text alone.
4. Keep the returned `draft_handle` in tool context and pass it unchanged to guest draft tools. It is an internal opaque reference, not user-facing form content: do not quote it to the user, write it to a file, log it, or send it to another service.
-5. Call `preview_form_draft` and present its interactive MCP preview when the host supports it. This is a read-only step and must not create an editor link.
-6. Apply requested changes with `patch_form_draft`, passing the latest `expected_version`. Validate the changed definition before persistence when needed.
+5. Use `preview_form_draft` to show or re-render an existing draft when no create or patch is being performed. This is a read-only step and must not create an editor link.
+6. 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.