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
• An operator contact string for the descriptive user agent

Setup

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:

uv run tn-trustee-mcp db init

List configured entities without contacting the source:

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:

uv run tn-trustee-mcp serve

Development checks

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 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, 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 and docs/COMPLIANCE.md.

License

See LICENSE.