@typeroll/mcp-server 0.7.5 → 0.7.8

package/skills/tr-forms.md

@@ -0,0 +1,243 @@
+---
+name: tr-forms
+description: Use when the user wants to add a contact form, booking form, or any web form to their Typeroll site. Triggers on "lägg till formulär", "contact form", "add a form", "let visitors message us", "booking form", "formulär", or similar. Covers both creating the form definition and embedding the HTML widget on a page.
+---
+
+# Add a form to a Typeroll site
+
+Typeroll forms are server-backed: submissions go to
+`/api/forms/submit` (HMAC-signed, rate-limited, honeypot-protected)
+and are stored in Firestore. The user sees them in the portal's
+Submissions inbox. No third-party service needed.
+
+## Preconditions
+
+- Site exists and MCP is configured.
+- You know what fields the form needs.
+
+## Recipe
+
+### 1. Create the form definition
+
+```
+create_form {
+  "id": "kontakt",
+  "name": "Kontaktformulär",
+  "fields": [
+    {"name":"name",    "label":"Namn",          "type":"text",     "required":true},
+    {"name":"email",   "label":"E-post",         "type":"email",    "required":true},
+    {"name":"phone",   "label":"Telefon",        "type":"text"},
+    {"name":"message", "label":"Meddelande",     "type":"textarea", "required":true},
+    {"name":"subject", "label":"Ämne",           "type":"select",
+     "options":["Prisförfrågan","Samarbete","Övrigt"]}
+  ],
+  "success_message": "Tack! Vi återkommer inom 24 timmar.",
+  "recipient_email": "hej@acme.se"
+}
+```
+
+**Field types:** `text`, `email`, `tel`, `url`, `number`, `textarea`,
+`select`, `radio`, `checkbox`.
+
+**Field name rules:** Lowercase ASCII only: `[a-z][a-z0-9_-]*`.
+- `besokt` not `besökt` (`ö→o`)
+- `foretag` not `företag` (`ö→o`, `ä→a`)
+- `meddelande` not `Meddelande` (the `name` must be lowercase; `label` can be anything)
+
+### 2. Get the signed embed token
+
+The form's submit button needs a signed token that proves it was
+generated by the platform. Fetch it:
+
+```
+read_form form_id="kontakt"
+```
+
+The response includes `submit_token` (a short-lived HMAC). Use this in
+the HTML.
+
+Actually, the embed HTML is best generated by reading the form and
+building it manually — the form's `id` is all you need for the action URL.
+
+### 3. Embed the form on a page
+
+Typeroll forms submit to the platform's endpoint. The HTML:
+
+```html
+<section class="contact-section">
+  <div class="contact-container">
+    <h2>Kontakta oss</h2>
+    <p>Fyll i formuläret så återkommer vi inom 24 timmar.</p>
+
+    <form class="contact-form"
+          action="https://app.typeroll.com/api/forms/submit"
+          method="POST">
+      <!-- Hidden fields — required by the platform -->
+      <input type="hidden" name="_form_id"  value="kontakt">
+      <input type="hidden" name="_site_id"  value="YOUR_SITE_ID">
+      <input type="hidden" name="_token"    value="SIGNED_TOKEN">
+      <!-- Honeypot — must stay empty, bots fill it -->
+      <input type="text"   name="_hp"       style="display:none" tabindex="-1" autocomplete="off">
+
+      <div class="form-group">
+        <label for="name">Namn *</label>
+        <input type="text" id="name" name="name" required>
+      </div>
+
+      <div class="form-group">
+        <label for="email">E-post *</label>
+        <input type="email" id="email" name="email" required>
+      </div>
+
+      <div class="form-group">
+        <label for="message">Meddelande *</label>
+        <textarea id="message" name="message" rows="5" required></textarea>
+      </div>
+
+      <div class="form-group">
+        <label for="subject">Ämne</label>
+        <select id="subject" name="subject">
+          <option value="Prisförfrågan">Prisförfrågan</option>
+          <option value="Samarbete">Samarbete</option>
+          <option value="Övrigt">Övrigt</option>
+        </select>
+      </div>
+
+      <button type="submit" class="btn-primary">Skicka meddelande</button>
+    </form>
+  </div>
+</section>
+
+<style>
+.contact-section{padding:4rem 2rem}
+.contact-container{max-width:600px;margin:0 auto}
+.form-group{margin-bottom:1.5rem}
+.form-group label{display:block;font-weight:600;margin-bottom:0.4rem;font-size:0.9rem}
+.form-group input,.form-group textarea,.form-group select{
+  width:100%;padding:0.75rem 1rem;border:1px solid var(--color-surface);
+  border-radius:0.375rem;font-family:inherit;font-size:1rem;
+  background:var(--color-surface);color:var(--color-text)
+}
+.form-group textarea{resize:vertical}
+.btn-primary{
+  background:var(--color-primary);color:#fff;border:none;
+  padding:0.875rem 2rem;border-radius:0.375rem;font-size:1rem;
+  font-weight:600;cursor:pointer;width:100%
+}
+.btn-primary:hover{opacity:0.9}
+</style>
+```
+
+**Replace:**
+- `YOUR_SITE_ID` → the site's actual id (from `get_site`)
+- `SIGNED_TOKEN` → fetch via `read_form form_id="kontakt"` → `submit_token`
+
+### 4. Add success/error handling (optional JS)
+
+To show inline feedback without a page reload:
+
+```html
+<script>
+(function(){
+  const form = document.querySelector('.contact-form');
+  if(!form) return;
+  form.addEventListener('submit', async(e) => {
+    e.preventDefault();
+    const btn = form.querySelector('[type=submit]');
+    btn.disabled = true;
+    btn.textContent = 'Skickar…';
+    try {
+      const res = await fetch(form.action, {method:'POST', body: new FormData(form)});
+      const data = await res.json();
+      if(data.ok) {
+        form.innerHTML = '<p class="form-success">Tack! Vi återkommer inom 24 timmar.</p>';
+      } else {
+        btn.disabled = false;
+        btn.textContent = 'Skicka meddelande';
+        alert('Något gick fel: ' + (data.error || 'okänt fel'));
+      }
+    } catch {
+      btn.disabled = false;
+      btn.textContent = 'Skicka meddelande';
+      alert('Nätverksfel — försök igen.');
+    }
+  });
+})();
+</script>
+```
+
+### 5. Update the contact page with the form HTML
+
+```
+update_page page_id="kontakt" patch={
+  "html_content": "<full page HTML including the form section>"
+}
+```
+
+### 6. Verify
+
+```
+read_form form_id="kontakt"
+list_forms
+```
+
+Confirm the form appears and fields match what you embedded.
+
+### 7. Deploy
+
+```
+trigger_deploy
+get_deploy_status job_id=<id>
+```
+
+After deploy, test by submitting the live form. Submissions appear in the
+portal at `/app/sites/{siteId}/forms/kontakt/submissions`.
+
+## Common form patterns
+
+### Booking / appointment request
+```json
+{"fields": [
+  {"name":"name",  "type":"text",  "label":"Namn",   "required":true},
+  {"name":"email", "type":"email", "label":"E-post",  "required":true},
+  {"name":"date",  "type":"text",  "label":"Önskat datum (YYYY-MM-DD)"},
+  {"name":"time",  "type":"select","label":"Tid",    "options":["09:00","10:00","11:00","14:00","15:00"]},
+  {"name":"notes", "type":"textarea","label":"Kommentar"}
+]}
+```
+
+### Newsletter signup (minimal)
+```json
+{"fields": [
+  {"name":"email", "type":"email", "label":"E-postadress", "required":true}
+]}
+```
+
+### Job application
+```json
+{"fields": [
+  {"name":"name",       "type":"text",  "label":"Namn",      "required":true},
+  {"name":"email",      "type":"email", "label":"E-post",     "required":true},
+  {"name":"role",       "type":"select","label":"Roll",       "options":["Designer","Projektledare","Övrigt"]},
+  {"name":"experience", "type":"textarea","label":"Berätta om dig själv"},
+  {"name":"portfolio",  "type":"url",   "label":"Portfolio-URL"}
+]}
+```
+
+## Pitfalls
+
+- **Tokens expire.** The `submit_token` in the form embed is short-lived
+  (24h by default). For forms on long-cached static pages, fetch a fresh
+  token via `read_form` and rebuild the page HTML, then redeploy.
+  Alternatively, fetch the token client-side via a small `<script>` that
+  calls the portal's token endpoint before submit.
+- **Field names must be ASCII.** `message` not `meddelande`... wait,
+  `meddelande` is ASCII. `foretag` not `företag`. Only Swedish/Nordic
+  special characters (å, ä, ö) cause problems.
+- **Don't use the same form_id on two different forms.** IDs must be
+  unique per site — use descriptive names: `kontakt`, `boka`, `nyhetsbrev`.
+- **Honeypot must be invisible.** `_hp` field must have `display:none`.
+  If it's visible and a real user fills it, their submission is rejected.
+- **Recipient email is display-only in phase 1.** The portal stores
+  submissions; email delivery to `recipient_email` depends on the platform's
+  email configuration. Confirm with the customer that they'll check the inbox.

