almanac-mcp 0.2.0__tar.gz

almanac_mcp-0.2.0/.gitignore

@@ -0,0 +1,96 @@
+# build output
+dist/
+.astro/
+
+# superpowers brainstorming session artifacts (mockups, server state)
+.superpowers/
+
+# Skills instaladas localmente via `npx skills add` (per-machine, no commit)
+.agents/
+
+# dependencies
+node_modules/
+
+# logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# environment
+.env
+.env.production
+.env.local
+
+# OS
+.DS_Store
+Thumbs.db
+
+# editors
+.vscode/
+.idea/
+
+# python
+__pycache__/
+*.pyc
+.venv/
+venv/
+
+# bundle original (entregado en zip, no se versiona)
+bcra-source-v2/
+
+# Carpetas auxiliares del dump completo del BCRA dentro de cada snapshot.
+# El pipeline solo usa los 14 .txt en el root del snapshot. El resto queda
+# local (con normalize_snapshot.py --keep-extras) por si lo necesitamos en
+# el futuro, pero no se sube al remote para no inflar el repo.
+# `**` matchea cualquier profundidad: algunos zips traen un wrapper extra
+# (ej. data/snapshots/202012/202012d/Entfin/...).
+data/snapshots/**/Asociac/
+data/snapshots/**/Entcam/
+data/snapshots/**/Entfin/
+data/snapshots/**/Info_Hist/
+data/snapshots/**/Repres/
+data/snapshots/**/Ayuda IEF.pdf
+
+# vercel
+.vercel/
+
+# pytest
+.pytest_cache/
+
+# claude code (preferencias locales del editor)
+.claude/settings.local.json
+
+# almanac — entornos virtuales y artefactos locales
+almanac/.venv/
+almanac/mcp/Scripts/
+almanac/mcp/Lib/
+almanac/mcp/Include/
+almanac/dist/
+almanac/build/
+almanac/*.egg-info/
+almanac/mcp/*.egg-info/
+almanac/.pytest_cache/
+almanac/mcp/.pytest_cache/
+almanac/.ruff_cache/
+almanac/mcp/.ruff_cache/
+almanac/.mypy_cache/
+almanac/htmlcov/
+almanac/.coverage
+almanac/coverage.xml
+
+# secrets locales de almanac
+almanac/.env
+almanac/.env.*
+!almanac/.env.example
+
+# Working folder local de assets para LinkedIn (PPTX, screenshots, scripts).
+# No se versiona — son artefactos de marketing personal, no del producto.
+_linkedin/
+
+# Fixtures pesadas que no se commiten (.7z BCRA mensuales ~33 MB c/u, XLS).
+# El scraper baja desde la URL oficial en CI; el archivo extraido sirve solo
+# para iteracion local. Si se necesita reproducibilidad de un mes especifico,
+# se puede pasar a gold/ en R2 con pin de hash.
+almanac/.fixtures/bcra_entidades_financieras_padron/*.7z
+almanac/.fixtures/bcra_entidades_financieras_padron/202*/

