@typeroll/mcp-server 0.7.4 → 0.7.7

package/skills/tr-brand.md

@@ -0,0 +1,169 @@
+---
+name: tr-brand
+description: Use when the user asks to create a brand identity, design system, or visual style for a site. Triggers on "create a brand", "design the look", "choose colors", "pick fonts", "make it look like [reference]", or "rebrand the site". Produces a cohesive palette, typography scale, and CSS custom properties applied to an existing site.
+---
+
+# Design a brand identity for a Typeroll site
+
+This skill turns a brief (or a reference URL/screenshot) into a complete
+visual design system applied to the site's settings and partials.
+
+## Preconditions
+
+- Site exists and MCP is configured.
+- You have at least one of: industry, mood words, reference URL, existing
+  logo colors, or competitor sites to contrast with.
+
+## Step 1 — Gather context
+
+Ask (or infer from the brief):
+
+1. **Industry + audience.** Law firm → formal, trust. Café → warm, approachable.
+   Tech startup → clean, modern. Interior design → refined, editorial.
+2. **Mood words.** 3–5 adjectives the brand should feel: "minimal, Nordic,
+   calm" or "bold, energetic, playful".
+3. **Reference.** A URL, a screenshot, or a competitor they like (and what
+   they want to be different from it).
+4. **Must-keep.** Existing logo color? Legal industry color conventions?
+
+If the user provided a URL, fetch it and note the dominant colors,
+typeface categories, and layout density.
+
+## Step 2 — Build the palette
+
+A Typeroll site uses 7 color tokens:
+
+| Token | Role | Design rule |
+|---|---|---|
+| `primary` | Brand identity. CTA buttons, active nav, links. | High contrast on `background`. |
+| `secondary` | Header, footer, darker sections. | Darker or more neutral than primary. |
+| `accent` | Highlights, price tags, badges, hover states. | High-energy complement. |
+| `background` | Page background. | Near-white for light themes, near-black for dark. |
+| `surface` | Cards, input boxes, code blocks. | Slightly off from `background`. |
+| `text` | Body copy. | ≥4.5:1 contrast ratio on `background`. |
+| `text_light` | Secondary labels, captions, placeholders. | ≥3:1 on `background`. |
+
+**Palette recipes by mood:**
+
+*Nordic / minimal:*
+```
+primary: #1f2a30   secondary: #142027   accent: #c9b89a
+background: #faf8f4  surface: #f2ede5  text: #1f2a30  text_light: #7a7265
+```
+
+*Warm / artisan:*
+```
+primary: #3d2b1f   secondary: #2a1d14   accent: #c8860a
+background: #fdf6ee  surface: #f7ede0  text: #1a1008  text_light: #8a7060
+```
+
+*Modern / tech:*
+```
+primary: #2563eb   secondary: #1e293b   accent: #f59e0b
+background: #ffffff  surface: #f8fafc  text: #0f172a  text_light: #64748b
+```
+
+*Editorial / dark:*
+```
+primary: #e2c08d   secondary: #0f0f0f   accent: #e2c08d
+background: #0f0f0f  surface: #1a1a1a  text: #f5f5f0  text_light: #a0a090
+```
+
+Check WCAG contrast ratios mentally: text on background must be ≥4.5:1.
+The online tool `https://webaim.org/resources/contrastchecker/` is useful
+but not accessible during a tool call — reason about perceived contrast
+instead (light grey on white = bad; dark grey on white = fine).
+
+## Step 3 — Choose typefaces
+
+Pick from high-quality Google Fonts pairings:
+
+| Heading | Body | Mood |
+|---|---|---|
+| Cormorant Garamond | Raleway | Luxury, editorial |
+| Playfair Display | Source Sans 3 | Classic, readable |
+| DM Serif Display | DM Sans | Contemporary, clean |
+| Fraunces | Mulish | Artisan, craft |
+| Syne | Inter | Bold, modern |
+| Plus Jakarta Sans | Plus Jakarta Sans | Clean, versatile |
+| Libre Baskerville | Libre Franklin | Traditional, trustworthy |
+
+Same font for heading and body is fine if it has enough weight variation
+(Inter at 700 + 400 works well).
+
+`size_base` should be 16 for most sites; 17–18 for text-heavy editorial
+sites; 15 for dense dashboards.
+
+## Step 4 — Apply to the site
+
+One call sets everything:
+
+```
+update_site_settings {
+  "colors": { ...all 7 tokens },
+  "fonts":  { "heading": "...", "body": "...", "size_base": 16 },
+  "custom_css": "/* optional: utility classes or @keyframes */"
+}
+```
+
+Read back to confirm: `read_site_settings`.
+
+## Step 5 — Update partials to use the new palette
+
+Partials that hardcoded hex colors need updating. Fetch the header:
+
+```
+read_partial partial_id="header"
+```
+
+If it has hardcoded colors, replace them with CSS variable references
+(`var(--color-primary)`) and call `replace_partial`:
+
+```
+replace_partial partial_id="header" html_content="<updated HTML>"
+```
+
+Same for footer.
+
+## Step 6 — Custom CSS for advanced tokens (optional)
+
+If the brand needs things beyond the 7 base tokens — e.g. a gradient,
+a special border radius, or a branded highlight color — add them via
+`custom_css`:
+
+```css
+:root {
+  --brand-gradient: linear-gradient(135deg, var(--color-primary), var(--color-accent));
+  --radius-brand: 2px;                    /* sharp corners for formal brands */
+  --letter-spacing-display: -0.03em;     /* tight tracking for display headings */
+}
+```
+
+Then reference `var(--brand-gradient)` etc. in page HTML and partials.
+
+## Step 7 — Preview
+
+```
+get_preview_link
+```
+
+Open in browser. Check:
+- Colors render as intended (not "undefined" or missing)
+- Fonts load (Google Fonts link is in `<head>`)
+- Nav text is readable against header background
+- Body text has sufficient contrast
+
+## Pitfalls
+
+- **Don't set colors without checking the header contrast.** If `primary`
+  is light, white nav text becomes unreadable. Either darken `primary` or
+  make the header use `secondary`.
+- **Custom_css is global.** Rules here apply to every page. Keep it to
+  `:root {}` token additions and truly global utilities. Page-specific
+  styles go in the page's HTML `<style>` block.
+- **Google Fonts load time.** Two different font families is fine; three
+  adds measurable LCP impact. Stick to two families with variable-font
+  versions when possible.
+- **Dark themes need dark surface too.** Setting `background: #0f0f0f`
+  but leaving `surface: #f8fafc` (white) breaks every card/input. Always
+  update all 7 tokens as a set.

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.