# OurDigital SEO Audit - Claude Desktop Project Knowledge

## Overview

This project knowledge file enables Claude Desktop to perform comprehensive SEO audits using MCP tools. It provides workflows for technical SEO analysis, schema validation, sitemap checking, and Core Web Vitals assessment.

## Available MCP Tools

### Primary Tools
| Tool | Purpose |
|------|---------|
| `firecrawl` | Website crawling, scraping, structured data extraction |
| `perplexity` | AI-powered research, competitive analysis |
| `notion` | Store audit findings in database |
| `fetch` | Fetch web pages and resources |
| `sequential-thinking` | Complex multi-step analysis |

### Tool Usage Patterns

#### Firecrawl - Web Scraping
```
firecrawl_scrape: Scrape single page content
firecrawl_crawl: Crawl entire website
firecrawl_extract: Extract structured data
firecrawl_map: Get site structure
```

#### Notion - Output Storage
```
API-post-search: Find existing databases
API-post-database-query: Query database
API-post-page: Create finding pages
API-patch-page: Update findings
```

## SEO Audit Workflows

### 1. Full Site Audit

**User prompt:** "Perform SEO audit for https://example.com"

**Workflow:**
1. Use `firecrawl_scrape` to get homepage content
2. Use `firecrawl_map` to discover site structure
3. Check robots.txt at /robots.txt
4. Check sitemap at /sitemap.xml
5. Extract and validate schema markup
6. Use `perplexity` for competitive insights
7. Store findings in Notion database

### 2. Schema Markup Validation

**User prompt:** "Validate schema on https://example.com"

**Workflow:**
1. Use `firecrawl_scrape` with extractSchema option
2. Look for JSON-LD in `<script type="application/ld+json">`
3. Check for Microdata (`itemscope`, `itemtype`, `itemprop`)
4. Validate against schema.org requirements
5. Check Rich Results eligibility

**Schema Types to Check:**
- Organization / LocalBusiness
- Product / Offer
- Article / BlogPosting
- FAQPage / HowTo
- BreadcrumbList
- WebSite / WebPage

**Required Properties by Type:**

| Type | Required | Recommended |
|------|----------|-------------|
| Organization | name, url | logo, sameAs, contactPoint |
| LocalBusiness | name, address | telephone, openingHours, geo |
| Product | name | image, description, offers, brand |
| Article | headline, author, datePublished | image, dateModified, publisher |
| FAQPage | mainEntity (Question + Answer) | - |

### 3. Robots.txt Analysis

**User prompt:** "Check robots.txt for example.com"

**Workflow:**
1. Fetch https://example.com/robots.txt
2. Parse directives:
   - User-agent rules
   - Disallow patterns
   - Allow patterns
   - Crawl-delay
   - Sitemap declarations
3. Check for issues:
   - Blocking CSS/JS resources
   - Missing sitemap reference
   - Overly restrictive rules

**Sample Analysis Output:**
```
Robots.txt Analysis
==================
User-agents: 3 defined (*, Googlebot, Bingbot)

Directives:
- Disallow: /admin/, /private/, /tmp/
- Allow: /public/, /blog/
- Sitemap: https://example.com/sitemap.xml

Issues Found:
- WARNING: CSS/JS files may be blocked (/assets/)
- OK: Sitemap is declared
- INFO: Crawl-delay set to 10s
```

### 4. Sitemap Validation

**User prompt:** "Validate sitemap at https://example.com/sitemap.xml"

**Workflow:**
1. Fetch sitemap XML
2. Parse and validate structure
3. Check:
   - XML syntax validity
   - URL count (max 50,000)
   - Lastmod date formats
   - URL accessibility (sample)
4. For sitemap index, check child sitemaps

**Validation Criteria:**
- Valid XML syntax
- `<urlset>` or `<sitemapindex>` root element
- Each `<url>` has `<loc>` element
- `<lastmod>` in W3C datetime format
- File size under 50MB uncompressed

### 5. Core Web Vitals Check

**User prompt:** "Check Core Web Vitals for https://example.com"

**Workflow:**
1. Use PageSpeed Insights (if API available)
2. Or analyze page with firecrawl for common issues
3. Check for:
   - Large images without optimization
   - Render-blocking resources
   - Layout shift causes
   - JavaScript execution time

**Metrics & Thresholds:**
| Metric | Good | Needs Improvement | Poor |
|--------|------|-------------------|------|
| LCP | < 2.5s | 2.5s - 4.0s | > 4.0s |
| CLS | < 0.1 | 0.1 - 0.25 | > 0.25 |
| FID/INP | < 100ms/200ms | 100-300ms/200-500ms | > 300ms/500ms |

### 6. Technical SEO Check

**User prompt:** "Check technical SEO for https://example.com"

**Workflow:**
1. Check HTTPS implementation
2. Verify canonical tags
3. Check meta robots tags
4. Analyze heading structure (H1-H6)
5. Check image alt attributes
6. Verify Open Graph / Twitter Cards
7. Check mobile-friendliness indicators

**Checklist:**
- [ ] HTTPS enabled
- [ ] Single canonical URL per page
- [ ] Proper robots meta tags
- [ ] One H1 per page
- [ ] All images have alt text
- [ ] OG tags present (og:title, og:description, og:image)
- [ ] Twitter Card tags present
- [ ] Viewport meta tag for mobile

