@heyseo/mcp-server 0.2.0 → 0.2.1

package/README.md

@@ -3,7 +3,9 @@
 
   # HeySeo MCP Server
 
-  Connect your LLM to your SEO data. Query Google Search Console, Google Analytics 4, and PageSpeed Insights directly from Claude, ChatGPT, Cursor, or any MCP-compatible client.
+  Connect your LLM to your SEO data. Query Google Search Console, Google Analytics 4, PageSpeed Insights, SERP data, indexing health, AI insights, and more — directly from Claude, ChatGPT, Cursor, or any MCP-compatible client.
+
+  **35 tools** | **10 resources** | **12 prompts**
 </div>
 
 ## Quick Start
@@ -202,6 +204,56 @@ Restart Claude Desktop, Cursor, or your MCP client to load the new server.
 | `heyseo_bulk_create_tasks` | Create multiple tasks at once (up to 10) |
 | `heyseo_bulk_update_tasks` | Update multiple tasks at once (up to 10) |
 
+### Reports
+
+| Tool | Description |
+|------|-------------|
+| `heyseo_list_reports` | List AI-generated SEO reports (weekly/monthly) |
+| `heyseo_get_report` | Get full report details including metrics and AI analysis |
+
+### Indexing Health
+
+| Tool | Description |
+|------|-------------|
+| `heyseo_indexing_status` | Get indexing health summary (indexed/not-indexed counts, health score) |
+| `heyseo_indexing_pages` | List pages with their indexing verdict and coverage state |
+| `heyseo_submit_for_indexing` | Submit a page to Google's Indexing API for faster indexing |
+
+### SEO Memory
+
+| Tool | Description |
+|------|-------------|
+| `heyseo_get_memory` | Get full SEO memory context (strategy, goals, learnings, health trend) |
+| `heyseo_update_strategy` | Update SEO strategy summary, create goals, or update goal progress |
+| `heyseo_record_action` | Record an SEO action taken on the site with hypothesis and metrics to track |
+| `heyseo_add_learning` | Add a key fact or success pattern to the site's learning memory |
+
+### AI Insights
+
+| Tool | Description |
+|------|-------------|
+| `heyseo_get_insights` | Get AI-generated insights (anomalies, opportunities, alerts, trends, milestones) |
+
+### On-Page Audit
+
+| Tool | Description |
+|------|-------------|
+| `heyseo_onpage_audit` | Run a full on-page SEO audit on any URL (score, meta tags, headings, links, images, issues) |
+
+### SERP Analysis
+
+| Tool | Description |
+|------|-------------|
+| `heyseo_serp_search` | Search Google SERP for a keyword with organic results, featured snippets, and PAA |
+
+### Sitemaps
+
+| Tool | Description |
+|------|-------------|
+| `heyseo_list_sitemaps` | List sitemaps registered in Google Search Console with status and errors |
+
+---
+
 ## Resources
 
 Access your SEO data as readable resources:
@@ -210,9 +262,16 @@ Access your SEO data as readable resources:
 |-----|-------------|
 | `heyseo://sites` | List all connected sites |
 | `heyseo://sites/{id}` | Site details |
-| `heyseo://sites/{id}/overview` | Current metrics overview |
+| `heyseo://sites/{id}/overview` | Current metrics overview (last 28 days) |
 | `heyseo://sites/{id}/keywords` | Top 50 keywords |
 | `heyseo://sites/{id}/pages` | Top 50 pages |
+| `heyseo://sites/{id}/reports` | Recent AI-generated SEO reports |
+| `heyseo://sites/{id}/indexing` | Indexing health summary |
+| `heyseo://sites/{id}/insights` | AI-generated insights |
+| `heyseo://sites/{id}/memory` | SEO memory context (strategy, goals, learnings) |
+| `heyseo://sites/{id}/sitemaps` | GSC sitemaps |
+
+---
 
 ## Prompts
 
@@ -228,7 +287,10 @@ Pre-built prompts for common SEO tasks:
 | `traffic_analysis` | Traffic patterns and sources |
 | `quick_wins` | Low-effort, high-impact opportunities |
 | `ranking_changes` | Recent ranking changes analysis |
-| `task_review` | Review and prioritize SEO tasks for a site |
+| `task_review` | Review and prioritize SEO tasks |
+| `indexing_audit` | Indexing health audit with fix recommendations |
+| `strategy_review` | Review and update SEO strategy based on memory |
+| `insights_briefing` | Summarize recent insights and suggest actions |
 
 ---
 
