Agent Discovery

Real-time protocols

Model Context Protocol · Streamable HTTP, JSON-RPC 2.0 POST https://www.gabrimatic.info/api/mcp

Stateless MCP server for the portfolio. It implements initialize, ping, tools/list, tools/call, resources/list, resources/read, prompts/list, and prompts/get. Tools: get_profile, get_journey, get_repos, get_page_markdown. Prompts: profile_overview, hiring_snapshot, repo_tour. Requests must send Accept: application/json, text/event-stream (the streamable HTTP transport requires both). Discovery card at /.well-known/mcp/server-card.json. Try it: curl -s -X POST https://www.gabrimatic.info/api/mcp -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Google Agent-to-Agent (A2A) · JSON-RPC 2.0 POST https://www.gabrimatic.info/api/a2a

Stateless A2A endpoint. It implements message/send, tasks/get, and tasks/cancel. Responses complete synchronously and point back to the sources they rely on. Agent Card at /.well-known/agent-card.json.

WebMCP · in-page tool registration navigator.modelContext on https://www.gabrimatic.info/

When the site loads in an MCP-aware browser, /webmcp.js registers navigate, get_page_markdown, and list_repos via navigator.modelContext.registerTool. Spec: webmachinelearning.github.io/webmcp.

JSON API

/api/repos accepts ?per_page= (1 - 100, default 100) and ?sort= (updated, created, pushed, full_name; default updated). /api/contributions groups merged external public PRs into one project entry with a same-origin logo URL and a link to Soroush's merged PRs in that repository. All endpoints set Access-Control-Allow-Origin: *.

The two live endpoints serve stale copies while revalidating, so the fetchedAt in a cached response can legitimately lag: up to one day beyond the fresh cache window. Each payload carries its own cache object stating exactly that policy - check it before flagging a timestamp as stale.

The JSON API is described by /openapi.json (OpenAPI 3.1). /api/profile and /api/journey return an ETag; send If-None-Match to skip unchanged bodies. A bare GET /api returns a JSON index of every live endpoint, and an unknown /api/* path returns a 404 that carries the same map, so a wrong guess always shows the way back.

OAuth 2.1 authorization server

An optional OAuth authorization server issues client tokens. Portfolio reads remain public, and tokens do not unlock additional data. Dynamic Client Registration supports loopback agent callbacks and same-site callbacks; authorization requires exact redirect_uri matching against the registration.

OAuth registration creates a client, not a user account or a verified agent identity. All reads are public, and their handlers do not validate bearer tokens. The site does not advertise an agent_auth claim flow. See /auth.md for the actual limits.

Access tokens are EdDSA-signed JWTs (typ: at+jwt), iss = https://www.gabrimatic.info, aud = https://www.gabrimatic.info/api/mcp, 1 hour TTL. Supported scopes: mcp:read, mcp:tools.

Markdown for Agents

Every page route returns Markdown when the request carries Accept: text/markdown. Direct *.md URLs are equivalent. This keeps the visual Flutter app and the retrievable text connected to the same source of truth.

curl -s -H 'Accept: text/markdown' https://www.gabrimatic.info/journey

Discovery

AI Catalog/.well-known/ai-catalog.json

AI Catalog 1.0 listing the existing MCP server card, A2A card, OpenAPI description, and portfolio skill. No new services are implied.

llms.txt · LLM agent quickstart /llms.txt

Single Markdown file in the de-facto llms.txt format. Lists the JSON endpoints, Markdown alternates, MCP/A2A discovery cards, and OAuth surfaces. It is the shortest path from a domain name to useful context. The companion /llms-full.txt is every page's Markdown concatenated in reading order, for agents that want the whole site in one request.

Agent Skills index · v0.2.0 /.well-known/agent-skills/index.json

Lists each SKILL.md with a SHA-256 digest so agents can cache it and verify what they read.

API Catalog · RFC 9727 /.well-known/api-catalog

Linkset advertising the APIs, discovery cards, and Markdown alternates exposed by the site.

Sitemap /sitemap.xml

Standard XML sitemap, also advertised through RFC 8288 Link headers on /.

RFC 8288 Link headers HEAD /

The root route returns Link headers for the sitemap, /llms.txt, Agent Skills index, A2A card, MCP server card, OAuth AS metadata, OAuth protected resource, API catalog, HTTP message signatures directory, this agents page, the Markdown alternate, and service links for /api/mcp and /api/a2a.

Content Signals /robots.txt

Content-Signal: search=yes, ai-input=yes, ai-train=no: retrieval and user-requested answering are allowed; training use is not. Training-only crawlers are blocked by user-agent.