Agent Ready

agent-ready-mcp

Agent Ready 的 MCP 服务 — 根据 Vercel Agent Readability Spec、llmstxt.org 标准和 Agent 协议清单（MCP 服务卡片、A2A、agents.json、agent-permissions.json、UCP、x402、NLWeb），扫描任意 URL，检查其对 AI Agent 的可读性。涵盖四类规范的 72 项检查 — 40 项站点与页面检查（15 项全站检查 + 每页 25 项）、10 项 llmstxt.org 检查，以及 22 项 Agent 协议清单检查 — 每项检查均提供修复指导，另有一项基于 23 项 WCAG 2.2 / 布局稳定性检查的无障碍子评分。

托管于 https://agent-ready.dev/api/v1/mcp（Streamable HTTP）；此软件包是对相同 REST 端点的轻量 stdio 封装，通过 npm 分发，供本地 MCP 客户端（Claude Desktop、Claude Code、Cursor、VS Code、Windsurf）使用。

功能

• scan_site — 对任意 URL 进行全新的 Agent 可读性扫描。匿名免费套餐无需密钥即可使用（每个 IP 每 30 天 3 次扫描，深度为 25 个页面，同步执行）；使用 Pro 密钥时，最多可扫描 250 个页面，并轮询托管 API，最长等待 60 秒。
• get_scan — 按 ID 获取先前运行的扫描（需要 Pro 密钥 — 扫描历史记录按账户区分）。
• ask — 以自然语言（NLWeb）搜索 Agent Ready 自身的方法、检查项和规范。公开使用，无需 API 密钥；返回 Schema.org 类型的结果。
• validate_structured_data — 根据 Agent Ready 的结构化数据检查项，验证页面上的（或粘贴的）JSON-LD。公开使用，无需 API 密钥；粘贴模式无需网络，因此 Agent 可以检查自己刚编写的 JSON-LD。
• 三个发现提示词 — scan、interpret_scan、remediation_plan。涵盖从 URL → 评分 → 修复计划的端到端工作流。
• SKILL.md — Claude Skill 描述文件，位于 skills/agent-ready/，用于激活路由。

设置

开始使用无需密钥：scan_site、ask 和 validate_structured_data 开箱即用，均支持匿名访问（scan_site 使用匿名免费额度 — 每个 IP 每 30 天可扫描 3 次，深度为 25 个页面）。Agent Ready Pro API key 可解锁每月 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	否	—	来自 Agent Ready 仪表板的 Pro Bearer 令牌。不提供此密钥时，scan_site 使用匿名免费套餐，且无法使用 get_scan。
AGENT_READY_API_URL	否	https://agent-ready.dev	用于覆盖可自托管或暂存部署的地址。
AGENT_READY_SCAN_TIMEOUT_MS	否	60000	scan_site 轮询的最长时间，超时后返回 running 占位符。
AGENT_READY_GET_TIMEOUT_MS	否	5000	get_scan 和每次轮询获取数据的超时时间。

工具

工具	输入	返回值
scan_site	url（字符串，必填）、pageLimit（数字，可选，最大 2000 — 受套餐限制；无密钥时固定为 25）	扫描对象：Vercel 评分（0–100）、llms.txt 子评分（0–100），以及包含 howToFix 字符串的各项检查结果。无密钥时使用匿名免费层（每个 IP 每 30 天 3 次扫描），并同步返回；使用 Pro 密钥时，如果扫描耗时超过轮询截止时间，则返回 { id, status: "running" } 占位对象。
get_scan	id（字符串，来自先前 scan_site 调用的扫描 ID）	与 scan_site 相同的扫描对象；如果 ID 未知或不属于经过身份验证的用户，则返回 not_found。需要 Pro 密钥。
ask	q（字符串，必填）、itemType（可选的语料筛选条件）、mode（可选，list 或 summarize）	基于 Agent Ready 的方法、检查项和规范，通过 NLWeb /ask 提问。公开使用 — 无需 API 密钥。返回带有 Schema.org 类型的结果对象。
validate_structured_data	url（字符串）或 jsonld（字符串）二选一	D 系列结构化数据结果：mode、url、各项检查结果和 summary 判定。公开使用 — 无需 API 密钥。验证 schema lint 和 Agent 一致性，这些是第一方验证器不提供的检查。

提示词

提示词	参数	功能
scan	url	执行全新扫描并提供高层摘要（评分、评级、排名前 3–5 的失败项、下一步）。
interpret_scan	id	用通俗易懂的语言解释先前扫描的结果，并按类别分组。
remediation_plan	id、可选的 focus（"seo" 或 "agents"）	优先级排序的修复文档，按 Now/Next/Later 分组，并为每项修复列出检查 ID。

示例工作流

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）

软件包中的 skills/agent-ready/SKILL.md 文件介绍了该技能。要在 Claude Desktop / Claude Code 中使用，请将 skills/agent-ready/ 目录复制到 ~/.claude/skills/。

该技能说明了何时激活（URL + 可读性审计意图）、应选择哪个工具、如何呈现扫描结果而不倾倒原始 JSON，以及何时改用其他工具（一般 SEO、性能分析、代码编辑）。

工作原理

此软件包是一个精简的 stdio→HTTPS 封装器：

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

所有扫描执行、持久化和 Pro 层配额强制管理均在托管服务端进行。npm 软件包只负责在通过 stdio 传输的 MCP JSON-RPC 与 REST API 之间进行转换。

如果你想直接使用托管的 MCP 服务（Streamable HTTP 传输，无需本地安装），请将 MCP 客户端指向 https://agent-ready.dev/api/v1/mcp，并设置 Authorization: Bearer ar_live_...。

方法

72 项检查、权重和评分公式详见 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。