# seoreport - AI Agent Integration

This file describes how an AI agent can interact with seoreport via the Model Context Protocol (MCP).

## Connection

- **MCP endpoint:** `https://seoreport.dev/mcp`
- **Protocol:** Streamable HTTP (JSON-RPC 2.0)
- **Content-Type:** `application/json`

## Authentication

MCP access is tied to the user's account.

1. The user signs in with a browser at `https://seoreport.dev`.
2. The user creates an API key at `https://seoreport.dev/dashboard/api-keys`.
3. The key is shown once. Store it in the agent's local secret store or environment, not in prompts, project files, shell history, chat transcripts, or logs.
4. Send the key on every MCP request:

```
Authorization: Bearer <your-api-key>
```

Use the same key for direct API calls and MCP calls when both surfaces are available. Rotate or revoke keys from the account/API-key dashboard if a key may have been exposed.

## Capabilities

Discover current capabilities with `tools/list`. Tool names are stable enough to automate against, but agents should still call `tools/list` at session start so they can adapt when the project adds, removes, or renames tools.

## Product Tools

### seoreport_create_report

Start a technical SEO audit of a website. Use when the user wants a site or page audited; SEOReport fetches the URL, so it must be publicly reachable. Pass wait=true to get the finished report back in the same call (reports take up to about 30 seconds); otherwise you get a job ID to poll with seoreport_get_report_status. Each report uses one credit from the account plan (seoreport_get_account shows the balance); without an active plan, use seoreport_list_plans and seoreport_start_checkout first.

**Parameters:**
- `url` (required): The website or page URL to audit, e.g. https://example.com. Without a scheme, https:// is assumed.
- `wait`: If true, wait up to about 30 seconds and return the finished report (score and top findings) inline. If it is not finished by then, poll seoreport_get_report_status with the returned jobId. Default false.

### seoreport_get_report_status

Check whether a report started with seoreport_create_report has finished. Returns its status, stage and isSnapshotReady; once isSnapshotReady is true, read the findings with seoreport_get_report or download it with seoreport_get_report_download. Poll no faster than the pollAfterMs seoreport_create_report returned. Only this account's reports are visible.

**Parameters:**
- `jobId` (required): The report job ID returned by seoreport_create_report or seoreport_list_reports.

### seoreport_get_report

Read a finished report: the overall score, the score per area, and the issues in fix order, each with severity, why it matters, how to fix it, what the audit observed and the pages affected. Use once the report is ready (seoreport_get_report_status shows isSnapshotReady). By default only open issues are returned, most important first; filter by severity or area, or set includePassed to see everything. For a file to keep or share, use seoreport_get_report_download.

**Parameters:**
- `jobId` (required): The report job ID returned by seoreport_create_report or seoreport_list_reports.
- `severity`: Lowest severity to include, e.g. high returns critical and high issues. Omit for all severities.
- `area`: Only findings in this area: an id from the areas list in an earlier response, e.g. security or structured_data.
- `includePassed`: If true, include passed and informational results as well as issues. Default false.
- `limit`: How many findings to return, from 1 to 200 (default 25). matchingFindings gives the total.

### seoreport_list_reports

List this account's most recent reports, newest first, with job ID, target URL, status and whether each is ready. Use it to find a job ID for seoreport_get_report or seoreport_get_report_download, or to check for an earlier report before starting a new one.

**Parameters:**
- `limit`: How many reports to return, from 1 to 50 (default 10).

### seoreport_get_report_download

Get a download URL for a finished report as PDF, Markdown, plain text or JSON. Use when the user wants a file to keep or share; to discuss the findings in the conversation, use seoreport_get_report instead. The report must be finished (seoreport_get_report_status shows isSnapshotReady). Fetch the URL with the same API key in the Authorization header.

**Parameters:**
- `jobId` (required): The report job ID returned by seoreport_create_report or seoreport_list_reports.
- `format`: File format: pdf (default), markdown, text or json.

### seoreport_submit_feedback

Send feedback to the SEOReport team: a feature request, bug report, question, praise or complaint. Use when the user voices a need or a problem with SEOReport during the session, and tell them you are sending it. Requires an active plan. Identical text sent again within a few minutes is refused as a duplicate.

**Parameters:**
- `content` (required): The feedback in the user's own words, 10 to 2000 characters.
- `category`: What kind of feedback this is; omit when unsure.

## Account Tools

### seoreport_get_account

Show the account this API key acts for: name and email, the active plan with its status and renewal date, and the report credits used and remaining this period with when they reset. Use it to confirm which account you are working for, before starting several reports, or when seoreport_create_report says the credits are used up.

**Parameters:**
None

## Billing Tools

### seoreport_list_plans

List the SEOReport subscription plans from the live catalog: plan ID, name, billing interval, monthly report credits and included features. Use when the account has no active plan or wants to change plan; pass the chosen plan ID to seoreport_start_checkout.

**Parameters:**
None

### seoreport_start_checkout

Create a checkout link for a subscription plan. Use after the user picks a plan from seoreport_list_plans. The user must open the returned URL in a browser and pay there; the agent cannot complete payment. Once paid, the plan is active and seoreport_create_report works.

**Parameters:**
- `planId` (required): The plan ID from seoreport_list_plans, e.g. 'pro-monthly'.

## Quick Start

1. Ask the user to sign in and create an API key at `https://seoreport.dev/dashboard/api-keys`.
2. Store the key in a local secret store or environment variable controlled by the agent runtime.
3. Initialize the MCP session, call `tools/list`, then call the specific tool needed for the user's task.

### Initialize

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": { "name": "agent", "version": "1.0.0" }
  }
}
```

### List Tools

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}
```

### Call A Tool

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "seoreport_create_report",
    "arguments": {}
  }
}
```

## Safety Rules

- Never put the API key in a URL query string.
- Never print the API key in logs or user-visible responses.
- Treat account, billing, checkout, deletion, and publishing tools as user-confirmed actions.
- For browser-only actions such as checkout or cancellation confirmation, return the URL to the user instead of trying to automate payment or account confirmation inside the agent.