# taxsort-mcp

[MCP](https://modelcontextprotocol.io/) server for personal tax transaction classification (US Schedule A & C). Built on [FastMCP](https://github.com/jlowin/fastmcp), monetized via [Tollbooth DPYC](https://github.com/lonniev/tollbooth-dpyc)™ Lightning micropayments.

> Don't Pester Your Customer™ (DPYC™) — API monetization for Entrepreneurial Bitcoin Advocates

*Inspired by [The Phantom Tollbooth](https://en.wikipedia.org/wiki/The_Phantom_Tollbooth) by Norton Juster, illustrated by Jules Feiffer (1961).*

## What It Does

Import bank CSV exports (SoFi, Chase, Schwab, US Bank, PayPal, Coinbase), classify transactions into IRS tax categories using Claude AI, review and override classifications, generate tax summaries grouped by IRS line item, and track API usage costs.

## Tools

Domain tools take the patron's `npub` and nothing else for identity: the connection proves it, either by signing each request with the npub's key (NIP-98) or as an OAuth holder connection that earned a grant through `request_npub_proof` / `receive_npub_proof`. The patron chooses the grant's lifetime, up to 30 days.

### Sessions

| Tool | Description |
|------|-------------|
| `create_session` | Create a tax session for a year |
| `list_sessions` | List your sessions |
| `get_session` | Session details + stats |
| `session_heartbeat` | Presence heartbeat; returns who else is active in the session |

### Verification & Unlock

| Tool | Description |
|------|-------------|
| `request_npub_proof` | Start npub verification via Secure Courier DM; returns a `nonce` (standard tool) |
| `receive_npub_proof` | Complete npub verification with that `nonce`; the connection then holds the npub (standard tool) |
| `verify_passphrase` | Verify a passphrase to unlock a timed-out session |
| `request_unlock` | Request a session unlock after timeout |
| `check_unlock` | Check if the unlock response is valid |

### Import

| Tool | Description |
|------|-------------|
| `import_csv` | Import CSV — idempotent, preserves user edits |
| `get_import_stats` | Import sources, date ranges, ambiguous counts |

### Transactions

| Tool | Description |
|------|-------------|
| `get_transactions` | Filter by category, month, account, date range, search, unclassified-only |
| `get_transactions_paged` | Server-side filtered, grouped, sorted, paginated transactions |
| `save_classifications` | Bulk write classifications from the FE (JSON array) |
| `delete_classification` | Remove a single classification, reverting to unclassified |
| `clear_transactions` | Delete all transactions and classifications for a session |
| `delete_account_transactions` | Delete all transactions for a specific imported account |
| `reset_classifications` | Delete all classifications but keep the imported transactions |
| `get_amount_neighbors` | Fetch transactions with the same amount within ±N days (duplicate detection) |

### Accounts

| Tool | Description |
|------|-------------|
| `get_accounts` | List all accounts in a session with types and transaction counts |
| `set_account_type` | Set an account's type: bank, card, investment, or loan |

### Summaries

| Tool | Description |
|------|-------------|
| `get_summary` | Grouped spending totals by IRS line, category, month, account |

### Rules

| Tool | Description |
|------|-------------|
| `get_rules` | Get patron's classification rules |
| `save_rule` | Create a description-pattern + optional amount-filter → subcategory rule |
| `delete_rule` | Delete a rule by ID |
| `apply_rules` | Re-apply all rules to unclassified transactions |
| `count_rule_matches` | Live preview of how many transactions match a rule pattern |

### Custom Categories

| Tool | Description |
|------|-------------|
| `get_custom_categories` | Get custom categories defined by this user |
| `save_custom_category` | Add a custom category/subcategory |
| `delete_custom_category` | Delete a custom category |

### Sharing

| Tool | Description |
|------|-------------|
| `create_share_token` | Generate a token to share session with spouse |
| `load_share_token` | Load a shared session via token |

### AI Advisors

| Tool | Description |
|------|-------------|
| `ask_advisor` | Ask the Financial Advisor about using TaxSort |
| `ask_tax_researcher` | Ask the Tax Code Researcher about IRS provisions |

### API Usage & Feedback

| Tool | Description |
|------|-------------|
| `report_api_usage` | Report Anthropic API usage from FE classification for cost tracking |
| `get_api_usage_stats` | Get aggregated API usage statistics for cost analysis |
| `get_anthropic_key` | Get the Anthropic API key for FE-driven classification |
| `get_github_token` | Get the GitHub token for creating feedback issues |
| `create_feedback_issue` | Create a GitHub issue for bug reports, feature requests, or feedback |
| `list_feedback_issues` | List feedback issues submitted by this patron |

### Standard DPYC™ (from tollbooth-dpyc wheel)

`register_standard_tools()` mounts the wheel's full set, including `session_status`, `check_balance`, `account_statement`, `purchase_credits`, `check_payment`, `check_price`, `service_status`, `request_credential_channel`, `receive_credentials`, `forget_credentials`, `request_npub_proof`, `receive_npub_proof`, `check_proof_status`, `held_identities`, the pricing-model and coupon tools, `request_adoption`, `report_issue`, and the delegated `oracle_*` tools. See the [tollbooth-dpyc README](https://github.com/lonniev/tollbooth-dpyc) for the list.

## Server-Side Pagination

`get_transactions_paged` performs filtering, grouping, sorting, and pagination entirely on the server. This is more efficient than fetching all transactions and processing client-side.

- `group_by`: `none`, `category`, `subcategory`, `account`, `month`
- `group_sort`: `asc` or `desc` (controls group ordering)
- `sort_col` + `sort_dir`: row ordering within each group
- `page` + `page_size`: zero-indexed pagination

## Amount Filter Expressions

Rules (`save_rule`, `count_rule_matches`) support compound filters with `amount_operator` and `amount_value`:

| Operator | Meaning |
|----------|---------|
| `lt` | Less than (`<-95` matches debits over $95) |
| `lte` | Less than or equal |
| `gt` | Greater than (`gte 50` matches amounts $50+) |
| `gte` | Greater than or equal |
| `eq` | Exact match (`!33` style negation not supported &mdash; use `neq`) |
| `neq` | Not equal |

Examples: `<-95` (debits exceeding $95), `[0..10)` (range via two rules), `gte 50`.

## Dual Classification

- **`save_classifications`** &mdash; bulk write from the frontend. Accepts a JSON array of `{id, category, subcategory, ...}` objects. Used during AI classification and manual review.
- **`delete_classification`** &mdash; single revert. Removes one classification, returning the transaction to unclassified state.

## Architecture

- **Pure MCP** &mdash; no custom REST endpoints. Horizon exposes Streamable HTTP (JSON-RPC 2.0)
- **Web app** &mdash; `frontend/` (React + Vite on Cloudflare Pages, https://taxsort-app.pages.dev) calls the same MCP tools
- **One env var** &mdash; `TOLLBOOTH_NOSTR_OPERATOR_NSEC`. Neon database provisioned automatically by Authority. BTCPay, the Anthropic API key and an optional GitHub token (for feedback issues) delivered via Secure Courier
- **Per-npub isolation** &mdash; each patron's transactions, rules, and sessions are keyed by their Nostr public key
- **NeonVault** &mdash; all persistence via Neon's HTTP SQL API (httpx, no asyncpg)
- **Tollbooth DPYC&trade;** &mdash; pre-funded Lightning balances, Authority-certified purchases, constraint-driven pricing

## Getting Started

```bash
pip install -e ".[dev]"
export TOLLBOOTH_NOSTR_OPERATOR_NSEC=nsec1...
python server.py
```

The domain schema is created automatically the first time the vault is used.

### Operator Onboarding

1. Generate a Nostr keypair, set `TOLLBOOTH_NOSTR_OPERATOR_NSEC`
2. Deploy to [Horizon](https://app.fastmcp.ai)
3. Get adopted by an Authority: call `request_adoption(authority_npub=..., service_url=...)` on your own MCP, signed with your operator nsec; the Authority's owner approves it
4. Deliver credentials via Secure Courier (`request_credential_channel(sender_npub=<operator npub>, service=...)` returns a `nonce`; reply to the DM, then `receive_credentials(sender_npub=..., service=..., nonce=...)`):
   ```json
   {
     "btcpay_host": "https://btcpay.example.com",
     "btcpay_api_key": "...",
     "btcpay_store_id": "...",
     "anthropic_api_key": "sk-ant-...",
     "github_token": "(optional) token that can open issues for feedback"
   }
   ```

---

## DPYC&trade; Social Contract

Part of the [DPYC&trade; Social Contract](https://github.com/lonniev/dpyc-community) &mdash; a network of monetized MCP services where AI agents pay for what they use via Bitcoin Lightning.

### Other Operators in the Network

| Repo | What it does |
|----------|-------------|
| [tollbooth-dpyc](https://github.com/lonniev/tollbooth-dpyc) | Shared Python SDK &mdash; vault, auth, pricing, Lightning, Nostr identity |
| [dpyc-community](https://github.com/lonniev/dpyc-community) | Governance registry &mdash; membership, advisories, threat model |
| [dpyc-oracle](https://github.com/lonniev/dpyc-oracle) | Community concierge &mdash; free onboarding and member lookup |
| [tollbooth-authority](https://github.com/lonniev/tollbooth-authority) | Certification backbone &mdash; Schnorr-signed certificates |
| [tollbooth-sample](https://github.com/lonniev/tollbooth-sample) | Sample Operator (canonical template) &mdash; weather stats reference |
| [tollbooth-pricing-studio](https://github.com/lonniev/tollbooth-pricing-studio) | iOS pricing-model editor / operator console |
| [cypher-mcp](https://github.com/lonniev/cypher-mcp) | Monetized graph answers &mdash; named Cypher templates over Neo4j/AuraDB |
| [schwab-mcp](https://github.com/lonniev/schwab-mcp) | Charles Schwab brokerage data &mdash; positions, quotes, options, orders |
| [thebrain-mcp](https://github.com/lonniev/thebrain-mcp) | TheBrain knowledge graph &mdash; thoughts, links, attachments |
| [excalibur-mcp](https://github.com/lonniev/excalibur-mcp) | X (Twitter) posting &mdash; social media automation with OAuth2 |
| [optionality-mcp](https://github.com/lonniev/optionality-mcp) | Options-trading practice game |
| [goodearth-mcp](https://github.com/lonniev/goodearth-mcp) | Region-scoped climate analytics for small farms |
| [beesknees-mcp](https://github.com/lonniev/beesknees-mcp) | The Bee's Knees &mdash; a multiplayer race to the queen |
| [roastify-mcp](https://github.com/lonniev/roastify-mcp) | Roastify coffee catalog and packaging artwork |
| [ChartRemotely-mcp](https://github.com/lonniev/ChartRemotely-mcp) | Puts a security on a desktop chart remotely |
| [tollbooth-web](https://github.com/lonniev/tollbooth-web) | Shared browser SDK for operator front ends |
| [tollbooth-oauth2-collector](https://github.com/lonniev/tollbooth-oauth2-collector) | OAuth2 callback handler &mdash; advocate service |
| [tollbooth-shortlinks](https://github.com/lonniev/tollbooth-shortlinks) | URL shortener utility |

---

## License

Apache License 2.0. Copyright 2026 Lonnie VanZandt.