@typeroll/mcp-server 0.7.4 → 0.7.7

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`).

package/skills/tr-seo.md

@@ -0,0 +1,179 @@
+---
+name: tr-seo
+description: Use when the user asks to improve SEO, fix meta tags, add structured data, check page titles, or audit the site's search visibility. Triggers on "SEO", "meta descriptions", "Google ranking", "structured data", "JSON-LD", "sitemap", "sökoptimering", or "hjälp mig synas på Google".
+---
+
+# SEO audit and improvements for a Typeroll site
+
+## What Typeroll handles automatically
+
+- `<html lang>` from site `language` setting (per-page override via `language` field)
+- `<title>` = `page.seo_title || page.title + settings.default_seo_suffix`
+- `<meta name="description">` from `page.seo_description`
+- `<meta name="robots">` from `page.noindex`
+- `<meta property="og:*">` Open Graph tags from seo_title, seo_description, og_image
+- `<link rel="canonical">` from `page.canonical_url` (falls back to the page's own URL)
+- Article schema from `kind: "article"` + `author` + `date_published`
+- Page schema from `kind: "page"` (default)
+- `robots.txt` from `settings.robots_txt`
+- Sanitized HTML that preserves semantic structure
+
+## Recipe
+
+### 1. Audit current state
+
+```
+list_pages status="all"
+read_site_settings
+```
+
+For each page, check:
+- Is `seo_title` set? (if not, Google uses `title` + suffix — often fine)
+- Is `seo_description` set? (150–160 chars, unique per page, includes keywords)
+- Is `og_image` set for the homepage and key landing pages?
+- Does the page have exactly one `<h1>`?
+
+### 2. Fix missing meta descriptions
+
+```
+batch_update_pages updates=[
+  {page_id: "home",     patch: {seo_description: "Acme designar rum..."}},
+  {page_id: "om-oss",   patch: {seo_description: "Vi är ett..."}},
+  {page_id: "tjanster", patch: {seo_description: "Våra tjänster..."}}
+]
+```
+
+Guidelines:
+- 150–160 characters
+- Include the most important keyword naturally
+- Make it a compelling reason to click, not a summary of the page's nav
+
+### 3. Fix page titles
+
+SEO title = what Google shows in search results.
+
+If `settings.default_seo_suffix` is set (e.g. " — Acme Studio"), every
+page whose `seo_title` is empty will show `title + suffix`. That's usually
+fine for inner pages; set an explicit `seo_title` only when you want
+something different.
+
+```
+update_site_settings {"default_seo_suffix": " — Acme Studio"}
+
+update_page page_id="home" patch={
+  "seo_title": "Acme Studio — Inredningsdesign i Stockholm"
+}
+```
+
+### 4. Add Open Graph images
+
+Set `og_image` on pages that get shared on social media. If the site has
+a branded hero image, upload it:
+
+```
+upload_media_from_url url="https://..." alt="Acme Studio — Inredningsdesign"
+# → returns cdn_url
+
+batch_update_pages updates=[
+  {page_id: "home",     patch: {og_image: "<cdn_url>"}},
+  {page_id: "om-oss",   patch: {og_image: "<cdn_url>"}}
+]
+```
+
+OG image dimensions: 1200×630px ideal. The platform doesn't resize —
+use a correctly-sized source image.
+
+### 5. Add structured data (JSON-LD)
+
+Typeroll auto-generates Article and Page schema, but you can override or
+extend with custom JSON-LD per page. Example: LocalBusiness on the homepage.
+
+```
+update_page page_id="home" patch={
+  "json_ld": "{\"@context\":\"https://schema.org\",\"@type\":\"LocalBusiness\",\"name\":\"Acme Studio\",\"url\":\"https://acme.se\",\"telephone\":\"+46812345\",\"address\":{\"@type\":\"PostalAddress\",\"streetAddress\":\"Drottninggatan 1\",\"addressLocality\":\"Stockholm\",\"postalCode\":\"111 51\",\"addressCountry\":\"SE\"}}"
+}
+```
+
+**Important:** JSON-LD goes in the `json_ld` field as a JSON *string*
+(not a nested object). The renderer injects it inside
+`<script type="application/ld+json">`.
+
+Common schemas worth adding:
+- Homepage: `LocalBusiness` or `Organization`
+- About: `AboutPage`
+- Contact: `ContactPage`
+- Blog articles: auto-generated from `kind:"article"` + `author`
+- Events: `Event` with `startDate`, `location`
+- Products: `Product` with `offers`
+
+### 6. robots.txt
+
+The default robots.txt allows all crawlers. Update if needed:
+
+```
+update_site_settings {
+  "robots_txt": "User-agent: *\nAllow: /\nSitemap: https://acme.se/sitemap.xml"
+}
+```
+
+Typeroll doesn't generate a sitemap automatically in phase 1. If the
+customer needs one, create a `/sitemap` page with HTML that lists all
+published pages, or write a static `sitemap.xml` as a page with
+`slug: "sitemap.xml"` and HTML-encoded XML (not recommended for large sites).
+
+### 7. Canonical URLs
+
+Set `canonical_url` when a page has a duplicate (e.g. the same content
+accessible via two slugs after a migration):
+
+```
+update_page page_id="tjansterna" patch={
+  "canonical_url": "https://acme.se/tjanster",
+  "noindex": true
+}
+```
+
+### 8. Language settings
+
+```
+update_site_settings {"language": "sv"}
+```
+
+Per-page override for multilingual content:
+```
+update_page page_id="about-en" patch={"language": "en"}
+```
+
+### 9. Heading audit
+
+Use `search_pages` to find structural problems:
+
+```
+search_pages contains="<h1"      # pages that have at least one H1
+```
+
+Then `read_page` on pages that seem to have none or multiple. Fix via
+`update_page patch={html_content: "<corrected HTML>"}`.
+
+### 10. Deploy
+
+```
+trigger_deploy
+get_deploy_status job_id=<id>
+```
+
+## Pitfalls
+
+- **Don't stuff keywords.** Write descriptions for humans. Google ignores
+  `<meta name="keywords">` (not a field in Typeroll anyway).
+- **JSON-LD is a string, not a nested field.** Pass the entire schema as
+  a JSON-encoded string in `json_ld`. The server escapes `</script` before
+  injection.
+- **OG images need absolute URLs.** The `cdn.typeroll.com` URLs are always
+  absolute — use those.
+- **`canonical_url` + `noindex` together.** If you noindex a page AND set
+  canonical, the canonical is redundant (noindexed pages don't pass equity).
+  Use one or the other.
+- **Default suffix on homepage looks odd.** "Acme Studio — Acme Studio"
+  happens when title="Acme Studio" and suffix=" — Acme Studio". Set an
+  explicit `seo_title` for the homepage.