Skip to content

docs: contagem do catalogo bate com o repo, e UCP/AP2 param de sugerir endpoint vivo - #225

Merged
fabianocruz merged 3 commits into
mainfrom
docs/catalogo-honesto
Aug 28, 2026
Merged

fabianocruz merged 3 commits into
mainfrom
docs/catalogo-honesto

Conversation

@fabianocruz

Copy link
Copy Markdown
Member

Onda de texto: o produto fica como esta, a superficie publica para de afirmar o que o codigo nao faz. Nenhum comportamento de codigo mudou (as duas edicoes em src/ sao comentario).

Um achado por linha

Achado Frase publicada O que o codigo faz Frase que ficou
catalog-satellites#1 (contagem) README.md:8 "127 MCP servers for LATAM commerce" packages/ tem 129 diretorios com server.json (git ls-tree -r origin/main --name-only | grep -c '^packages/.*/server\.json$' => 129; python3 scripts/audit-catalog.py (scripts/audit-catalog.py:76-84, discover_servers() = glob packages/*/*/server.json) imprime "Servers scanned: 129") "MCP servers for LATAM commerce · live in the official MCP Registry · MIT License". Sem numero cravado no hero: ele ja derivou de 110 para 127 (commit 22ee3ff) e derivou de novo.
catalog-satellites#1 (ponteiro) README.md:11 "Live machine-readable count: codespar.dev/api/servers" curl https://codespar.dev/api/servers responde "count":133 hoje, com 133 entradas. Nao bate com os 129 do repo, e a rota vive em outro repo "Machine-readable catalog: codespar.dev/api/servers". O link fica (ele foi posto de proposito em 22ee3ff), a palavra "count" sai, porque nao consigo provar que aquele numero e a contagem deste repo.
catalog-satellites#1 (17 invisiveis) ## All Servers com 112 linhas de servidor; headers "Payments (42 servers)", "Banking (12)", "Identity & KYC (5)", "Crypto (9)", "Argentina (5)", "Colombia (5)", "Mexico (6)" 17 pacotes existiam em packages/ e nao apareciam em tabela nenhuma: argentina/payway, banking/iniciador, banking/midaz, banking/pluggy, banking/pomelo, colombia/bold-co, colombia/cobre, colombia/epayco, crypto/coinbase-cdp, identity/bigdatacorp, identity/caf, identity/certta, mexico/clip, payments/flow-cl, payments/kushki, payments/niubiz, payments/pagbrasil As 17 linhas entraram na tabela da categoria delas e os headers viraram 46 / 16 / 8 / 10 / 6 / 8 / 7. Agora sao 129 linhas de servidor, uma por packages/<cat>/<slug>/server.json, e cada header e igual ao numero de linhas embaixo dele.
catalog-satellites#3 (UCP) README.md:61 "Google's full commerce stack for AI agents" packages/payments/ucp/src/index.ts:69-71: BASE_URL = SANDBOX ? "https://sandbox.commerce.googleapis.com/ucp/v1" : "https://commerce.googleapis.com/ucp/v1". Medido hoje: curl https://commerce.googleapis.com/ucp/v1/products => HTTP 404 com a pagina generica Error 404 (Not Found)!!1 do frontend Google; curl https://sandbox.commerce.googleapis.com/ucp/v1 => curl exit 60 (TLS) A frase saiu. A linha ficou com o marcador <sub>no live endpoint</sub> e a descricao do surface de tools ("agentic shopping, cart, checkout, orders, delivery, identity"), que e o que as 20 schemas realmente declaram. Nota logo abaixo da tabela diz o endereco, o 404 e o TLS.
catalog-satellites#3 (AP2) README.md:64 "60+ partners including Visa, Mastercard, Stripe, PayPal" packages/payments/ap2/src/index.ts:60-62: BASE_URL = SANDBOX ? "https://sandbox.ap2.googleapis.com/v1" : "https://ap2.googleapis.com/v1". Medido hoje: curl https://ap2.googleapis.com/v1/mandates => HTTP 404 com a mesma pagina generica; curl https://sandbox.ap2.googleapis.com/v1 => exit 60, verbose imprime subjectAltName does not match host name sandbox.ap2.googleapis.com A frase saiu (nao da para prova-la contra codigo nenhum). A linha ficou com <sub>no live endpoint</sub>, e a mesma nota vale para as duas.

