feat(mcp): enhance instructions with post content format rules

[dpaulos6]

Description

This PR updates the MCP server instructions for Marble post workflows to make the post content format rules clearer and safer for agents.

The main change is clarifying that read tools may return post content as Markdown for convenience, but mutating post tools such as create_post and update_post must always receive clean HTML in the content field.

It also adds explicit examples of invalid Markdown write content and valid HTML write content, plus a safer read/edit/write workflow for agents.

Motivation and Context

The previous instructions could be confusing for agents because post content may be read as Markdown, while post creation and updates require HTML.

This read/write mismatch can cause agents to mistakenly round-trip Markdown back into create_post or update_post, resulting in malformed post content or overwritten editor output.

This change makes the expected behavior explicit:

• Markdown may be used for read convenience only.
• Post writes must use clean semantic HTML.
• Agents should convert Markdown to HTML before mutating posts.
• Agents should preserve unrelated metadata when editing existing posts.

How to Test

1. Start the MCP server locally.
2. Inspect the generated server instructions.
3. Confirm there is a clear “Critical post content format rule” section.
4. Confirm get_posts, search_posts, and get_post are described as read tools where Markdown may be returned for convenience.
5. Confirm create_post and update_post are described as write tools that require clean HTML in the content field.
6. Ask an agent to edit a post that was read as Markdown.
7. Verify the agent converts the final body to HTML before calling update_post.
8. Verify the instructions include examples of bad Markdown write content and good HTML write content.

Screenshots (if applicable)

N/A

Video Demo (if applicable)

N/A

Types of Changes

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• ⚠️ Breaking change (fix or feature that alters existing functionality)
• 🎨 UI/UX Improvements
• ⚡ Performance Enhancement
• 📖 Documentation (updates to README, docs, or comments)

Summary by CodeRabbit

• Documentation
  • Strengthened post content rules: create/update must use clean semantic HTML (no Markdown), and agents must convert incoming Markdown to HTML before saving.
  • Clarified read vs. write behavior for tools, stricter allowed attributes/styles, and explicit media/embed formatting rules (images, figures, YouTube, Twitter).
  • Improved guidance for authentication, permission failures, destructive-action confirmation, and preserving unrelated fields during edits.

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	marble-mcp	da8ed1f	Commit Preview URL Branch Preview URL	Jun 03 2026, 10:28 AM

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
marble-web	Ready	Preview, Comment	Jun 3, 2026 10:28am

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
marble-app	Skipped		Jun 3, 2026 10:28am

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 2 committers have signed the CLA.

✅ dpaulos6
❌ Copilot
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 9f2c115d-9f47-46a1-ad6a-d86bb0ebf1c8

📥 Commits

Reviewing files that changed from the base of the PR and between ca2f35b and da8ed1f.

📒 Files selected for processing (1)

• apps/mcp/src/lib/instructions.ts

---

Walkthrough

Updated server instructions in MCP to require HTML-only content for post mutations, clarified auth and destructive-action workflows, distinguished read vs write tool behavior, tightened allowed attributes and inline styles, standardized media/embed formats, and turned disallowed markup into an explicit checklist.

Changes

MCP Post Handling Guidance Clarification

Layer / File(s)	Summary
Main instruction text: HTML-only writes, auth, and edit workflow apps/mcp/src/lib/instructions.ts	Replaced and expanded primary instruction blocks to require HTML-only content for create/update operations (explicitly forbidding Markdown in writes), clarified authentication/permission handling and destructive-action confirmation, and added a fetch-and-preserve step for large edits.
Allowed inline styles restatement apps/mcp/src/lib/instructions.ts	Reiterated the limited allowed inline-style properties (color, background-color, text-decoration) and stated other style declarations may be removed.
Figures/media/embeds and disallowed markup checklist apps/mcp/src/lib/instructions.ts	Reorganized figures/media/embed rules (including data-align/data-width, YouTube wrapper format, X/Twitter markers) and reworked disallowed/unsafe markup into a clear checklist prohibiting scripts, event handlers, javascript: URLs, non-YouTube iframes, unsupported attributes, and raw Markdown in write content.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 I nibble rules in tidy rows tonight,
No Markdown in writes — only HTML bright.
Media wrapped neatly, attributes slim and clear,
Permission prompts and preserves appear.
A rabbit hops, proofreading every line with delight.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main change: enhancing MCP instructions with post content format rules, which directly matches the core objective of clarifying read/write behavior and HTML requirements.
Description check	✅ Passed	The description is comprehensive and follows the template structure with all major sections completed: clear problem statement, motivation addressing the read/write mismatch issue, detailed testing instructions, and properly marked change types.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch dpaulos6-patch-1

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

This PR updates the Marble MCP server’s agent-facing instructions to prevent agents from round-tripping Markdown into post mutation tools by clearly separating read-format convenience (Markdown) from write-format requirements (clean semantic HTML).

Changes:

• Added a “Critical post content format rule” clarifying that create_post / update_post must always receive clean HTML in content, even if read tools returned Markdown.
• Added a safer read/edit/write workflow and concrete “bad Markdown write” vs “good HTML write” examples.
• Reorganized and clarified HTML sanitization guidance (allowed tags/URLs/attributes/styles and disallowed markup).

[dpaulos6]

@copilot can you fix the formatting issue related to the form?

packages/editor/src/components/marks/editor-link-selector.tsx:144:9 lint/a11y/noNoninteractiveElementInteractions 

  ✖ Non-interactive element should not have event handler.
  
    142 │       />
    143 │       <PopoverContent align="start" className="w-fit p-0" sideOffset={10}>
  > 144 │         <form
        │         ^^^^^
  > 145 │           className="flex items-center gap-0.5 p-1"
         ...
  > 151 │           onSubmit={handleSubmit}
  > 152 │         >
        │         ^
    153 │           <input
    154 │             aria-label="Link URL"
  
  ℹ Consider replace semantically interactive element like <button/> or <a href/>.

[taqh]

LGTM