{
  "markdown": "# latam-synth\n\n**Privacy-safe synthetic financial data for Latin American fintech — available through Python, CLI, REST, Apify Actor, and Model Context Protocol (MCP) for AI agents.**\n\nGenerador de datos sintéticos de comportamiento de ahorro financiero, calibrado con las distribuciones estadísticas de **506,311 registros reales** de una app de ahorro LatAm (2015–2024): 305,808 transacciones, 108,570 metas de ahorro y 91,933 usuarios de México, Colombia, Argentina, Perú, Chile y más.\n\n**El output es 100% sintético**: ningún registro deriva de un usuario real, solo de distribuciones agregadas. Sin PII y sin riesgo de reidentificación.\n\n---\n\n## Model Context Protocol (MCP)\n\nLatAm Synth is available to AI agents as an **MCP tool** through two independent paths:\n\n- **Remote (hosted):** the **Apify MCP Server** exposes the `active_yardstick/latam-synth` Actor as a callable MCP tool over Streamable HTTP. Nothing to install.\n- **Local (stdio):** `latam-synth-mcp`, shipped in this repository, runs the generator in-process without calling Apify. For local MCP clients and containerised catalog checks.\n\nBoth paths return the same tables with the same referential integrity, because both are thin adapters over the same `SyntheticGenerator`.\n\n### MCP details\n\n- **MCP capability:** Tools\n- **Transport:** Streamable HTTP (remote) / stdio (local)\n- **Hosted MCP server:** Apify MCP Server\n- **Local MCP server:** `latam-synth-mcp` (extra `[mcp]`, SDK `mcp>=2,<3`)\n- **Actor exposed as tool:** `active_yardstick/latam-synth`\n- **Authentication:** Apify OAuth or Bearer token\n- **Official MCP Registry name:** `io.github.jmendozapuche/latam-fintech-synthetic-data`\n- **Registry metadata:** [`server.json`](./server.json)\n- **Apify Actor:** https://apify.com/active_yardstick/latam-synth\n\n### MCP endpoint\n\n```text\nhttps://mcp.apify.com?tools=active_yardstick/latam-synth\n```\n\nThe `tools` parameter restricts the Apify MCP Server to the LatAm Synth Actor, making it directly discoverable and callable by compatible AI agents.\n\n### Example MCP configuration — OAuth\n\n```json\n{\n  \"mcpServers\": {\n    \"latam-synth\": {\n      \"url\": \"https://mcp.apify.com?tools=active_yardstick/latam-synth\"\n    }\n  }\n}\n```\n\nOn first connection, a compatible MCP client can open the Apify OAuth flow so the user can authorize access without placing an API token directly in the configuration.\n\n### Example MCP configuration — Bearer token\n\n```json\n{\n  \"mcpServers\": {\n    \"latam-synth\": {\n      \"url\": \"https://mcp.apify.com?tools=active_yardstick/latam-synth\",\n      \"headers\": {\n        \"Authorization\": \"Bearer <APIFY_TOKEN>\"\n      }\n    }\n  }\n}\n```\n\nReplace `<APIFY_TOKEN>` with an Apify API token.\n\n### What AI agents can do with LatAm Synth\n\nAn MCP-compatible agent can invoke LatAm Synth to generate:\n\n- synthetic financial users\n- linked savings goals\n- deposit and withdrawal transactions\n- country-filtered Latin American datasets\n- reproducible datasets using a random seed\n- realistic fintech test data without exposing personally identifiable information\n\nTypical agent use cases include:\n\n- evaluating financial AI agents\n- generating test fixtures on demand\n- creating synthetic datasets for demos and POCs\n- testing recommendation or savings assistants\n- bootstrapping ML and data-pipeline experiments\n\nLatAm Synth currently exposes its functionality through **MCP Tools**. It does not currently expose MCP Resources or Prompts.\n\n### How MCP is implemented\n\nThe remote path does **not** require an MCP transport server inside this repository: Apify hosts it. The local path does ship one (`src/latam_synth/mcp_server.py`), for clients that prefer to run the generator themselves — no token, no network, no per-run cost.\n\nThe architecture is:\n\n```text\nMCP-compatible AI client\n        |\n        |  Streamable HTTP\n        v\nApify MCP Server\n        |\n        |  exposes Actor as MCP Tool\n        v\nactive_yardstick/latam-synth\n        |\n        v\nSynthetic users + goals + transactions\n```\n\nApify provides the hosted MCP server and authentication layer. The LatAm Synth Actor provides the executable tool functionality and structured input/output.\n\n### Local MCP server (stdio)\n\n```bash\npip install -e \".[mcp]\"\nlatam-synth-mcp                    # entry point\npython -m latam_synth.mcp_server   # equivalent\n```\n\nConfiguration for a local MCP client (Claude Desktop / Claude Code):\n\n```json\n{\n  \"mcpServers\": {\n    \"latam-synth\": {\n      \"command\": \"latam-synth-mcp\"\n    }\n  }\n}\n```\n\nExposed tools:\n\n| Tool | What it does |\n| --- | --- |\n| `generate_latam_financial_data` | Generates users + goals + transactions. Args: `users` (1-200), `seed`, `countries`, `start_date`, `end_date`. |\n| `describe_latam_synth_dataset` | Returns schema, goal categories, available countries and the privacy policy. No arguments. |\n\nBoth are annotated `read_only` and `idempotent`: nothing is written and the same\nseed returns the same dataset. The 200-user cap per call keeps responses small\nenough for an agent context — for larger volumes use the CLI or the Actor.\n\nDeployment detail, Docker image and Glama configuration: [`docs/mcp_local.md`](./docs/mcp_local.md).\n\n---\n\n## Para qué sirve\n\n- **Testing y QA fintech**: fixtures realistas para pipelines de pago, apps de presupuesto y motores de metas.\n- **Demos y POCs**: dashboards con datos verosímiles de LatAm que se pueden mostrar públicamente.\n- **Entrenamiento de ML**: datos de arranque para modelos de churn, recomendación y segmentación con patrones reales como estacionalidad, tasas de abandono y categorías de metas.\n- **AI agents**: generación bajo demanda de datasets financieros sintéticos a través de MCP.\n- **Educación**: datasets ilimitados para cursos de data science con narrativa de negocio real.\n\n---\n\n## Uso rápido\n\n### CLI\n\n```bash\npip install -e .\nlatam-synth generate --users 5000 --seed 42 --format csv --out ./output\n```\n\nSolo México y Colombia, formato parquet:\n\n```bash\nlatam-synth generate --users 10000 --countries Mexico Colombia --format parquet\n```\n\n### Python\n\n```python\nfrom latam_synth import SyntheticGenerator, GeneratorConfig\n\ndata = SyntheticGenerator(\n    GeneratorConfig(n_users=1000, seed=42)\n).generate()\n\ndata[\"transactions\"].head()\n```\n\n---\n\n## Qué hace fiel a este generador\n\nLa calibración fue verificada contra datos reales. Ver:\n\n```text\ndocs/validation_report.txt\n```\n\nEl generador incorpora:\n\n- distribuciones de montos lognormales por tipo de transacción\n- estacionalidad mensual real\n- pico de enero post-propósitos y valle de diciembre\n- 8 categorías de metas con montos y horizontes propios\n- tasas de logro y abandono observadas\n- 73.8% de metas vencidas\n- uplift de metas compartidas\n- scores de usuario correlacionados\n- cópula gaussiana con ρ=0.89 para disciplina-logro\n- trayectorias temporales coherentes por meta\n- integridad referencial entre usuarios, metas y transacciones\n\n---\n\n## Apify Actor\n\nLatAm Synth is also available as a hosted Apify Actor:\n\n```text\nactive_yardstick/latam-synth\n```\n\nActor page:\n\n```text\nhttps://apify.com/active_yardstick/latam-synth\n```\n\nThe Actor can be called directly from Apify, through the Apify API, or exposed to AI clients through the Apify MCP Server.\n\nExample input:\n\n```json\n{\n  \"users\": 1000,\n  \"seed\": 42,\n  \"countries\": [\"Mexico\", \"Colombia\"],\n  \"format\": \"csv\",\n  \"push_to_dataset\": true,\n  \"start_date\": \"2023-01-01\",\n  \"end_date\": \"2024-12-31\"\n}\n```\n\nThe `seed` parameter makes generation reproducible. The same seed and configuration produce the same synthetic output.\n\n---\n\n## Where to find your output (Apify)\n\nEvery run writes output to two places.\n\n### Key-value store — all three tables\n\n1. Open the run in Apify Console and click the **Storage** tab.\n2. Click **Key-value store**.\n3. Download the generated files:\n   - `users.csv` — one row per synthetic user\n   - `goals.csv` — savings goals linked to users\n   - `transactions.csv` — deposit/withdrawal transactions linked to goals\n   - `OUTPUT` — always present; JSON summary of the run, including parameters, row counts and downloadable keys\n   - if `format: json` was selected, `OUTPUT_DATA` contains all three tables in a single JSON file instead of the three CSV files\n4. Click the download icon next to each key to save the file.\n\n### Dataset — transactions\n\nBy default (`push_to_dataset: true`), all transactions are also pushed to the run's **Dataset**.\n\nThis allows you to:\n\n- export as JSON, CSV, or Excel directly from the Dataset tab\n- connect native Apify integrations to the Dataset output\n- consume transactions programmatically\n\nTo disable this for very large runs where only the key-value-store files are needed, set:\n\n```json\n{\n  \"push_to_dataset\": false\n}\n```\n\nThe run log prints exact file names and row counts at the end of execution.\n\n---\n\n## API REST local\n\nInstall the API dependencies:\n\n```bash\npip install -e \".[api]\"\nuvicorn latam_synth.api:app --port 8000\n```\n\nGenerate JSON with the three tables:\n\n```bash\ncurl -s -X POST http://localhost:8000/generate \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"users\": 100, \"seed\": 42, \"countries\": [\"Mexico\", \"Colombia\"]}' | jq .meta\n```\n\nExample metadata response:\n\n```json\n{\n  \"users\": 100,\n  \"goals\": 121,\n  \"transactions\": 453\n}\n```\n\nDownload transaction CSV directly:\n\n```bash\ncurl -s -X POST http://localhost:8000/generate \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Accept: text/csv\" \\\n  -d '{\"users\": 500, \"seed\": 7}' \\\n  -o transactions.csv\n```\n\nHealth check:\n\n```bash\ncurl http://localhost:8000/health\n```\n\n```json\n{\n  \"status\": \"ok\",\n  \"version\": \"0.2.0\"\n}\n```\n\nLocal REST API limits:\n\n- Rate limit: 10 requests/min per IP\n- Maximum: 50,000 users per request\n\n---\n\n## Privacy\n\nThe generated datasets are designed for development, testing, demos, experimentation and education without requiring production PII.\n\nKey properties:\n\n- 100% synthetic records\n- no row is copied from a real user\n- no names, emails, IDs or other direct PII are reproduced from the calibration dataset\n- generation is based on aggregate statistical distributions\n- synthetic tables preserve realistic relationships between users, goals and transactions\n\n---\n\n## Desarrollo\n\n```bash\npip install -e \".[dev]\"\npytest\n```\n\n---\n\n## MCP registry metadata\n\nThis repository includes [`server.json`](./server.json) for MCP registry discovery.\n\nCurrent server identity:\n\n```text\nio.github.jmendozapuche/latam-fintech-synthetic-data\n```\n\nThe registered remote MCP endpoint is:\n\n```text\nhttps://mcp.apify.com?tools=active_yardstick/latam-synth\n```\n\n---\n\n## Changelog\n\n### v0.2\n\n- mezcla de lognormales (KS=0.032)\n- snap a valores redondos (69.5% en malla)\n- trayectorias temporales coherentes por meta\n- 100% de transacciones dentro de la ventana `[created_at, deadline]`\n- API FastAPI\n- Apify Actor\n- MCP exposure through the hosted Apify MCP Server\n",
  "bytes": 10803,
  "sha": "4a535e344cc91a1edf2f636bc76e75a6935d9616c1a569b555150d9f548d93c0",
  "repo_slug": "jmendozapuche/latam-synth",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_jmendozapuche_latam_fintech_sy_966c072c/readme"
}