Controle positivo do 404

Um 404 sozinho nao distingue "servico nao registrado" de "sonda quebrada". curl https://storage.googleapis.com/storage/v1/b (servico googleapis registrado de verdade) responde HTTP 400 com JSON estruturado {"error":{"code":400,"message":"Required parameter: project"}}. Os dois hosts do catalogo respondem a pagina HTML generica do frontend, que e o que um nome *.googleapis.com devolve quando nao ha servico registrado embaixo dele.

Como conferir as 17 linhas novas sem reabrir a investigacao

Cada linha nova tem 4 campos, e os 4 saem do proprio pacote:

  • Tools: veio do header ## Tools (N) do README do pacote, e foi conferido contando as declaracoes de tool no src/index.ts (name: "..." dentro do array de ListToolsRequestSchema, ou chamadas server.tool( nos pacotes que usam McpServer). Bateu nos 17: payway 6, iniciador 9, midaz 5, pluggy 16, pomelo 9, bold-co 7, cobre 8, epayco 8, coinbase-cdp 15, bigdatacorp 10, caf 9, certta 11, clip 6, flow-cl 8, kushki 10, niubiz 4, pagbrasil 3.
  • npm: campo name do package.json do pacote.
  • Auth: lido no src/index.ts. OAuth2 so onde ha troca de credencial por token: pomelo (packages/banking/pomelo/src/index.ts:68-75, POST {AUTH_URL}/oauth/token com grant_type: "client_credentials"). API Key (optional) no midaz porque packages/banking/midaz/src/index.ts:57 so manda Authorization se MIDAZ_API_KEY existir. User/Password no niubiz porque packages/payments/niubiz/src/index.ts:66 monta Basic base64(NIUBIZ_USER:NIUBIZ_PASSWORD).
  • Nenhuma das 17 levou <sub>alpha</sub>: todas estao em 0.1.x sem sufixo -alpha no package.json e sem TODO(verify) no fonte, que e o que marca alpha aqui (controle: packages/banking/itau esta em 0.2.0-alpha.3 com 19 TODO(verify)).

Checagem que roda em cima do resultado, e que passa:

  • 129 linhas de servidor nas tabelas == 129 packages/*/*/server.json, sem sobra dos dois lados.
  • todos os 12 headers (N servers) iguais a contagem de linhas da tabela deles.
  • nas 129 linhas, Tools == ## Tools (N) do README do pacote e npm == name do package.json. Zero divergencia.

O que este PR de proposito NAO fez

  • Nao mexi em docs/catalog-audit-2026-04-30.md:3 ("Servers scanned: 111"). E relatorio gerado e datado no proprio nome do arquivo; 111 era verdade quando foi gerado. Reescrever numero de relatorio datado e falsificar registro, nao consertar doc.
  • Nao escrevi "em breve", "em rollout" nem "planned" para UCP/AP2. Nenhum dos tres da para provar contra o codigo de hoje. O que ficou escrito e so o que foi medido: o endereco que o servidor chama e o que aquele endereco responde.
  • Nao toquei codespar.dev/api/servers (count 133): a rota vive em outro repo.
  • Nao toquei x402 nem Stripe ACP: o achado desta lane e sobre ap2 e ucp, e nao medi os outros dois.
  • Nao mudei comportamento. As duas edicoes em src/index.ts sao bloco de comentario, e o motivo de existirem e que o docstring e onde o proximo dev olha antes de gastar um dia contra um host morto.

Fora do alcance desta lane

