feat(plugin): skill 222a-seo-audit (переработан из Codex-версии)
This commit is contained in:
Alex
parent
632e979727
commit
8462929a39
112
plugins/222a-seo-audit/skills/222a-seo-audit/SKILL.md
Normal file
112
plugins/222a-seo-audit/skills/222a-seo-audit/SKILL.md
Normal file
@ -0,0 +1,112 @@
|
||||
---
|
||||
name: "222a-seo-audit"
|
||||
description: "Use when working with 222A SEO audit data: running audits, analyzing technical issues, GSC/Yandex metrics, generating client reports. Triggers: SEO audit, technical SEO, аудит сайта, GSC, Yandex Webmaster, core web vitals."
|
||||
---
|
||||
|
||||
# 222A MCP Audit
|
||||
|
||||
Use the 222A MCP server for SEO audit context instead of scraping local database tables or asking for raw exports. The MCP contract intentionally exposes safe, manager-level audit data and hides raw HTML, headers, screenshots, logs, and low-level check payloads.
|
||||
|
||||
## Quick Start
|
||||
|
||||
1. The 222A MCP server is preconfigured by this plugin (`.mcp.json`). It connects to `https://222a.ru/api/mcp` using a Bearer token from `MCP_222A_TOKEN` env variable.
|
||||
2. The user creates the token at `https://222a.ru/lk/ai-tokens` (see plugin README).
|
||||
3. Use `mcp.read` for context and existing analyses; use `mcp.write` when saving durable audit work back to 222A.
|
||||
4. Read `references/mcp-contract.md` before manual JSON-RPC calls, debugging, or saving analyses.
|
||||
5. Treat `https://222a.ru/ai/capabilities.json` as the shared capability manifest.
|
||||
|
||||
## Common Workflow
|
||||
|
||||
- When the user asks what 222A can do, call `get_available_actions`, read `222a://capabilities`, or use REST `GET /api/v1/ai-audit-workspace/actions`, then present the returned action menu.
|
||||
- For the full manager workflow, use `run_project_audit_and_save_summary` from the shared manifest: `list_projects`, choose an existing project or create one with `create_project` when missing, `start_audit`, `get_audit_status`, `get_audit_context`, then `save_audit_artifact`.
|
||||
- For recurring monitoring, use `schedule_project_audit`: `list_projects`, then `schedule_audit` with a real `project_id`, cron expression, and timezone. Use `list_audit_schedules`, `update_audit_schedule`, and `delete_audit_schedule` to inspect or change periodic runs.
|
||||
- For recommendation work, use `analyze_audit_and_save_recommendations`: `get_audit_workspace_summary`, `get_audit_context`, `list_audit_artifacts`, then save as `seo_recommendations` when write access exists.
|
||||
- For role-based specialist tasks, use `prepare_specialist_tasks`: split the work into SEO, content, and development tasks, then save useful outputs as `seo_recommendations`, `content_tasks`, and `developer_tasks`.
|
||||
- For client-facing reports, use `create_client_report_from_ready_artifacts`: check workspace state, inspect artifacts, then use `create_client_report` for `client_ready` work and save as `client_report`.
|
||||
- To inspect affected URLs for one issue, take `issue_code` from `get_audit_context` and call `get_issue_pages` instead of asking for raw page checks. This also covers supported aggregate-only duplicate issues such as `seo.duplicate_title`, `seo.duplicate_meta_description`, `seo.duplicate_h1`. Always inspect `evidence_type` and `evidence[]`: Google CTR issues can include `gsc_page_metrics`, Yandex position drops can include `yandex_webmaster_queries`, site-level sitemap misses can include `sitemap_discovery`, duplicate H1 returns `duplicate_h1_groups`, near-duplicate text returns `near_duplicate_groups`, URL structure issues return `url_samples` or `mixed_case_groups`, and hreflang issues return `hreflang_*` evidence types. Page-level checks (schema, og, viewport, redirect_chain, perf.dom_too_large, perf.no_compression, viewport_bad, js_errors, content.missing_author/date/stale, tap_targets_small, font_too_small, heading_hierarchy_broken) include per-page `data` with the specific finding (problems list, missing tags, hop chain, metric values, samples).
|
||||
- To inspect all problems for one URL, take `page_id` from `get_issue_pages` and call `get_page_audit` instead of asking for raw page checks.
|
||||
- Distinguish `tech.internal_broken_link` (high — REAL broken: target is 4xx/5xx or genuinely missing) from `tech.target_not_crawled` (info — target was discovered but skipped by crawl policy: max_pages_cap, robots_disallowed). For target_not_crawled NEVER call these «broken links» — recommend increasing `max_pages` (especially when `top_uncrawled_targets[].incoming_count` is high — those URLs appear in nav/footer of many pages and are likely important categories like /articles, /sitemap) or adjusting robots.txt.
|
||||
- To find near-duplicates of a page across the team's other completed audits (e.g. the same content appearing on two projects, or content stolen between sites), call `find_similar_pages_across_audits` with `audit_run_id` + `page_id`/`url`. Default similarity threshold is 0.85; lower it (e.g. 0.7) to widen the search. Returns matches sorted by similarity with project/audit context. Pages without sufficient text return `reason=no_simhash`.
|
||||
- When reading `get_audit_context`, inspect `progress_since_previous` first. If it is available, use it for the quick "what was fixed / what organically appeared" manager summary, including `top_resolved_pages` and `top_appeared_pages` when present, then call `compare_audits` only when the user needs drill-down. `appeared_issues_count` is organic; treat `appeared_due_to_new_data_source_count` and `top_appeared_due_to_new_data_source` as new evidence from a newly connected source, not as site degradation. `resolved_issues_count` is organic; treat `resolved_due_to_data_source_unavailable_count` and `top_resolved_due_to_data_source_unavailable` as false-positive resolutions caused by a previously connected source going offline — do NOT report them as real fixes. Perf issues (cls/inp/page_weight) that toggle severity around lab thresholds across runs are flagged is_flaky=true and isolated into `appeared_flaky_count`, `resolved_flaky_count`, `changed_flaky_count`, and `top_flaky_issues` — treat them as measurement noise, do NOT highlight them as progress or regression. Site-level (audit-wide) issues such as ya.*, seo.duplicate_*, tech.crawled_not_in_sitemap, seo.url_*, content.near_duplicate, seo.hreflang_*, seo.indexed_not_crawled live in a separate set of counts (site_appeared_issues_count/site_resolved_issues_count/site_changed_issues_count and top_site_appeared_issues/top_site_resolved_issues/top_site_changed_issues), with the same data-source disambiguation (site_appeared_due_to_new_data_source / site_resolved_due_to_data_source_unavailable). Report them as audit-wide changes (affecting many URLs at once) distinct from per-URL page issues.
|
||||
- To explain progress between two completed audits, call `compare_audits` and save useful conclusions as `progress_comparison` when write access exists. Treat the issue `changed` bucket as severity changes; same-severity persistent issues are in `unchanged`.
|
||||
- When monitoring an audit, poll politely, avoid tight loops, and always keep `audit_run_id` visible so the user can resume later.
|
||||
- List resources to discover available audits: `resources/list`.
|
||||
- Read `audit://{audit_run_id}/context` or call `get_audit_context` before analysis.
|
||||
- Read `audit://{audit_run_id}/workspace-summary` or call `get_audit_workspace_summary` when deciding whether to create/update a manager synthesis or client report. Use `workspace.progress_since_previous` for a quick progress note when available.
|
||||
- Read `audit://{audit_run_id}/analyses` before writing, to avoid duplicating prior conclusions.
|
||||
- Save durable, manager-facing output with `save_audit_artifact` unless the user explicitly says not to save it.
|
||||
- Set `source` to `"claude-code"`.
|
||||
|
||||
## AI Artifacts
|
||||
|
||||
When the user asks for an analysis, plan, comparison, client text, or recommendations, save the result back to 222A as an append-only artifact unless they explicitly say not to save it. This keeps a durable history of work by different AI clients and specialists.
|
||||
|
||||
Use:
|
||||
- `list_projects` to find existing projects before starting audits.
|
||||
- `create_project` to create a new current-team project only after confirming it is not already in `list_projects`.
|
||||
- `start_audit` to start a new audit for an existing current-team project.
|
||||
- `get_audit_status` to monitor safe progress metadata.
|
||||
- `schedule_audit` to create a periodic audit schedule for an existing current-team project.
|
||||
- `list_audit_schedules`, `update_audit_schedule`, and `delete_audit_schedule` to manage periodic audit schedules.
|
||||
- `get_issue_pages` to list safe page URLs, titles, and HTTP statuses for a specific issue code.
|
||||
- `get_page_audit` to list all safe issue summaries for one specific page.
|
||||
- `compare_audits` to compare two completed audits and summarize progress.
|
||||
- `get_audit_workspace_summary` to understand saved AI work, latest synthesis, client-ready count, channels, progress since previous audit, and recommended next actions.
|
||||
- `list_audits` before choosing an audit.
|
||||
- `get_audit_context` to read safe audit data.
|
||||
- `list_audit_artifacts` to inspect existing work.
|
||||
- `synthesize_audit_artifacts` to combine saved specialist/AI work into a manager synthesis.
|
||||
- `create_client_report` to build a client-facing report from `client_ready` artifacts.
|
||||
- `save_audit_artifact` to create a new artifact.
|
||||
|
||||
Never overwrite existing artifacts. If you revise previous work, pass `parent_artifact_id` and create a new artifact.
|
||||
|
||||
Preferred artifact types:
|
||||
- `executive_summary`
|
||||
- `work_plan`
|
||||
- `progress_comparison`
|
||||
- `client_report`
|
||||
|
||||
## Prompt templates
|
||||
|
||||
The shared capability manifest at `https://222a.ru/ai/capabilities.json` publishes `prompt_templates` for user-facing audit workflows:
|
||||
|
||||
- `list_projects`
|
||||
- `create_project`
|
||||
- `start_project_audit`
|
||||
- `schedule_project_audit`
|
||||
- `check_audit_status`
|
||||
- `get_issue_pages`
|
||||
- `get_page_audit`
|
||||
- `compare_audits`
|
||||
- `run_audit_then_save_summary` (`run_project_audit_and_save_summary`)
|
||||
- `analyze_audit_and_save_recommendations`
|
||||
- `prepare_specialist_tasks`
|
||||
- `list_audits`
|
||||
- `latest_audit_summary`
|
||||
- `save_executive_summary`
|
||||
- `save_work_plan`
|
||||
- `manager_synthesis`
|
||||
- `create_client_report`
|
||||
- `do_not_save`
|
||||
|
||||
When durable work uses `mcp.write`, save it append-only unless the user explicitly says not to save it.
|
||||
|
||||
## Slash Commands
|
||||
|
||||
This plugin provides 5 slash commands for common workflows. When a user's request matches one of these, suggest the corresponding command:
|
||||
|
||||
- `/222a-audit <url|project_id>` — full audit cycle: project → start → poll → executive summary → save artifact
|
||||
- `/222a-status [audit_run_id]` — current/specified audit status; defaults to latest from `list_audits`
|
||||
- `/222a-issue <issue_code> [audit_run_id]` — unpack one issue: pages + remediation + evidence
|
||||
- `/222a-report [audit_run_id]` — build client report from `client_ready` artifacts via `create_client_report`
|
||||
- `/222a-progress [audit_run_id]` — compare with previous audit via `progress_since_previous` or `compare_audits`
|
||||
|
||||
The commands trigger the same workflows described above with standardized output and automatic artifact saving.
|
||||
|
||||
## Analysis Rules
|
||||
|
||||
- Treat MCP context as the source of truth for what is safe to show to the model.
|
||||
- Do not request raw HTML, screenshots, headers, cookies, console logs, or full crawler payloads.
|
||||
- If `save_audit_artifact` or `save_audit_analysis` fails with an MCP scope error, report that the token needs `mcp.write`.
|
||||
- If a read tool returns an empty result with `visible=false` or a `hint`, follow the hint: usually call `list_audits`, choose a visible audit, or ask the user for the right audit.
|
||||
@ -0,0 +1,722 @@
|
||||
# 222A MCP Contract
|
||||
|
||||
## Endpoint
|
||||
|
||||
- Production URL: `https://222a.ru/api/mcp`
|
||||
- Local URL: use `APP_URL` plus `/api/mcp`
|
||||
- Transport: Streamable HTTP
|
||||
- Protocol: JSON-RPC 2.0 over POST
|
||||
- MCP protocol version returned by `initialize`: `2025-06-18`
|
||||
- Auth: `Authorization: Bearer <token>`
|
||||
|
||||
Create tokens in the 222A LK page `/lk/ai-tokens`.
|
||||
|
||||
Shared machine-readable capability manifest:
|
||||
|
||||
- Production URL: `https://222a.ru/ai/capabilities.json`
|
||||
- Repository source: `backend/resources/ai/222a-ai-capabilities.json`
|
||||
|
||||
Manifest v2 fields:
|
||||
|
||||
- `contract_version`: version identifier for the published AI workspace contract.
|
||||
- `scopes`: token scopes and what each one authorizes.
|
||||
- `source_clients`: allowed client identifiers for saved artifacts and analyses.
|
||||
- `links`: canonical URLs for MCP, skill archives, token management, and related resources.
|
||||
- `mcp_tools`: MCP tool descriptions, scopes, input schemas, and output expectations.
|
||||
- `mcp_resources`: resource URIs/templates exposed to MCP clients.
|
||||
- `rest_api`: REST mirror metadata and endpoint contracts.
|
||||
- `recommended_workflows`: named multi-step workflows clients should compose from existing tools/endpoints.
|
||||
- `prompt_templates`: user-facing prompt templates for common audit workflows.
|
||||
|
||||
Shared REST API for future clients:
|
||||
|
||||
- Production base path: `https://222a.ru/api/v1/ai-audit-workspace`
|
||||
- Auth: the same user-owned Sanctum Bearer token and `mcp.read` / `mcp.write` scopes.
|
||||
- Purpose: expose the same audit workspace operations to non-MCP clients without creating a separate domain contract.
|
||||
- Action menu: `GET /actions` mirrors `get_available_actions` and accepts optional `audit_run_id`.
|
||||
- Schedule endpoints mirror MCP schedule tools: `POST /projects/{project_id}/audit-schedules`, `GET /audit-schedules`, `PATCH /audit-schedules/{schedule_id}`, and `DELETE /audit-schedules/{schedule_id}`.
|
||||
|
||||
## Scopes
|
||||
|
||||
- `mcp.read`: list/read audit resources and call read tools.
|
||||
- `mcp.write`: includes read access and allows saving append-only AI artifacts.
|
||||
|
||||
Tokens can also have `ai-tasks.*` scopes, but those are for pull-mode AI workers, not audit MCP analysis.
|
||||
|
||||
## Resources
|
||||
|
||||
`resources/list` returns resources for the current token user's current or first accessible team.
|
||||
|
||||
Resource templates:
|
||||
|
||||
- `audit://{audit_run_id}/context`
|
||||
- `audit://{audit_run_id}/analyses`
|
||||
- `audit://{audit_run_id}/workspace-summary`
|
||||
|
||||
Static resources:
|
||||
|
||||
- `222a://capabilities`: available user-facing actions, workflows, prompt templates, artifact types, links, and save-back behavior.
|
||||
|
||||
`audit://.../context` includes safe audit summary data such as project identity, run stats, issue index, page samples, saved AI analyses, and AI summary status. It does not include raw HTML bodies, raw check data, console logs, headers, cookies, or screenshots.
|
||||
|
||||
`audit://.../analyses` returns saved AI analyses/artifacts for the audit run, including author metadata.
|
||||
|
||||
`audit://.../workspace-summary` returns the same manager-friendly AI workspace state as `get_audit_workspace_summary`: artifact counts, latest manager synthesis, client-ready count, channels, progress since previous audit, next actions, and the save-back rule.
|
||||
|
||||
`222a://capabilities` mirrors `get_available_actions` for clients that prefer MCP resources over tools.
|
||||
|
||||
## Save-Back Rule
|
||||
|
||||
222A is an append-only AI workspace for SEO audits. When an AI client produces durable audit work for a user, it should save the result back to 222A with `save_audit_artifact` whenever `mcp.write` is available, unless the user explicitly asks not to save.
|
||||
|
||||
Durable audit work includes executive summaries, work plans, progress comparisons, client reports, technical notes, SEO recommendations, content tasks, developer tasks, and manager syntheses.
|
||||
|
||||
Before saving, inspect existing work with `list_audit_artifacts` when an `audit_run_id` is known. Never overwrite previous work. If revising a previous artifact, create a new artifact and pass `parent_artifact_id`.
|
||||
|
||||
## Tools
|
||||
|
||||
### `get_available_actions`
|
||||
|
||||
Requires `mcp.read`.
|
||||
|
||||
Input:
|
||||
|
||||
```json
|
||||
{
|
||||
"audit_run_id": 123
|
||||
}
|
||||
```
|
||||
|
||||
Output includes the user-facing action menu from the shared manifest: prompt templates, recommended workflows, artifact types, save-back rule, and links. Use this when the user asks what 222A can do, what to do next, or which audit actions are available. `audit_run_id` is optional and substitutes `<audit_run_id>` placeholders in returned prompts.
|
||||
|
||||
### `list_projects`
|
||||
|
||||
Requires `mcp.read`.
|
||||
|
||||
Input:
|
||||
|
||||
```json
|
||||
{
|
||||
"limit": 10
|
||||
}
|
||||
```
|
||||
|
||||
Output includes current-team projects and latest audit hints in `structuredContent.projects`. Use this before starting audits. Do not invent `project_id` values.
|
||||
|
||||
### `create_project`
|
||||
|
||||
Requires `mcp.write`.
|
||||
|
||||
Input:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Example project",
|
||||
"root_url": "https://example.com"
|
||||
}
|
||||
```
|
||||
|
||||
Creates a current-team project for a new audit target and returns the created project payload. Call `list_projects` first and use this only when the needed site is not already present.
|
||||
|
||||
### `start_audit`
|
||||
|
||||
Requires `mcp.write`.
|
||||
|
||||
Input:
|
||||
|
||||
```json
|
||||
{
|
||||
"project_id": 45
|
||||
}
|
||||
```
|
||||
|
||||
Starts an audit for an existing current-team project. Only call this after the project id came from `list_projects` or an equivalent REST project list.
|
||||
|
||||
### `get_audit_status`
|
||||
|
||||
Requires `mcp.read`.
|
||||
|
||||
Input:
|
||||
|
||||
```json
|
||||
{
|
||||
"audit_run_id": 123
|
||||
}
|
||||
```
|
||||
|
||||
Returns safe status and progress metadata. Poll politely and expose `audit_run_id` so the user can resume the workflow later.
|
||||
|
||||
### `schedule_audit`
|
||||
|
||||
Requires `mcp.write`.
|
||||
|
||||
Input:
|
||||
|
||||
```json
|
||||
{
|
||||
"project_id": 45,
|
||||
"cron_expression": "0 3 * * *",
|
||||
"timezone": "Europe/Moscow",
|
||||
"audit_options": {
|
||||
"max_pages": 500
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Creates one enabled periodic audit schedule for an existing current-team project. Cron expressions must not run more often than once per hour, and each project can have only one active schedule. Output includes `schedule_id`, `next_run_at`, `cron_expression`, `timezone`, `is_enabled`, `last_run_at`, `last_audit_run_id`, and `audit_options`.
|
||||
|
||||
### `list_audit_schedules`
|
||||
|
||||
Requires `mcp.read`.
|
||||
|
||||
Input:
|
||||
|
||||
```json
|
||||
{
|
||||
"project_id": 45
|
||||
}
|
||||
```
|
||||
|
||||
Returns current-team audit schedules in `structuredContent.schedules`. `project_id` is optional.
|
||||
|
||||
### `update_audit_schedule`
|
||||
|
||||
Requires `mcp.write`.
|
||||
|
||||
Input:
|
||||
|
||||
```json
|
||||
{
|
||||
"schedule_id": 12,
|
||||
"cron_expression": "0 4 * * *",
|
||||
"timezone": "Europe/Moscow",
|
||||
"audit_options": {
|
||||
"max_pages": 1000
|
||||
},
|
||||
"is_enabled": true
|
||||
}
|
||||
```
|
||||
|
||||
Updates schedule settings and recalculates `next_run_at`. Set `is_enabled=false` to pause the schedule without deleting it.
|
||||
|
||||
### `delete_audit_schedule`
|
||||
|
||||
Requires `mcp.write`.
|
||||
|
||||
Input:
|
||||
|
||||
```json
|
||||
{
|
||||
"schedule_id": 12
|
||||
}
|
||||
```
|
||||
|
||||
Deletes one current-team audit schedule and returns `{ "deleted": true }`.
|
||||
|
||||
### `list_audits`
|
||||
|
||||
Requires `mcp.read`.
|
||||
|
||||
Input:
|
||||
|
||||
```json
|
||||
{
|
||||
"limit": 10
|
||||
}
|
||||
```
|
||||
|
||||
Output includes current-team audits newest first in `structuredContent.audit_runs`. Use this before choosing an audit when the user asks for projects, audits, recent audits, latest audits, or audit history.
|
||||
|
||||
### `get_audit_context`
|
||||
|
||||
Requires `mcp.read`.
|
||||
|
||||
Input:
|
||||
|
||||
```json
|
||||
{
|
||||
"audit_run_id": 123
|
||||
}
|
||||
```
|
||||
|
||||
Output includes the same safe context as `audit://123/context` in `structuredContent`. When a previous completed audit exists for the same project, `progress_since_previous` summarizes the adjacent diff: previous/current audit ids and finish times, resolved and organically appeared issue counts, issues attributed to newly connected data sources, issues attributed to data sources that became unavailable, improved/worsened severity counts, flaky perf counts (`appeared_flaky_count`, `resolved_flaky_count`, `changed_flaky_count`, `top_flaky_issues`), site-level issue counts (`site_appeared_issues_count`, `site_resolved_issues_count`, `site_changed_issues_count`, `top_site_appeared_issues`, `top_site_resolved_issues`, `top_site_changed_issues`, plus parallel `site_appeared_due_to_new_data_source_count` / `site_resolved_due_to_data_source_unavailable_count` and `top_site_*` variants), page deltas, `top_resolved_pages`, `top_appeared_pages`, HTTP status recovery/regression counts, score/page-crawl deltas, and top safe issue samples. `appeared_issues_count` is organic; explain `appeared_due_to_new_data_source_count` and `top_appeared_due_to_new_data_source` separately as new evidence, not automatic site degradation. `resolved_issues_count` is organic; explain `resolved_due_to_data_source_unavailable_count` and `top_resolved_due_to_data_source_unavailable` separately as false-positive resolutions caused by a previously connected source going offline, not real fixes. Flaky perf issues are kept out of `appeared`/`resolved`/`changed` buckets and routed to `appeared_flaky`/`resolved_flaky`/`changed_flaky` instead — these are measurement noise around lab thresholds, not real progress or regression. Site-level issues (ya.*, seo.duplicate_*, tech.crawled_not_in_sitemap, seo.url_*, content.near_duplicate, seo.hreflang_*, seo.indexed_not_crawled) are tracked separately in the `site_issues` bucket — they affect many URLs at once, not single pages. Use this for a quick manager answer about what was fixed since the last audit; call `compare_audits` for full drill-down (`compare_audits` payload includes both `issues` and `site_issues` buckets).
|
||||
|
||||
### `get_issue_pages`
|
||||
|
||||
Requires `mcp.read`.
|
||||
|
||||
Input:
|
||||
|
||||
```json
|
||||
{
|
||||
"audit_run_id": 123,
|
||||
"issue_code": "seo.missing_h1",
|
||||
"limit": 25
|
||||
}
|
||||
```
|
||||
|
||||
Output includes safe page-level findings in `structuredContent`: audit/project identity, issue metadata, `pages_count`, `total_pages_count`, `has_more`, and a `pages` list with `page_id`, `url`, `title`, and `http_status`. It supports normal page-check issues and supported aggregate-only duplicate issues such as `seo.duplicate_title` and `seo.duplicate_meta_description`. It can also return `evidence_type` and `evidence` for non-page signals: `evidence_type=gsc_page_metrics` for Google Search Console CTR issues, `evidence_type=yandex_webmaster_queries` for Yandex query issues such as `ya.position_dropped`, and `evidence_type=sitemap_discovery` for site-level `tech.sitemap_missing`. It does not include raw HTML, headers, screenshots, or raw check payloads.
|
||||
|
||||
Use this after `get_audit_context` when the user asks which URLs are affected by a specific issue. For `seo.high_impressions_low_ctr`, include clicks, impressions, CTR, and position from `pages[].gsc` or `evidence[]`. For `seo.indexed_not_crawled`, `page_id` can be null and fragment URLs are collapsed to the canonical URL with source samples. For `ya.position_dropped`, show `query_text`, `position_before`, `position_after`, and `delta_positions` from `evidence[]`. For `tech.sitemap_missing`, show `checked_paths`, robots Sitemap directives, and probe statuses. If both `pages` and `evidence` are empty, use the returned hint and suggest checking `issue_code` from the context.
|
||||
|
||||
### `get_page_audit`
|
||||
|
||||
Requires `mcp.read`.
|
||||
|
||||
Input:
|
||||
|
||||
```json
|
||||
{
|
||||
"audit_run_id": 123,
|
||||
"page_id": 456
|
||||
}
|
||||
```
|
||||
|
||||
`url` may be used instead of `page_id` when the exact audit page URL is known. Output includes safe page metadata and all issue summaries for that page: code, severity, category, Russian title, and Russian description. It does not include raw HTML, headers, screenshots, console logs, network failures, or raw check payloads.
|
||||
|
||||
Use this after `get_issue_pages` when the user asks what exactly is wrong on a specific URL.
|
||||
|
||||
### `compare_audits`
|
||||
|
||||
Requires `mcp.read`.
|
||||
|
||||
Input:
|
||||
|
||||
```json
|
||||
{
|
||||
"base_audit_run_id": 123,
|
||||
"compare_audit_run_id": 124,
|
||||
"limit": 10
|
||||
}
|
||||
```
|
||||
|
||||
Output includes safe progress buckets for two completed current-team audits of the same project: `metrics`, issue buckets (`appeared`, `resolved`, `changed`, `unchanged`), and page buckets (`appeared`, `resolved`, `content_changed`, `robots_changed`, `unchanged`). Issue `changed` means severity changed; persistent same-severity issues are in `unchanged`. Bucket items include safe URLs, issue codes, severities, HTTP statuses, and robots statuses. They do not include raw check payloads, raw HTML, headers, screenshots, or content hashes.
|
||||
|
||||
Use this when the user asks for progress between audits. If the result is useful and `mcp.write` is available, save the conclusion append-only as `artifact_type=progress_comparison`.
|
||||
|
||||
### `get_audit_workspace_summary`
|
||||
|
||||
Requires `mcp.read`.
|
||||
|
||||
Input:
|
||||
|
||||
```json
|
||||
{
|
||||
"audit_run_id": 123
|
||||
}
|
||||
```
|
||||
|
||||
Output includes manager-friendly AI workspace state in `structuredContent.workspace`: artifact counts, human revisions, client-ready count, channels used by AI/LK/API clients, latest manager synthesis metadata, new artifact count after that synthesis, `progress_since_previous`, recommended next actions, and the save-back rule.
|
||||
|
||||
Use this before deciding what to do next on an audit. If it recommends `update_manager_synthesis`, call `synthesize_audit_artifacts`. If it recommends `create_client_report`, call `create_client_report`.
|
||||
|
||||
### `list_audit_artifacts`
|
||||
|
||||
Requires `mcp.read`.
|
||||
|
||||
Input:
|
||||
|
||||
```json
|
||||
{
|
||||
"audit_run_id": 123,
|
||||
"limit": 10
|
||||
}
|
||||
```
|
||||
|
||||
Output includes already saved AI work for the audit in `structuredContent.artifacts`.
|
||||
|
||||
### `synthesize_audit_artifacts`
|
||||
|
||||
Requires `mcp.read`. Requires `mcp.write` only when `save` is `true`.
|
||||
|
||||
Input:
|
||||
|
||||
```json
|
||||
{
|
||||
"audit_run_id": 123,
|
||||
"limit": 10,
|
||||
"save": true,
|
||||
"title": "Manager synthesis",
|
||||
"source_client": "codex_skill"
|
||||
}
|
||||
```
|
||||
|
||||
Output includes a manager-facing synthesis draft in `structuredContent.summary_markdown`, the source artifacts used, and `saved_artifact` when `save=true`.
|
||||
|
||||
Use this when a manager wants a combined conclusion from several saved AI/specialist artifacts. If the synthesis is useful and `mcp.write` is available, save it as `manager_synthesis`.
|
||||
|
||||
### `create_client_report`
|
||||
|
||||
Requires `mcp.read`. Requires `mcp.write` only when `save` is `true`.
|
||||
|
||||
Input:
|
||||
|
||||
```json
|
||||
{
|
||||
"audit_run_id": 123,
|
||||
"limit": 10,
|
||||
"save": true,
|
||||
"title": "Client report",
|
||||
"source_client": "codex_skill"
|
||||
}
|
||||
```
|
||||
|
||||
Output includes a client-facing report draft in `structuredContent.summary_markdown`, only `client_ready` source artifacts, and `saved_artifact` when `save=true`.
|
||||
|
||||
Use this when a manager wants a client report from already approved AI/specialist work. It saves append-only as `client_report`.
|
||||
|
||||
### `save_audit_artifact`
|
||||
|
||||
Requires `mcp.write`.
|
||||
|
||||
Input:
|
||||
|
||||
```json
|
||||
{
|
||||
"audit_run_id": 123,
|
||||
"artifact_type": "executive_summary",
|
||||
"title": "Executive summary",
|
||||
"summary_markdown": "## Summary\n...",
|
||||
"structured_blocks": [],
|
||||
"recommendations": [
|
||||
{
|
||||
"title": "Fix missing H1",
|
||||
"priority": "high"
|
||||
}
|
||||
],
|
||||
"metadata": {
|
||||
"model": "codex",
|
||||
"prompt_version": "manual/v1"
|
||||
},
|
||||
"status": "draft",
|
||||
"source_client": "codex_skill",
|
||||
"source_actor_type": "ai",
|
||||
"source": "mcp-codex",
|
||||
"ai_model": "gpt",
|
||||
"prompt_version": "audit-artifact/v1"
|
||||
}
|
||||
```
|
||||
|
||||
Required fields: `audit_run_id`, `artifact_type`, `title`, `summary_markdown`.
|
||||
|
||||
Optional fields: `structured_blocks`, `recommendations`, `metadata`, `status`, `visibility`, `parent_artifact_id`, `source_client`, `source_actor_type`, `source`, `ai_model`, `prompt_version`.
|
||||
|
||||
The saved artifact is attached to the audit run, team, current token user, and current access token. Saving is append-only: the server creates a new record and never overwrites previous work.
|
||||
|
||||
Artifact types:
|
||||
|
||||
- `executive_summary`
|
||||
- `work_plan`
|
||||
- `progress_comparison`
|
||||
- `client_report`
|
||||
- `technical_notes`
|
||||
- `seo_recommendations`
|
||||
- `content_tasks`
|
||||
- `developer_tasks`
|
||||
- `manager_synthesis`
|
||||
|
||||
### `save_audit_analysis`
|
||||
|
||||
Requires `mcp.write`.
|
||||
|
||||
Compatibility tool for older analysis clients. Prefer `save_audit_artifact` for new MCP, skill, and ChatGPT App integrations.
|
||||
|
||||
## REST API Mirror
|
||||
|
||||
Future API, Actions, bot, or custom client integrations should use the same artifact language and save-back rule. The REST API mirrors the core MCP workspace operations:
|
||||
|
||||
- `GET /api/v1/ai-audit-workspace/audits`
|
||||
- `GET /api/v1/ai-audit-workspace/audits/latest/context`
|
||||
- `GET /api/v1/ai-audit-workspace/projects`
|
||||
- `POST /api/v1/ai-audit-workspace/projects`
|
||||
- `GET /api/v1/ai-audit-workspace/audits/{audit_run_id}/context`
|
||||
- `GET /api/v1/ai-audit-workspace/audits/{audit_run_id}/issues/{issue_code}/pages`
|
||||
- `GET /api/v1/ai-audit-workspace/audits/{base_audit_run_id}/compare/{compare_audit_run_id}`
|
||||
- `GET /api/v1/ai-audit-workspace/audits/{audit_run_id}/pages/{page_id}/audit`
|
||||
- `GET /api/v1/ai-audit-workspace/audits/{audit_run_id}/workspace-summary`
|
||||
- `GET /api/v1/ai-audit-workspace/audits/{audit_run_id}/artifacts`
|
||||
- `POST /api/v1/ai-audit-workspace/audits/{audit_run_id}/artifacts`
|
||||
- `POST /api/v1/ai-audit-workspace/audits/{audit_run_id}/artifact-synthesis`
|
||||
- `POST /api/v1/ai-audit-workspace/audits/{audit_run_id}/client-report`
|
||||
|
||||
Use `source_client: "future_client"` for REST clients that are not ChatGPT App, Codex skill, Claude skill, internal AI, or manual LK actions.
|
||||
|
||||
## Recommended Workflows
|
||||
|
||||
The manifest publishes `recommended_workflows` so MCP, skills, ChatGPT Apps, and future clients perform the same manager workflows without adding long-running server-side jobs.
|
||||
|
||||
### `run_project_audit_and_save_summary`
|
||||
|
||||
Purpose: start a fresh audit for an existing project, monitor completion, read safe audit context, and save a durable executive summary back to 222A.
|
||||
|
||||
Tool chain:
|
||||
|
||||
`list_projects → start_audit → get_audit_status → get_audit_context → list_audit_artifacts → save_audit_artifact`
|
||||
|
||||
Rules:
|
||||
|
||||
- Use only projects returned by `list_projects` or `GET /api/v1/ai-audit-workspace/projects`.
|
||||
- Ask the user to choose if several projects are plausible.
|
||||
- Do not invent `project_id` or `audit_run_id`.
|
||||
- Do not claim completion until `get_audit_status` returns a terminal completed state.
|
||||
- Poll politely; if the client session may time out, return `audit_run_id` and ask the user to continue later.
|
||||
- If the audit fails or is cancelled, report the final status and safe error text; do not invent an analysis.
|
||||
- If `mcp.write` is available and the user did not ask not to save, save the manager-facing result append-only as `artifact_type=executive_summary`.
|
||||
|
||||
### `analyze_audit_and_save_recommendations`
|
||||
|
||||
Purpose: turn safe audit data and existing AI work into prioritized SEO recommendations for a manager.
|
||||
|
||||
Tool/resource chain:
|
||||
|
||||
`get_audit_workspace_summary → get_audit_context → list_audit_artifacts → save_audit_artifact`
|
||||
|
||||
Resource-capable clients can use:
|
||||
|
||||
`audit://{audit_run_id}/workspace-summary → audit://{audit_run_id}/context → audit://{audit_run_id}/analyses`
|
||||
|
||||
Rules:
|
||||
|
||||
- Start with workspace summary when `audit_run_id` is known so you understand existing work, latest synthesis, client-ready count, and next actions.
|
||||
- Read safe audit context before making recommendations.
|
||||
- Inspect existing artifacts before saving to avoid duplicating prior conclusions.
|
||||
- Do not request or expose raw HTML, headers, screenshots, cookies, console logs, or raw check payloads.
|
||||
- If `mcp.write` is available and the user did not ask not to save, save append-only as `artifact_type=seo_recommendations`.
|
||||
- If write scope is missing, still provide useful recommendations and clearly say they were not saved.
|
||||
|
||||
### `prepare_specialist_tasks`
|
||||
|
||||
Purpose: split audit findings and saved AI work into role-specific tasks for SEO, content, and development specialists.
|
||||
|
||||
Tool/resource chain:
|
||||
|
||||
`get_audit_workspace_summary → get_audit_context → list_audit_artifacts → save_audit_artifact`
|
||||
|
||||
Save targets:
|
||||
|
||||
- `seo_recommendations` for SEO specialist recommendations.
|
||||
- `content_tasks` for copy, content structure, metadata, and editorial tasks.
|
||||
- `developer_tasks` for redirects, canonicals, templates, rendering, performance, security, and implementation tasks.
|
||||
|
||||
Rules:
|
||||
|
||||
- Start with workspace summary and existing artifacts to avoid duplicating previous specialist work.
|
||||
- Make each task actionable and testable: priority, reason from audit data, expected result, and verification step.
|
||||
- Save separate append-only artifacts for each useful role output when `mcp.write` is available.
|
||||
- If a role has no meaningful work, say so instead of inventing tasks.
|
||||
- If write scope is missing, provide the role-specific tasks and clearly say they were not saved.
|
||||
|
||||
### `create_client_report_from_ready_artifacts`
|
||||
|
||||
Purpose: turn approved AI/specialist work into a client-facing report.
|
||||
|
||||
Tool/resource chain:
|
||||
|
||||
`get_audit_workspace_summary → list_audit_artifacts → create_client_report`
|
||||
|
||||
Resource-capable clients can use:
|
||||
|
||||
`audit://{audit_run_id}/workspace-summary → audit://{audit_run_id}/analyses`
|
||||
|
||||
Rules:
|
||||
|
||||
- Start with workspace summary to check `client_ready_count`, latest manager synthesis, and next actions.
|
||||
- Inspect saved artifacts and include only material that is ready for the client.
|
||||
- Prefer `create_client_report` over hand-writing this artifact because it uses the shared 222A client report builder.
|
||||
- If `mcp.write` is available and the user did not ask not to save, call `create_client_report` with `save=true` and save append-only as `artifact_type=client_report`.
|
||||
- If there are no `client_ready` artifacts, say which internal artifacts should be reviewed or marked ready first.
|
||||
|
||||
## REST Endpoint Contracts
|
||||
|
||||
Each endpoint in `rest_api.endpoints` describes the same contract shape:
|
||||
|
||||
- `method`: HTTP verb.
|
||||
- `path`: path relative to `/api/v1/ai-audit-workspace`.
|
||||
- `scope`: required token scope, usually `mcp.read` or `mcp.write`.
|
||||
- `purpose`: human-readable reason to call the endpoint.
|
||||
- `request_example`: example query parameters or JSON body.
|
||||
- `response_shape`: high-level response fields clients should expect.
|
||||
- `mcp_equivalent`: matching MCP tool or resource for clients that use JSON-RPC.
|
||||
|
||||
These endpoint contracts keep REST clients aligned with MCP clients and the same append-only save-back behavior.
|
||||
|
||||
## Prompt Template IDs
|
||||
|
||||
The manifest publishes these `prompt_templates` IDs:
|
||||
|
||||
- `list_projects`
|
||||
- `create_project`
|
||||
- `start_project_audit`
|
||||
- `check_audit_status`
|
||||
- `get_issue_pages`
|
||||
- `get_page_audit`
|
||||
- `compare_audits`
|
||||
- `run_audit_then_save_summary`
|
||||
- `analyze_audit_and_save_recommendations`
|
||||
- `prepare_specialist_tasks`
|
||||
- `list_audits`
|
||||
- `latest_audit_summary`
|
||||
- `save_executive_summary`
|
||||
- `save_work_plan`
|
||||
- `manager_synthesis`
|
||||
- `create_client_report`
|
||||
- `do_not_save`
|
||||
|
||||
These are user-facing prompts for clients and UI actions, not secret system prompts.
|
||||
|
||||
## JSON-RPC Examples
|
||||
|
||||
Initialize:
|
||||
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 1,
|
||||
"method": "initialize"
|
||||
}
|
||||
```
|
||||
|
||||
List tools:
|
||||
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 2,
|
||||
"method": "tools/list"
|
||||
}
|
||||
```
|
||||
|
||||
Read audit context resource:
|
||||
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 3,
|
||||
"method": "resources/read",
|
||||
"params": {
|
||||
"uri": "audit://123/context"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Call context tool:
|
||||
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 4,
|
||||
"method": "tools/call",
|
||||
"params": {
|
||||
"name": "get_audit_context",
|
||||
"arguments": {
|
||||
"audit_run_id": 123
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Get pages affected by one issue:
|
||||
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 5,
|
||||
"method": "tools/call",
|
||||
"params": {
|
||||
"name": "get_issue_pages",
|
||||
"arguments": {
|
||||
"audit_run_id": 123,
|
||||
"issue_code": "seo.missing_h1",
|
||||
"limit": 25
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
List audits:
|
||||
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 6,
|
||||
"method": "tools/call",
|
||||
"params": {
|
||||
"name": "list_audits",
|
||||
"arguments": {
|
||||
"limit": 10
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Save artifact:
|
||||
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 7,
|
||||
"method": "tools/call",
|
||||
"params": {
|
||||
"name": "save_audit_artifact",
|
||||
"arguments": {
|
||||
"audit_run_id": 123,
|
||||
"artifact_type": "executive_summary",
|
||||
"title": "SEO audit executive summary",
|
||||
"summary_markdown": "## Summary\nThe audit shows...",
|
||||
"recommendations": [],
|
||||
"status": "draft",
|
||||
"source_client": "codex_skill",
|
||||
"source_actor_type": "ai",
|
||||
"metadata": {
|
||||
"model": "codex"
|
||||
},
|
||||
"source": "mcp-codex"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Synthesize artifacts and save the result:
|
||||
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 8,
|
||||
"method": "tools/call",
|
||||
"params": {
|
||||
"name": "synthesize_audit_artifacts",
|
||||
"arguments": {
|
||||
"audit_run_id": 123,
|
||||
"save": true,
|
||||
"title": "Manager synthesis",
|
||||
"source_client": "codex_skill"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 9,
|
||||
"method": "tools/call",
|
||||
"params": {
|
||||
"name": "create_client_report",
|
||||
"arguments": {
|
||||
"audit_run_id": 123,
|
||||
"save": true,
|
||||
"title": "Client report",
|
||||
"source_client": "codex_skill"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
- HTTP 401: missing or invalid Bearer token.
|
||||
- HTTP 403: token is valid but lacks any `mcp.*` scope.
|
||||
- JSON-RPC error `-32003`: required MCP scope is missing, usually `mcp.write`.
|
||||
- JSON-RPC error `-32004`: a write operation could not find the target project, audit run, or parent artifact, so the write did not happen.
|
||||
- Read-only audit tools avoid `-32004` for missing/invisible audits. They return `isError=false`, empty arrays such as `issues`, `artifacts`, `pages`, or `source_artifacts`, and a `hint` telling the client to use `list_audits` or save the missing prerequisite work first.
|
||||
- JSON-RPC error `-32602`: unsupported URI, unknown tool, or invalid arguments.
|
||||
Loading…
Reference in New Issue
Block a user