Brasil GEO MCP API

openapi: 3.2.0
info:
  title: pública de Alexandre Caramaschi MCP API
  version: 1.13.2
  description: 'Consulta pública de negócio, contato, cursos, texto e mídia das aulas, busca híbrida nas aulas, grafo de conhecimento dos cursos e pesquisa. MCP JSON-RPC e REST legado compartilham /api/mcp. Não envia mensagens, não realiza compras e não expõe administração. O registro de agente (RFC 7591) e o token client_credentials são opcionais: identificam o cliente nas respostas e ampliam o corpo aceito; sem token, tudo continua público.'
servers:
- url: https://alexandrecaramaschi.com
security: []
tags:
- name: MCP
paths:
  /api/mcp:
    get:
      operationId: discoverPublicTools
      summary: Consultar metadados e ferramentas disponíveis
      security:
      - {}
      - agentClientCredentials:
        - mcp:read
      responses:
        '200':
          description: Metadados públicos
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Token Bearer inválido ou expirado; WWW-Authenticate aponta para /.well-known/oauth-protected-resource.
        '403':
          description: Origin não permitida.
        '405':
          description: 'GET com Accept text/event-stream: o servidor não abre canal SSE.'
      tags:
      - MCP
    post:
      operationId: callPublicTool
      summary: Executar chamada MCP ou consulta REST legada
      description: 'MCP exige Accept: application/json, text/event-stream. Após initialize, envie MCP-Protocol-Version negociado. Limite de corpo: 16 KiB sem token; 64 KiB com token de agente válido (Authorization: Bearer). Com token, initialize e tools/call trazem _meta.client_id e a resposta traz X-Agent-Client. Desde a versão 1.8.0, em tools/call, limit e maxChars aceitam também número inteiro, e erro de entrada (argumento desconhecido, tipo ou faixa inválidos) volta como resultado com isError: true e structuredContent {error: ''invalid_argument'', message, argument, accepted}; o erro JSON-RPC -32602 fica para ferramenta desconhecida, arguments que não é objeto e corpo malformado. No REST legado, os argumentos vão no próprio corpo, ao lado de tool, sempre como texto.'
      security:
      - {}
      - agentClientCredentials:
        - mcp:read
      parameters:
      - in: header
        name: MCP-Protocol-Version
        required: false
        schema:
          type: string
          enum:
          - '2026-07-28'
          - '2025-11-25'
          - '2025-06-18'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/RpcRequest'
              - $ref: '#/components/schemas/LegacyRequest'
            examples:
              mcp:
                value:
                  jsonrpc: '2.0'
                  id: 1
                  method: tools/list
              legacy:
                value:
                  tool: listCourses
              legacySearch:
                value:
                  tool: searchContent
                  query: como medir citações em IA
                  limit: '5'
              legacyGraph:
                value:
                  tool: exploreKnowledgeGraph
                  node: x:geo
              mcpGraph:
                value:
                  jsonrpc: '2.0'
                  id: 2
                  method: tools/call
                  params:
                    name: exploreKnowledgeGraph
                    arguments:
                      query: dados estruturados
                      limit: 5
      responses:
        '200':
          description: Resultado público ou erro JSON-RPC
          headers:
            X-Agent-Client:
              description: client_id do agente, presente somente com token válido.
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
        '202':
          description: Notificação MCP aceita, sem corpo.
        '400':
          description: JSON, protocolo ou mensagem inválidos.
      tags:
      - MCP
components:
  schemas:
    LegacyRequest:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    RpcRequest:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
externalDocs:
  url: https://alexandrecaramaschi.com/developers.md
x-markdown-negotiation:
  summary: Qualquer rota pública em HTML responde em Markdown por negociação de conteúdo na própria URL, sem caminho novo.
  request:
    header: Accept
    value: text/markdown
    rule: 'Markdown somente quando q(text/markdown) > 0 e q(text/markdown) > q(text/html), conforme RFC 9110. Curingas */* e text/* não contam. Alias legado: application/llm.'
  response:
    contentType: text/markdown; charset=utf-8
    headers:
    - 'Vary: Accept'
    - 'Link: <url canônica>; rel="canonical"'
    - 'x-markdown-tokens: estimativa (caracteres / 4), método em x-markdown-tokens-method'
    - 'Cache-Control: public, s-maxage=3600, stale-while-revalidate=86400'
    body: Front matter YAML (title, canonical, author, datas, description, language), H1 e seções.
  routes:
  - /
  - /artigos/{slug}
  - /educacao
  - /educacao/{curso}
  - /educacao/{curso}/{capitulo}
  - /insights/{slug}
  - /publicacoes
  - /glossario
  - /faq
  - /cases
  - páginas-pilar da raiz
  excluded:
  - /api/*
  - /admin*
  - /auth/*
  - /_next/*
  - arquivos com extensão
  - /mcp
  - /.well-known/*
  - páginas privadas ou noindex
  - /artefacto/*
  - /guia/*
  - /faq/{sub}
  - /caso/*
  - /landing/*
  example: 'curl -H "Accept: text/markdown" https://alexandrecaramaschi.com/artigos/geo-vs-seo-vs-aeo-o-que-muda-na-pratica'
  docs: https://alexandrecaramaschi.com/developers.md
x-agent-auth:
  summary: Registro dinâmico anônimo e token client_credentials de uma hora, opcionais para o MCP.
  authorization_server_metadata: https://alexandrecaramaschi.com/.well-known/oauth-authorization-server
  protected_resource_metadata: https://alexandrecaramaschi.com/.well-known/oauth-protected-resource/api/mcp
  jwks_uri: https://alexandrecaramaschi.com/.well-known/jwks.json
  docs: https://alexandrecaramaschi.com/auth.md