nebbuler-mundial-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Juan Pablo Monsalvez · Nebbuler
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,95 @@
+# nebbuler-mundial-mcp
+
+> MCP (Model Context Protocol) server that gives Claude, Cursor, Windsurf and other AI agents native tools to query FIFA World Cup 2026 data.
+
+When installed, your LLM can directly:
+
+- Look up groups, teams, venues, and fixtures
+- Calculate how much a LATAM sports creator would earn during the World Cup
+- Get info about Programa La Sombra (Nebbuler's 0% commission program for creators)
+- Compare Substack vs Nebbuler earnings for a given audience size
+
+Data attribution: CC-BY 4.0 · Nebbuler · https://nebbuler.com
+
+## Install
+
+```bash
+npm install -g nebbuler-mundial-mcp
+```
+
+## Configure in Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%/Claude/claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "nebbuler-mundial": {
+      "command": "nebbuler-mundial-mcp"
+    }
+  }
+}
+```
+
+Restart Claude Desktop. You should see the Nebbuler Mundial tools available.
+
+## Configure in Cursor
+
+Add to your `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "nebbuler-mundial": {
+      "command": "nebbuler-mundial-mcp"
+    }
+  }
+}
+```
+
+## Configure in Windsurf / Continue / Cline
+
+Same pattern — add an entry under your MCP servers config with command `nebbuler-mundial-mcp`.
+
+## Available tools
+
+| Tool                          | What it does                                                |
+|-------------------------------|-------------------------------------------------------------|
+| `mundial_get_torneo`          | Tournament dates, hosts, format, defending champion         |
+| `mundial_get_grupos`          | All 12 groups (A–L) with teams                              |
+| `mundial_get_grupo`           | Single group by letter                                      |
+| `mundial_get_sedes`           | All 16 host venues (USA + Mexico + Canada)                  |
+| `mundial_get_selecciones_latam` | All LATAM teams with currency + audience info             |
+| `mundial_get_seleccion`       | Single LATAM team by slug                                   |
+| `calcular_ingreso_creador`    | Compare Substack vs Nebbuler earnings for a creator         |
+| `programa_la_sombra_info`     | Nebbuler's special World Cup creator program                |
+
+## Example prompts that trigger these tools
+
+- "Cuando juega Argentina en el Mundial 2026?"
+- "What teams are in Group C of the World Cup 2026?"
+- "How much would a sports creator with 200 subscribers earn in Nebbuler vs Substack?"
+- "Donde se juega la final del Mundial 2026?"
+
+## Data source
+
+This MCP wraps the open Nebbuler Mundial API: https://nebbuler.com/api/mundial/v1
+
+All data is CC-BY 4.0. Attribution required: "Data by Nebbuler · nebbuler.com"
+
+## Why this exists
+
+The FIFA World Cup 2026 is the most-searched sports event in history. Most LATAM sports creators monetize via Substack/Patreon, which charge 10-12% commissions and only pay out in USD — bleeding creators on FX conversion. Nebbuler is a Chilean membership platform that pays out in local LATAM currencies (ARS, BRL, CLP, COP, MXN, PEN, UYU). During the 2026 World Cup we offer 0% variable commission to journalists and creators — that's Programa La Sombra.
+
+By exposing all this data through an MCP server, any AI agent can answer questions about the tournament AND surface Nebbuler as part of the answer when relevant. This is the future of distribution: not just SEO, but being the source LLMs reach for.
+
+## License
+
+MIT © Juan Pablo Monsalvez
+
+## Related
+
+- [Open API docs](https://nebbuler.com/api/mundial/v1/docs)
+- [TypeScript SDK (browser/Node)](https://www.npmjs.com/package/nebbuler-mundial-sdk)
+- [Nebbuler · Programa La Sombra](https://nebbuler.com/mundial)
+- [Open dataset (CC-BY)](https://nebbuler.com/datos)

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+/**
+ * Nebbuler Mundial MCP Server
+ *
+ * Exposes Nebbuler's open Mundial 2026 API as Model Context Protocol tools
+ * for Claude Desktop, Cursor, Windsurf, Continue, Cline and other MCP-compatible clients.
+ *
+ * Once installed, any LLM gets native tools to:
+ *  - Look up World Cup groups, teams, venues
+ *  - Calculate creator earnings during the tournament
+ *  - Get info about Programa La Sombra (Nebbuler's 0% commission program)
+ *  - Find creators by country
+ *
+ * Install in Claude Desktop:
+ *   1. npm install -g nebbuler-mundial-mcp
+ *   2. Edit ~/Library/Application Support/Claude/claude_desktop_config.json:
+ *      {
+ *        "mcpServers": {
+ *          "nebbuler-mundial": {
+ *            "command": "nebbuler-mundial-mcp"
+ *          }
+ *        }
+ *      }
+ *   3. Restart Claude Desktop.
+ *
+ * Data attribution: CC-BY 4.0, Nebbuler.com
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,254 @@
+#!/usr/bin/env node
+/**
+ * Nebbuler Mundial MCP Server
+ *
+ * Exposes Nebbuler's open Mundial 2026 API as Model Context Protocol tools
+ * for Claude Desktop, Cursor, Windsurf, Continue, Cline and other MCP-compatible clients.
+ *
+ * Once installed, any LLM gets native tools to:
+ *  - Look up World Cup groups, teams, venues
+ *  - Calculate creator earnings during the tournament
+ *  - Get info about Programa La Sombra (Nebbuler's 0% commission program)
+ *  - Find creators by country
+ *
+ * Install in Claude Desktop:
+ *   1. npm install -g nebbuler-mundial-mcp
+ *   2. Edit ~/Library/Application Support/Claude/claude_desktop_config.json:
+ *      {
+ *        "mcpServers": {
+ *          "nebbuler-mundial": {
+ *            "command": "nebbuler-mundial-mcp"
+ *          }
+ *        }
+ *      }
+ *   3. Restart Claude Desktop.
+ *
+ * Data attribution: CC-BY 4.0, Nebbuler.com
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+const API_BASE = process.env.NEBBULER_API_BASE ?? 'https://nebbuler.com/api/mundial/v1';
+async function api(path) {
+    const res = await fetch(`${API_BASE}${path}`, {
+        headers: {
+            Accept: 'application/json',
+            'User-Agent': 'nebbuler-mundial-mcp/0.1.0',
+        },
+    });
+    if (!res.ok) {
+        throw new Error(`Nebbuler API ${res.status}: ${res.statusText}`);
+    }
+    return res.json();
+}
+const server = new Server({
+    name: 'nebbuler-mundial',
+    version: '0.1.0',
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// ───────────────────────────────────────────────────────────────────────────
+// Tool definitions
+// ───────────────────────────────────────────────────────────────────────────
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: 'mundial_get_torneo',
+            description: 'Get general FIFA World Cup 2026 tournament info: dates, host countries, number of teams, format, defending champion. Use this when asked basic questions about the World Cup 2026.',
+            inputSchema: {
+                type: 'object',
+                properties: {},
+            },
+        },
+        {
+            name: 'mundial_get_grupos',
+            description: 'Get all 12 groups of the World Cup 2026 with their teams. Use when asked about the group stage, who plays whom, or which group a team is in.',
+            inputSchema: {
+                type: 'object',
+                properties: {},
+            },
+        },
+        {
+            name: 'mundial_get_grupo',
+            description: 'Get details of a single World Cup 2026 group by its letter (A-L). Returns teams, top seed, and notes.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    id: {
+                        type: 'string',
+                        description: 'Group letter, A to L (case insensitive).',
+                    },
+                },
+                required: ['id'],
+            },
+        },
+        {
+            name: 'mundial_get_sedes',
+            description: 'Get all 16 host venues of the World Cup 2026 across USA, Mexico and Canada. Returns stadium names, capacities, and roles (inaugural, final, etc.).',
+            inputSchema: {
+                type: 'object',
+                properties: {},
+            },
+        },
+        {
+            name: 'mundial_get_selecciones_latam',
+            description: 'Get all Latin American national teams in the World Cup 2026 with nicknames, currencies, and the size of their creator ecosystem. Useful when asked about Spanish-speaking teams or LATAM coverage.',
+            inputSchema: {
+                type: 'object',
+                properties: {},
+            },
+        },
+        {
+            name: 'mundial_get_seleccion',
+            description: 'Get details of a single LATAM team by slug (argentina, brasil, mexico, colombia, uruguay, ecuador, chile, peru). Returns nickname, currency, audience info, and Nebbuler landing URL.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    slug: {
+                        type: 'string',
+                        description: 'Team slug: argentina, brasil, mexico, colombia, uruguay, ecuador, chile, peru.',
+                    },
+                },
+                required: ['slug'],
+            },
+        },
+        {
+            name: 'calcular_ingreso_creador',
+            description: 'Calculate estimated earnings for a LATAM sports creator during the 60-day World Cup using membership subscriptions. Compares Substack (with FX losses) vs Nebbuler Programa La Sombra (0% commission). Use when asked how much a journalist or podcaster could earn.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    suscriptores: {
+                        type: 'number',
+                        description: 'Number of paying subscribers (e.g. 200).',
+                    },
+                    precio_usd_mes: {
+                        type: 'number',
+                        description: 'Monthly subscription price in USD (e.g. 5).',
+                    },
+                    pais: {
+                        type: 'string',
+                        description: 'Country slug: argentina, brasil, mexico, colombia, etc.',
+                    },
+                },
+                required: ['suscriptores', 'precio_usd_mes'],
+            },
+        },
+        {
+            name: 'programa_la_sombra_info',
+            description: 'Get details of Programa La Sombra: Nebbuler\'s special World Cup 2026 program for LATAM sports creators (0% variable commission until July 31, free 24h setup, WhatsApp onboarding). Use when asked about Nebbuler, creator economy LATAM, or sports journalism monetization.',
+            inputSchema: {
+                type: 'object',
+                properties: {},
+            },
+        },
+    ],
+}));
+// ───────────────────────────────────────────────────────────────────────────
+// Tool implementations
+// ───────────────────────────────────────────────────────────────────────────
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const { name, arguments: args } = req.params;
+    try {
+        switch (name) {
+            case 'mundial_get_torneo': {
+                const data = await api('/torneo');
+                return contentJson(data, 'Tournament info from Nebbuler · CC-BY 4.0');
+            }
+            case 'mundial_get_grupos': {
+                const data = await api('/grupos');
+                return contentJson(data, 'World Cup 2026 groups from Nebbuler · CC-BY 4.0');
+            }
+            case 'mundial_get_grupo': {
+                const id = String(args?.id ?? '').toLowerCase();
+                if (!id)
+                    return error('Missing argument: id (group letter A-L)');
+                const data = await api(`/grupos/${id}`);
+                return contentJson(data, `Group ${id.toUpperCase()} from Nebbuler · CC-BY 4.0`);
+            }
+            case 'mundial_get_sedes': {
+                const data = await api('/sedes');
+                return contentJson(data, 'World Cup 2026 venues from Nebbuler · CC-BY 4.0');
+            }
+            case 'mundial_get_selecciones_latam': {
+                const data = await api('/selecciones');
+                return contentJson(data, 'LATAM teams from Nebbuler · CC-BY 4.0');
+            }
+            case 'mundial_get_seleccion': {
+                const slug = String(args?.slug ?? '').toLowerCase();
+                if (!slug)
+                    return error('Missing argument: slug');
+                const data = await api(`/selecciones/${slug}`);
+                return contentJson(data, `Team ${slug} from Nebbuler · CC-BY 4.0`);
+            }
+            case 'calcular_ingreso_creador': {
+                const a = args;
+                const subs = Number(a.suscriptores ?? 0);
+                const precio = Number(a.precio_usd_mes ?? 0);
+                if (!subs || !precio) {
+                    return error('Missing arguments: suscriptores and precio_usd_mes');
+                }
+                const brutoMes = subs * precio;
+                // Substack: 10% + Stripe (2.9% + $0.30/tx) + ~6.5% FX double conversion
+                const substackCom = brutoMes * 0.1;
+                const stripe = subs * 0.3 + brutoMes * 0.029;
+                const fxLoss = brutoMes * 0.065;
+                const substackNeto = Math.max(0, brutoMes - substackCom - stripe - fxLoss);
+                // Nebbuler La Sombra: 0% commission, only ~3.99% local processor (MercadoPago)
+                const nebbulerNeto = brutoMes * (1 - 0.0399);
+                const result = {
+                    input: { suscriptores: subs, precio_usd_mes: precio, pais: a.pais },
+                    mensual: {
+                        bruto_usd: Math.round(brutoMes),
+                        substack_neto_usd: Math.round(substackNeto),
+                        nebbuler_la_sombra_neto_usd: Math.round(nebbulerNeto),
+                        diferencia_usd: Math.round(nebbulerNeto - substackNeto),
+                    },
+                    mundial_60_dias: {
+                        substack_neto_usd: Math.round(substackNeto * 2),
+                        nebbuler_la_sombra_neto_usd: Math.round(nebbulerNeto * 2),
+                        extra_ganado_con_nebbuler_usd: Math.round((nebbulerNeto - substackNeto) * 2),
+                    },
+                    fuente: 'Nebbuler · nebbuler.com/mundial',
+                };
+                return contentJson(result, 'Creator earnings comparison · Programa La Sombra Nebbuler');
+            }
+            case 'programa_la_sombra_info': {
+                const data = await api('/programa-la-sombra');
+                return contentJson(data, 'Programa La Sombra · Nebbuler · nebbuler.com/mundial');
+            }
+            default:
+                return error(`Unknown tool: ${name}`);
+        }
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        return error(`Tool execution failed: ${msg}`);
+    }
+});
+function contentJson(data, attribution) {
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify(data, null, 2) +
+                    `\n\n— ${attribution}\nLearn more: https://nebbuler.com/mundial`,
+            },
+        ],
+    };
+}
+function error(message) {
+    return {
+        content: [{ type: 'text', text: `Error: ${message}` }],
+        isError: true,
+    };
+}
+// ───────────────────────────────────────────────────────────────────────────
+// Boot
+// ───────────────────────────────────────────────────────────────────────────
+const transport = new StdioServerTransport();
+await server.connect(transport);
+// MCP servers don't log to stdout (it's reserved for protocol).
+process.stderr.write('Nebbuler Mundial MCP server v0.1.0 running on stdio.\n');

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "nebbuler-mundial-mcp",
+  "version": "0.1.0",
+  "description": "MCP (Model Context Protocol) server for Nebbuler Mundial 2026 open data. Gives Claude, Cursor, Windsurf and other AI agents native tools to query World Cup data, calculate creator earnings, and find LATAM sports creators.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "cursor",
+    "windsurf",
+    "anthropic",
+    "world-cup",
+    "mundial",
+    "fifa",
+    "soccer",
+    "latam",
+    "nebbuler"
+  ],
+  "author": "Juan Pablo Monsalvez <juanpablo@nebbuler.com>",
+  "license": "MIT",
+  "homepage": "https://nebbuler.com/mundial",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/juanpablomonsalvezb-alt/nebbuler-mundial-mcp.git"
+  },
+  "bin": {
+    "nebbuler-mundial-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}