catalog-satellites#9 (o kya/verify.mjs que resolve did:web pela API da CodeSpar e imprime VERIFIED para mandato vencido) esta em codespar/agentic-payments-standards, que nao e este repo. Segue sem conserto, e a metade do "VERIFIED para vencido" e defeito de codigo, nao de texto.

fabianocruz and others added 2 commits August 27, 2026 12:40
…e endpoint

Two published claims did not hold against the code.

1) Server count. The README hero said "127 MCP servers" and the tables
   listed 112 rows, while packages/ holds 129 directories with a
   server.json (scripts/audit-catalog.py prints "Servers scanned: 129").
   Seventeen servers existed in packages/ but appeared in no table:
   argentina/payway, banking/iniciador, banking/midaz, banking/pluggy,
   banking/pomelo, colombia/bold-co, colombia/cobre, colombia/epayco,
   crypto/coinbase-cdp, identity/bigdatacorp, identity/caf,
   identity/certta, mexico/clip, payments/flow-cl, payments/kushki,
   payments/niubiz, payments/pagbrasil.

   The hero no longer carries a hardcoded number (it drifted from 110 to
   127 already), the seventeen missing rows are now in their category
   tables, and every per-category header count now equals the number of
   rows under it. Table rows: 129, one per packages/<cat>/<slug>/
   server.json. Each new row's tool count comes from that package's own
   "## Tools (N)" header and was cross-checked by counting the tool
   declarations in its src/index.ts; each npm identifier matches that
   package's package.json name. The hero pointer to
   codespar.dev/api/servers no longer calls itself a count, because that
   endpoint answers 133 today and does not match this repo.

2) UCP and AP2 endpoints. The protocol table sold "@codespar/mcp-ucp" as
   "Google's full commerce stack for AI agents" and "@codespar/mcp-ap2"
   with "60+ partners including Visa, Mastercard, Stripe, PayPal", with
   nothing said about where the two servers actually point.
   packages/payments/ucp/src/index.ts:69-71 calls
   commerce.googleapis.com/ucp/v1 and packages/payments/ap2/src/index.ts:
   60-62 calls ap2.googleapis.com/v1. Measured today: both answer the
   Google frontend's generic "Error 404 (Not Found)" HTML page, the
   response a *.googleapis.com name gives when no API service is
   registered under it, while a registered service (storage.googleapis.com)
   answers a structured JSON API error. Both sandbox hosts fail the TLS
   handshake, since the wildcard certificate does not cover a fourth
   label.

   The two unprovable sentences are gone, both rows carry a "no live
   endpoint" marker, and the root README, the two package READMEs and the
   two source docstrings state what was measured. No behaviour changed:
   the source edits are comments only.

Text only. Nothing was softened into "coming soon" or "planned", because
neither can be shown from the code today.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PSy1otpr7x4tHGRxBPQ6Cj
…ir duplicates

The previous commit replaced false claims with new claims that were also
unprovable, and left copies of the old ones standing. This reworks both.

Claims removed because nothing supports them:
- "the 42 tool schemas ... follow those specifications" (5 surfaces). We never
  checked a schema against a spec. The banners now state only what was
  observed, and say plainly that the definitions are unverified.
- "which is what a *.googleapis.com name returns when no API service is
  registered under it": a causal law inferred from one probe. Replaced by the
  observation plus its controls.
- "60+ partners including Visa, Mastercard, Stripe, PayPal, and Square", which
  survived in ap2/README.md:17, and the same partner list restated in the
  list_payment_methods description (README table and src/index.ts).
- "AP2 provides a sandbox environment for testing", which survived in the file
  the PR edited. The sandbox host fails TLS.
- "Live in ChatGPT with 1M+ Shopify merchants", in the root table and again in
  stripe-acp/README.md:12.
- The credential steps for developers.google.com/ap2 and
  developers.google.com/agents/commerce, and the github.com/anthropic-payments
  spec link. All three answer 404. The dead UCP URL was also published as
  provider.docsUrl in server.json.