@@ -243,80 +305,95 @@ Before performing any SEO operations, you must select a site:
 
 **Select a site:**
 > "Select the site with ID: abc123def456"
->
-> Or ask Claude to list sites and select one for you
 
 **Check current site:**
 > "What site am I currently working with?"
 
-### SEO Operations
+### Performance Analysis
 
-Once a site is selected, you can perform SEO operations:
-
-**Get top keywords:**
 > "What are my top 10 keywords this month?"
 
-**Run an SEO audit:**
-> "Run an SEO audit on my site"
-
-**Compare performance:**
 > "How did we do this week vs last week?"
 
-**Analyze page speed:**
 > "Check the page speed for our homepage"
 
-**Find opportunities:**
+> "How has my ranking for 'best seo tools' changed over the last 30 days?"
+
+### Audits & Opportunities
+
+> "Run an SEO audit on my site"
+
 > "Find quick win SEO opportunities"
 
-**Track keyword ranking history:**
-> "How has my ranking for 'best seo tools' changed over the last 30 days?"
+> "Run an on-page audit on https://example.com/blog/post"
+
+> "Search Google for 'best project management tools' and show me the SERP"
+
+### Indexing Health
+
+> "What's my indexing health status?"
+
+> "Show me pages that aren't indexed"
+
+> "Submit my /new-landing-page for indexing"
+
+### Reports & Insights
+
+> "Show me my latest SEO reports"
+
+> "What AI insights do you have for my site?"
+
+> "Give me an insights briefing"
+
+### Strategy & Memory
+
+> "What's our current SEO strategy?"
+
+> "Update the strategy summary to focus on technical SEO improvements"
+
+> "Create a goal to increase organic clicks by 20% by Q3"
+
+> "Record that we optimized all meta descriptions today"
+
+> "Add a learning: long-form guides rank better for informational queries"
+
+### Task Management
 
-**Review and prioritize tasks:**
 > "Review my SEO tasks and help me prioritize them"
 
-**Create tasks from audit findings:**
 > "Create tasks for the top 5 issues you found in the audit"
 
-**Bulk update task status:**
 > "Mark all the technical tasks as done"
 
+### Sitemaps
+
+> "List my sitemaps from Google Search Console"
+
 ---
 
-## Site Selection Workflow
-
-The HeySeo MCP server uses explicit site selection to prevent data isolation issues:
-
-### Typical Workflow
-
-1. **Initialize**: User starts a conversation with Claude
-2. **List Sites**: User asks to see available sites
-   ```
-   → heyseo_list_sites
-   ← Returns all available sites with IDs and connection status
-   ```
-3. **Select Site**: User chooses which site to work with
-   ```
-   → heyseo_select_site { siteId: "your-site-id" }
-   ← Confirms selection and shows site details
-   ```
-4. **Verify Selection**: (Optional) User confirms the current site
-   ```
-   → heyseo_get_current_site
-   ← Returns details of the selected site
-   ```
-5. **Perform Operations**: All subsequent SEO operations use the selected site
-   ```
-   → heyseo_query_gsc { siteId: <auto-filled>, ... }
-   → heyseo_top_keywords { siteId: <auto-filled>, ... }
-   → etc.
-   ```
-
-### Benefits
-
-- **Data Isolation**: Prevents accidentally querying wrong site's data
-- **Explicit Selection**: User clearly knows which site they're working with
-- **Session Persistence**: Selection persists across multiple operations
-- **Safety**: Perfect for users managing multiple sites
+## API Key Scopes
+
+When creating an API key, you can restrict access to specific features:
+
+| Scope | Description |
+|-------|-------------|
+| `sites:read` | Read site information |
+| `gsc:read` | Read Google Search Console data |
+| `ga4:read` | Read Google Analytics 4 data |
+| `pagespeed:read` | Run PageSpeed analyses |
+| `tasks:read` | Read tasks |
+| `tasks:write` | Create, update, delete tasks |
+| `reports:read` | Read AI-generated reports |
+| `indexing:read` | Read indexing status and pages |
+| `indexing:write` | Submit pages for indexing |
+| `memory:read` | Read SEO memory context |
+| `memory:write` | Update strategy, goals, actions, learnings |
+| `insights:read` | Read AI-generated insights |
+| `onpage:read` | Run on-page audits |
+| `serp:read` | Search Google SERP |
+| `sitemaps:read` | Read GSC sitemaps |
+
+Use `all` scope for full access.
 
 ---
 
@@ -341,4 +418,4 @@ MIT
 ## Support
 
 - Website: [heyseo.app](https://heyseo.app)
-- Email: support@heyseo.app
+- Email: hello@heyseo.app