Automatic es + pt translations

Author: avdata99

docs/catalogs/brasil.es.md

@@ -0,0 +1,26 @@
+# Brasil
+
+**Repo:** [okfn/mcp-dados-brasil](https://github.com/okfn/mcp-dados-brasil)
+· **Portal:** [dados.gov.br](https://dados.gov.br)
+· **Idioma:** portugués
+
+Definiciones de datasets para el portal nacional de datos abiertos de
+Brasil. Cada archivo `.yaml` bajo `datasets/` declara un dataset y sus
+herramientas; el repo también contiene herramientas en Python para los
+casos más elaborados.
+
+## Desde el terreno
+
+Este catálogo respaldó un piloto con la Contraloría General de la Unión
+de Brasil, enfocado en las **enmiendas parlamentarias**, uno de los
+datasets más solicitados del portal. El objetivo era probar si la
+ciudadanía podía preguntar en lenguaje natural y obtener respuestas
+trazables hasta los datos oficiales. Ver [lecciones de los
+pilotos](../lessons/index.md).
+
+## Agregar un dataset
+
+Sigue la guía general de [datasets en YAML](../plugins/yaml-datasets.md):
+un nuevo archivo `.yaml` en `datasets/`, push, y volver a hacer fetch en
+el servidor. Las descripciones, los parámetros y las preguntas de
+ejemplo están escritas en portugués, acorde a la audiencia.

docs/catalogs/brasil.pt.md

@@ -0,0 +1,25 @@
+# Brasil
+
+**Repo:** [okfn/mcp-dados-brasil](https://github.com/okfn/mcp-dados-brasil)
+· **Portal:** [dados.gov.br](https://dados.gov.br)
+· **Idioma:** português
+
+Definições de datasets para o portal nacional de dados abertos do
+Brasil. Cada arquivo `.yaml` em `datasets/` declara um dataset e suas
+ferramentas; o repo também contém ferramentas em Python para os casos
+mais elaborados.
+
+## Direto do campo
+
+Este catálogo sustentou um piloto com a Controladoria-Geral da União,
+focado nas **emendas parlamentares**, um dos datasets mais requisitados
+do portal. O objetivo era testar se os cidadãos podiam perguntar em
+linguagem natural e obter respostas rastreáveis até os dados oficiais.
+Veja [lições dos pilotos](../lessons/index.md).
+
+## Adicionando um dataset
+
+Siga o guia geral de [datasets em YAML](../plugins/yaml-datasets.md):
+um novo arquivo `.yaml` em `datasets/`, push, e refazer o fetch no
+servidor. As descrições, os parâmetros e as perguntas de exemplo estão
+escritos em português, de acordo com o público.

docs/catalogs/index.es.md

@@ -0,0 +1,10 @@
+# Catálogos de datos
+
+Los plugins que existen hoy, cada uno mantenido en su propio repo y en
+su propio idioma:
+
+- [Uruguay](uruguay.md): datasets de catalogodatos.gub.uy, en español.
+- [Brasil](brasil.md): datasets de dados.gov.br, en portugués.
+
+Ambos están en etapa Alpha y son las mejores plantillas para empezar un
+nuevo plugin de país: ver [plugins](../plugins/index.md).

docs/catalogs/index.pt.md

@@ -0,0 +1,10 @@
+# Catálogos de dados
+
+Os plugins que existem hoje, cada um mantido em seu próprio repo e em
+seu próprio idioma:
+
+- [Uruguai](uruguay.md): datasets de catalogodatos.gub.uy, em espanhol.
+- [Brasil](brasil.md): datasets de dados.gov.br, em português.
+
+Ambos estão em estágio Alpha e são os melhores modelos para começar um
+novo plugin de país: veja [plugins](../plugins/index.md).

docs/catalogs/uruguay.es.md

@@ -0,0 +1,41 @@
+# Uruguay
+
+**Repo:** [okfn/mcp-datos-uruguay-ben](https://github.com/okfn/mcp-datos-uruguay-ben)
+· **Portal:** [catalogodatos.gub.uy](https://catalogodatos.gub.uy/)
+· **Idioma:** español
+
+Herramientas MCP sobre el *Balance Energetico Nacional* (BEN) de
+Uruguay, publicado por el Ministerio de Industria, Energía y Minería
+(MIEM) en el portal nacional de datos abiertos.
+
+![El catálogo de energía de Uruguay respondiendo preguntas en el chat](../assets/images/datos-uruguay.png)
+
+## Lo más destacado
+
+El plugin expone herramientas sobre la matriz eléctrica, la potencia
+instalada, el factor de emisión de la red, el consumo final, el
+abastecimiento primario, las importaciones de petróleo y gas, el
+intercambio de electricidad y las emisiones de CO2 por sector, además
+de un [glosario del BEN](../lessons/glossary.md) con definiciones
+oficiales.
+
+## Acotado a propósito
+
+Este repo reemplazó al anterior `mcp-datos-uruguay`, más amplio, que
+intentaba cubrir todo el portal y se volvió demasiado general. Acotar
+el plugin a un solo dominio bien entendido (energía) es una decisión
+deliberada: ver [por qué acotamos los plugins](../lessons/scope.md).
+
+## Instalación
+
+Es un paquete de Python instalable con pip. Instálalo en el entorno del
+servidor MCP y reinicia el servidor; no hay que agregar ninguna entrada
+en `tool_sources.yaml`. Las descripciones, los parámetros y las
+preguntas de ejemplo están escritas en español, acorde a la audiencia.
+
+## Desde el terreno
+
+Este catálogo impulsó un piloto público sobre los datos de energía de
+Uruguay en julio de 2026. Todo lo que aprendimos al operarlo, las
+fortalezas, los modos de falla y los cambios que publicamos, está
+escrito en [lecciones del piloto](../lessons/index.md).

docs/catalogs/uruguay.pt.md

@@ -0,0 +1,43 @@
+# Uruguai
+
+**Repo:** [okfn/mcp-datos-uruguay-ben](https://github.com/okfn/mcp-datos-uruguay-ben)
+· **Portal:** [catalogodatos.gub.uy](https://catalogodatos.gub.uy/)
+· **Idioma:** espanhol
+
+Ferramentas MCP sobre o *Balance Energetico Nacional* (BEN, o balanço
+energético nacional) do Uruguai, publicado pelo Ministério da
+Indústria, Energia e Mineração (MIEM) no portal nacional de dados
+abertos.
+
+![O catálogo de energia do Uruguai respondendo perguntas no chat](../assets/images/datos-uruguay.png)
+
+## Destaques
+
+O plugin expõe ferramentas sobre a matriz elétrica, a capacidade
+instalada, o fator de emissão da rede, o consumo final, a oferta
+primária, as importações de petróleo e gás, o intercâmbio de
+eletricidade e as emissões de CO2 por setor, além de um
+[glossário do BEN](../lessons/glossary.md) com definições oficiais.
+
+## Focado de propósito
+
+Este repo substituiu o antigo `mcp-datos-uruguay`, mais amplo, que
+tentava cobrir o portal inteiro e ficou genérico demais. Restringir o
+plugin a um único domínio bem compreendido (energia) é uma escolha
+deliberada: veja [por que restringimos o escopo dos
+plugins](../lessons/scope.md).
+
+## Instalação
+
+É um pacote Python instalável com pip. Instale-o no ambiente do
+servidor MCP e reinicie o servidor; não há nenhuma entrada para
+adicionar em `tool_sources.yaml`. As descrições, os parâmetros e as
+perguntas de exemplo estão escritos em espanhol, de acordo com o
+público.
+
+## Direto do campo
+
+Este catálogo alimentou um piloto público sobre os dados de energia do
+Uruguai em julho de 2026. Tudo o que aprendemos ao operá-lo, os pontos
+fortes, os modos de falha e as mudanças que publicamos, está registrado
+em [lições do piloto](../lessons/index.md).

docs/contributing.es.md

@@ -0,0 +1,35 @@
+# Contribuir
+
+Este sitio es Markdown plano construido con
+[MkDocs](https://www.mkdocs.org/) y el tema
+[Material](https://squidfunk.github.io/mkdocs-material/), alojado en
+GitHub Pages. Cada página tiene un ícono de edición (lápiz) que te
+lleva directo al archivo en GitHub.
+
+## Trabajar en local
+
+```bash
+git clone https://github.com/okfn/mcp-docs
+cd mcp-docs
+uv sync
+uv run mkdocs serve    # live preview at http://127.0.0.1:8000
+```
+
+El sitio se reconstruye automáticamente al guardar. Hacer push a `main`
+lo publica mediante un workflow de GitHub Actions.
+
+## Reglas de la casa
+
+- **Archivos chicos.** Un tema por página, páginas de una o dos
+  pantallas. Si una página crece más que eso, divídela. Los archivos
+  chicos también permiten que la gente edite en paralelo sin conflictos
+  de merge.
+- **Primero lo humano.** Esto es un manual, no una referencia de API.
+  Explica el porqué antes del cómo; los bloques de código acompañan al
+  texto, no al revés.
+- **Puntuación simple.** Comillas rectas, guiones simples, tres puntos.
+  Sin Unicode tipográfico, sin emojis decorativos.
+- **Las capturas de pantalla** viven en `docs/assets/images/`.
+  Comprímelas cuando puedas.
+- Las páginas nuevas deben agregarse a la sección `nav` de
+  `mkdocs.yml`, o se construirán pero no aparecerán en la navegación.

docs/contributing.pt.md

@@ -0,0 +1,35 @@
+# Contribuir
+
+Este site é Markdown puro construído com
+[MkDocs](https://www.mkdocs.org/) e o tema
+[Material](https://squidfunk.github.io/mkdocs-material/), hospedado no
+GitHub Pages. Cada página tem um ícone de edição (lápis) que leva você
+direto ao arquivo no GitHub.
+
+## Trabalhando localmente
+
+```bash
+git clone https://github.com/okfn/mcp-docs
+cd mcp-docs
+uv sync
+uv run mkdocs serve    # live preview at http://127.0.0.1:8000
+```
+
+O site é reconstruído automaticamente quando você salva. Fazer push
+para `main` publica o site por meio de um workflow do GitHub Actions.
+
+## Regras da casa
+
+- **Arquivos pequenos.** Um tópico por página, páginas de uma ou duas
+  telas. Se uma página crescer além disso, divida-a. Arquivos pequenos
+  também permitem que as pessoas editem em paralelo sem conflitos de
+  merge.
+- **Humano primeiro.** Isto é um manual, não uma referência de API.
+  Explique o porquê antes do como; os blocos de código apoiam o texto,
+  não o contrário.
+- **Pontuação simples.** Aspas retas, hífens simples, três pontos. Sem
+  Unicode tipográfico, sem emojis decorativos.
+- **As capturas de tela** ficam em `docs/assets/images/`. Comprima-as
+  quando puder.
+- Páginas novas precisam ser adicionadas à seção `nav` do
+  `mkdocs.yml`, ou serão construídas mas não aparecerão na navegação.

docs/dev/architecture.es.md

@@ -0,0 +1,103 @@
+# Arquitectura
+
+Tres partes móviles hacen funcionar la plataforma, el chat gateway, el LLM y el
+servidor MCP con sus herramientas de plugin, y un contrato las une.
+
+El **gateway es el único iniciador**: llama tanto al LLM como al servidor
+MCP y espera cada respuesta. El LLM y el servidor MCP nunca hablan entre
+sí, y el servidor MCP no puede interrumpir: solo habla cuando se le
+habla.
+
+```mermaid
+sequenceDiagram
+    actor User as Usuario
+    participant Gateway as Chat gateway
+    participant LLM
+    participant MCP as Servidor MCP
+    participant Tool as Herramienta del plugin
+    participant Data as Datasets
+
+    User->>Gateway: pregunta
+    Gateway->>LLM: pregunta + catálogo de herramientas
+    LLM-->>Gateway: llama esta herramienta, con estos argumentos
+    Gateway->>MCP: ejecuta esa herramienta
+    MCP->>Tool: despacha a la función del plugin
+    Tool->>Data: lee
+    Data-->>Tool: filas
+    Tool-->>MCP: texto + tablas/gráficos/fuentes
+    MCP-->>Gateway: ese resultado, sin cambios
+    Gateway->>LLM: solo el texto de la herramienta
+    LLM-->>Gateway: la respuesta, en palabras
+    Gateway-->>User: esas palabras, más tablas/gráficos dibujados desde los datos
+```
+
+Esa es toda la imagen en tiempo de ejecución, y el tiempo corre hacia
+abajo. El LLM le responde al gateway **dos veces, en dos momentos
+distintos**, y las dos respuestas no son la misma clase de cosa:
+
+- **La primera respuesta nombra una herramienta.** El modelo todavía no
+  vio ningún dato. Está mirando el catálogo de herramientas y eligiendo
+  una, así que esta respuesta es un pedido, no una respuesta.
+- **La última respuesta es la respuesta.** A esta altura la herramienta
+  ya corrió y el gateway le entregó al modelo el texto de la
+  herramienta, así que el modelo está escribiendo prosa sobre datos que
+  realmente recibió.
+
+El medio del diagrama puede repetirse: si el modelo quiere una segunda
+herramienta, pide de nuevo y el ciclo corre una vez más antes de la
+respuesta final.
+
+Fíjate por dónde viajan los datos estructurados: al LLM se le entrega
+solo el texto de la herramienta, mientras que las tablas y los gráficos
+pasan de largo, directo a la pantalla del usuario, [sin pasar nunca por
+la IA](../overview/idea.md).
+
+## Dónde se ubica el plugin
+
+La **herramienta del plugin** es la única parte de esta imagen que sabe
+algo sobre un dataset específico. Todo lo que está arriba es genérico:
+el gateway, el LLM y el servidor MCP funcionarían igual sobre enmiendas
+parlamentarias o sobre un balance energético. Todo lo que está abajo es
+un archivo.
+
+El servidor MCP no lee datos. Recibe una llamada, despacha a la función
+del plugin registrada bajo ese nombre y pasa el resultado de vuelta
+**sin cambios**. Así que los números que ve un usuario fueron calculados
+por código del repo del plugin de un país, por gente que conoce esos
+datos, que es exactamente por qué los plugins están [acotados a un
+dominio que alguien entiende](../lessons/scope.md).
+
+## Lo que el diagrama deja afuera
+
+**El catálogo de herramientas llega primero.** Antes de todo esto, el
+gateway le pide al servidor MCP su lista de herramientas (`tools/list`)
+y la guarda en caché. Esa llamada es iniciativa propia del gateway y
+ocurre sin ninguna IA involucrada, así que para cuando al modelo se le
+pregunta algo, el catálogo del que elige ya está fijo. Ejecutar una
+herramienta es `tools/call`.
+
+**Una herramienta puede dirigirse al usuario directamente.** Además de
+tablas y gráficos, una herramienta puede devolver un mensaje `force`:
+texto que se muestra al usuario como un mensaje propio, que nunca se
+agrega a la conversación que lee el LLM. La herramienta le habla al
+humano por encima del modelo, por diseño.
+
+## El contrato
+
+Cada herramienta devuelve un texto para el LLM **y** un payload
+`structuredContent` para la interfaz, y ese payload debe declarar de
+dónde vinieron los datos.
+
+Las fuentes no son una convención. Una herramienta que no declara el
+contrato portador de fuentes es rechazada al arranque y nunca se vuelve
+invocable, lo cual es más estricto de lo que exige el estándar MCP. Mira
+[resultados de las herramientas](../plugins/tool-results.md) para la
+forma completa y cómo se hace cumplir.
+
+## Transportes
+
+El servidor MCP habla dos transportes:
+
+- **stdio**: para uso local, por ejemplo conectarlo a Claude Desktop.
+- **HTTP**: para despliegues reales, donde el gateway (o cualquier
+  cliente) se conecta por la red.