<div align="center">

# mcp_bcrp

**BCRP data tools for Python/MCP and native Stata workflows.**

[![PyPI](https://img.shields.io/pypi/v/mcp-bcrp.svg?style=flat-square&color=blue)](https://pypi.org/project/mcp-bcrp/)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue?style=flat-square&logo=python&logoColor=white)](https://www.python.org/downloads/)
[![Tests](https://img.shields.io/github/actions/workflow/status/MaykolMedrano/mcp_bcrp/ci.yml?branch=main&style=flat-square)](https://github.com/MaykolMedrano/mcp_bcrp/actions)
[![Downloads](https://img.shields.io/pypi/dm/mcp-bcrp?style=flat-square&color=blue)](https://pypi.org/project/mcp-bcrp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)

</div>

## Overview

This repository provides two independent interfaces to the public statistical
source of the Banco Central de Reserva del Perú (BCRP):

- **`mcp-bcrp`** — Python client, metadata search and optional FastMCP server;
- **`usebcrp`** — native Stata package for data retrieval, search and
  transformations.

Both interfaces query the same BCRP source, but they have separate runtimes,
tests, documentation and release processes. Installing one does not install
the other.

## Python implementation

The Python package provides asynchronous data access and catalog search. The
FastMCP server is an optional interface for MCP-compatible AI applications.

Install or update from PyPI:

```bash
pip install --upgrade mcp-bcrp
```

Help: [Python guide](python/README.md) · [examples and notebooks](python/examples/)

Replication: [Python test suite](python/tests/)

From a checkout, run the tests from the repository root:

```bash
python -m pytest python/tests -q
```

## Stata implementation

The native Stata package preserves the `usebcrp` command syntax and adds
catalog search, caching, transformations and metadata output.

Install or update from GitHub:

```stata
net install usebcrp, ///
    from("https://raw.githubusercontent.com/MaykolMedrano/mcp_bcrp/main/stata") replace
```

Requirements: Stata 16 or later and HTTPS access. The package uses the public
BCRP API and does not require Python, FastMCP or an LLM provider.

Help: [user guide](stata/docs/GUIA_USUARIO.md) · [Stata help file](stata/usebcrp.sthlp) · [distribution guide](stata/docs/DISTRIBUTION.md)

Replication: [Stata test suite](stata/tests/)

From a checkout, run the deterministic suite with the configured StataNow
executable:

```powershell
powershell -ExecutionPolicy Bypass -File stata/scripts/run-tests.ps1
```

## Repository structure

```text
mcp_bcrp/
├── python/
│   ├── mcp_bcrp/       Python client, search and MCP server
│   ├── tests/          Python tests
│   ├── examples/       Python examples and notebooks
│   └── README.md       Python documentation
├── stata/
│   ├── *.ado, *.sthlp  Native Stata runtime
│   ├── tests/          Stata tests and fixtures
│   ├── docs/           Stata documentation
│   ├── scripts/        Test and release scripts
│   ├── catalog/        Catalog provenance and build scripts
│   └── README.md       Stata documentation
├── docs/               Shared architecture documentation
├── pyproject.toml      Python/PyPI build configuration
└── README.md           Project overview
```

The `stata/` directory is also the exact `net install` site: `stata.toc` and
`usebcrp.pkg` remain directly inside it.

## Data source and references

- [Banco Central de Reserva del Perú](https://www.bcrp.gob.pe/)
- [BCRPData statistical series](https://estadisticas.bcrp.gob.pe/estadisticas/series/)
- [FastMCP](https://github.com/jlowin/fastmcp), used by the optional Python MCP layer
- [Catalog provenance and reproduction](stata/catalog/README.md)
- [Repository architecture](docs/ARQUITECTURA.md)

## Author

**Maykol Medrano**<br>
Pontificia Universidad Católica de Chile<br>
Email: [mmedrano2@uc.cl](mailto:mmedrano2@uc.cl)<br>
GitHub: [MaykolMedrano](https://github.com/MaykolMedrano)

## License and disclaimer

This project is released under the [MIT License](LICENSE). It is an
independent open-source project and is not an official product of the Banco
Central de Reserva del Perú. Data availability and accuracy depend on the
upstream BCRP service.