bcrp-mcp 0.1.0__tar.gz

bcrp_mcp-0.1.0/.env.example

@@ -0,0 +1,5 @@
+# BCRP (Peru central bank) needs no credentials — this file is here only so you can
+# override defaults if you want to.
+
+# Where the disk cache lives (defaults to your OS cache directory).
+# BCRP_CACHE_DIR=

bcrp_mcp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,44 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    name: Build and publish
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/bcrp-mcp
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build and test dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build pytest pytest-asyncio respx
+          python -m pip install .
+
+      - name: Run test suite
+        run: python -m pytest -q
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: Publish distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

bcrp_mcp-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+.venv/
+venv/
+env/
+dist/
+build/
+*.egg-info/
+.eggs/
+.env
+.env.local
+.env.*.local
+*.key
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+uv.lock
+.DS_Store
+Thumbs.db
+
+# npm installer package
+node_modules/
+*.tgz
+# staged at pack time from the canonical skills/ at the repo root
+npm/skills/

bcrp_mcp-0.1.0/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
+this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-08-22
+
+### Added
+
+- Conformance with [`ARSENAL-SPEC.md`](../ARSENAL-SPEC.md), the CLI contract shared
+  by every research server in this workspace:
+  - Five output formats: `table`, `json`, `jsonl`, `csv`, `md`.
+  - A stable JSON envelope (`ok`, `command`, `source`, `fetched_at`, `cached`,
+    `count`, `meta`, `data`, `rows`) and a matching error envelope carrying an
+    actionable `hint`.
+  - Seven documented exit codes, so a script can branch on *why* a call failed.
+  - A disk cache shared across invocations, with `--refresh`, `--no-cache` and a
+    `cache stats|clear|path` subcommand.
+  - `describe --json`: a machine-readable manifest derived from the parser
+    itself, so it cannot drift from the real commands.
+  - UTF-8 output forced on Windows consoles, which default to a code page that
+    cannot encode accented text.
+- A curated catalog so you can find a series code by keyword.
+- Multi-series export in tidy long format (series_code, period, value).
+- `server.json` for the official MCP registry, plus `LICENSE`, `SECURITY.md` and
+  `CONTRIBUTING.md`.
+
+### Changed
+
+- Data goes to stdout and notes to stderr, so piping to `jq` always yields
+  parseable output.
+
+[Unreleased]: https://github.com/JOSETRA44/bcrp-mcp/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/JOSETRA44/bcrp-mcp/releases/tag/v0.1.0

bcrp_mcp-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,49 @@
+# Contributing
+
+Thanks for taking the time. This project is small and the bar is simple: it
+should keep working for the people already using it.
+
+## Getting set up
+
+```bash
+git clone https://github.com/JOSETRA44/bcrp-mcp
+cd BCRP-mcp
+uv sync              # creates the venv and installs dev dependencies
+uv run pytest -q     # run the test suite
+```
+
+## The contract
+
+This CLI implements [`ARSENAL-SPEC.md`](../ARSENAL-SPEC.md), shared with the other
+research servers in this workspace. If you add or change a command, it must keep:
+
+- all five output formats working, including on an **empty** result set;
+- the JSON envelope shape, with `count == len(rows)`;
+- the documented exit codes — an empty result is exit 0, not an error;
+- `describe --json` listing your new command, with `row_fields` and an example;
+- data on stdout, notes and progress on stderr.
+
+Check it with:
+
+```bash
+arsenal doctor bcrp --live
+```
+
+## Tests
+
+- `uv run pytest -q` — the suite must be green before you open a PR.
+
+Tests must be **hermetic**: no network calls, no reliance on the developer's real
+cache directory or credentials. Mock the transport and point the cache at a
+temporary directory.
+
+Name a test so its failure reads as a sentence about the behaviour that broke,
+and add a comment when the *reason* the test exists is not obvious.
+
+## Pull requests
+
+- One logical change per PR.
+- Update `CHANGELOG.md` under `## [Unreleased]`.
+- If you change a tool's description, remember the model reads it on every call:
+  say what the tool returns, when to prefer it over a sibling, and what its
+  parameters mean, with a real example value.