### 7. Local SEO Audit

**User prompt:** "Local SEO audit for [Business Name] in [Location]"

**Workflow:**
1. Search for business citations with `perplexity`
2. Check for LocalBusiness schema
3. Verify NAP (Name, Address, Phone) consistency
4. Look for review signals
5. Check Google Business Profile (manual)

## Notion Database Integration

### Default Database
- **Database ID**: `2c8581e5-8a1e-8035-880b-e38cefc2f3ef`
- **Name**: OurDigital SEO Audit Log

### Database Properties
| Property | Type | Values |
|----------|------|--------|
| Issue | Title | Finding title |
| Site | URL | Audited site URL |
| Category | Select | Technical SEO, On-page SEO, Content, Local SEO, Performance, Schema/Structured Data, Sitemap, Robots.txt |
| Priority | Select | Critical, High, Medium, Low |
| Status | Status | Not started, In progress, Done |
| URL | URL | Specific page with issue |
| Found Date | Date | Discovery date |
| Audit ID | Rich Text | Groups findings from same audit |

### Page Content Template
Each finding page should contain:

```markdown
## Description
[Detailed explanation of the issue]

## Impact
[Business/ranking impact with warning callout]

## Recommendation
[Actionable solution with lightbulb callout]
```

### Creating Findings
Use Notion MCP to create pages:
1. Query database to check for existing entries
2. Create new page with properties
3. Add content blocks (Description, Impact, Recommendation)

## Schema Markup Templates

### Organization Schema
```json
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "[Company Name]",
  "url": "[Website URL]",
  "logo": "[Logo URL]",
  "sameAs": [
    "[Social Media URLs]"
  ],
  "contactPoint": {
    "@type": "ContactPoint",
    "telephone": "[Phone]",
    "contactType": "customer service"
  }
}
```

### LocalBusiness Schema
```json
{
  "@context": "https://schema.org",
  "@type": "LocalBusiness",
  "name": "[Business Name]",
  "address": {
    "@type": "PostalAddress",
    "streetAddress": "[Street]",
    "addressLocality": "[City]",
    "addressCountry": "[Country Code]"
  },
  "telephone": "[Phone]",
  "openingHoursSpecification": [{
    "@type": "OpeningHoursSpecification",
    "dayOfWeek": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"],
    "opens": "09:00",
    "closes": "18:00"
  }]
}
```

### Article Schema
```json
{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "[Article Title]",
  "author": {
    "@type": "Person",
    "name": "[Author Name]"
  },
  "datePublished": "[ISO Date]",
  "dateModified": "[ISO Date]",
  "publisher": {
    "@type": "Organization",
    "name": "[Publisher Name]",
    "logo": {
      "@type": "ImageObject",
      "url": "[Logo URL]"
    }
  }
}
```

### FAQPage Schema
```json
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [{
    "@type": "Question",
    "name": "[Question Text]",
    "acceptedAnswer": {
      "@type": "Answer",
      "text": "[Answer Text]"
    }
  }]
}
```

### BreadcrumbList Schema
```json
{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [{
    "@type": "ListItem",
    "position": 1,
    "name": "Home",
    "item": "[Homepage URL]"
  }, {
    "@type": "ListItem",
    "position": 2,
    "name": "[Category]",
    "item": "[Category URL]"
  }]
}
```

## Common SEO Issues Reference

### Critical Priority
- Site not accessible (5xx errors)
- Robots.txt blocking entire site
- No HTTPS implementation
- Duplicate content across domain
- Sitemap returning errors

### High Priority
- Missing or duplicate title tags
- No meta descriptions
- Schema markup errors
- Broken internal links
- Missing canonical tags
- Core Web Vitals failing

### Medium Priority
- Missing alt text on images
- Thin content pages
- Missing Open Graph tags
- Suboptimal heading structure
- Missing breadcrumb schema

### Low Priority
- Missing Twitter Card tags
- Suboptimal URL structure
- Missing FAQ schema
- Review schema not implemented

## Quick Commands Reference

| Task | Prompt |
|------|--------|
| Full audit | "Perform SEO audit for [URL]" |
| Schema check | "Validate schema on [URL]" |
| Sitemap check | "Validate sitemap at [URL]" |
| Robots.txt | "Analyze robots.txt for [domain]" |
| Performance | "Check Core Web Vitals for [URL]" |
| Generate schema | "Generate [type] schema for [details]" |
| Export to Notion | "Export findings to Notion" |
| Local SEO | "Local SEO audit for [business] in [location]" |
| Competitive | "Compare SEO of [URL1] vs [URL2]" |

## Tips for Best Results

1. **Be specific** - Provide full URLs including https://
2. **One site at a time** - Audit one domain per session for clarity
3. **Check Notion** - Review existing findings before creating duplicates
4. **Prioritize fixes** - Focus on Critical/High issues first
5. **Validate changes** - Re-audit after implementing fixes

## Limitations

- No direct Python script execution (use MCP tools instead)
- PageSpeed API requires separate configuration
- Google Search Console data requires authenticated access
- GA4 data requires service account setup
- Large sites may require multiple sessions