ticorates-mcp 1.0.0__tar.gz

ticorates_mcp-1.0.0/.dockerignore

@@ -0,0 +1,11 @@
+.venv/
+.git/
+.github/
+tests/
+__pycache__/
+.pytest_cache/
+*.pyc
+*.db
+.env
+.DS_Store
+bruno/

ticorates_mcp-1.0.0/.env.example

@@ -0,0 +1,2 @@
+BCCR_API_KEY=your_token_here
+BCCR_BASE_URL=https://apim.bccr.fi.cr/SDDE/api/Bccr.GE.SDDE.Publico.Indicadores.API

ticorates_mcp-1.0.0/.github/workflows/deploy.yml

@@ -0,0 +1,25 @@
+name: Deploy to Raspberry Pi
+
+on:
+  workflow_run:
+    workflows: ["Publish Docker image"]
+    types:
+      - completed
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    if: ${{ github.event_name == 'workflow_dispatch' || github.event.workflow_run.conclusion == 'success' }}
+    steps:
+      - name: Deploy to Raspberry Pi
+        uses: appleboy/ssh-action@v1
+        with:
+          host: ${{ secrets.PI_HOST }}
+          port: ${{ secrets.PI_SSH_PORT }}
+          username: ${{ secrets.PI_USER }}
+          key: ${{ secrets.PI_SSH_KEY }}
+          script: |
+            docker compose -f /home/jonach/docker-composers/ticorates/docker-compose.yml pull
+            docker compose -f /home/jonach/docker-composers/ticorates/docker-compose.yml up -d
+            docker image prune -f

ticorates_mcp-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,66 @@
+name: Publish Docker image
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Run tests
+        run: |
+          uv sync --extra dev
+          uv run pytest tests/
+
+  publish-pypi:
+    needs: test
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/ticorates-mcp
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Log in to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          platforms: linux/amd64,linux/arm64
+          tags: |
+            jonach1998/ticorates:latest
+            jonach1998/ticorates:${{ github.ref_name }}
+

ticorates_mcp-1.0.0/.gitignore

@@ -0,0 +1,8 @@
+.env
+__pycache__/
+.pytest_cache/
+*.pyc
+.venv/
+*.db
+.DS_Store
+bruno/environments/local.bru

ticorates_mcp-1.0.0/Dockerfile