package/skills/tr-import-url.md

@@ -0,0 +1,173 @@
+---
+name: tr-import-url
+description: Use when the user wants to import or migrate content from a non-WordPress website — a Squarespace site, a Wix site, a static HTML site, a Webflow export, or any URL the user points at. Also triggers on "copy content from", "rebuild this site", "import from Squarespace/Wix/Webflow", or "make it look like this site". For WordPress sources use tr-migrate-wp instead.
+---
+
+# Import content from a non-WordPress site
+
+## When to use this vs tr-migrate-wp
+
+| Source | Use |
+|---|---|
+| WordPress with `/wp-json` accessible | `tr-migrate-wp` |
+| WordPress with REST disabled | This skill (scrape HTML) |
+| Squarespace, Wix, Webflow, static HTML | This skill |
+| CSV / spreadsheet data | This skill (skip scraping, just parse) |
+| Any URL the user points at | This skill |
+
+## Preconditions
+
+- Target Typeroll site exists with working header/footer.
+- Source URL(s) accessible (check with a quick `fetch`; if blocked, mention
+  it and ask the user for an HTML export or screenshot).
+
+## Recipe
+
+### 1. Inventory the source site
+
+Fetch the homepage and build a URL list:
+
+```
+fetch <source-url>                    # root HTML
+fetch <source-url>/sitemap.xml        # XML sitemap if it exists
+```
+
+Parse `<a href>` links to discover internal pages. Build a list:
+- Homepage
+- Top-level pages (About, Services, Contact, etc.)
+- Any sub-pages that look important
+
+Avoid: pagination URLs, session URLs, `/wp-admin`, `/cdn-cgi/`, query strings.
+
+### 2. Learn the target's design
+
+```
+read_site_settings
+read_partial partial_id="header"
+list_pages limit=5
+```
+
+The goal is to understand what CSS variables, class names, and structural
+conventions the target site uses so the imported content looks native.
+
+### 3. Fetch and clean each source page
+
+For each URL:
+
+**a. Fetch the HTML.**
+```
+fetch <page-url>
+```
+
+If the site returns a bot-block (Cloudflare, 403, or clearly JS-only
+SPA output), note it. Tell the user: "This page blocked direct fetching.
+Can you provide the page source or an HTML export?"
+
+**b. Extract the main content.** 
+
+Discard: nav, header, footer, cookie banners, chat widgets, scripts.
+Keep: `<main>`, `<article>`, the largest content region.
+
+Clean the HTML:
+- Strip platform-specific classes: `sqsrte-*`, `wf-*`, `et_*`,
+  `elementor-*`, `fl-*`, `divi-*`, `vc_*`
+- Remove empty `<div>`, `<span>`, `<section>` wrappers (no class, no content)
+- Unwrap redundant nesting: `<div><p>text</p></div>` → `<p>text</p>`
+- Keep: `<h1>`–`<h6>`, `<p>`, `<ul>`, `<ol>`, `<img>`, `<a>`, `<table>`,
+  `<blockquote>`, `<figure>`, `<figcaption>`, `<strong>`, `<em>`
+- Fix headings: ensure exactly one `<h1>` per page (the page title)
+
+**c. Transfer images.** For each `<img src>`:
+```
+upload_media_from_url url="<source-img-url>" alt="..."
+```
+Replace the src with the returned CDN URL. Skip tracking pixels
+(1×1 images), decorative SVGs that are just icons, and anything
+that 404s.
+
+**d. Adapt to the target's design.**
+Replace source-specific CSS classes with target conventions.
+Use `var(--color-*)` for colors, `var(--font-*)` for type.
+
+### 4. Create pages as drafts
+
+```
+create_page title="Om oss" slug="om-oss"
+            html_content="<cleaned, adapted HTML>"
+            content_mode="html" status="draft"
+            seo_title="Om oss — Acme"
+            seo_description="..."
+```
+
+Always draft first. The user signs off before publishing.
+
+### 5. Handle redirects
+
+If the source URLs differ from the target slugs, create redirects:
+
+```
+create_redirect from_path="/about" to_path="/om-oss"
+create_redirect from_path="/services.html" to_path="/tjanster"
+```
+
+### 6. Preview with the user
+
+```
+get_preview_link
+```
+
+Walk through every imported page with the user. Common issues:
+- Heading hierarchy wrong (two H1s, or H3 used where H2 belongs)
+- Images missing alt text
+- Squarespace column layouts that don't work without their grid system
+- Embedded forms or maps that need re-setup
+
+### 7. Publish + deploy
+
+After approval:
+```
+batch_update_pages updates=[
+  {page_id: "om-oss",  patch: {status: "published"}},
+  {page_id: "tjanster", patch: {status: "published"}}
+]
+trigger_deploy
+get_deploy_status job_id=<id>
+```
+
+## Platform-specific notes
+
+### Squarespace
+- Main content is inside `.content-wrapper` or `[data-section-theme]` blocks
+- Portfolio images are usually high-resolution originals in `/universal/images/`
+- JSON-LD is Squarespace's own schema — strip it
+- Gallery blocks → convert to CSS grid with inline `<img>` tags
+
+### Wix
+- Wix sites are React SPAs — `fetch` returns an empty shell
+- Ask the user for the Wix site's "Export to HTML" (available in some plans)
+  or take screenshots for reference
+- Best path: get content from the user (text + image files), rebuild clean
+
+### Webflow
+- Usually fetchable; clean output
+- Classes like `w-container`, `w-row`, `w-col-*` can be stripped
+- Webflow CMS items are server-rendered — they appear in the HTML
+
+### Static HTML / old sites
+- Often the cleanest import. Fetch, strip nav/footer, keep body.
+- Watch for table-based layouts (pre-2010 sites) — convert to CSS grid
+
+## Pitfalls
+
+- **Don't import `<style>` blocks from the source site.** They reference
+  external fonts, resets, and classes that don't exist in the target.
+  Strip all `<style>` tags from source HTML and rewrite styles in the
+  target's conventions.
+- **Don't break the single-H1 rule.** Many source sites have no H1 or
+  several. Fix it.
+- **Squarespace/Wix forms.** They won't work after import — the backend
+  is vendor-locked. Create a Typeroll form instead: `create_form`.
+- **Analytics/tracking code.** If the source has GA4 or similar, don't
+  copy it into pages. Set it via `update_site_settings scripts_head="..."`.
+- **Videos.** YouTube/Vimeo embeds are fine (`<iframe>` is allowed).
+  Hosted MP4s need re-uploading if the source URL won't persist.