@heyseo/mcp-server 0.2.0 → 0.3.0

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.
+
+  **72 tools** | **10 resources** | **12 prompts**
 </div>
 
 ## Quick Start
@@ -157,6 +159,9 @@ Restart Claude Desktop, Cursor, or your MCP client to load the new server.
 | `heyseo_list_sites` | List all available sites and their connection status (GSC/GA4) |
 | `heyseo_select_site` | Select a specific site for all subsequent operations |
 | `heyseo_get_current_site` | Get information about the currently selected site |
+| `heyseo_update_site` | Update site settings (name, URL) |
+| `heyseo_delete_site` | Delete a site from your account |
+| `heyseo_sync_analytics` | Trigger an analytics data sync for a site |
 
 ### Google Search Console
 
@@ -181,6 +186,7 @@ Restart Claude Desktop, Cursor, or your MCP client to load the new server.
 |------|-------------|
 | `heyseo_pagespeed` | Run PageSpeed Insights analysis with Core Web Vitals |
 | `heyseo_pagespeed_bulk` | Analyze multiple pages at once |
+| `heyseo_pagespeed_history` | Get PageSpeed analysis history for a site |
 
 ### Comparison & Opportunities
 
@@ -199,9 +205,117 @@ Restart Claude Desktop, Cursor, or your MCP client to load the new server.
 | `heyseo_get_task` | Get detailed information about a specific task |
 | `heyseo_update_task` | Update task title, description, status, priority, or category |
 | `heyseo_delete_task` | Delete a task from the Kanban board |
