cat ~/docs.md

Developer docs: REST API, MCP server and Markdown

Everything here is public and read-only. Authentication: none, so there is no API key and no sign-in. Responses allow any origin (CORS).

# REST API

Base URL: https://omarafet.vercel.app/api/v1. OpenAPI 3.1 spec: /openapi.json. API catalog (RFC 9727): /.well-known/api-catalog. Every endpoint is GET.

Lists are paginated: ?limit= (1 to 100, default 50) and ?cursor= from next_cursor; a Link header with rel=next points to the next page. Versioning: the version is in the path; a breaking change would go to /api/v2, and /api/v1 keeps its shape.

$ curl https://omarafet.vercel.app/api/v1/projects?tag=security

# Errors

API errors are application/problem+json (RFC 9457) with a code and a hint: not_found (404), invalid_parameter (400), invalid_cursor (400), method_not_allowed (405: the API is read-only).

# Markdown

Request any page with `Accept: text/markdown`, or add `.md` to its path: /index.md, /about.md, /contact.md, /privacy.md, /docs.md. Responses carry `Vary: Accept`. A request that accepts neither HTML nor Markdown gets 406.

$ curl -H 'Accept: text/markdown' https://omarafet.vercel.app/

# llms.txt and sitemap

/llms.txt lists the pages and says when to use this site. /sitemap.xml lists every page.

# MCP server

Endpoint: /mcp (Streamable HTTP, JSON responses, stateless, no auth). Server card: /.well-known/mcp. Protocol versions: 2025-11-25, 2025-06-18, 2025-03-26. Every tool is read-only.

Resources: the Markdown version of each page. Numbers come from FlagYard, bugbounty.sa and CoderHub, refreshed at each deploy.

$ claude mcp add --transport http omarafet https://omarafet.vercel.app/mcp

$ curl -s https://omarafet.vercel.app/mcp -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"omarafet_get_ctf_stats","arguments":{}}}'

cd ~ · docs.md