@heyseo/mcp-server 0.1.3 → 0.2.1

package/README.md

@@ -1,6 +1,12 @@
-# HeySeo MCP Server
+<div align="center">
+  <img src="https://heyseo.app/img/logo.svg" alt="HeySeo Logo" width="200" />
 
-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.
+  # HeySeo MCP Server
+
+  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
 
@@ -144,6 +150,16 @@ Restart Claude Desktop, Cursor, or your MCP client to load the new server.
 
 ## Available Tools
 
+### Site Management
+
+**Select a site before running SEO operations.** The MCP server requires explicit site selection to ensure data isolation and prevent accidental cross-site operations.
+
+| Tool | Description |
+|------|-------------|
+| `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 |
+
 ### Google Search Console
 
 | Tool | Description |
@@ -188,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:
@@ -196,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
 
@@ -214,39 +287,114 @@ 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 |
 
 ---
 
 ## Usage Examples
 
-**Get top keywords:**
-> "What are my top 10 keywords this month?"
+### Site Selection (Start here!)
 
-**Run an SEO audit:**
-> "Run an SEO audit on my site"
+Before performing any SEO operations, you must select a site:
+
+**List available sites:**
+> "Show me all my connected sites"
+
+**Select a site:**
+> "Select the site with ID: abc123def456"
+
+**Check current site:**
+> "What site am I currently working with?"
+
+### Performance Analysis
+
+> "What are my top 10 keywords this month?"
 
-**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"
+
+---
+
+## 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.
+
 ---
 
 ## Environment Variables
@@ -263,23 +411,6 @@ Pre-built prompts for common SEO tasks:
 
 ---
 
-## Development
-
-```bash
-# Clone the repo
-git clone https://github.com/heyseo/mcp-server
-cd mcp-server
-
-# Install dependencies
-npm install
-
-# Build
-npm run build
-
-# Test locally
-HEYSEO_API_KEY=your_key node dist/index.js
-```
-
 ## License
 
 MIT
@@ -287,4 +418,4 @@ MIT
 ## Support
 
 - Website: [heyseo.app](https://heyseo.app)
-- Email: support@heyseo.app
+- Email: hello@heyseo.app