- "Endpoint paths follow public docs" in the AP2 alpha notice: the same
  conformance claim the review rejected, seven lines above the new banner.

Consistency, since the review found the criterion applied unevenly:
- x402 gets the same treatment as UCP and AP2. api.x402.org is NXDOMAIN on
  8.8.8.8 and 1.1.1.1 while x402.org itself resolves, so its BASE_URL reaches
  nothing either. Marked in both tables and in the banner.
- The "no live endpoint" marker now appears in the catalog table too, not only
  the protocol table.
- x402/server.json claimed sandbox.available: true. The package has no sandbox
  switch at all, so it now reads false, matching UCP and AP2.

Every line reference was re-resolved after the source edits moved them.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PSy1otpr7x4tHGRxBPQ6Cj
@fabianocruz

Copy link
Copy Markdown
Member Author

Repair pushed as de7e2ba. Item by item.

BLOCKING 1. "the 42 tool schemas in these two packages follow those specifications", in five surfaces

Removed everywhere. Nobody checked a schema against a spec, so the claim is gone rather than reworded. The banners now assert only what was observed, and end with the negative explicitly: "we have not checked them against a conforming implementation". Same removal in the two src/index.ts header comments, which carried the shorter form "The tool schemas below follow the spec".

BLOCKING 2. ## Sandbox / Testing survived in the file the PR edited

Section deleted from packages/payments/ap2/README.md. The env table row it was backed by also asserted a sandbox exists; it now says what the flag mechanically does: true switches BASE_URL to https://sandbox.ap2.googleapis.com/v1, which fails TLS. Same fix in ucp/README.md, and in the Environment: block of both source files, which had the same "Set to true for sandbox mode" wording.

BLOCKING 3. "60+ partners including Visa, Mastercard, Stripe, PayPal" survived at ap2/README.md:17

Removed, replaced by a link to ap2-protocol.org (verified 200). The sweep found the same partner list restated a third time in the list_payment_methods description, in both the README tool table and src/index.ts:238. Both now read "List payment methods offered by the AP2 partner network", with no company names.

NOT BLOCKING. Credential steps for a service that does not exist

Removed from both files. All three URLs were checked and all three are dead: developers.google.com/ap2 404, developers.google.com/agents/commerce 404, github.com/anthropic-payments/ap2-spec 404. The Links section carried two of them, so those went too.

One extra, from the sweep: the dead UCP URL was also published as provider.docsUrl in packages/payments/ucp/server.json, which ships to the MCP Registry. google-agentic-commerce has no UCP repo, so there is no verified replacement and the field is dropped rather than substituted. scripts/audit-catalog.py:178 will report this as LOW "provider.docsUrl missing", which is the honest state.

NOT BLOCKING. Marker missing from the catalog table

Added to all catalog rows, not only the protocol table.

NOT BLOCKING. Criterion applied to two of four protocols

Applied to all four, and it moved one more row than the review asked for:

  • "Live in ChatGPT with 1M+ Shopify merchants" removed from the Stripe ACP row. It also survived in packages/payments/stripe-acp/README.md:12; removed there too.
  • x402 fails the same test and now carries the same marker. api.x402.org is NXDOMAIN on 8.8.8.8 and 1.1.1.1, while api.stripe.com and x402.org resolve on the same resolvers, so this is not a local DNS artifact. Its BASE_URL reaches nothing, same as UCP and AP2.
  • x402/server.json declared sandbox.available: true. There is no X402_SANDBOX, no testnet switch, and no second base URL anywhere in the package, so it now reads false, matching UCP and AP2.
  • The AP2 alpha notice said "Endpoint paths follow public docs and BACEN/provider conventions". That is the same unprovable conformance claim this review rejected, seven lines above the new banner, so it is gone. Kept in the other eight packages that carry the boilerplate, since this PR did not test their endpoints.

NOT BLOCKING. Causal generalization from one positive control

