Metadata-Version: 2.5
Name: aquamatrix-simar-mcp
Version: 0.1.0
Summary: MCP server for reading Aquamatrix SIMAR billing data
Project-URL: Homepage, https://github.com/OldemarJesus/aquamatrix-python-mcp
Project-URL: Repository, https://github.com/OldemarJesus/aquamatrix-python-mcp
Project-URL: Issues, https://github.com/OldemarJesus/aquamatrix-python-mcp/issues
Project-URL: Documentation, https://oldemarjesus.github.io/aquamatrix-python-mcp/
Project-URL: SDK, https://github.com/OldemarJesus/aquamatrix-python-sdk
Author-email: Oldemar Jesus <oldemego@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: aquamatrix,async,billing,mcp,simar
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.14
Requires-Dist: aquamatrix-simar<0.2,>=0.1.0
Requires-Dist: mcp<3,>=2.3.0
Provides-Extra: dev
Requires-Dist: mkdocs-material>=9.6; extra == 'dev'
Requires-Dist: mkdocstrings[python]>=0.29; extra == 'dev'
Requires-Dist: mypy>=1.16; extra == 'dev'
Requires-Dist: pytest-asyncio>=1.0; extra == 'dev'
Requires-Dist: pytest>=8.3; extra == 'dev'
Requires-Dist: ruff>=0.12; extra == 'dev'
Description-Content-Type: text/markdown

# Aquamatrix SIMAR MCP Server

An async Model Context Protocol server exposing the read-only billing features of the [Aquamatrix SIMAR Python SDK](https://github.com/OldemarJesus/aquamatrix-python-sdk). Unofficial and not affiliated with SIMAR or Aquamatrix.

## Tools

- `get_invoices`: fetch one page of invoice history with optional date filtering.
- `get_pending_invoices`: list invoices the SDK recognizes as unpaid.
- `get_billing_summary`: return the portal's invoice-to-pay and failed-invoice counts.

All tools are read-only. Invoice amounts are returned as decimal strings; dates use ISO `YYYY-MM-DD` strings. Credentials are supplied only through the server process environment, never through tool calls.

## Requirements and installation

- Python 3.14 or newer.
- A SIMAR portal account.

```shell
python -m pip install aquamatrix-simar-mcp
```

Set `SIMAR_NIF` and `SIMAR_PASSWORD` in the MCP server process environment. Optionally set `SIMAR_BASE_URL` when using a compatible portal host.

## Docker Compose

The Compose example runs Streamable HTTP inside a container and publishes it only on host loopback. Set credentials in the process environment or an ignored `.env` file; do not commit secrets.

```shell
export SIMAR_NIF='your-nif'
export SIMAR_PASSWORD='your-password'
docker compose up --build -d
```

The MCP endpoint is `http://127.0.0.1:8000/mcp`. Set `MCP_PORT` to change the port. The container opts into `0.0.0.0` only within its network namespace; Docker's host-side port binding remains `127.0.0.1`. See the [container guide](docs/guide/docker.md) before changing the network exposure.

## Run

For local MCP hosts, use stdio:

```shell
aquamatrix-simar-mcp
```

For a local HTTP client, use current Streamable HTTP:

```shell
MCP_TRANSPORT=streamable-http aquamatrix-simar-mcp
```

The HTTP server binds to `127.0.0.1:8000` by default. It has no HTTP authentication; do not expose it directly to an untrusted network. SSE is intentionally not provided because Streamable HTTP is the current standard transport.

Configuration:

| Variable | Default | Description |
| --- | --- | --- |
| `SIMAR_NIF` | Required | SIMAR account NIF |
| `SIMAR_PASSWORD` | Required | SIMAR account password |
| `SIMAR_BASE_URL` | `https://www.aquamatrix.pt` | Portal base URL |
| `MCP_TRANSPORT` | `stdio` | `stdio` or `streamable-http` |
| `MCP_HOST` | `127.0.0.1` | HTTP bind address; loopback only |
| `MCP_ALLOW_NON_LOOPBACK` | `false` | Explicit opt-in to a non-loopback bind, intended for container networking |
| `MCP_PORT` | `8000` | HTTP port |

## Development

```shell
python -m pip install -e '.[dev]'
pytest
ruff check .
mypy src
```

See [PRD.md](PRD.md), [ARCH.md](ARCH.md), and [AGENTS.md](AGENTS.md) for scope, design, and contributor requirements.

## Documentation

The [documentation site](https://oldemarjesus.github.io/aquamatrix-python-mcp/) includes installation, Docker Compose, security, and publishing guidance. GitHub Pages is built and deployed by GitHub Actions.

## Author and license

Copyright (c) 2026 Oldemar Jesus <oldemego@gmail.com>. MIT licensed; see [LICENSE](LICENSE).