@@ -0,0 +1,16 @@
+FROM python:3.13-slim
+
+WORKDIR /app
+
+RUN apt-get update && apt-get install -y --no-install-recommends curl tzdata && rm -rf /var/lib/apt/lists/*
+
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv
+
+COPY pyproject.toml uv.lock README.md ./
+RUN uv sync --no-dev --frozen
+
+COPY . .
+
+EXPOSE 8000
+
+CMD ["uv", "run", "uvicorn", "ticorates.main:app", "--host", "0.0.0.0", "--port", "8000"]

ticorates_mcp-1.0.0/LICENSE

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

ticorates_mcp-1.0.0/PKG-INFO

@@ -0,0 +1,397 @@
+Metadata-Version: 2.4
+Name: ticorates-mcp
+Version: 1.0.0
+Summary: Public exchange rate API for Costa Rica, powered by BCCR
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.13
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pydantic-settings>=2.6.0
+Requires-Dist: sqlmodel>=0.0.22
+Requires-Dist: uvicorn>=0.32.0
+Provides-Extra: dev
+Requires-Dist: httpx>=0.28.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest-env>=1.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# TicoRates
+
+Public exchange rate API for Costa Rica, powered by [BCCR](https://www.bccr.fi.cr/) (Banco Central de Costa Rica). Supports 43 currencies with on-demand caching and a built-in MCP server for AI assistants.
+
+- **REST API** — Simple HTTP endpoints, no authentication required
+- **43 currencies** — USD, EUR, GBP, JPY, CAD, AUD, CHF, and more
+- **On-demand caching** — rates are fetched from BCCR on first request and served instantly after
+- **Historical rates** — query any date or date range going back years
+- **MCP server** — native integration with Claude, Cursor, Windsurf, and other AI tools
+- **Self-hosted** — Docker image available for `linux/amd64` and `linux/arm64`
+
+---
+
+## Table of Contents
+
+- [API Reference](#api-reference)
+- [MCP Server](#mcp-server)
+- [Self-Hosting](#self-hosting)
+- [Development](#development)
+
+---
+
+## API Reference
+
+**Base URL:** `https://ticorates.dev`  
+**Interactive docs:** `https://ticorates.dev/docs`
+
+---
+
+### `GET /currencies`
+
+Returns all supported currency codes and their full names.
+
+```
+GET /currencies
+```
+
+**Response**
+
+```json
+{
+  "USD": "United States Dollar",
+  "EUR": "Euro (European Union)",
+  "GBP": "British Pound Sterling (United Kingdom)",
+  "JPY": "Japanese Yen (Japan)"
+}
+```
+
+---
+
+### `GET /rates/latest`
+
+Returns today's exchange rates from BCCR. Omit `currency` to get all 43 currencies at once.
+
+| Parameter  | Type   | Required | Description                           |
+|------------|--------|----------|---------------------------------------|
+| `currency` | string | No       | Filter to a single code (e.g. `USD`)  |
+
+```
+GET /rates/latest
+GET /rates/latest?currency=USD
+```
+
+**Response**
+
+```json
+{
+  "date": "2025-05-27",
+  "rates": {
+    "USD": {
+      "purchase": 512.50,
+      "sale": 519.75,
+      "description": "United States Dollar"
+    }
+  }
+}
+```
+
+---
+
+### `GET /rates`
+
+Returns rates for a specific date or date range. Provide either `date` or both `from` + `to`.
+
+| Parameter  | Type   | Required | Description                             |
+|------------|--------|----------|-----------------------------------------|
+| `date`     | string | No*      | Single date in `YYYY-MM-DD` format      |
+| `from`     | string | No*      | Start of range in `YYYY-MM-DD` format   |
+| `to`       | string | No*      | End of range in `YYYY-MM-DD` format     |
+| `currency` | string | No       | Filter to a single code (e.g. `EUR`)    |
+
+*Either `date` or both `from` + `to` must be provided.
+
+```
+GET /rates?date=2025-01-15
+GET /rates?date=2025-01-15&currency=EUR
+GET /rates?from=2025-01-01&to=2025-01-31
+GET /rates?from=2025-01-01&to=2025-01-31&currency=USD
+```
+
+A single-date request returns an object. A date-range request returns an array sorted by date.
+
+**Response — single date**
+
+```json
+{
+  "date": "2025-01-15",
+  "rates": {
+    "USD": { "purchase": 510.25, "sale": 517.50, "description": "United States Dollar" },
+    "EUR": { "purchase": 552.00, "sale": 560.30, "description": "Euro (European Union)" }
+  }
+}
+```
+
+**Response — date range**
+
+```json
+[
+  {
+    "date": "2025-01-01",
+    "rates": { "USD": { "purchase": 508.00, "sale": 515.00, "description": "United States Dollar" } }
+  },
+  {
+    "date": "2025-01-02",
+    "rates": { "USD": { "purchase": 509.50, "sale": 516.75, "description": "United States Dollar" } }
+  }
+]
+```
+
+---
+
+### `GET /health`
+
+Health check endpoint. Returns `200 OK` when the service is running.
+
+```json
+{ "status": "ok" }
+```
+
+---
+
+### Error responses
+
+| Status | Condition                                           |
+|--------|-----------------------------------------------------|
+| `400`  | Missing required parameters or unsupported currency |
+| `422`  | Invalid date format (must be `YYYY-MM-DD`)          |
+| `502`  | BCCR upstream error                                 |
+
+---
+
+## MCP Server
+
+TicoRates includes an [MCP](https://modelcontextprotocol.io/) server that gives AI assistants direct access to Costa Rican exchange rates. No API key required — it connects to `https://ticorates.dev` by default.
+
+### Available tools
+
+| Tool                       | Description                                      |
+|----------------------------|--------------------------------------------------|
+| `get_supported_currencies` | List all available currency codes and names      |
+| `get_latest_rates`         | Today's rates for one or all currencies          |
+| `get_rates_for_date`       | Historical rates for a specific date             |
+| `get_rates_for_date_range` | Rates for a date range, one entry per day        |
+| `convert_amount`           | Convert between any two currencies               |
+| `get_rate_change`          | Absolute and percentage change between two dates |
+| `get_historical_average`   | Average purchase/sale rate over a period         |
+
+---
+
+### Setup
+
+The same config block works across all MCP-compatible clients. Pick yours below.
+
+#### Claude Desktop
+
+Edit `claude_desktop_config.json` and restart Claude Desktop.
+
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "ticorates": {
+      "command": "uvx",
+      "args": ["ticorates-mcp"]
+    }
+  }
+}
+```
+
+---
+
+#### Claude Code
+
+Run once in your terminal:
+
+```bash
+claude mcp add ticorates -- uvx ticorates-mcp
+```
+
+Or add it manually to `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "ticorates": {
+      "command": "uvx",
+      "args": ["ticorates-mcp"]
+    }
+  }
+}
+```
+
+---
+
+#### Cursor
+
+Add to `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "ticorates": {
+      "command": "uvx",
+      "args": ["ticorates-mcp"]
+    }
+  }
+}
+```
+
+Or go to **Settings → Cursor Settings → Features → MCP → Add MCP Server**.
+
+---
+
+#### Windsurf
+
+Open the Cascade panel → **⚙ Settings → MCP Servers → Add**, then enter:
+
+- **Command:** `uvx`
+- **Args:** `ticorates-mcp`
+
+---
+
+#### OpenAI Codex CLI
+
+Run once in your terminal:
+
+```bash
+codex mcp add ticorates -- uvx ticorates-mcp
+```
+
+Or add it manually to `~/.codex/config.toml` (global) or `.codex/config.toml` (project-scoped):
+
+```toml
+[mcp_servers.ticorates]
+command = "uvx"
+args = ["ticorates-mcp"]
+```
+
+---
+
+#### Other clients
+
+Any MCP-compatible client that supports `stdio` transport works with TicoRates. Use the same config structure shown above.
+
+---
+
+### Pointing the MCP at a self-hosted instance
+
+By default, `ticorates-mcp` connects to `https://ticorates.dev`. If you're running your own instance, override it with the `TICORATES_BASE_URL` environment variable in your client's config.
+
+**Claude Desktop / Claude Code / Cursor / Windsurf** (`JSON`):
+
+```json
+{
+  "mcpServers": {
+    "ticorates": {
+      "command": "uvx",
+      "args": ["ticorates-mcp"],
+      "env": {
+        "TICORATES_BASE_URL": "http://your-server:8000"
+      }
+    }
+  }
+}
+```
+
+**OpenAI Codex CLI** (`config.toml`):
+
+```toml
+[mcp_servers.ticorates]
+command = "uvx"
+args = ["ticorates-mcp"]
+env = { TICORATES_BASE_URL = "http://your-server:8000" }
+```
+
+Or via CLI:
+
+```bash
+codex mcp add ticorates --env TICORATES_BASE_URL=http://your-server:8000 -- uvx ticorates-mcp
+```
+
+---
+
+## Self-Hosting
+
+### Prerequisites
+
+- Docker and Docker Compose
+- A BCCR API key — register at the [BCCR developer portal](https://www.bccr.fi.cr/)
+
+### Setup
+
+**1. Create a `docker-compose.yml`:**
+
+```yaml
+services:
+  ticorates:
+    image: jonach1998/ticorates:latest
+    ports:
+      - "8000:8000"
+    env_file: .env
+    volumes:
+      - ticorates_data:/app/ticorates.db
+    restart: always
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 10s
+
+volumes:
+  ticorates_data:
+```
+
+**2. Create a `.env` file:**
+
+```env
+BCCR_API_KEY=your_token_here
+BCCR_BASE_URL=https://apim.bccr.fi.cr/SDDE/api/Bccr.GE.SDDE.Publico.Indicadores.API
+```
+
+**3. Start the service:**
+
+```bash
+docker compose up -d
+```
+
+The API will be available at `http://localhost:8000`.  
+Interactive docs at `http://localhost:8000/docs`.
+
+---
+
+## Development
+
+**Requirements:** Python 3.13+, [uv](https://docs.astral.sh/uv/)
+
+```bash
+# Clone the repo and install dependencies
+git clone https://github.com/jonach1998/ticorates
+cd ticorates
+uv sync --extra dev
+
+# Copy and fill in your BCCR credentials
+cp .env.example .env
+
+# Run the API
+uv run uvicorn ticorates.main:app --reload
+
+# Run the MCP server
+uv run ticorates-mcp
+
+# Run tests
+uv run pytest
+```