https://aiscan.site/assets/docs.checks.capabilities-DE_ntV99.js

1import{cn as s,j as e}from"./index-DCkA9xGt.js";import{D as n}from"./DocsLayout-iRTJ5Cog.js";import{F as t,t as o}from"./FurtherReading-W7qHVTL-.js";import"./chevron-left-C0cOdp3D.js";import"./book-open-BY3KF-Tx.js";const i=[{id:"p1",label:"P1 — API Catalog"},{id:"p2",label:"P2 — MCP Server Card"},{id:"p3",label:"P3 — Agent Skills"},{id:"p4",label:"P4 — OAuth discovery"},{id:"e2",label:"E2 — OpenAPI description"}];function p(){const r=s.useLoaderData();return e.jsxs(n,{path:"/docs/checks/capabilities",toc:[...i],children:[e.jsxs("p",{children:["The Capabilities dimension is where reading turns into doing. Each check here exposes a machine-readable manifest of ",e.jsx("em",{children:"what an agent can call"})," on your site — APIs, tools, skills, and the OAuth flow they need to do it authenticated."]}),e.jsxs("h2",{id:"p1",children:["P1 — API Catalog (RFC 9727) ",e.jsx("span",{className:"text-xs text-muted-foreground",children:"(weight 4)"})]}),e.jsxs("p",{children:[e.jsx("a",{href:"https://datatracker.ietf.org/doc/rfc9727/",target:"_blank",rel:"noreferrer",children:"RFC 9727"})," defines"," ",e.jsx("code",{children:"/.well-known/api-catalog"})," — a Linkset document listing every API your site exposes."]}),e.jsx("h4",{children:"How to fix"}),e.jsx("pre",{children:e.jsx("code",{children:`# /.well-known/api-catalog
2{
3  "linkset": [
4    {
5      "anchor": "https://example.com/",
6      "service-desc": [
7        { "href": "https://example.com/api/openapi.json", "type": "application/openapi+json" }
8      ]
9    }
10  ]
11}`})}),e.jsxs("p",{children:["Pair with a ",e.jsx("code",{children:"Link"})," header (",e.jsx("a",{href:"/docs/checks/discoverability#d3",children:"D3"}),") for instant discovery."]}),e.jsxs("h2",{id:"p2",children:["P2 — MCP Server Card ",e.jsx("span",{className:"text-xs text-muted-foreground",children:"(weight 5)"})]}),e.jsxs("p",{children:["Model Context Protocol lets an agent connect to your site as if it were a tool runtime. The convention AIScan checks for: a server card at ",e.jsx("code",{children:"/.well-known/mcp/server-card.json"})," describing the available tools, resources, and prompts."]}),e.jsx("h4",{children:"How to fix"}),e.jsxs("p",{children:["Implement an MCP server (HTTP transport works for most web apps), then publish a server card. See our own live example at ",e.jsx("a",{href:"/.well-known/mcp/server-card.json",target:"_blank",rel:"noreferrer",children:"/.well-known/mcp/server-card.json"}),". Read ",e.jsx("a",{href:"/docs/mcp",children:"MCP Server"})," for the full integration guide."]}),e.jsxs("h2",{id:"p3",children:["P3 — Agent Skills bundle ",e.jsx("span",{className:"text-xs text-muted-foreground",children:"(weight 4)"})]}),e.jsxs("p",{children:["Agent Skills are a portable JSON/Markdown bundle that teaches Claude Code (and compatible runtimes) when to use your service and how to call it. AIScan checks for a discoverable ",e.jsx("code",{children:"aiscan-skill.json"}),"-style bundle plus an accompanying ",e.jsx("code",{children:"CLAUDE.md"}),"."]}),e.jsx("h4",{children:"How to fix"}),e.jsxs("p",{children:["See ",e.jsx("a",{href:"/docs/agent-skill",children:"Agent Skill & CLAUDE.md"})," for the format, plus our own files at"," ",e.jsx("a",{href:"/aiscan-skill.json",children:"/aiscan-skill.json"})," and ",e.jsx("a",{href:"/CLAUDE.md",children:"/CLAUDE.md"})," as a reference."]}),e.jsxs("h2",{id:"p4",children:["P4 — OAuth protected-resource metadata ",e.jsx("span",{className:"text-xs text-muted-foreground",children:"(weight 3)"})]}),e.jsxs("p",{children:["For authenticated APIs, agents need to know which OAuth authorisation server to talk to."," ",e.jsx("a",{href:"https://datatracker.ietf.org/doc/rfc9728/",target:"_blank",rel:"noreferrer",children:"RFC 9728"})," defines"," ",e.jsx("code",{children:"/.well-known/oauth-protected-resource"})," for exactly that."]}),e.jsx("h4",{children:"How to fix"}),e.jsx("pre",{children:e.jsx("code",{children:`# /.well-known/oauth-protected-resource
12{
13  "resource": "https://example.com/api",
14  "authorization_servers": ["https://auth.example.com"],
15  "bearer_methods_supported": ["header"],
16  "scopes_supported": ["read", "write"]
17}`})}),e.jsx("p",{children:"Required only if your site has authenticated APIs — otherwise the check is N/A."}),e.jsxs("h2",{id:"e2",children:["E2 — Machine-readable API description ",e.jsx("span",{className:"text-xs text-muted-foreground",children:"(weight 3, recommended)"})]}),e.jsxs("p",{children:["If your site exposes endpoints, agents shouldn't have to reverse-engineer them. AIScan looks for"," ",e.jsx("code",{children:"/openapi.json"}),", ",e.jsx("code",{children:"/openapi.yaml"}),", ",e.jsx("code",{children:"/api/openapi.json"}),","," ",e.jsx("code",{children:"/.well-known/openapi.json"}),", ",e.jsx("code",{children:"/swagger.json"}),", or a ",e.jsx("code",{children:"service-desc"})," link in your ",e.jsx("a",{href:"https://www.rfc-editor.org/rfc/rfc9727",target:"_blank",rel:"noreferrer",children:"RFC 9727"})," API catalog."]}),e.jsx("p",{children:"On sites we detect as pure content sites, this is reported as an optional improvement rather than a failure — the report says so explicitly instead of silently dropping the check."}),e.jsx("h4",{children:"How to fix"}),e.jsx("pre",{children:e.jsx("code",{children:`# 1. Publish the spec
18GET /openapi.json  ->  200 application/json (OpenAPI 3.1)
19
20# 2. Advertise it
21Link: </openapi.json>; rel="service-desc"; type="application/json"`})}),e.jsxs("p",{children:["Ours is at ",e.jsx("a",{href:"/openapi.json",children:"/openapi.json"}),", linked from"," ",e.jsx("a",{href:"/.well-known/api-catalog",children:"/.well-known/api-catalog"}),"."]}),e.jsx(t,{items:o(r)})]})}export{p as component};