# AllGoodInsp

> A curated design reference database for AI and humans. Each site is analyzed for typography, layout, color, motion, and information architecture decisions. AI connects via MCP or REST API to retrieve structured design data and produce better web design output.

## About

AllGoodInsp is a curated collection of design references built for both humans and AI.

Every site in the collection is analyzed for its design decisions — typography, layout, color, motion, and information architecture — and stored as structured data that AI tools can query through MCP (Model Context Protocol).

**For humans:** Browse the gallery for inspiration. Save favorites, organize collections, and claim credit on sites you've worked on.

**For AI:** Connect via MCP to retrieve structured design references. Instead of generating from generic prompts, AI can base its output on real design decisions from quality sites — producing better, more intentional results. The primary tool, `extract_essence`, synthesizes 2-5 references into a ready-to-save DESIGN.md: design tokens, CSS custom properties, motion notes, section structure, and binding do's-and-don'ts. Save it at the project root and reference it from CLAUDE.md/AGENTS.md so it loads on every generation. A REST API is also available for programmatic access.

**What makes it different:** Every reference is hand-reviewed with its design decisions written out — including motion and information architecture, the layers screenshot libraries and token formats leave undocumented — and extract_essence merges several references into one working document instead of leaving the model to average raw material. See https://allgoodinsp.com/compare

**How sites are selected:** Sites are selected for distinctive design decisions — not just visual polish, but intentional choices in typography, layout, color, and motion that other designers and AI can learn from.

## MCP Server

AllGoodInsp provides an MCP (Model Context Protocol) server that lets AI tools query a curated collection of design references.

- **Endpoint:** `https://mcp.allgoodinsp.com`
- **Transport:** Streamable HTTP with OAuth 2.1
- **Supported clients:** Claude Desktop, Claude Code, Cursor, Windsurf, Cline

### Quick setup

1. Create an account: sign in with Google at https://allgoodinsp.com/login
2. Add to your MCP client configuration:
   ```json
   {
     "mcpServers": {
       "allgoodinsp": {
         "url": "https://mcp.allgoodinsp.com"
       }
     }
   }
   ```
3. On first connection, your MCP client will open a browser window for OAuth authorization.

### Available tools

- `extract_essence(site_ids, brief, aspect_overrides?, reference_intents?)` — PRIMARY tool. Synthesize 2-5 references into a ready-to-save DESIGN.md: YAML design tokens, CSS custom properties, typography, color, spacing, motion, section structure, reference allocation, and binding do's-and-don'ts
- `search_sites(query, category?, country?)` — Search sites by mood, purpose, or description using vector embeddings
- `get_site(site_id, detail?)` — Retrieve design analysis for a site. detail: full (default) or summary
- `search_by_component(query, limit?, section?, imagery?, subject?, composition?, bg_tone?, type_scale?, ui_pattern?, color_system?)` — Find sites by design element (e.g. "hero with video background"). Optional result limit; the other optional parameters are filters
- `get_methodology(layers?)` — Design methodology. layers: principles, craft, patterns, ia
- `get_reference_guide()` — Deep-dive guide for reading and combining references
- `get_principles(category?)` — Design principles for typography, layout, color, motion, or IA
- `get_patterns()` — Reusable technique combinations distilled from the collection
- `self_review()` — Post-implementation checklist: verify output against the design rules and fix violations

### Example prompts

- "Search AllGoodInsp for sites with a minimal, editorial feel"
- "Find references for a SaaS landing page with bold typography"
- "Retrieve references from AllGoodInsp and build a website for a Japanese tea shop that blends tradition with modernity — sincere yet playful."

## REST API

The REST API provides programmatic access to the same design reference data available via MCP. All endpoints return JSON and support CORS.

### Base URL

```
https://api.allgoodinsp.com/v1
```

### Authentication

Site listing, taxonomy, screenshots, and search work without authentication, subject to stricter rate limits. Full site detail, extract-essence, and submissions require an API key. Generate one from your account page (or via POST /v1/auth/register) and include it in the Authorization header:

```
Authorization: Bearer YOUR_API_KEY
```

### Rate limits

| Tier | General | Search | Extract-essence | Submissions |
|------|---------|--------|-----------------|-------------|
| Authenticated | 10/min, 50/day | 5/min, 25/day | 3/min, 30/day | 5/hour, 3/day |
| Unauthenticated | 5/hour, 10/day | 3/hour, 5/day | Not available | Not available |

Rate limit status is returned in `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` response headers.

### Endpoints

#### GET /sites

List all sites with optional filters and pagination.

Query parameters:
- `category` — Filter by category (e.g. `software-saas`, `agency`)
- `country` — Filter by ISO 3166-1 alpha-2 code (e.g. `JP`, `US`)
- `region` — Filter by region (e.g. `east-asia`, `europe`)
- `page` — Page number (default: 1)
- `limit` — Results per page, 1–100 (default: 30)

