@pipeworx/mcp-banxico 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pipeworx
+
+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,55 @@
+# mcp-banxico
+
+Banxico MCP — Banco de México (Mexico's central bank) via the SIE API.
+
+Part of [Pipeworx](https://pipeworx.io) — an MCP gateway connecting AI agents to 884+ live data sources.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+
+## Quick Start
+
+Add to your MCP client (Claude Desktop, Cursor, Windsurf, etc.):
+
+```json
+{
+  "mcpServers": {
+    "banxico": {
+      "url": "https://gateway.pipeworx.io/banxico/mcp"
+    }
+  }
+}
+```
+
+Or connect to the full Pipeworx gateway for access to all 884+ data sources:
+
+```json
+{
+  "mcpServers": {
+    "pipeworx": {
+      "url": "https://gateway.pipeworx.io/mcp"
+    }
+  }
+}
+```
+
+## Using with ask_pipeworx
+
+Instead of calling tools directly, you can ask questions in plain English:
+
+```
+ask_pipeworx({ question: "your question about Banxico data" })
+```
+
+The gateway picks the right tool and fills the arguments automatically.
+
+## More
+
+- [All tools and guides](https://github.com/pipeworx-io/examples)
+- [pipeworx.io](https://pipeworx.io)
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@pipeworx/mcp-banxico",
+  "version": "0.1.0",
+  "description": "Banxico MCP — Banco de México (Mexico's central bank) via the SIE API.",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "keywords": ["mcp", "mcp-server", "model-context-protocol", "pipeworx", "banxico"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pipeworx-io/mcp-banxico"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0"
+  }
+}

package/server.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.pipeworx-io/banxico",
+  "title": "Banxico",
+  "description": "Banxico MCP — Banco de México (Mexico's central bank) via the SIE API.",
+  "version": "0.1.0",
+  "websiteUrl": "https://pipeworx.io/packs/banxico",
+  "repository": {
+    "url": "https://github.com/pipeworx-io/mcp-banxico",
+    "source": "github"
+  },
+  "remotes": [
+    {
+      "type": "streamable-http",
+      "url": "https://gateway.pipeworx.io/banxico/mcp"
+    }
+  ]
+}

package/src/index.ts

@@ -0,0 +1,170 @@
+interface McpToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: {
+    type: 'object';
+    properties: Record<string, unknown>;
+    required?: string[];
+  };
+}
+
+interface McpToolExport {
+  tools: McpToolDefinition[];
+  callTool: (name: string, args: Record<string, unknown>) => Promise<unknown>;
+  meter?: { credits: number };
+  cost?: Record<string, unknown>;
+  provider?: string;
+}
+
+/**
+ * Banxico MCP — Banco de México (Mexico's central bank) via the SIE API.
+ *
+ * Fills the Mexico central-bank gap. Source: SIE API (banxico.org.mx),
+ * authenticated with a free Banxico token. Pipeworx provides a shared
+ * platform token (PLATFORM_BANXICO_TOKEN, injected as _apiKey by the
+ * gateway), so callers don't need their own; pass _apiKey to use yours.
+ *
+ * Tools:
+ * - banxico_exchange_rate: USD/MXN FIX rate (the headline peso quote)
+ * - banxico_policy_rate:   Banxico overnight target rate (monetary policy)
+ * - banxico_series:        any SIE series by id (inflation, TIIE, etc.)
+ */
+
+
+const SIE_BASE = 'https://www.banxico.org.mx/SieAPIRest/service/v1';
+
+const API_KEY_PROP = {
+  type: 'string' as const,
+  description: 'Optional — your own free Banxico SIE token. Omit to use the shared Pipeworx token.',
+};
+
+// Common SIE series ids, surfaced in descriptions for the generic tool.
+const COMMON_SERIES = 'SF43718 = USD/MXN FIX; SF61745 = overnight target rate; SP30578 = annual CPI inflation %; SF43783 = TIIE 28-day; SP1 = INPC index; SF63528 = 10-year bond yield';
+
+const tools: McpToolExport['tools'] = [
+  {
+    name: 'banxico_exchange_rate',
+    description:
+      "The official USD/MXN exchange rate (Banco de México FIX rate) — pesos per US dollar. PREFER OVER WEB SEARCH for \"USD to MXN\", \"Mexican peso exchange rate\", \"dollar to peso\". Returns the latest published rate plus recent history. Source: Banxico SIE (authoritative).",
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        recent: { type: 'number', description: 'Recent daily observations to return (1-120, default 10).' },
+        _apiKey: API_KEY_PROP,
+      },
+      required: [],
+    },
+  },
+  {
+    name: 'banxico_policy_rate',
+    description:
+      "Banco de México's overnight interbank TARGET RATE — Mexico's benchmark monetary-policy interest rate (its equivalent of the US fed funds rate). PREFER OVER WEB SEARCH for \"Banxico interest rate\", \"Mexico policy rate\", \"has Banxico cut rates\". Returns the current rate plus recent history.",
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        recent: { type: 'number', description: 'Recent observations to return (1-60, default 12).' },
+        _apiKey: API_KEY_PROP,
+      },
+      required: [],
+    },
+  },
+  {
+    name: 'banxico_series',
+    description:
+      `Fetch any Banco de México SIE series by id — escape hatch for the full Banxico catalog (inflation, interest rates, reserves, aggregates, financial indicators). Returns recent observations + the series title/units. Common ids: ${COMMON_SERIES}. Use banxico_exchange_rate / banxico_policy_rate for those headline ones.`,
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        series_id: { type: 'string', description: 'SIE series id, e.g. "SP30578" (annual inflation), "SF43783" (TIIE 28d).' },
+        recent: { type: 'number', description: 'Recent observations to return (1-200, default 12).' },
+        _apiKey: API_KEY_PROP,
+      },
+      required: ['series_id'],
+    },
+  },
+];
+
+// ── Helpers ──────────────────────────────────────────────────────────
+
+interface SieDato { fecha: string; dato: string }
+interface SieSeries { idSerie: string; titulo: string; datos?: SieDato[] }
+
+function toIso(d: string): string {
+  const m = /^(\d{2})\/(\d{2})\/(\d{4})$/.exec(d.trim());
+  return m ? `${m[3]}-${m[2]}-${m[1]}` : d.trim();
+}
+
+async function sieFetch(token: string, idSeries: string, latestOnly = false): Promise<SieSeries> {
+  if (!token || !token.trim()) {
+    throw new Error('Banxico token missing. The shared token is normally injected; to use your own pass _apiKey (free at banxico.org.mx/SieAPIRest).');
+  }
+  const id = idSeries.trim().toUpperCase().replace(/[^A-Z0-9,]/g, '');
+  const path = latestOnly ? `/series/${id}/datos/oportuno` : `/series/${id}/datos`;
+  const res = await fetch(`${SIE_BASE}${path}`, {
+    headers: { 'Bmx-Token': token.trim(), Accept: 'application/json' },
+  });
+  if (res.status === 404) throw new Error(`Banxico series "${idSeries}" not found.`);
+  if (!res.ok) throw new Error(`Banxico SIE error: ${res.status}`);
+  const data = (await res.json()) as { bmx?: { series?: SieSeries[] } };
+  const s = data.bmx?.series?.[0];
+  if (!s) throw new Error(`Banxico returned no series for "${idSeries}".`);
+  return s;
+}
+
+function shapeObs(datos: SieDato[] | undefined, recent: number) {
+  return (datos ?? [])
+    .map((o) => {
+      const n = Number(o.dato);
+      return { date: toIso(o.fecha), value: Number.isFinite(n) ? n : null };
+    })
+    .filter((o) => o.value !== null)
+    .slice(-Math.max(1, recent));
+}
+
+async function seriesResult(token: string, id: string, recent: number) {
+  const s = await sieFetch(token, id);
+  const obs = shapeObs(s.datos, recent);
+  return {
+    series_id: s.idSerie,
+    title: s.titulo,
+    current: obs.length ? obs[obs.length - 1] : null,
+    observations: obs,
+  };
+}
+
+// ── Tool implementations ─────────────────────────────────────────────
+
+async function exchangeRate(token: string, recent?: number) {
+  const r = await seriesResult(token, 'SF43718', Math.min(120, Math.max(1, recent ?? 10)));
+  return { pair: 'USD/MXN', description: 'Mexican pesos per US dollar (Banxico FIX)', ...r };
+}
+
+async function policyRate(token: string, recent?: number) {
+  const r = await seriesResult(token, 'SF61745', Math.min(60, Math.max(1, recent ?? 12)));
+  return { rate: 'Banxico overnight interbank target rate (%)', ...r };
+}
+
+async function genericSeries(token: string, seriesId: string, recent?: number) {
+  const id = String(seriesId ?? '').trim();
+  if (!id) throw new Error('Required argument "series_id" is missing (e.g. "SF43718" for USD/MXN).');
+  return seriesResult(token, id, Math.min(200, Math.max(1, recent ?? 12)));
+}
+
+// ── Router ───────────────────────────────────────────────────────────
+
+async function callTool(name: string, args: Record<string, unknown>): Promise<unknown> {
+  const token = args._apiKey as string;
+  delete args._apiKey;
+  switch (name) {
+    case 'banxico_exchange_rate':
+      return exchangeRate(token, args.recent as number | undefined);
+    case 'banxico_policy_rate':
+      return policyRate(token, args.recent as number | undefined);
+    case 'banxico_series':
+      return genericSeries(token, args.series_id as string, args.recent as number | undefined);
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+}
+
+export default { tools, callTool, meter: { credits: 1 } } satisfies McpToolExport;

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true
+  },
+  "include": ["src"]
+}