+| `heyseo_move_task` | Move or reorder a task on the Kanban board |
 | `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 |
+| `heyseo_generate_report` | Generate a new SEO report on demand |
+| `heyseo_delete_report` | Delete a report |
+| `heyseo_report_settings` | Get report schedule settings for a site |
+| `heyseo_update_report_settings` | Update report schedule (day, time, frequency) |
+| `heyseo_send_test_report` | Send a test report email to verify setup |
+
+### 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 |
+| `heyseo_indexing_check` | Trigger an indexing check for all monitored pages |
+| `heyseo_indexing_history` | Get indexing check history over time |
+| `heyseo_indexing_settings` | Get indexing monitoring settings |
+| `heyseo_update_indexing_settings` | Update indexing monitoring settings |
+| `heyseo_indexing_submissions` | Get indexing submission history |
+| `heyseo_remove_indexing_page` | Remove a page from indexing monitoring |
+
+### SEO Memory
+
+| Tool | Description |
+|------|-------------|
+| `heyseo_get_memory` | Get full SEO memory context (strategy, goals, learnings, health trend) |
+| `heyseo_update_strategy` | Update SEO strategy summary |
+| `heyseo_record_action` | Record an SEO action with hypothesis and metrics to track |
+| `heyseo_add_learning` | Add a key fact or success pattern to site memory |
+| `heyseo_delete_goal` | Delete a goal |
+| `heyseo_memory_snapshots` | Get performance snapshots over time |
+| `heyseo_generate_snapshot` | Generate a new performance snapshot |
+| `heyseo_queue_action` | Queue an action for future implementation |
+| `heyseo_update_queued_action` | Update a queued action's status or priority |
+
+### AI Insights
+
+| Tool | Description |
+|------|-------------|
+| `heyseo_get_insights` | Get AI-generated insights (anomalies, opportunities, alerts, trends) |
+| `heyseo_generate_insights` | Generate new AI insights on demand |
+
+### AI Knowledge
+
+| Tool | Description |
+|------|-------------|
+| `heyseo_get_knowledge` | Get the AI knowledge base for a site |
+| `heyseo_update_knowledge` | Update AI knowledge (business context, competitors, goals) |
+
+### AI Chat
+
+| Tool | Description |
+|------|-------------|
+| `heyseo_chat` | Send a message to the AI assistant about your SEO data |
+
+### Conversations
+
+| Tool | Description |
+|------|-------------|
+| `heyseo_list_conversations` | List AI chat conversations |
+| `heyseo_get_conversation` | Get a conversation with all messages |
+| `heyseo_create_conversation` | Create a new conversation |
+| `heyseo_delete_conversation` | Delete a conversation |
+
+### On-Page Audit
+
+| Tool | Description |
+|------|-------------|
+| `heyseo_onpage_audit` | Run a full on-page SEO audit on any URL |
+| `heyseo_onpage_history` | Get on-page audit history for a site |
+
+### SERP Analysis
+
+| Tool | Description |
+|------|-------------|
+| `heyseo_serp_search` | Search Google SERP for a keyword with organic results, featured snippets, and PAA |
+| `heyseo_serp_history` | Get SERP search history |
+| `heyseo_serp_batch` | Batch SERP preview for multiple keywords at once |
+
+### Sitemaps
+
+| Tool | Description |
+|------|-------------|
+| `heyseo_list_sitemaps` | List sitemaps registered in Google Search Console |
+| `heyseo_submit_sitemap` | Submit a sitemap to Google Search Console |
+| `heyseo_delete_sitemap` | Delete a sitemap from Google Search Console |
+
+### DataForSEO
+
+| Tool | Description |
+|------|-------------|
+| `heyseo_keyword_volume` | Get keyword search volume data for one or more keywords |
+
+### Notifications
+
+| Tool | Description |
+|------|-------------|
+| `heyseo_notification_settings` | Get notification settings |
+| `heyseo_update_notification_settings` | Update notification preferences |
+
+---
+
 ## Resources
 
 Access your SEO data as readable resources:
@@ -210,9 +324,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 +349,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 +367,130 @@ 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
 
-Once a site is selected, you can perform SEO operations:
+### Performance Analysis
 
-**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"
+
+> "Run an indexing check on all monitored pages"
+
+> "Show me the indexing submission history"
+
+### Reports & Insights
+
+> "Show me my latest SEO reports"
+
+> "Generate a new weekly report"
+
+> "What AI insights do you have for my site?"
+
+> "Generate fresh insights for my site"
+
+### 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"
+
+> "Take a performance snapshot"
+
+> "Queue an action to rewrite our FAQ page"
+
+### AI Chat & Knowledge
+
+> "Chat with the AI about my site's SEO performance"
+
+> "Show me the AI knowledge base for this site"
+
+> "Update the knowledge base with our business context"
+
+### 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"
 
+> "Move the title tag task to in-progress"
+
+### Keyword Research
+
+> "Get search volume for 'seo tools', 'seo software', 'seo platform'"
+
+### Sitemaps
+
+> "List my sitemaps from Google Search Console"
+
+> "Submit a new sitemap at /sitemap.xml"
+
 ---
 
-## 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 |
+| `sites:write` | Update or delete sites |
+| `gsc:read` | Read Google Search Console data |
+| `ga4:read` | Read Google Analytics 4 data |
+| `pagespeed:read` | Run PageSpeed analyses and view history |
+| `tasks:read` | Read tasks |
+| `tasks:write` | Create, update, delete, move tasks |
+| `reports:read` | Read AI-generated reports and settings |
+| `reports:write` | Generate, delete reports and update settings |
+| `indexing:read` | Read indexing status, pages, history, settings |
+| `indexing:write` | Submit for indexing, run checks, update settings, remove pages |
+| `memory:read` | Read SEO memory, snapshots |
+| `memory:write` | Update strategy, goals, actions, learnings, snapshots |
+| `insights:read` | Read AI-generated insights |
+| `insights:write` | Generate new insights |
+| `knowledge:read` | Read AI knowledge base |
+| `knowledge:write` | Update AI knowledge |
+| `onpage:read` | Run on-page audits and view history |
+| `serp:read` | Search Google SERP and view history |
+| `sitemaps:read` | Read GSC sitemaps |
+| `sitemaps:write` | Submit or delete GSC sitemaps |
+| `chat:write` | Send messages to AI assistant |
+| `conversations:read` | Read conversations |
+| `conversations:write` | Create or delete conversations |
+| `notifications:read` | Read notification settings |
+| `notifications:write` | Update notification settings |
+| `dataforseo:read` | Access keyword volume data |
+
+Use `all` scope for full access.
 
 ---
 
@@ -325,7 +499,7 @@ The HeySeo MCP server uses explicit site selection to prevent data isolation iss
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
 | `HEYSEO_API_KEY` | Yes | - | Your HeySeo API key |
-| `HEYSEO_API_URL` | No | `https://www.heyseo.app` | Custom API URL |
+| `HEYSEO_API_URL` | No | `https://my.heyseo.app` | Custom API URL |
 
 ## Rate Limits
 
@@ -341,4 +515,4 @@ MIT
 ## Support
 
 - Website: [heyseo.app](https://heyseo.app)
-- Email: support@heyseo.app
+- Email: hello@heyseo.app