Claude Code Integration

Copy this into your project's CLAUDE.md to give Claude Code full context for building on SpiderIQ.

Also works with other IDEs

This CLAUDE.md works with Claude Code (CLI, VS Code extension, JetBrains plugin), Cursor, Windsurf, and Google Antigravity. Any IDE that reads CLAUDE.md + .mcp.json will pick up the SpiderIQ context.

---

Drop-in CLAUDE.md

Create a file called CLAUDE.md in your project root with this content:

# SpiderIQ Content Platform

This project uses SpiderIQ to build, manage, and deploy websites.

## MCP Setup

The `.mcp.json` in this project connects to SpiderIQ. After restart, you have 146+ tools.

## Authentication

Run `npx spideriq auth whoami` to check auth status.
If not authenticated: `npx spideriq auth request --email admin@company.com`

## Build a Site

1. **Read the reference first:** Use `template_get_help` MCP tool (or `GET /api/v1/content/help?format=yaml`)
2. **Settings:** `PATCH /api/v1/dashboard/content/settings` — site_name, primary_color, logo
3. **Navigation:** `PUT /api/v1/dashboard/content/navigation/header` — menu items
4. **Pages:** `POST /api/v1/dashboard/content/pages` — create with blocks
5. **Publish:** `POST /api/v1/dashboard/content/pages/{id}/publish`
6. **Theme:** `POST /api/v1/dashboard/templates/apply-theme` — apply "default"
7. **Check readiness:** `GET /api/v1/dashboard/content/deploy/readiness` — verify all checks pass
8. **Deploy:** `POST /api/v1/dashboard/content/deploy` — live in ~2-5 seconds

## IMPORTANT: Deploy Requirements

Deploy will **reject** your request if any of these are missing:
- Site settings with `site_name` (step 2)
- At least 1 verified domain
- At least 1 template / theme applied (step 6)
- At least 1 published page (step 5)

**Always call** `GET /dashboard/content/deploy/readiness` before deploying. It tells you exactly what's missing.

## Key Rules

- **Always read `/content/help` first** — it has every block type, Liquid filter, and template variable
- **Always check readiness before deploy** — `GET /dashboard/content/deploy/readiness`
- **Component slugs must be unique** — creating a duplicate slug+version returns 400. Use update or increment version.
- **Use `format=yaml`** on GET requests — saves 40-76% tokens
- **Block types:** hero, features_grid, cta_section, testimonials, pricing_table, faq, stats_bar, rich_text, image, video_embed, code_example, logo_cloud, comparison_table, spacer, component
- **Page templates:** default, landing, feature, legal, dynamic_landing
- **Components use Shadow DOM** — CSS is automatically isolated, use `var(--primary)` for theme colors, never Tailwind
- **Public endpoints** (GET /content/*) need no auth — use `X-Content-Domain` header
- **Dashboard endpoints** (POST/PATCH /dashboard/content/*) need Bearer auth

## Dynamic Landing Pages

For personalized outreach pages:
- Template: `dynamic_landing`
- URL: `/lp/{page_slug}/{salesperson}/{google_place_id}`
- **Preferred:** flat email-marketing merge tags — `{{ firstname }}`, `{{ company_name }}`, `{{ city }}`, `{{ industry }}`, `{{ logo }}`, `{{ email }}` (~40 total). Fetch the full vocabulary via `GET /content/variables` or the `content_get_variables` MCP tool. Full reference: [Merge Tags](./merge-tags).
- **Also available (power users):** the raw IDAP shape — `{{ lead.name }}`, `{{ lead.city }}`, `{{ lead.related.emails[0].address }}`, `{{ salesperson.name }}`.
- Lead data fetched automatically from IDAP by Place ID; preview without real data at `/lp/{slug}/demo`.

## IDAP Data Access

Read CRM data (businesses, emails, contacts, phones):
- `GET /api/v1/idap/businesses?limit=20&include=emails&format=yaml`
- `GET /api/v1/idap/businesses/{id}?include=emails,phones,domains,contacts`
- `POST /api/v1/idap/businesses/{id}/flags` — flag leads as qualified/contacted

## API Base

- Production: `https://spideriq.ai/api/v1`
- Docs: `https://docs.spideriq.ai`
- Health: `GET /api/v1/system/health`

---

.mcp.json

Add this to your project root:

{
  "mcpServers": {
    "spideriq": {
      "command": "npx",
      "args": ["@spideriq/mcp"],
      "env": {
        "SPIDERIQ_FORMAT": "yaml"
      }
    }
  }
}

---

Workflow Examples

Build a Landing Page

1. Use template_get_help to read the content reference
2. Use content_create_page with template "landing", blocks: hero + features_grid + cta_section
3. Use content_publish_page
4. Use template_apply_theme with "default"
5. Use content_deploy_site

Create a Blog

1. Use content_create_post with title, body (Tiptap JSON), cover_image_url, tags
2. Use content_publish_post
3. Repeat for each post
4. Use content_deploy_site

Build a Personalized Outreach Page

1. Use idap_list_resources type="businesses" to see available lead data
2. Use content_create_page with template "dynamic_landing"
   - Use {business} and {city} placeholders in custom_fields
3. Use content_publish_page
4. Use template_update_config to add salesperson profiles
5. Use content_deploy_site
6. Share: https://yoursite.com/lp/{slug}/{salesperson}/{place_id}

Query Lead Data

1. Use idap_list_resources type="businesses" limit=50 include="emails" format="yaml"
2. Use idap_fetch_resource type="businesses" id="uuid" include="emails,phones,contacts"
3. Use idap_write_flags to mark leads as "qualified" or "contacted"

---

Common MCP Tool Patterns

Creating a page with components

# First, check available components
Use content_list_components

# Create page using a component block
Use content_create_page with blocks:
[{
  "type": "component",
  "component_slug": "sys-hero-simple",
  "props": { "headline": "Welcome", "cta_text": "Get Started" }
}]

Full site build in one session

1. template_get_help → read reference
2. PATCH settings → branding
3. PUT navigation/header → menu
4. POST pages (home, features, pricing, about) → content
5. POST pages/{id}/publish (x4) → publish all
6. POST templates/apply-theme → theme
7. POST deploy → live

---

Troubleshooting

Problem	Solution
"Invalid credentials"	Run npx spideriq auth whoami to check token
"No content configured for domain"	Set X-Content-Domain header on public API calls
Page shows empty	Check page is published (POST /pages/{id}/publish)
Deploy fails	Check GET /dashboard/content/deploy/status for errors
Component CSS leaks	Components use Shadow DOM — all CSS must be inside the component, no Tailwind
{{ lead.name }} shows empty	Page must use dynamic_landing template and URL must match /lp/ pattern