Skip to main content
Glama
Balneabilidade SC MCP

Balneabilidade SC MCP

by LucioB16

Balneabilidade SC MCP

Dated samples, not live readings. The card below is a real MCP response excerpt. The sample was collected on 2026-11-09 and published on 2026-11-13, so it does not describe the water today. IMA/SC sampling is weekly in-season and monthly off-season.

Latest published sample

Praia de Zimbros · Bombinhas

Ponto 09

improper · 1,046 NMP/100mL

Ponto 10

proper · 789 NMP/100mL

Sample date

2026-11-09

Bulletin

2026-11-13

Beach summary

mixed (the points disagree)

The response lists each sampling point with its sample date and bulletin date. One point does not decide the beach.

What you can ask

  • “What is the latest published result for Praia de Zimbros, and when was it sampled?”

  • “Show every sampling point; are the conditions mixed?”

  • “Show the 2025 history for Praia de Zimbros, with dates and lab values.”

  • “Which beaches are called Praia Brava?” The answer lists candidates when several beaches share the name.

Related MCP server: DJEN (Diário de Justiça)

Installation

Install with your agent

Copy this prompt into a coding agent. It includes the repository and the setup guide, so the agent does not need to search for either.

Install the Balneabilidade SC MCP server from:
https://github.com/LucioB16/balneabilidade-sc-mcp

Setup guide:
https://github.com/LucioB16/balneabilidade-sc-mcp/blob/main/docs/MCP_SERVER.md

Do it locally. Do not search for the project or the documentation elsewhere.

Requirements:
- Clone the repository into a directory I confirm.
- Use uv: run `uv sync --extra dev` and `uv run pytest`.
- Register a local stdio MCP server named `balneabilidade-sc`:
  `uv --directory <checkout> run balneabilidade-sc-mcp`
- If you cannot edit my MCP client configuration, print the exact JSON and tell me where to paste it.
- Verify the client lists all five tools and run one query for "Praia de Zimbros", municipality "Bombinhas".
- Show me the configuration and the verification output.

Do not expose the server over the network. Ask before modifying files outside the project or any global configuration. Do not install globally. Do not commit credentials or local configuration.

If uv is not installed, ask before installing it. Manual setup is below.

Manual install

git clone https://github.com/LucioB16/balneabilidade-sc-mcp.git
cd balneabilidade-sc-mcp
uv sync --extra mcp
uv run balneabilidade-sc-mcp

The last command starts the stdio server and waits for a client. Logs go to stderr; stdout carries the MCP protocol.

Add it to an MCP client with uv --directory (adjust the absolute path):

{
  "mcpServers": {
    "balneabilidade-sc": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/balneabilidade-sc-mcp",
        "run",
        "balneabilidade-sc-mcp"
      ]
    }
  }
}

On Windows, the installed executable also works:

{
  "mcpServers": {
    "balneabilidade-sc": {
      "command": "C:\\path\\to\\balneabilidade-sc-mcp\\.venv\\Scripts\\balneabilidade-sc-mcp.exe",
      "args": []
    }
  }
}

Tools

Tool

Main inputs

What it returns

search_beaches

query, optional municipality, limit

Candidate beaches, municipality, point count and match type

get_sampling_points

beach, optional municipality

Point UUIDs, locations and coordinates

get_bathing_status

beach, optional municipality, point_id

Latest dated result per point, beach summary, freshness and provenance

get_bathing_history

beach, optional municipality, point_id, from_date, to_date, limit, cursor

Dated CSV records with qualifiers, unit, raw names and coverage

get_bulletin_page

page, optional bulletin_date, dpi

PNG page for vision fallback only

What a response includes

Every dated point result carries:

Field

Meaning

classification

proper, improper, indeterminate or unknown

freshness

current, carried_forward, excluded, stale, unverified or unknown

sample_date

The date the sample was collected

bulletin_date

The date the publishing bulletin was issued, when known

source / source_url

bulletin_pdf, csv, analyses, catalog or cache, plus the source URL

summary.status

proper, improper, mixed, partial or unknown

A point that IMA/SC did not collect, or one whose sample was discarded, is not presented as current. The point keeps its raw label and an explicit freshness flag. Any improper point prevents a proper beach summary.

History

