agent-ready-mcp

MCP сервер для Agent Ready — сканируйте любой URL на читаемость агента AI в соответствии с [Vercel Agent Readability Spec], стандартом [llmstxt.org], и манифестами agent-protocol (MCP server cards, A2A, agents.json, agent-permissions.json, UCP, x402, NLWeb). 69 проверок по четырём семействам спецификаций — 38 для Vercel spec (15 на уровне сайта + 23 на странице), 10 для llmstxt.org и 21 для манифестов agent-protocol — каждая с рекомендациями по исправлениям по каждой проверке, плюс отдельная подоценка доступности из 23 проверок WCAG 2.2 / стабильности компоновки.

Размещён по адресу https://agent-ready.dev/api/v1/mcp (Streamable HTTP); этот пакет представляет собой тонкую обёртку stdio вокруг тех же REST-эндпойнтов, распространяется через npm для локальных MCP-клиентов (Claude Desktop, Claude Code, Cursor, VS Code, Windsurf).

Возможности

scan_site — свежее сканирование читаемости агента по любому URL. Работает без ключа на анонимном бесплатном тарифе (3 скана/30 дней на IP, глубина до 25 страниц, синхронно); с Pro-ключом сканирует до 250 страниц, опрашивая hosted API до 60 секунд.
get_scan — получение ранее запущенного скана по id (требуется Pro-ключ — история сканов привязана к учётной записи).
ask — поиск на естественном языке (NLWeb) по собственной методологии Agent Ready, проверкам и спецификациям. Публично, API-ключ не требуется; возвращает результаты в формате Schema.org.
validate_structured_data — валидация JSON-LD страницы (или вставленного текста) по проверкам структурированных данных Agent Ready. Публично, API-ключ не требуется; режим вставки не требует сети, поэтому агент может проверить JSON-LD, который он сам создал.
Три промпта обнаружения — scan, interpret_scan, remediation_plan. Полные рабочие процессы от URL → оценка → план исправления.
SKILL.md — описание навыка Claude, включённое в skills/agent-ready/ для маршрутизации активации.

Настройка

Без ключа начать можно: scan_site, ask и validate_structured_data работают анонимно «из коробки» (сканирование scan_site в рамках бесплатной анонимной квоты — 3 скана за 30 дней на IP, глубина до 25 страниц). Пропуск Pro API-ключа для Agent Ready разблокирует 50 сканов в месяц, глубину до 250 страниц, историю сканов (get_scan) и еженедельный мониторинг — зарегистрируйтесь на [agent-ready.dev] и получите ключ в [панель управления]. Блок env в конфигурациях ниже опционален; пропустите его, чтобы запускать без ключа.

Claude Desktop

Добавьте в ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) или %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "agent-ready": {
      "command": "npx",
      "args": ["-y", "agent-ready-mcp@latest"],
      "env": {
        "AGENT_READY_API_KEY": "ar_live_..."
      }
    }
  }
}

Claude Code

claude mcp add agent-ready \
  -e AGENT_READY_API_KEY=ar_live_... \
  -- npx -y agent-ready-mcp@latest

Cursor / VS Code / Windsurf

.cursor/mcp.json, .vscode/mcp.json, или ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "agent-ready": {
      "command": "npx",
      "args": ["-y", "agent-ready-mcp@latest"],
      "env": {
        "AGENT_READY_API_KEY": "ar_live_..."
      }
    }
  }
}

Переменные окружения

Переменная	Обязательна	По умолчанию	Назначение
AGENT_READY_API_KEY	Нет	—	Привилегированный токен Bearer из панели Agent Ready. Без него `scan_site` использует анонимную бесплатную квоту, а `get_scan` недоступен.
AGENT_READY_API_URL	Нет	https://agent-ready.dev	Переопределение для self-hosted или staging-развертываний.
AGENT_READY_SCAN_TIMEOUT_MS	Нет	60000	Сколько времени `scan_site` опрашивает перед возвращением placeholder-значения.
AGENT_READY_GET_TIMEOUT_MS	Нет	5000	Таймаут для `get_scan` и для отдельных запросов опроса.