The clause "which is what a *.googleapis.com name returns when no API service is registered under it" is removed. It was inference, not measurement. The text now reports the observation and lists the controls separately: storage.googleapis.com and translate.googleapis.com both answered structured JSON errors, and x402.org resolved and answered 200. The TLS sentence is now grounded in the cert actually served, whose SAN list is *.googleapis.com with no entry covering a further label.

Every claim is dated 2026-08-27, so it reads as an observation with a timestamp rather than a standing truth.

Sweep

grep -rn over the whole clone for each removed phrase, across *.json *.tsx *.ts *.mdx *.md, excluding node_modules and dist. Three hits remain and are deliberate:

  • packages/payments/ap2/README.md:96 and packages/payments/ucp/README.md:98 contain the dead portal URLs, in the sentences that state they answer 404.
  • packages/crypto/unblockpay/README.md:76 matches "sandbox environment for testing" but is a different provider and not the same claim. api.sandbox.unblockpay.com resolves to a live AWS API Gateway, unlike the AP2 sandbox host.

Nine other packages match "for sandbox mode" (celcoin, pagseguro, asaas, cielo, efi, ebanx, melhor-envio, superfrete, stark-bank). Those are real providers with real sandboxes and are outside this PR; I did not test their endpoints and did not touch their wording.

Left alone on purpose

  • The AP2 ## Roadmap section, whose items are marked "(planned)". It promises nothing about today's behavior and sits under the no-live-endpoint banner. Worth a separate call if you want forward-looking sections gone repo-wide.
  • The ## Use Cases list in ap2/README.md. It describes the protocol, not this server's working state.
  • The registry description fields in all three server.json files. Adding "no live endpoint" fits UCP's 63 characters but pushes AP2 and x402 past the registry's 100-char limit, so adding it to one and not the others would reintroduce exactly the uneven-criterion problem. sandbox.available: false plus the README banner carry it instead.

Note

The source edits shifted the BASE_URL line numbers the banners cite. Every reference was re-resolved after the edits and checked against the file: UCP 71-73, AP2 62-64, x402 40, plus the header blocks at UCP 78-83 and AP2 69-73.

…minava

A re-revisao reprovou a frase de controle em cinco superficies, e ela estava
errada mesmo. Rodei agora: translate.googleapis.com/v1 devolve o MESMO 404
generico em HTML que ap2.googleapis.com/v1, e storage.googleapis.com/v1
devolve XML (InvalidBucketName), nao "a structured JSON API error". Ou seja
o controle nao distinguia "nome sem servico registrado" de "path errado em
servico registrado", que era exatamente o que ele deveria distinguir.

A conclusao nao dependia dele e continua de pe: todo path que estes
servidores de fato chamam falhou na mesma rodada. O README raiz agora diz
isso, e diz tambem que um 404 generico sozinho nao prova ausencia de
servico.
@fabianocruz

Copy link
Copy Markdown
Member Author

Fechando o BLOCKING da frase de controle, e o revisor estava certo no mérito.

Rodei agora, da minha máquina:

https://translate.googleapis.com/v1  -> HTTP 404, mesma página genérica em HTML
https://ap2.googleapis.com/v1        -> HTTP 404, mesma página genérica em HTML
https://storage.googleapis.com/v1    -> HTTP 400, XML (InvalidBucketName)

Ou seja: nenhum dos dois controles respondeu "a structured JSON API error", e o controle comparável (serviço registrado, path inexistente) devolve exatamente o mesmo 404 genérico. O controle não distinguia o que precisava distinguir.

A frase saiu das cinco superfícies. A conclusão não dependia dela e continua de pé: todo path que estes servidores de fato chamam falhou na mesma rodada. O README raiz agora diz isso e registra que um 404 genérico sozinho não prova ausência de serviço.

@fabianocruz
fabianocruz merged commit 96a83d7 into main Aug 28, 2026
3 checks passed
@fabianocruz
fabianocruz deleted the docs/catalogo-honesto branch August 28, 2026 01:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant