@typeroll/mcp-server 0.7.5 → 0.7.7

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.

package/skills/tr-new-site.md

@@ -0,0 +1,198 @@
+---
+name: tr-new-site
+description: Use when the user wants to create a new Typeroll site from scratch, set up the initial design, or bootstrap a blank site with working header/footer, brand colors, and a homepage. Also triggers on "start a new site", "set up a site for", or "build a website for [company]".
+---
+
+# Bootstrap a new Typeroll site
+
+Start here when the site already exists as a database record (created via
+the portal UI or API) but has no design, no header/footer, and no pages.
+The goal is to go from blank to a working 4-page site with correct brand
+identity in a single session.
+
+## Preconditions
+
+- `@typeroll/mcp-server` configured with a valid `TYPEROLL_API_KEY`.
+- The site exists (confirm with `get_site`).
+- You have the customer brief: company name, industry, 2–3 key brand colors,
+  tone of voice (formal / friendly / minimal / vibrant), and a list of
+  initial pages.
+
+## Recipe
+
+### 1. Audit current state
+
+```
+get_site
+read_site_settings      # see what (if anything) is already configured
+list_pages              # don't overwrite pages that already exist
+list_partials           # check if header/footer already have content
+```
+
+### 2. Brand + settings
+
+One `update_site_settings` call with every field you know:
+
+```json
+{
+  "site_name": "Acme Studio",
+  "tagline": "Short, punchy tagline",
+  "language": "sv",
+  "colors": {
+    "primary":    "#1a1a2e",
+    "secondary":  "#16213e",
+    "accent":     "#e94560",
+    "background": "#f5f5f5",
+    "surface":    "#ffffff",
+    "text":       "#1a1a2e",
+    "text_light": "#6b7280"
+  },
+  "fonts": {
+    "heading": "Playfair Display",
+    "body":    "Inter",
+    "size_base": 16
+  },
+  "contact": {
+    "email": "hej@acme.se",
+    "phone": "+46 8 123 456",
+    "address": "Drottninggatan 1, 111 51 Stockholm"
+  },
+  "social": {
+    "instagram": "https://instagram.com/acme",
+    "linkedin":  "https://linkedin.com/company/acme"
+  }
+}
+```
+
+Read it back: `read_site_settings` — confirm `updated_fields` includes
+everything you intended.
+
+Google Fonts names: use the full display name as it appears on
+fonts.google.com, e.g. "Cormorant Garamond", "DM Sans", "Plus Jakarta Sans".
+
+### 3. Header partial
+
+Replace the header with a real nav. Keep it simple:
+
+```html
+<header class="site-header">
+  <div class="header-inner">
+    <a class="header-logo" href="/">Acme Studio</a>
+    <nav class="header-nav">
+      <a href="/om-oss">Om oss</a>
+      <a href="/tjanster">Tjänster</a>
+      <a href="/kontakt">Kontakt</a>
+    </nav>
+  </div>
+</header>
+<style>
+.site-header{background:var(--color-primary);padding:1rem 2rem}
+.header-inner{max-width:1080px;margin:0 auto;display:flex;align-items:center;justify-content:space-between}
+.header-logo{color:#fff;text-decoration:none;font-family:var(--font-heading);font-size:1.25rem;font-weight:700}
+.header-nav{display:flex;gap:2rem}
+.header-nav a{color:rgba(255,255,255,0.85);text-decoration:none;font-size:0.9rem;letter-spacing:0.05em;text-transform:uppercase}
+.header-nav a:hover{color:#fff}
+</style>
+```
+
+Use `replace_partial partial_id="header" html_content="..."`.
+
+### 4. Footer partial
+
+```html
+<footer class="site-footer">
+  <div class="footer-inner">
+    <p class="footer-brand">Acme Studio</p>
+    <p class="footer-tagline">Tagline here</p>
+    <div class="footer-links">
+      <a href="/om-oss">Om oss</a>
+      <a href="/kontakt">Kontakt</a>
+    </div>
+    <p class="footer-copy">© 2025 Acme Studio. Alla rättigheter förbehållna.</p>
+  </div>
+</footer>
+<style>
+.site-footer{background:var(--color-secondary);color:rgba(255,255,255,0.7);padding:3rem 2rem;margin-top:4rem}
+.footer-inner{max-width:1080px;margin:0 auto;text-align:center;display:grid;gap:1rem}
+.footer-brand{font-family:var(--font-heading);font-size:1.5rem;color:#fff;font-weight:700}
+.footer-links{display:flex;justify-content:center;gap:2rem}
+.footer-links a{color:rgba(255,255,255,0.7);text-decoration:none}
+.footer-links a:hover{color:#fff}
+.footer-copy{font-size:0.8rem;opacity:0.5}
+</style>
+```
+
+Use `replace_partial partial_id="footer" html_content="..."`.
+
+### 5. Homepage
+
+```
+create_page title="Start" slug="" content_mode="html"
+            html_content="<full hero + intro HTML>"
+            status="published"
+```
+
+`slug=""` creates the homepage under `page_id: "home"`. If it already
+exists, use `update_page page_id="home" patch={html_content: "..."}`.
+
+A minimal homepage structure:
+- Hero: full-width section with `<h1>`, tagline, one CTA button
+- Intro: 2–3 sentences about what the company does
+- Services/features grid: 3 cards max
+- CTA band: "Kontakta oss" or similar
+
+### 6. Inner pages
+
+Create each page:
+```
+create_page title="Om oss" slug="om-oss" content_mode="html"
+            html_content="..." status="published"
+```
+
+Standard set: Om oss, Tjänster, Kontakt. Add more if the brief says so.
+
+### 7. Preview + iterate
+
+```
+get_preview_link        # get a signed URL for the whole site
+get_page_preview page_id="home"   # get rendered HTML to spot-check
+```
+
+Share the preview link with the user. Iterate on feedback.
+
+### 8. Deploy
+
+When the user approves:
+```
+trigger_deploy
+get_deploy_status job_id=<id>    # poll until status=succeeded
+```
+
+## Design conventions
+
+- **One `<h1>` per page.** SEO and screen reader requirement.
+- **CSS variables for colors.** Always use `var(--color-primary)` etc. in
+  partial `<style>` blocks — never hardcode hex values.
+- **Responsive layout.** Use `max-width` on containers, `display:flex`
+  or `display:grid` for layouts, and `clamp()` for fluid type.
+- **Scoped styles.** Put `<style>` at the bottom of partial HTML.
+  Styles apply to the whole page; prefix class names with the partial ID
+  to avoid collisions (`site-header__*`, `site-footer__*`).
+- **Minimal JS.** The platform doesn't bundle JS. If you need interactions,
+  write a small `<script>` inside the partial or page; keep it under 50
+  lines. Avoid external CDN dependencies in page bodies.
+
+## Pitfalls
+
+- **Don't create pages that already exist.** Run `list_pages` first;
+  if the slug is taken, use `update_page` instead of `create_page`.
+- **Don't hardcode text from settings into partials.** If `site_name`
+  is "Acme", the header partial should have literal "Acme" in it —
+  there's no template engine. When the name changes the user updates
+  the partial.
+- **Google Fonts names are case-sensitive.** "Playfair Display" works;
+  "playfair display" or "Playfair-Display" do not.
+- **Empty `custom_css` field.** If you set `custom_css: ""` it's
+  stored as an empty string, not removed. Use it only when you have
+  global styles that span both partials and pages (e.g. utility classes,
+  `@keyframes`, `:root` overrides for things not in `colors`/`fonts`).