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.
- - /api/v1/profile: who Omar is, roles, interests, links
- - /api/v1/ctf: FlagYard rank, labs, CTF event results
- - /api/v1/bug-bounty: valid findings by severity
- - /api/v1/projects: projects, ?tag= (security, ai, rust ...)
- - /api/v1/achievements: results and events, ?section=
- - /api/v1/certificates: certificates, ?folder=
- - /api/v1/badges: FlagYard and Tuwaiq badges
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.
- - omarafet_get_profile: who Omar is, experience, education, interests, links
- - omarafet_get_ctf_stats: FlagYard rank, labs, CTF event results
- - omarafet_get_bug_bounty_stats: valid findings by severity
- - omarafet_list_projects: projects, filter by tag (security, ai, rust ...)
- - omarafet_list_achievements: results and events, filter by section
- - omarafet_list_certificates: certificates, filter by folder
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":{}}}'