# TN Trustee MCP

Read-only MCP access to public Tennessee property-tax information.

> [!IMPORTANT]
> This project does not submit property-tax payments and does not access the payment
> cart. It retrieves and normalizes public-facing information only. Amounts shown
> exclude interest and are not payoff totals. Confirm any amount owed with the county
> trustee before paying.

The project is in Phase 1. It currently provides configuration, normalized data
contracts, SQLite persistence, a command shell, and an MCP STDIO server shell with
zero registered tools. It does not yet contact TennesseeTrustee.org.

## Requirements

- Python 3.12 or later
- [uv](https://docs.astral.sh/uv/)
- An operator contact string for the descriptive user agent

## Setup

```powershell
uv python install 3.12
uv sync --extra dev
Copy-Item .env.example .env
```

Replace `operator@example.com` in `.env` with a monitored contact address.
The required variable name is `TN_TRUSTEE_USER_AGENT_CONTACT`.

Initialize the local database:

```powershell
uv run tn-trustee-mcp db init
```

List configured entities without contacting the source:

```powershell
uv run tn-trustee-mcp entities list
```

Entity configuration keeps the landing and search URLs separate. `entity_path`
contains the entity query parameter. `search_path` is the query-free `/search.php`
endpoint.

Start the Phase 1 MCP shell:

```powershell
uv run tn-trustee-mcp serve
```

## Development checks

```powershell
uv run ruff check .
uv run ruff format --check .
uv run mypy
uv run pytest
uv run python -m build
```

CLI tests inspect the registered command tree directly so option visibility is
validated consistently on Windows and Linux.

## Project reference

See [assessment.md](assessment.md) for the current phase, implemented components,
open questions, validation baseline, and next action. Contributors and coding agents
maintain it with every delivered repository change.

Every delivered repository change must update [CHANGELOG.md](CHANGELOG.md),
[assessment.md](assessment.md), and this README. The changelog records what changed.
The assessment provides a quick current-state reference. The README must stay aligned
with the current setup, behavior, scope, and operator instructions.

## Current scope

- Cheatham County and Stewart County configuration only
- HTTPS query parameter routes through `tennesseetrustee.org`
- Separate validated entity landing and search paths
- Public, read-only property-tax information
- Local SQLite cache and future snapshot storage
- Visible Phase 1 CLI stubs for search, record, snapshot, and source-status commands

Search behavior and HTML parsing are intentionally absent until the Phase 2 source
inspection is complete.

## Safety

The server must never access cart, checkout, or payment endpoints. It must never
submit payments, bypass authentication or CAPTCHA, disable certificate validation,
or perform bulk owner-name harvesting. See [SECURITY.md](SECURITY.md) and
[docs/COMPLIANCE.md](docs/COMPLIANCE.md).

## License

See [LICENSE](LICENSE).