```bash
curl "https://api.allgoodinsp.com/v1/sites?category=agency&country=JP&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Response:
```json
{
  "sites": [
    {
      "site_id": "example-agency",
      "site_name": "Example Agency",
      "url": "https://example-agency.com/",
      "category": "agency",
      "country": "JP",
      "region": "east-asia"
    }
  ],
  "pagination": { "page": 1, "limit": 10, "total": 42, "total_pages": 5 }
}
```

#### GET /sites/:site_id

Retrieve the full design analysis for a single site. Includes sections, components, CSS values, and principle references. Requires an API key and costs 1 credit (same as MCP `get_site`). Charged responses carry `X-Credits-Free-Remaining` / `X-Credits-Paid-Remaining` headers.

```bash
curl "https://api.allgoodinsp.com/v1/sites/stripe-com" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Response:
```json
{
  "meta": {
    "site_id": "stripe-com",
    "site_name": "Stripe",
    "url": "https://stripe.com/",
    "category": "software-saas",
    "country": "US",
    "region": "north-america"
  },
  "convention_breaks": [],
  "sections": [
    {
      "section": "hero",
      "role": "...",
      "dominant_decision": "...",
      "components": [
        {
          "target": "Hero Headline",
          "principle_refs": ["typo_002", "layout_003"],
          "what": "...",
          "css": "...",
          "why": "..."
        }
      ]
    }
  ]
}
```

#### GET /search

Semantic search across all sites. Matches against mood, purpose, and design descriptions using vector embeddings.

Query parameters:
- `q` — **Required.** Search query (e.g. `minimal editorial typography`)
- `limit` — Max results, 1–30 (default: 20)

```bash
curl "https://api.allgoodinsp.com/v1/search?q=bold+typography+dark+theme&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Each search response includes a `next_step` object pointing at the synthesis step (`POST /extract-essence`) with an example request body.

#### POST /extract-essence

The primary synthesis endpoint. Merges 2-5 references into a ready-to-save DESIGN.md. Requires authentication; costs 5 credits per successful call (failed calls are not charged).

Request body:
- `site_ids` — **Required.** Array of 2-5 site IDs
- `brief` — **Required.** Design goal, at least 10 characters (e.g. `"SaaS landing page, confident and minimal"`)
- `aspect_overrides` — Optional map assigning a site_id to `color` / `typography` / `layout` / `sections`
- `reference_intents` — Optional array of `{ site_id, take, leave? }` per-reference directives

```bash
curl -X POST "https://api.allgoodinsp.com/v1/extract-essence" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"site_ids": ["<id>", "<id>", "<id>"], "brief": "SaaS landing page, confident and minimal"}'
```

Response:
```json
{
  "site_ids": ["..."],
  "format": "design-md",
  "filename_hint": "DESIGN.md",
  "brief": "<complete DESIGN.md markdown: YAML token frontmatter + sections>",
  "credits": { "free_remaining": 70, "paid_remaining": 0 }
}
```

Save the `brief` string as `DESIGN.md` at your project root and reference it from CLAUDE.md/AGENTS.md. Unknown site_ids return 404 with suggested alternatives matching your brief; insufficient credits return 402.

#### GET /taxonomy

Get all categories, countries, and regions with site counts. Useful for building filter UIs.

```bash
curl "https://api.allgoodinsp.com/v1/taxonomy"
```

#### GET /screenshots/:site_id

Retrieve a screenshot of the site as a WebP image.

Query parameters:
- `size` — `full` for the full viewport screenshot (default: thumbnail)

Returns `image/webp` with a 24-hour cache header. Returns 404 if no screenshot is available.

#### POST /submissions

Submit a site URL for review. Requires authentication. Submissions enter a moderation queue and are not published immediately.

Request body:
- `url` — **Required.** The site URL (must be http or https)
- `siteName` — Optional site name (max 200 characters)
- `description` — Optional description or notes (max 2000 characters)

```bash
curl -X POST "https://api.allgoodinsp.com/v1/submissions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "siteName": "Example Site"}'
```

Returns 409 if the URL already exists in the collection or is already pending review.

### Error responses

All errors return JSON with an `error` field: `{ "error": "Site not found" }`

| Status | Meaning |
|--------|---------|
| 400 | Bad request (missing or invalid parameters) |
| 401 | Invalid or expired API key |
| 402 | Insufficient credits (extract-essence) |
| 404 | Resource not found |
| 405 | Method not allowed |
| 409 | Duplicate resource (URL already exists or pending) |
| 429 | Rate limit exceeded |

## Design data structure

Each site reference contains structured design analysis:

```json
{
  "meta": {
    "site_id": "example-site",
    "site_name": "Example Site",
    "url": "https://example-site.com/",
    "category": "software-saas",
    "country": "US",
    "region": "north-america"
  },
  "convention_breaks": [
    {
      "principle_id": "typo_001",
      "what": "description of the convention break",
      "why_intentional": "why this works despite breaking convention",
      "scope": "hero | navigation | content | global",
      "import_warning": "caution when importing this decision"
    }
  ],
  "sections": [
    {
      "section": "hero",
      "role": "what this section does",
      "dominant_decision": "the key design choice",
      "components": [
        {
          "target": "Hero Headline",
          "principle_refs": ["typo_002", "layout_003"],
          "what": "description of the design decision",
          "css": "relevant CSS values",
          "why": "rationale for this choice"
        }
      ]
    }
  ]
}
```

## Knowledge system

AllGoodInsp maintains three layers of design knowledge, distilled from the reference collection:

- **Principles** — Universal design truths across 5 categories: typography, layout, color, motion, information architecture
- **Patterns** — Recurring technique combinations observed across 3+ sites
- **References** — Individual site design decisions with CSS values and rationale

## Optional

- [Privacy Policy](https://allgoodinsp.com/privacy)
- [Contact](https://allgoodinsp.com/contact): hello@allgoodinsp.com