almanac_mcp-0.2.0/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: almanac-mcp
+Version: 0.2.0
+Summary: MCP server for Almanac — Argentine financial data (BCRA, CNV, INDEC, SEC) for Claude Desktop, Cursor, Copilot
+Project-URL: Homepage, https://almanac.ar
+Project-URL: Documentation, https://almanac.ar/mcp
+Project-URL: Source, https://github.com/nicolascolombo/Almanac
+Author: Nicolás Colombo
+License: Proprietary
+Keywords: almanac,argentina,bcra,claude,cnv,financial-data,indec,mcp,sec
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp>=1.0
+Requires-Dist: pydantic>=2.8
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# almanac-mcp
+
+MCP server for [Almanac](https://almanac.ar) — Argentine financial and
+economic data (BCRA, CNV, INDEC, SEC) exposed directly to your AI
+assistant (Claude Desktop, Cursor, Copilot, etc.) via the Model Context
+Protocol.
+
+## What it does
+
+Once connected, your AI assistant can:
+
+- **List the catalog** of published datasets (BCRA monetarias,
+  tipos de cambio, INDEC IPC, CNV hechos relevantes, SEC EDGAR XBRL
+  filings, and more)
+- **Inspect schemas** column-by-column with descriptions, types, and
+  pre-built example queries
+- **Run SQL** directly against the production datasets — sub-second
+  latency, cross-dataset JOINs work natively (e.g. join INDEC IPC with
+  BCRA reservas, or SEC financial facts with CNV hechos relevantes by
+  CUIT)
+- **Download full snapshots** as signed parquet/CSV URLs to work locally
+  with DuckDB, polars, pandas, R, or any other tool
+
+## v0.2 architecture (HTTP-only)
+
+In v0.2 the client is a thin HTTP wrapper. No psycopg, no DuckDB, no
+parquet libs — the package installs in seconds and ships only `mcp`,
+`httpx`, and `pydantic`. All data plane operations are server-side at
+`https://almanac.ar/api/mcp/v1/invoke`. Benefits:
+
+- Zero credentials on your machine (just `ALMANAC_API_KEY`)
+- Schema discovery + AI metadata live server-side and update without a
+  client version bump
+- Telemetry and rate limits centralised
+
+## Requirements
+
+- Python 3.10+
+- An Almanac account on plan **Pro+** or **Enterprise** (the MCP server
+  is not part of the Pro tier)
+- An API key generated at <https://almanac.ar/account/api-keys>
+
+## Install
+
+```bash
+uvx almanac-mcp                  # try it without installing
+# or
+pip install almanac-mcp          # persistent install
+```
+
+## Configuration
+
+The client requires `ALMANAC_API_KEY` in the environment. It optionally
+respects `ALMANAC_SITE_URL` (defaults to `https://almanac.ar`).
+
+### Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`
+(macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "almanac": {
+      "command": "uvx",
+      "args": ["almanac-mcp"],
+      "env": {
+        "ALMANAC_API_KEY": "alm_your_key_here"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The Almanac tools appear automatically.
+
+### Cursor
+
+`~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "almanac": {
+      "command": "uvx",
+      "args": ["almanac-mcp"],
+      "env": { "ALMANAC_API_KEY": "alm_your_key_here" }
+    }
+  }
+}
+```
+
+### GitHub Copilot (VS Code)
+
+Add to `.vscode/settings.json`:
+
+```json
+{
+  "github.copilot.chat.mcp.servers": {
+    "almanac": {
+      "command": "uvx",
+      "args": ["almanac-mcp"],
+      "env": { "ALMANAC_API_KEY": "alm_your_key_here" }
+    }
+  }
+}
+```
+
+## Tools
+
+All four tools follow the `<domain>.<action>` naming convention:
+
+### `catalog.list`
+
+Lists every published dataset with a brief summary. No params.
+
+### `catalog.get(dataset_id)`
+
+Full metadata for a single dataset, including:
+
+- Description, frequency, historical depth
+- Business questions and typical use cases
+- Methodology notes and known gotchas
+- Pre-built example SQL queries
+- `mcp.table_name` — exact Postgres table (e.g. `data_bcra_monetarias_indicadores`)
+- `mcp.columns` — list of `{name, type, nullable}` to write SQL correctly
+
+### `data.query(sql)`
+
+Runs a `SELECT`/`WITH`/`EXPLAIN` query against the production tables.
+DDL/DML are rejected. Server-side constraints:
+
+- `statement_timeout` 30 s
+- 10.000 row cap (truncation signalled in response)
+- `work_mem` 32 MB
+
+Response shape: `{ rows, row_count, truncated, columns }`. Tables are
+documented through `catalog.get` (`mcp.table_name`).
+
+### `data.snapshot_url(dataset_id, format="parquet")`
+
+Returns a 10-minute signed R2 URL to the complete production snapshot
+(parquet or CSV). Use this when you want to download the full dataset
+and work with it locally.
+
+## Example session
+
+> User: "What were Argentina's international reserves on the last
+> business day, and how do they compare to a year ago?"
+
+The assistant will:
+
+1. Call `catalog.list` to see what is available.
+2. Call `catalog.get("bcra.monetarias.indicadores")` to find the
+   relevant variable and learn the table schema.
+3. Call `data.query` with something like:
+
+```sql
+SELECT fecha, valor, unidad
+FROM data_bcra_monetarias_indicadores
+WHERE descripcion ILIKE '%reservas internacionales%'
+  AND fecha <= CURRENT_DATE
+ORDER BY fecha DESC
+LIMIT 30
+```
+
+4. Compare the most recent value with the same date a year ago and
+   reply with concrete numbers.
+
+## License
+
+Proprietary. Use of this package requires an active Almanac subscription
+(plan Pro+ or Enterprise). See <https://almanac.ar/pricing> for details.
+
+## Support
+
+- Documentation: <https://almanac.ar/mcp>
+- Issues: <https://github.com/nicolascolombo/Almanac/issues>
+- Email: contacto@almanac.ar

almanac_mcp-0.2.0/README.md

@@ -0,0 +1,179 @@
+# almanac-mcp
+
+MCP server for [Almanac](https://almanac.ar) — Argentine financial and
+economic data (BCRA, CNV, INDEC, SEC) exposed directly to your AI
+assistant (Claude Desktop, Cursor, Copilot, etc.) via the Model Context
+Protocol.
+
+## What it does
+
+Once connected, your AI assistant can:
+
+- **List the catalog** of published datasets (BCRA monetarias,
+  tipos de cambio, INDEC IPC, CNV hechos relevantes, SEC EDGAR XBRL
+  filings, and more)
+- **Inspect schemas** column-by-column with descriptions, types, and
+  pre-built example queries
+- **Run SQL** directly against the production datasets — sub-second
+  latency, cross-dataset JOINs work natively (e.g. join INDEC IPC with
+  BCRA reservas, or SEC financial facts with CNV hechos relevantes by
+  CUIT)
+- **Download full snapshots** as signed parquet/CSV URLs to work locally
+  with DuckDB, polars, pandas, R, or any other tool
+
+## v0.2 architecture (HTTP-only)
+
+In v0.2 the client is a thin HTTP wrapper. No psycopg, no DuckDB, no
+parquet libs — the package installs in seconds and ships only `mcp`,
+`httpx`, and `pydantic`. All data plane operations are server-side at
+`https://almanac.ar/api/mcp/v1/invoke`. Benefits:
+
+- Zero credentials on your machine (just `ALMANAC_API_KEY`)
+- Schema discovery + AI metadata live server-side and update without a
+  client version bump
+- Telemetry and rate limits centralised
+
+## Requirements
+
+- Python 3.10+
+- An Almanac account on plan **Pro+** or **Enterprise** (the MCP server
+  is not part of the Pro tier)
+- An API key generated at <https://almanac.ar/account/api-keys>
+
+## Install
+
+```bash
+uvx almanac-mcp                  # try it without installing
+# or
+pip install almanac-mcp          # persistent install
+```
+
+## Configuration
+
+The client requires `ALMANAC_API_KEY` in the environment. It optionally
+respects `ALMANAC_SITE_URL` (defaults to `https://almanac.ar`).
+
+### Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`
+(macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "almanac": {
+      "command": "uvx",
+      "args": ["almanac-mcp"],
+      "env": {
+        "ALMANAC_API_KEY": "alm_your_key_here"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The Almanac tools appear automatically.
+
+### Cursor
+
+`~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "almanac": {
+      "command": "uvx",
+      "args": ["almanac-mcp"],
+      "env": { "ALMANAC_API_KEY": "alm_your_key_here" }
+    }
+  }
+}
+```
+
+### GitHub Copilot (VS Code)
+
+Add to `.vscode/settings.json`:
+
+```json
+{
+  "github.copilot.chat.mcp.servers": {
+    "almanac": {
+      "command": "uvx",
+      "args": ["almanac-mcp"],
+      "env": { "ALMANAC_API_KEY": "alm_your_key_here" }
+    }
+  }
+}
+```
+
+## Tools
+
+All four tools follow the `<domain>.<action>` naming convention:
+
+### `catalog.list`
+
+Lists every published dataset with a brief summary. No params.
+
+### `catalog.get(dataset_id)`
+
+Full metadata for a single dataset, including:
+
+- Description, frequency, historical depth
+- Business questions and typical use cases
+- Methodology notes and known gotchas
+- Pre-built example SQL queries
+- `mcp.table_name` — exact Postgres table (e.g. `data_bcra_monetarias_indicadores`)
+- `mcp.columns` — list of `{name, type, nullable}` to write SQL correctly
+
+### `data.query(sql)`
+
+Runs a `SELECT`/`WITH`/`EXPLAIN` query against the production tables.
+DDL/DML are rejected. Server-side constraints:
+
+- `statement_timeout` 30 s
+- 10.000 row cap (truncation signalled in response)
+- `work_mem` 32 MB
+
+Response shape: `{ rows, row_count, truncated, columns }`. Tables are
+documented through `catalog.get` (`mcp.table_name`).
+
+### `data.snapshot_url(dataset_id, format="parquet")`
+
+Returns a 10-minute signed R2 URL to the complete production snapshot
+(parquet or CSV). Use this when you want to download the full dataset
+and work with it locally.
+
+## Example session
+
+> User: "What were Argentina's international reserves on the last
+> business day, and how do they compare to a year ago?"
+
+The assistant will:
+
+1. Call `catalog.list` to see what is available.
+2. Call `catalog.get("bcra.monetarias.indicadores")` to find the
+   relevant variable and learn the table schema.
+3. Call `data.query` with something like:
+
+```sql
+SELECT fecha, valor, unidad
+FROM data_bcra_monetarias_indicadores
+WHERE descripcion ILIKE '%reservas internacionales%'
+  AND fecha <= CURRENT_DATE
+ORDER BY fecha DESC
+LIMIT 30
+```
+
+4. Compare the most recent value with the same date a year ago and
+   reply with concrete numbers.
+
+## License
+
+Proprietary. Use of this package requires an active Almanac subscription
+(plan Pro+ or Enterprise). See <https://almanac.ar/pricing> for details.
+
+## Support
+
+- Documentation: <https://almanac.ar/mcp>
+- Issues: <https://github.com/nicolascolombo/Almanac/issues>
+- Email: contacto@almanac.ar

almanac_mcp-0.2.0/pyproject.toml

@@ -0,0 +1,65 @@
+[project]
+name = "almanac-mcp"
+version = "0.2.0"
+description = "MCP server for Almanac — Argentine financial data (BCRA, CNV, INDEC, SEC) for Claude Desktop, Cursor, Copilot"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{ name = "Nicolás Colombo" }]
+license = { text = "Proprietary" }
+keywords = ["mcp", "almanac", "bcra", "cnv", "indec", "sec", "argentina", "financial-data", "claude"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Financial and Insurance Industry",
+    "License :: Other/Proprietary License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business :: Financial",
+    "Topic :: Scientific/Engineering",
+]
+
+dependencies = [
+    "mcp>=1.0",
+    "httpx>=0.27",
+    "pydantic>=2.8",
+]
+
+[project.urls]
+Homepage = "https://almanac.ar"
+Documentation = "https://almanac.ar/mcp"
+Source = "https://github.com/nicolascolombo/Almanac"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.3",
+    "pytest-asyncio>=0.24",
+    "respx>=0.21",
+    "ruff>=0.7",
+]
+
+[project.scripts]
+almanac-mcp = "almanac_mcp.__main__:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/almanac_mcp"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/almanac_mcp",
+    "README.md",
+    "pyproject.toml",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP"]

almanac_mcp-0.2.0/src/almanac_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""MCP server for the Almanac argentino."""
+
+__version__ = "0.2.0"

almanac_mcp-0.2.0/src/almanac_mcp/__main__.py

@@ -0,0 +1,14 @@
+"""Entrypoint: arranca el MCP server por stdio (modo Claude Desktop / Cursor)."""
+
+from __future__ import annotations
+
+from almanac_mcp.server import build_server
+
+
+def main() -> None:
+    server = build_server()
+    server.run()
+
+
+if __name__ == "__main__":
+    main()

almanac_mcp-0.2.0/src/almanac_mcp/client.py

@@ -0,0 +1,195 @@
+"""Cliente HTTP del MCP server. Habla con /api/mcp/v1/invoke.
+
+Funcionalidad: invoca tools por nombre, maneja retries con backoff
+exponencial para 5xx (server transient), no retry para 4xx (input
+inválido del agente), traduce errores estructurados a excepciones
+Python pythónicas.
+
+Tipos de error:
+    InvalidParams      → el agente mandó params malformados; corregir SQL/args
+    ToolUnknown        → tool name no existe en el server (versión mismatch)
+    NotFound           → dataset/snapshot no existe
+    TierRequired       → API key con tier insuficiente (Pro+ requerido)
+    RateLimited        → 429, esperar y reintentar
+    Timeout            → query > 30s, refinar
+    InternalError      → 500 del server (poco común)
+    NetworkError       → connection refused / DNS / etc.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+import uuid
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+from almanac_mcp.settings import Settings
+
+log = logging.getLogger(__name__)
+
+USER_AGENT = "almanac-mcp/0.2.0 (+https://almanac.ar/mcp)"
+REQUEST_TIMEOUT_S = 60.0
+MAX_RETRIES = 3
+RETRY_BASE_DELAY_S = 0.5
+
+
+class MCPClientError(Exception):
+    """Base de errors del client."""
+
+    code: str
+
+    def __init__(self, message: str, code: str = "unknown", details: dict[str, Any] | None = None):
+        super().__init__(message)
+        self.code = code
+        self.details = details or {}
+
+
+class InvalidParams(MCPClientError):
+    code = "invalid_params"
+
+
+class ToolUnknown(MCPClientError):
+    code = "tool_unknown"
+
+
+class NotFound(MCPClientError):
+    code = "not_found"
+
+
+class TierRequired(MCPClientError):
+    code = "tier_required"
+
+
+class RateLimited(MCPClientError):
+    code = "rate_limited"
+
+
+class TimeoutError(MCPClientError):  # noqa: A001
+    code = "timeout"
+
+
+class InternalError(MCPClientError):
+    code = "internal"
+
+
+class NetworkError(MCPClientError):
+    code = "network"
+
+
+_ERROR_BY_CODE: dict[str, type[MCPClientError]] = {
+    "invalid_params": InvalidParams,
+    "tool_unknown": ToolUnknown,
+    "not_found": NotFound,
+    "tier_required": TierRequired,
+    "rate_limited": RateLimited,
+    "timeout": TimeoutError,
+    "internal": InternalError,
+}
+
+
+@dataclass(frozen=True)
+class InvokeResult:
+    result: Any
+    request_id: str
+    latency_ms: int
+
+
+class MCPHttpClient:
+    """Cliente HTTP del MCP server. Singleton por proceso típicamente."""
+
+    def __init__(self, settings: Settings, *, transport: httpx.BaseTransport | None = None):
+        self.settings = settings
+        self._http = httpx.Client(
+            base_url=settings.site_url,
+            timeout=REQUEST_TIMEOUT_S,
+            headers={
+                "Authorization": f"Bearer {settings.api_key}",
+                "User-Agent": USER_AGENT,
+                "Content-Type": "application/json",
+            },
+            transport=transport,
+        )
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> MCPHttpClient:
+        return self
+
+    def __exit__(self, *_exc_info: Any) -> None:
+        self.close()
+
+    def invoke(
+        self,
+        tool: str,
+        params: dict[str, Any] | None = None,
+        *,
+        client_info: dict[str, str] | None = None,
+    ) -> InvokeResult:
+        request_id = str(uuid.uuid4())
+        body: dict[str, Any] = {"tool": tool, "request_id": request_id}
+        if params is not None:
+            body["params"] = params
+        if client_info:
+            body["client_info"] = client_info
+
+        last_exc: Exception | None = None
+        for attempt in range(MAX_RETRIES):
+            try:
+                resp = self._http.post("/api/mcp/v1/invoke", json=body)
+            except httpx.RequestError as e:
+                last_exc = e
+                if attempt < MAX_RETRIES - 1:
+                    self._sleep_backoff(attempt)
+                    continue
+                raise NetworkError(f"Error de red contra Almanac: {e}") from e
+
+            # 5xx → retry; 4xx → fail immediate; 2xx → parse
+            if resp.status_code >= 500:
+                last_exc = httpx.HTTPStatusError(
+                    f"Server {resp.status_code}", request=resp.request, response=resp
+                )
+                if attempt < MAX_RETRIES - 1:
+                    self._sleep_backoff(attempt)
+                    continue
+                # Out of retries, fall through to parse the error body.
+
+            return self._parse_response(resp, request_id)
+
+        # Solo llegamos acá si NetworkError no relanzó (no debería pasar).
+        raise NetworkError(f"Sin respuesta del server tras {MAX_RETRIES} intentos: {last_exc}")
+
+    @staticmethod
+    def _sleep_backoff(attempt: int) -> None:
+        delay = RETRY_BASE_DELAY_S * (2**attempt)
+        log.debug("mcp_client.retry", extra={"attempt": attempt, "delay_s": delay})
+        time.sleep(delay)
+
+    @staticmethod
+    def _parse_response(resp: httpx.Response, request_id: str) -> InvokeResult:
+        try:
+            payload = resp.json()
+        except ValueError as e:
+            raise InternalError(
+                f"Server devolvió body no-JSON (status {resp.status_code}): {resp.text[:200]}",
+            ) from e
+
+        latency_ms = int(payload.get("latency_ms") or 0)
+        server_request_id = payload.get("request_id") or request_id
+
+        if payload.get("ok") is True:
+            return InvokeResult(
+                result=payload.get("result"),
+                request_id=server_request_id,
+                latency_ms=latency_ms,
+            )
+
+        error = payload.get("error") or {}
+        code = error.get("code") or "internal"
+        message = error.get("message") or f"Server error {resp.status_code}"
+        details = error.get("details") or {}
+        exc_cls = _ERROR_BY_CODE.get(code, InternalError)
+        raise exc_cls(message, code=code, details=details)

almanac_mcp-0.2.0/src/almanac_mcp/server.py

@@ -0,0 +1,131 @@
+"""FastMCP server v0.2 — delega todo al endpoint HTTP /api/mcp/v1/invoke.
+
+Las 4 tools v0.2 con dotted naming (`<dominio>.<acción>`):
+    catalog.list          → lista datasets publicados
+    catalog.get           → metadata completa + schema + example_queries
+    data.snapshot_url     → signed URL al snapshot productivo completo (R2)
+    data.query            → ejecuta SQL contra Postgres data_* (datos completos)
+
+El client Python ya NO toca Postgres ni R2 directo. Todo el compute y
+security pasa por el web server. Beneficios:
+    - Cero credenciales en el cliente (solo ALMANAC_API_KEY)
+    - Schema discovery + AI metadata viven server-side y se actualizan sin
+      bump de versión del client
+    - Telemetry centralizado en mcp_invocations
+"""
+
+from __future__ import annotations
+
+import logging
+import platform
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+
+from almanac_mcp import __version__
+from almanac_mcp.client import MCPHttpClient
+from almanac_mcp.settings import Settings
+
+log = logging.getLogger(__name__)
+
+
+def _client_info() -> dict[str, str]:
+    """Metadata del client para telemetry server-side."""
+    return {
+        "client": "almanac-mcp",
+        "version": __version__,
+        "os": platform.system().lower(),
+    }
+
+
+def build_server(settings: Settings | None = None) -> FastMCP:
+    """Construye el server MCP con las 4 tools registradas."""
+    if settings is None:
+        settings = Settings.from_env()
+
+    mcp = FastMCP("almanac")
+    client = MCPHttpClient(settings)
+
+    @mcp.tool(name="catalog.list")
+    def catalog_list() -> list[dict[str, Any]]:
+        """Lista los datasets publicados del Almanac (BCRA, CNV, INDEC, SEC, etc).
+
+        Cada item trae: dataset_id, name, source, description, frequency,
+        historical_depth. Para metadata completa + schema de columnas + queries
+        de ejemplo, usar catalog.get(dataset_id).
+        """
+        return client.invoke("catalog.list", {}, client_info=_client_info()).result
+
+    @mcp.tool(name="catalog.get")
+    def catalog_get(dataset_id: str) -> dict[str, Any]:
+        """Devuelve metadata completa + schema de la tabla Postgres del dataset.
+
+        Incluye:
+            - Descripción + business_questions + methodology_notes + gotchas
+            - example_queries (templates SQL listos para usar)
+            - mcp.table_name: nombre exacto de la tabla en Postgres (data_*)
+            - mcp.columns: lista de (name, type, nullable) para armar SQL
+            - mcp.queryable_via_sql: bool — si False, usar data.snapshot_url
+
+        Args:
+            dataset_id: Identificador formato {fuente}.{categoria}.{nombre},
+                ej: 'bcra.monetarias.indicadores'.
+        """
+        return client.invoke(
+            "catalog.get",
+            {"dataset_id": dataset_id},
+            client_info=_client_info(),
+        ).result
+
+    @mcp.tool(name="data.snapshot_url")
+    def data_snapshot_url(dataset_id: str, format: str = "parquet") -> dict[str, Any]:
+        """Devuelve una URL firmada R2 de 10 minutos al snapshot productivo completo.
+
+        Útil cuando el cliente quiere bajar el dataset completo y trabajarlo
+        localmente (DuckDB, polars, pandas, R, etc). Para queries SQL rápidas
+        sobre los datos completos sin descarga, usar `data.query`.
+
+        Args:
+            dataset_id: Identificador del dataset.
+            format: 'parquet' (recomendado) o 'csv'.
+
+        Returns:
+            { url, expires_in_seconds, dataset_id, format,
+              snapshot: { snapshot_at, rows_count, file_size_bytes } }
+        """
+        return client.invoke(
+            "data.snapshot_url",
+            {"dataset_id": dataset_id, "format": format},
+            client_info=_client_info(),
+        ).result
+
+    @mcp.tool(name="data.query")
+    def data_query(sql: str) -> dict[str, Any]:
+        """Ejecuta una query SQL SELECT/WITH/EXPLAIN sobre las tablas de Almanac.
+
+        Las tablas disponibles tienen prefijo `data_*` (ver catalog.get →
+        mcp.table_name por dataset). Soporta JOINs cross-dataset entre BCRA,
+        INDEC, CNV, SEC. Solo lectura — DDL/DML rechazados.
+
+        Constraints server-side:
+            - statement_timeout: 30s
+            - cap de filas: 10.000 (truncated=true si excede)
+            - work_mem: 32 MB
+
+        Args:
+            sql: Query SQL válida. Ej:
+                "SELECT fecha, valor FROM data_bcra_monetarias_indicadores
+                 WHERE id_variable = 1 AND fecha >= '2024-01-01'
+                 ORDER BY fecha DESC LIMIT 100"
+
+        Returns:
+            { rows: list[dict], row_count: int, truncated: bool,
+              columns: list[str] }
+        """
+        return client.invoke(
+            "data.query",
+            {"sql": sql},
+            client_info=_client_info(),
+        ).result
+
+    return mcp

almanac_mcp-0.2.0/src/almanac_mcp/settings.py

@@ -0,0 +1,41 @@
+"""Configuración del MCP client v0.2.
+
+v0.2 cambia el modelo: en lugar de pegarle directo a Postgres / R2,
+todas las tools delegan al endpoint HTTP /api/mcp/v1/invoke del web
+de Almanac. El client solo necesita URL del site + API key del user.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Settings:
+    """Configuración inmutable del client. Sin I/O en __init__."""
+
+    site_url: str
+    api_key: str
+
+    @classmethod
+    def from_env(cls) -> Settings:
+        api_key = os.environ.get("ALMANAC_API_KEY", "").strip()
+        if not api_key:
+            raise RuntimeError(
+                "ALMANAC_API_KEY no está definida. Generá una key en "
+                "https://almanac.ar/account/api-keys (requiere plan Pro+ o Enterprise) "
+                "y configurala en el env del cliente MCP."
+            )
+        if not api_key.startswith("alm_"):
+            raise RuntimeError(
+                "ALMANAC_API_KEY tiene formato inválido. Las keys de Almanac "
+                "arrancan con 'alm_'. Revisá tu config."
+            )
+        site_url = os.environ.get("ALMANAC_SITE_URL", "https://almanac.ar").rstrip("/")
+        return cls(site_url=site_url, api_key=api_key)
+
+    @property
+    def invoke_url(self) -> str:
+        """URL del endpoint multiplexor JSON del web server."""
+        return f"{self.site_url}/api/mcp/v1/invoke"