get_bathing_history reads the CSV exports published by IMA/SC:

  • inclusive from_date/to_date and descending order;

  • bounded pagination with a cursor;

  • raw point names, location and csv_year;

  • E. coli values with <20/<10/> 24196 qualifiers and the NMP/100mL unit;

  • years_without_data separated from years_unavailable;

  • exact duplicate rows are deduplicated and counted;

  • point-name drift is exposed in unmatched_names instead of being guessed;

  • when CSV and the latest bulletin disagree about the same sample, the bulletin verdict is kept and a warning is returned.

History comes from the CSV exports. The latest bulletin PDF is the reference for current status.

Example questions

  • “What is the latest published result for Praia de Zimbros, and when was it sampled?”

  • “Show every sampling point; are the conditions mixed?”

  • “Show the 2025 history for Praia de Zimbros, with dates and lab values.”

  • “Which beaches are called Praia Brava?”

A useful answer gives the point, the sample date and the bulletin date. It does not say “safe now”.

Vision fallback

The deterministic PDF parser is primary. If it cannot validate a trustworthy point table, get_bathing_status includes vision_fallback metadata. A client with a vision-capable model can call get_bulletin_page and read the original PNG pages. The server only returns page images. It does not call an LLM or create rows, and it leaves the status unchanged.

Development

uv sync --extra dev
uv run pytest
uv run ruff check src tests
uv run ruff format --check src tests
uv run mypy src
uv build

The offline suite has 75 tests and never calls IMA. The read-only discovery probe is separate:

python scripts/discovery_probe.py

CI runs lint, format check, mypy, offline tests and package build on Python 3.11 and 3.12. It needs no credentials and makes no IMA calls.

Data, attribution and license

The source is the Instituto do Meio Ambiente de Santa Catarina (IMA/SC), https://balneabilidade.ima.sc.gov.br/. Always cite the agency, the report/bulletin number, the sample date and the source URL.

No data-reuse license was confirmed for IMA/SC material. This repository does not redistribute PDFs, CSV exports or bulk datasets; the provider fetches them at runtime. See docs/ATTRIBUTION.md before publishing derived data.

Code and documentation are MIT licensed. The license does not cover IMA/SC data. See LICENSE.

Limitations

  • PDF parsing depends on layout. The vision fallback runs in the client; the server does not run OCR.

  • History comes from CSV; the PDF is the reference only for the latest bulletin.

  • Exact-name joins expose drift instead of guessing; renamed points may appear as unmatched.

  • The default command remains local stdio. An optional stateless Streamable HTTP app is available for hosted clients; review remote HTTP deployment before exposing it.

  • The remote endpoint is unauthenticated and read-only. Provider pacing is per process; use ingress rate limits and a single replica unless shared cache and global request limiting are configured.

  • The provider uses a small TTL file cache instead of a database.

  • This is not a medical or safety guarantee.

Documentation

Project layout

src/balneabilidade_sc_mcp/
  provider.py       source reconciliation, freshness, history
  bulletin.py       portal index, PDF parsing, exclusions
  history.py        CSV export/parser
  catalog.py        map catalog and matching
  server.py         MCP tools shared by stdio and Streamable HTTP
  http_server.py    hosted Streamable HTTP entry point
  pdf_vision.py     PNG rendering fallback
docs/               discovery, contract, provider, server, release, attribution
tests/              75 offline tests with synthetic fixtures

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables querying the official MPT SC (Brazilian Labor Prosecution Office of Santa Catarina) negative case certificate (Certidão Negativa de Feitos) database through a read-only, pay-per-query MCP tool.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables searching Brazilian National Electronic Court Gazette (DJEN) publications and judicial notifications by OAB, lawyer name, case number, court, and date, returning full text and certificate links, plus party-name case discovery.
      2
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Web scraping for AI agents: scrape, map, crawl and batch public pages into Markdown, tables and JSON, with an Evidence Record on every page. Blocked, empty and wrong pages come back as such, with the reason.
      39
      7
      AGPL 3.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables Brazilian legal practitioners to search and verify case law, súmulas, and federal legislation against official sources, and to audit entire draft documents citation by citation with source provenance, collection dates, and verification status. Every response carries its own verification flag so a failed source lookup never silently becomes "no results", and citations blocked by anti-bot protections are returned as pending manual review with an official search link.
      MIT