nettsaga-mcp

MCP server for Nettsaga's web-dev workflow — boilerplate scaffolding, content + market crawling, build & QA workflows, stock-photo sourcing (Pexels + iStock via VPS proxy), favicon generation, palette extraction, and shared assets. Current release: v2.0.7.

Quick Setup

1. Get your credentials

You need two values from the Nettsaga VPS setup:

| Variable | Where to get it | |----------|-----------------| | NS_MCP_URL | VPS proxy URL (e.g. https://your-vps:3001) | | NS_MCP_API_KEY | Shared API key for the proxy |

All other secrets (Pexels API key, iStock credentials) live on the VPS — you don't need them locally.

2. Install the MCP server

Claude Code — PowerShell (Windows):

claude mcp add nettsaga -s user `
  -e NS_MCP_URL=your_vps_url `
  -e NS_MCP_API_KEY=your_api_key `
  -- npx nettsaga-mcp

Claude Code — Bash (macOS/Linux):

claude mcp add nettsaga -s user \
  -e NS_MCP_URL=your_vps_url \
  -e NS_MCP_API_KEY=your_api_key \
  -- npx nettsaga-mcp

OpenAI Codex CLI — add to ~/.codex/config.toml:

[mcp_servers.nettsaga]
command = "npx"
args = ["-y", "nettsaga-mcp"]
env = { NS_MCP_URL = "$NS_MCP_URL", NS_MCP_API_KEY = "$NS_MCP_API_KEY" }

Local install (developing the MCP itself):

# Claude Code
claude mcp add nettsaga -s user -- node /absolute/path/to/nettsaga-mcp/dist/index.js

# Codex — add to ~/.codex/config.toml
# [mcp_servers.nettsaga]
# command = "node"
# args = ["/absolute/path/to/nettsaga-mcp/dist/index.js"]

3. Restart Claude Code

Close and reopen Claude Code (or reload the window). All 34 tools register on next session.

Boilerplate vs Templates — two distinct subsystems

These are independent and serve different roles. Don't confuse them.

| | Boilerplate | Templates | |---|---|---| | Purpose | Scaffold the new client project | Reference patterns from past projects | | Action | COPIES files INTO a new client repo | READS source the AI studies before writing | | Library | resources/boilerplate-variants/ (3 pre-stripped variants ship with MCP) | ~/.nettsaga/templates/ (user-populated; nothing ships) | | Tools | scaffold_full, fill_site_config, apply_palette, extract_palette, wire_logo, generate_favicon, qa_scaffold, verify_cleanup | clone_template_repo, register_template, use_template, list_templates, delete_template | | Output | A runnable Next.js project | Component source the AI adapts into the project being built | | Lifecycle | Edit master → regenerate variants → copy on scaffold | User registers each past repo once via register_template → reuse forever |

Available Tools (34)

Boilerplate (8)

| Tool | Description | |------|-------------| | scaffold_full | One-call full scaffold. Copies the matching pre-stripped variant (no-spa / no-mpa / usa-mpa) AND writes lib/site-config.ts deterministically from structured client data. Also writes a .nettsaga-mcp/scaffold.json marker so qa_workflow knows to chain qa_scaffold before the pre-delivery audit. | | fill_site_config | Deterministically writes lib/site-config.ts from a structured JSON payload. Same shape as scaffold_full's client_data. | | apply_palette | Edits app/globals.css to replace specific design tokens in :root and/or .dark blocks. Brace-aware (preserves @theme inline, @layer base, --chart-*, --sidebar-*, --radius). Idempotent. | | extract_palette | Extract an OKLCH palette from a screenshot of the client's old website. Auto-detects light vs dark, maps dominant colors to CSS tokens, WCAG AA contrast checks. Pairs with apply_palette. | | wire_logo | Swaps the text wordmark in header.tsx for an <Image src="/logo.{ext}"> and merges the metadata.icons block into app/layout.tsx. Idempotent, JSX-aware. | | generate_favicon | Generate the full favicon set (favicon.svg, favicon.ico multi-res, PNG variants, apple-touch-icon.png) into public/. Two modes: source_image_path or initials + primary_color. | | qa_scaffold | Post-scaffolding QA — 5 parallel sub-agents (cleanup, content + SEO + assets, i18n branched on market, runtime/browser, accessibility WCAG AA). Only runs for projects generated by scaffold_full; errors out otherwise. Auto-chained by qa_workflow when the scaffold marker is detected. | | verify_cleanup | Deterministic file scan verifying the cleanup checklist passed. Single tree-walk over dual-mode patterns + trace patterns + forbidden files. |

Templates (5)

| Tool | Description | |------|-------------| | clone_template_repo | Step 1 — shallow-clones a past-project repo into ~/.nettsaga/templates/.staging/, walks components, returns inference signals (country code, currency, services, etc.). | | register_template | Step 2 — moves staged components into ~/.nettsaga/templates/{country}/{category}/{project}/, strips client noise to {{PLACEHOLDER}} tokens, updates index.json. | | use_template | Smart-match read. Given market + section, scores the user's library and returns the top component-source matches for the AI to study before writing. | | list_templates | Browse the user's registered template library, optionally filtered by country / category / section. | | delete_template | Remove a registered template (drops index entry + on-disk dir). |

Templates location resolution: NETTSAGA_USER_TEMPLATES_DIR env var → ~/.nettsaga/templates/. The library never ships with the MCP.

Workflows (2)

| Tool | Description | |------|-------------| | build_workflow | Full build checklist + design guidelines + 5-batch sub-agent pipeline. Call before starting any website build. Includes the Services Pre-flight Gate (crawl old site → confirm service count → architecture decision). | | qa_workflow | Default QA tool. Stack-aware pre-delivery checklist (5 parallel agents, including Regional Image Audit). When called on a scaffolded project (marker present), auto-chains qa_scaffold first, then the pre-delivery audit. Unqualified "run QA" requests always go here. |

Section Specs & Shared Assets (4)

| Tool | Description | |------|-------------| | section_spec | Get a specific section specification (header / hero / services / etc.) from rules/section-specifics/. | | list_section_specs | List every section-spec file available. | | list_assets | List shared Nettsaga assets (certificates, review-site logos, career-site logos, flags). | | copy_assets | Copy shared assets into a project's public/ folders. NO-market essentials: Mesterbedrift / Mittanbud / Anbudstorget / etc. |

Stock Photos (6)

All iStock operations go through the VPS proxy — no local Playwright or iStock credentials needed.

| Tool | Description | |------|-------------| | pexels_search | Search Pexels via the VPS proxy. Thumbnail previews capped at 16 images / 2 MB for safe context use. Color filter, orientation, duplicate-marking vs project manifest. Always include region keywords (NO=Norwegian/Scandinavian, AU=Australian, USA=American, PH=Filipino). | | pexels_download | Download a Pexels image with auto-optimization, duplicate prevention, and a visual preview. | | istock_login | Sign in to iStock via the VPS proxy. Skips automatically if the proxy session is still valid. Run before istock_search / istock_download. | | istock_setup | One-time CAPTCHA recovery tool. Triggers the proxy to solve any active reCAPTCHA challenge. Run when istock_login reports a CAPTCHA. | | istock_search | Search iStock via the VPS proxy. Returns a screenshot + up to 30 result URLs for visual evaluation. Section-aware criteria (hero / services / about / gallery). Always include region keywords. | | istock_download | Download a specific iStock image via the VPS proxy. Optimises the file and saves to the given path. Proxy-side deduplication prevents re-purchasing. |

VPS Images (1)

| Tool | Description | |------|-------------| | vps_images | Manage images on the hosted image VPS (ns-img). Actions: list_folders, list (images in a folder), mkdir, delete. Returns full public CDN URLs. |

Image Management (4)

| Tool | Description | |------|-------------| | optimize_image | Optimize one image in-place (max 1920 px, mozjpeg / PNG / WebP). | | optimize_all_images | Batch optimize a directory recursively. Reports per-file + total savings. | | audit_images | Audit a directory for oversized images, format breakdown, total weight. | | list_downloaded_images | List Pexels images already downloaded in the project (via the .nettsaga-mcp/ manifest). |

Scrape + i18n (3)

| Tool | Description | |------|-------------| | scrape_client_site | Fast HTTP + HTML scrape of the client's existing website via undici + cheerio. Returns company info, services, testimonials, contact data. | | apply_translations | Write NO + EN translation pairs into lib/i18n.ts deterministically. Pairs with the scaffold_full → translation-subagent flow on NO builds. | | qa_i18n | Audit a NO-market site for i18n integrity: NO↔EN key symmetry, orphan t() calls, hardcoded-text scan. |

Animation (1)

| Tool | Description | |------|-------------| | apply_animation | Returns a detailed prompt instructing the AI to wire GSAP reveal primitives (TextReveal + Reveal) into every section of a scaffolded Nettsaga project. |

Typical scaffold flow (FAST PATH)

1. AI crawls the client's old site (playwright MCP + scrape_client_site) and
   extracts a structured client_data JSON. Optionally screenshots the hero
   for palette extraction.

   [SERVICES PRE-FLIGHT] Count services on old site → decide architecture:
   USA → always MPA; NO/AU/PH: 1-6 services → SPA, >6 → SPA + dedicated page.

2. extract_palette(image_path: hero-screenshot)             → OKLCH tokens

3. scaffold_full(target_dir, market, architecture, client_data, business_name?)
       → copies pre-stripped variant + writes site-config.ts in ONE call
       → writes .nettsaga-mcp/scaffold.json marker
       → returns "next steps" checklist

4. apply_palette(target_dir, tokens)                         → globals.css updated
   generate_favicon(target_dir, source_image_path | initials+primary_color)
   wire_logo(target_dir, logo_path: '/logo.svg', alt)        → header + metadata
   copy_assets(category, dest_dir)                            → NO market essentials

5. Image sourcing (per section, always include region keywords in queries):
   - pexels_search(query + region keyword, color, orientation) → free stock
   - istock_login → istock_search → istock_download            → premium stock

6. AI sets NEXT_PUBLIC_SITE_URL, drops real images into public/{hero,gallery,...},
   wires the contact form.

7. qa_workflow(project_dir)         → auto-chains qa_scaffold (marker detected),
                                       then runs the pre-delivery audit (incl. Regional Image Audit)
   SHIP

End-to-end: ~2 minutes for the deterministic portion.

The variants under resources/boilerplate-variants/{no-spa,no-mpa,usa-mpa}/ ship PRE-STRIPPED — no useEffectiveMarket, no MarketProvider, no SPA/MPA branches.

Usage Examples

Scaffold a new project

"Scaffold Acme Cleaning AS (Norwegian market) into C:/Projects/clients/acme-cleaning. Their old site is acmecleaning.no."

Claude crawls the site, counts services, extracts client_data, calls scaffold_full with market: "NO", architecture: "SPA" (or MPA if >6 services), and proceeds through the palette / favicon / logo / asset steps.

Generate a favicon

"Generate the favicon from the client logo at public/logo.svg."

Claude calls generate_favicon with target_dir and source_image_path. Outputs the full set into public/ and returns a metadata.icons snippet to paste into app/layout.tsx.

Run QA

"Run nettsaga QA on this project."

Claude calls qa_workflow with the project dir. If the scaffold marker exists, a preamble forces qa_scaffold first (5 agents on post-scaffold cleanup), then the full pre-delivery checklist (5 agents on mobile / nav / i18n / performance / branding + regional image audit). All findings collected into unified pass/fail reports with file:line + suggested fixes.

Search for market-appropriate stock photos

"Search Pexels for Norwegian construction site photos in muted blue tones."

Claude calls pexels_search with region keyword "Norwegian" + color filter, evaluates thumbnail previews, picks the best matches, and downloads via pexels_download.

iStock premium picks

"Search iStock for 'modern dental clinic reception in natural light'."

Claude calls istock_login (once per session; proxy caches the session), then istock_search for a screenshot + result URLs, then istock_download per chosen image. No local browser required.

Register a past project as a template reference

"Register https://github.com/our-agency/acme-roofing as a template — USA roofing."

Claude calls clone_template_repo, reads the inference signals, then register_template to finalize under ~/.nettsaga/templates/usa/roofing/acme-roofing/.

Use registered templates when building

"I'm building a USA HVAC site. Find a Hero pattern from a past project."

Claude calls use_template({ market: "USA", category: "hvac", section: "Hero" }) and studies the returned component source before writing the new component.

Audit images before delivery

"Audit public/ for anything over 1 MB."

Claude calls audit_images. Pair with optimize_all_images to bring offenders under the threshold.

Project State

Downloaded Pexels images, iStock session marker, and scaffold marker all live under .nettsaga-mcp/ at the project root:

.nettsaga-mcp/
  scaffold.json         ← written by scaffold_full
  pexels-downloads.json ← written by pexels_download

Add to .gitignore and let verify_cleanup remove it before delivery.

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | NS_MCP_URL | Yes | VPS proxy base URL. All stock photo and VPS image tools route through this. | | NS_MCP_API_KEY | Yes | Shared API key for the VPS proxy. | | NETTSAGA_USER_TEMPLATES_DIR | No | Override the default ~/.nettsaga/templates/ path (useful for agency-shared libraries). |

Troubleshooting

Tools not showing up — Restart Claude Code after adding the MCP server. For local-installed servers (node /path/dist/index.js), changes are picked up on next tool call since stdio MCP spawns fresh.

vps_images / pexels_search / iStock tools return connection errors — Check that NS_MCP_URL points to the correct VPS address and the proxy is running. Verify NS_MCP_API_KEY matches the proxy's configured key.

iStock login reports a CAPTCHA — Run istock_setup. The proxy will open a VNC window for manual solving (or auto-solve if CAPSOLVER is configured). The session then persists for weeks.

iStock download says "PREVIOUSLY DOWNLOADED" — The asset was already purchased on the proxy account. The proxy-side deduplication flag skips re-buying. Pass a different image or contact the team to reset.

generate_favicon fails on SVG — sharp renders SVGs at fixed density (384 DPI). For complex logos, supply a 512×512 PNG instead.

HMR feels like a memory leak in next dev — Fixed in v2.0.1: the boilerplate variants pin turbopack.root and outputFileTracingRoot so Next doesn't walk up to stray parent package.json files.

Changelog

• v2.0.7 — Unified all secrets on VPS: clients only need NS_MCP_URL + NS_MCP_API_KEY. Added VPS proxy routes for Pexels and VPS image management (vps_images tool). Removed local Playwright dependency. Removed use_hvac_images. Added istock_setup for CAPTCHA recovery. Added Services Pre-flight Gate and Regional Image Audit (#17) to build/QA workflows. Added apply_animation tool.
• v2.0.1 — Boilerplate next.config.ts pins workspace root (fixes HMR memory-leak feel).
• v2.0.0 — Renamed qa_boilerplate → qa_scaffold; qa_workflow now auto-chains it when the scaffold marker is detected. Revived iStock tools as first-class MCP tools. pexels_search now caps thumbnail payload at 2 MB / 16 images.
• v1.x — See git history.

Uninstall

claude mcp remove nettsaga -s user