io.github.lonniev/taxsort-mcp

taxsort-mcp

MCP server for personal tax transaction classification (US Schedule A & C). Built on FastMCP, monetized via Tollbooth DPYC™ Lightning micropayments.

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

Inspired by 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

Verification & Unlock

Import

Transactions

Accounts

Summaries

Rules

Custom Categories

Sharing

AI Advisors

API Usage & Feedback

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 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:

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

Dual Classification

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

Architecture

• Pure MCP — no custom REST endpoints. Horizon exposes Streamable HTTP (JSON-RPC 2.0)
• Web app — frontend/ (React + Vite on Cloudflare Pages, https://taxsort-app.pages.dev) calls the same MCP tools
• One env var — 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 — each patron's transactions, rules, and sessions are keyed by their Nostr public key
• NeonVault — all persistence via Neon's HTTP SQL API (httpx, no asyncpg)
• Tollbooth DPYC™ — pre-funded Lightning balances, Authority-certified purchases, constraint-driven pricing

Getting Started

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
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=...)):

    {
      "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™ Social Contract

Part of the DPYC™ Social Contract — a network of monetized MCP services where AI agents pay for what they use via Bitcoin Lightning.

Other Operators in the Network

License

Apache License 2.0. Copyright 2026 Lonnie VanZandt.