Инструменты

Инструмент	Вводы	Возвращает
scan_site	url (строка, обязательно), pageLimit (число, необязательно, макс 2000 — ограничено планом; для безплатного тарифa — фиксировано 25)	Объект скана: балл Vercel 0–100, подбалл llms.txt 0–100, результаты по каждой проверке с текстом howToFix. Безключевые запуски возвращают синхронно; для Pro-ключа возвращаются `{ id, status: "running" }` как placeholder, если скан превысил срок опроса.
get_scan	id (строка, идентификатор скана из предыдущего вызова scan_site)	Такой же объект скана, как у scan_site, или `not_found`, если id неизвестен или не принадлежит аутентифицированному пользователю. Требуется Pro-ключ.
ask	q (строка, обязательно), itemType (необязательно — фильтр по корпусу), mode (необязательно — list или summarize)	NLWeb /ask по методологии, проверкам и спецификациям Agent Ready. Публично — API-ключ не нужен. Результаты в формате, совместимом со Schema.org.
validate_structured_data	ровно один из url (строка) или jsonld (строка)	Результат структурированных данных D-сериа: режим, url, результаты по проверкам и сводная вердиктика. Публично — API-ключ не требуется. Валидирует lint схемы и согласованность агента, которые не покрывают встроенные валидаторы первого лица.

Промпты

Промпт	Аргументы	Что делает
scan	url	Свежий скан + обзор высокого уровня (оценка, рейтинг, топ-3 ошибки, следующий шаг).
interpret_scan	id	Пояснение Plain-English к результатам предыдущего скана, сгруппированное по категориям.
remediation_plan	id, необязательное focus ("seo" или "agents")	Приоритезированный документ по исправлениям с блоками Now/Next/Later и per-fix check ids.

Пример рабочего процесса

You: Use agent-ready to scan https://my-saas.com
Claude: [calls scan_site] Your site scored 78/100 (Good) on the Vercel Agent
        Readability Spec. The top 3 fixes: …
You: Can you build me a remediation plan?
Claude: [calls remediation_plan with the scan id] Here's the prioritised list…

Навык (Anthropic Claude Skills)

SKILL.md лежит в skills/agent-ready/SKILL.md внутри пакета. Чтобы использовать его в Claude Desktop / Claude Code, скопируйте каталог skills/agent-ready/ в ~/.claude/skills/.

Навык описывает, когда активировать (URL + intent аудит читаемости), какой инструмент выбрать, как выводить результаты скана без вывода сырого JSON и когда передавать управление другим инструментам (общий SEO, профилирование производительности, редактирование кода).

Как это работает

Этот пакет — тонкий обёртка stdio→HTTPS:

MCP client (stdio) ↔ agent-ready-mcp ↔ HTTPS ↔ agent-ready.dev/api/v1/scans

Все выполнение скана, сохранение данных и контроль квоты Pro-уровня происходят на размещённом сервере. NPM-пакет лишь обеспечивает перевод между MCP JSON-RPC поверх stdio и REST API.

Если вы хотите использовать размещённый MCP-сервер напрямую (передача через Streamable HTTP, установка локально не требуется), укажите ваш MCP-клиенту адрес https://agent-ready.dev/api/v1/mcp и заголовок Authorization: Bearer ar_live_....

Методология

69 проверок, их веса и формула расчета оценки задокументированы на [agent-ready.dev/methodology]. И manifest.json, и server.json в этом репозитории соответствуют соответствующим схемам реестра (Glama Marketplace v0.3 и MCP registry 2025-12-11 соответственно).

Разработка

npm install
npm run build       # → dist/mcp-server.mjs
npm test
npm run typecheck

Выпуск

См. RELEASE.md. Это единый источник правды для версий, локальных проверок, пуша тегов, гайдингов GitHub Actions выпуска, и ручных шагов после релиза.

Лицензия

MIT — см. LICENSE.