bcrp_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JOSETRA44
+
+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.

bcrp_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,225 @@
+Metadata-Version: 2.5
+Name: bcrp-mcp
+Version: 0.1.0
+Summary: MCP server for the Banco Central de Reserva del Peru (BCRP) statistics API — access macroeconomic data, exchange rates, interest rates, monetary indicators, and more
+Project-URL: Homepage, https://github.com/JOSETRA44/bcrp-mcp
+Project-URL: Repository, https://github.com/JOSETRA44/bcrp-mcp
+Project-URL: Bug Tracker, https://github.com/JOSETRA44/bcrp-mcp/issues
+Project-URL: Documentation, https://estadisticas.bcrp.gob.pe/estadisticas/series/ayuda/api
+Author-email: JOSETRA44 <drivearchiver@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 JOSETRA44
+        
+        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.
+License-File: LICENSE
+Keywords: ai,banco-central,bcrp,economic-data,exchange-rate,gdp,inflation,llm,macroeconomics,mcp,model-context-protocol,peru,statistics
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.11
+Requires-Dist: anyio>=4.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp<2.0.0,>=1.0.0
+Requires-Dist: platformdirs>=4.0.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Description-Content-Type: text/markdown
+
+<img width="1600" height="500" alt="BCRP MCP" src="https://github.com/user-attachments/assets/79323612-ebec-49ea-91d5-321b5950bbbc" />
+
+[![PyPI](https://img.shields.io/pypi/v/bcrp-mcp?logo=pypi&logoColor=white)](https://pypi.org/project/bcrp-mcp/)
+[![Python](https://img.shields.io/pypi/pyversions/bcrp-mcp?logo=python&logoColor=white)](https://pypi.org/project/bcrp-mcp/)
+[![Publish](https://github.com/JOSETRA44/BCRP-mcp/actions/workflows/publish.yml/badge.svg)](https://github.com/JOSETRA44/BCRP-mcp/actions/workflows/publish.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+# BCRP MCP
+
+<!-- mcp-name: io.github.JOSETRA44/bcrp-mcp -->
+
+Servidor [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) para
+consultar **BCRPData**, la base oficial de estadísticas económicas del
+[Banco Central de Reserva del Perú (BCRP)](https://www.bcrp.gob.pe/).
+
+Permite a clientes MCP y agentes de IA consultar tipos de cambio, tasas de
+interés, reservas internacionales, liquidez, crédito, commodities, bolsa y PBI.
+La API del BCRP es pública: **no se necesita API key ni registro**.
+
+## Instalación rápida
+
+Se requiere Python 3.11 o posterior.
+
+### Con `uvx` (recomendado para clientes MCP)
+
+```bash
+uvx bcrp-mcp
+```
+
+### Con `pip`
+
+```bash
+python -m pip install bcrp-mcp
+bcrp-mcp
+```
+
+La instalación también proporciona el CLI `bcrp`:
+
+```bash
+bcrp --help
+bcrp catalog search "tipo de cambio"
+bcrp series latest PD04637PD --n 5
+```
+
+### Desde el código fuente
+
+```bash
+git clone https://github.com/JOSETRA44/BCRP-mcp.git
+cd BCRP-mcp
+uv sync
+uv run bcrp-mcp
+```
+
+## Configuración en clientes MCP
+
+El servidor usa transporte stdio. Con `uvx`, la configuración es la misma en
+Claude Desktop, Claude Code, Cursor y otros clientes compatibles:
+
+```json
+{
+  "mcpServers": {
+    "bcrp": {
+      "command": "uvx",
+      "args": ["bcrp-mcp"]
+    }
+  }
+}
+```
+
+En VS Code + GitHub Copilot (`.vscode/mcp.json`):
+
+```json
+{
+  "servers": {
+    "bcrp": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["bcrp-mcp"]
+    }
+  }
+}
+```
+
+## Herramientas MCP
+
+| Herramienta | Uso |
+|---|---|
+| `bcrp_get_series` | Obtiene 1–10 series con un rango opcional; deben compartir frecuencia. |
+| `bcrp_get_latest` | Obtiene los últimos valores de 1–10 series. |
+| `bcrp_get_series_long` | Exporta hasta 50 series en una tabla larga, incluso con frecuencias mixtas. |
+| `bcrp_describe_series` | Consulta nombre, frecuencia y rango disponible de una serie. |
+| `bcrp_search_catalog` | Busca códigos en el catálogo curado de indicadores. |
+| `bcrp_list_catalog_categories` | Lista las categorías disponibles. |
+| `bcrp_get_macro_snapshot` | Devuelve un resumen de indicadores macroeconómicos clave. |
+
+Ejemplos de preguntas:
+
+```text
+¿Cuál es el tipo de cambio actual en Perú?
+Compara la tasa de referencia y las reservas internacionales desde 2020.
+Obtén un snapshot de los principales indicadores de la economía peruana.
+```
+
+## CLI
+
+El comando `bcrp` usa la misma lógica que el servidor MCP y admite salida para
+terminal o automatización:
+
+```bash
+bcrp series describe PD04637PD
+bcrp series latest PD04637PD PD12301MD --n 5
+bcrp series get PN00196MM --start 2020-1 --end 2024-12
+bcrp catalog categories
+bcrp macro snapshot
+```
+
+Opciones útiles:
+
+```bash
+bcrp series latest PD04637PD --n 5 --json
+bcrp series latest PD04637PD --n 5 --ascii --no-color
+```
+
+Los formatos de período dependen de la frecuencia: diario
+`DD-MM-YYYY`, mensual `YYYY-M`, trimestral `YYYY-Q` y anual `YYYY`.
+Las series de una misma consulta deben tener la misma frecuencia, salvo
+`bcrp_get_series_long`.
+
+## Configuración opcional
+
+Todos los valores tienen valores predeterminados razonables y pueden definirse
+con variables de entorno o un archivo `.env`:
+
+| Variable | Predeterminado | Descripción |
+|---|---:|---|
+| `BCRP_CACHE_TTL` | `300` | Duración de la caché en segundos; `0` la desactiva. |
+| `BCRP_TIMEOUT` | `30` | Timeout HTTP en segundos. |
+| `BCRP_MAX_RETRIES` | `3` | Reintentos ante errores transitorios. |
+| `BCRP_LANGUAGE` | `esp` | Idioma de nombres: `esp` o `ing`. |
+| `LOG_LEVEL` | `INFO` | Nivel de logging. |
+
+No se configura ninguna credencial: BCRPData es de acceso abierto.
+
+## Desarrollo
+
+```bash
+uv sync
+uv run pytest -q
+uv run python -m build
+```
+
+El proyecto usa `src/` layout, Hatchling para construir el paquete y publica
+dos entry points: `bcrp-mcp` (servidor) y `bcrp` (CLI).
+
+## Publicación
+
+Las versiones se publican mediante GitHub Actions al crear un release de
+GitHub. El workflow `.github/workflows/publish.yml` ejecuta las pruebas,
+construye los artefactos y publica en PyPI usando Trusted Publishing (OIDC);
+no requiere un token de PyPI almacenado en secretos.
+
+## Datos y licencia
+
+Los datos provienen de [BCRPData](https://estadisticas.bcrp.gob.pe/estadisticas/series/).
+Consulte sus [condiciones de uso](https://estadisticas.bcrp.gob.pe/estadisticas/series/ayuda/condicionesUso).
+
+MIT — consulte [LICENSE](LICENSE).
+
+## Documentación del proyecto
+
+- [CHANGELOG.md](CHANGELOG.md): historial de cambios.
+- [CONTRIBUTING.md](CONTRIBUTING.md): guía para contribuir.
+- [SECURITY.md](SECURITY.md): reporte de vulnerabilidades.
+- [server.json](server.json): metadatos para el registro MCP.

bcrp_mcp-0.1.0/README.md

@@ -0,0 +1,174 @@
+<img width="1600" height="500" alt="BCRP MCP" src="https://github.com/user-attachments/assets/79323612-ebec-49ea-91d5-321b5950bbbc" />
+
+[![PyPI](https://img.shields.io/pypi/v/bcrp-mcp?logo=pypi&logoColor=white)](https://pypi.org/project/bcrp-mcp/)
+[![Python](https://img.shields.io/pypi/pyversions/bcrp-mcp?logo=python&logoColor=white)](https://pypi.org/project/bcrp-mcp/)
+[![Publish](https://github.com/JOSETRA44/BCRP-mcp/actions/workflows/publish.yml/badge.svg)](https://github.com/JOSETRA44/BCRP-mcp/actions/workflows/publish.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+# BCRP MCP
+
+<!-- mcp-name: io.github.JOSETRA44/bcrp-mcp -->
+
+Servidor [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) para
+consultar **BCRPData**, la base oficial de estadísticas económicas del
+[Banco Central de Reserva del Perú (BCRP)](https://www.bcrp.gob.pe/).
+
+Permite a clientes MCP y agentes de IA consultar tipos de cambio, tasas de
+interés, reservas internacionales, liquidez, crédito, commodities, bolsa y PBI.
+La API del BCRP es pública: **no se necesita API key ni registro**.
+
+## Instalación rápida
+
+Se requiere Python 3.11 o posterior.
+
+### Con `uvx` (recomendado para clientes MCP)
+
+```bash
+uvx bcrp-mcp
+```
+
+### Con `pip`
+
+```bash
+python -m pip install bcrp-mcp
+bcrp-mcp
+```
+
+La instalación también proporciona el CLI `bcrp`:
+
+```bash
+bcrp --help
+bcrp catalog search "tipo de cambio"
+bcrp series latest PD04637PD --n 5
+```
+
+### Desde el código fuente
+
+```bash
+git clone https://github.com/JOSETRA44/BCRP-mcp.git
+cd BCRP-mcp
+uv sync
+uv run bcrp-mcp
+```
+
+## Configuración en clientes MCP
+
+El servidor usa transporte stdio. Con `uvx`, la configuración es la misma en
+Claude Desktop, Claude Code, Cursor y otros clientes compatibles:
+
+```json
+{
+  "mcpServers": {
+    "bcrp": {
+      "command": "uvx",
+      "args": ["bcrp-mcp"]
+    }
+  }
+}
+```
+
+En VS Code + GitHub Copilot (`.vscode/mcp.json`):
+
+```json
+{
+  "servers": {
+    "bcrp": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["bcrp-mcp"]
+    }
+  }
+}
+```
+
+## Herramientas MCP
+
+| Herramienta | Uso |
+|---|---|
+| `bcrp_get_series` | Obtiene 1–10 series con un rango opcional; deben compartir frecuencia. |
+| `bcrp_get_latest` | Obtiene los últimos valores de 1–10 series. |
+| `bcrp_get_series_long` | Exporta hasta 50 series en una tabla larga, incluso con frecuencias mixtas. |
+| `bcrp_describe_series` | Consulta nombre, frecuencia y rango disponible de una serie. |
+| `bcrp_search_catalog` | Busca códigos en el catálogo curado de indicadores. |
+| `bcrp_list_catalog_categories` | Lista las categorías disponibles. |
+| `bcrp_get_macro_snapshot` | Devuelve un resumen de indicadores macroeconómicos clave. |
+
+Ejemplos de preguntas:
+
+```text
+¿Cuál es el tipo de cambio actual en Perú?
+Compara la tasa de referencia y las reservas internacionales desde 2020.
+Obtén un snapshot de los principales indicadores de la economía peruana.
+```
+
+## CLI
+
+El comando `bcrp` usa la misma lógica que el servidor MCP y admite salida para
+terminal o automatización:
+
+```bash
+bcrp series describe PD04637PD
+bcrp series latest PD04637PD PD12301MD --n 5
+bcrp series get PN00196MM --start 2020-1 --end 2024-12
+bcrp catalog categories
+bcrp macro snapshot
+```
+
+Opciones útiles:
+
+```bash
+bcrp series latest PD04637PD --n 5 --json
+bcrp series latest PD04637PD --n 5 --ascii --no-color
+```
+
+Los formatos de período dependen de la frecuencia: diario
+`DD-MM-YYYY`, mensual `YYYY-M`, trimestral `YYYY-Q` y anual `YYYY`.
+Las series de una misma consulta deben tener la misma frecuencia, salvo
+`bcrp_get_series_long`.
+
+## Configuración opcional
+
+Todos los valores tienen valores predeterminados razonables y pueden definirse
+con variables de entorno o un archivo `.env`:
+
+| Variable | Predeterminado | Descripción |
+|---|---:|---|
+| `BCRP_CACHE_TTL` | `300` | Duración de la caché en segundos; `0` la desactiva. |
+| `BCRP_TIMEOUT` | `30` | Timeout HTTP en segundos. |
+| `BCRP_MAX_RETRIES` | `3` | Reintentos ante errores transitorios. |
+| `BCRP_LANGUAGE` | `esp` | Idioma de nombres: `esp` o `ing`. |
+| `LOG_LEVEL` | `INFO` | Nivel de logging. |
+
+No se configura ninguna credencial: BCRPData es de acceso abierto.
+
+## Desarrollo
+
+```bash
+uv sync
+uv run pytest -q
+uv run python -m build
+```
+
+El proyecto usa `src/` layout, Hatchling para construir el paquete y publica
+dos entry points: `bcrp-mcp` (servidor) y `bcrp` (CLI).
+
+## Publicación
+
+Las versiones se publican mediante GitHub Actions al crear un release de
+GitHub. El workflow `.github/workflows/publish.yml` ejecuta las pruebas,
+construye los artefactos y publica en PyPI usando Trusted Publishing (OIDC);
+no requiere un token de PyPI almacenado en secretos.
+
+## Datos y licencia
+
+Los datos provienen de [BCRPData](https://estadisticas.bcrp.gob.pe/estadisticas/series/).
+Consulte sus [condiciones de uso](https://estadisticas.bcrp.gob.pe/estadisticas/series/ayuda/condicionesUso).
+
+MIT — consulte [LICENSE](LICENSE).
+
+## Documentación del proyecto
+
+- [CHANGELOG.md](CHANGELOG.md): historial de cambios.
+- [CONTRIBUTING.md](CONTRIBUTING.md): guía para contribuir.
+- [SECURITY.md](SECURITY.md): reporte de vulnerabilidades.
+- [server.json](server.json): metadatos para el registro MCP.

bcrp_mcp-0.1.0/SECURITY.md

@@ -0,0 +1,26 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+Please report security issues privately rather than in a public issue:
+open a [security advisory](https://github.com/JOSETRA44/bcrp-mcp/security/advisories/new) on this repository.
+
+Include what you did, what happened, and what you expected. You can expect an
+acknowledgement within a few days.
+
+## What this server sends, and where
+
+Outbound requests go only to:
+
+- `estadisticas.bcrp.gob.pe`
+
+No telemetry, no analytics, and no data is sent anywhere else.
+
+## Credentials
+
+This server needs none. There is no API key to leak.
+
+## Scope
+
+This project is a client for a public data source. Vulnerabilities in the
+upstream API itself are out of scope here — report those to its operator.