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

All domain tools take proof: str for DPYC authentication.

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
`receive_npub_proof`	Complete npub verification (reply to the DM to prove npub ownership)
`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)

check_balance, purchase_credits, check_payment, check_price, service_status, request_credential_channel, receive_credentials, forget_credentials, oracle_how_to_join, oracle_about, oracle_lookup_member, oracle_network_advisory, oracle_get_tax_rate

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 — use `neq`)
`neq`	Not equal

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)
One env var — TOLLBOOTH_NOSTR_OPERATOR_NSEC. Neon database provisioned automatically by Authority. BTCPay and Anthropic API key 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

Terminal

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

Schema migration runs automatically on startup.

Operator Onboarding

Generate a Nostr keypair, set TOLLBOOTH_NOSTR_OPERATOR_NSEC
Deploy to Horizon
Register with Authority: register_operator(npub=..., service_url=...)

Deliver credentials via Secure Courier:

config.json

{
  "btcpay_host": "https://btcpay.example.com",
  "btcpay_api_key": "...",
  "btcpay_store_id": "...",
  "anthropic_api_key": "sk-ant-..."
}

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

Repo	What it does
tollbooth-dpyc	Shared Python SDK — vault, auth, pricing, Lightning, Nostr identity
dpyc-community	Governance registry — membership, advisories, threat model
dpyc-oracle	Community concierge — free onboarding and member lookup
tollbooth-authority	Certification backbone — Schnorr-signed certificates
tollbooth-sample	Sample Operator (canonical template) — weather stats reference
tollbooth-pricing-studio	iOS pricing-model editor / operator console
cypher-mcp	Monetized graph answers — named Cypher templates over Neo4j/AuraDB
schwab-mcp	Charles Schwab brokerage data — positions, quotes, options, orders
thebrain-mcp	TheBrain knowledge graph — thoughts, links, attachments
excalibur-mcp	X (Twitter) posting — social media automation with OAuth2
optionality-mcp	Options analytics — brokerage-data operator
tollbooth-oauth2-collector	OAuth2 callback handler — advocate service
tollbooth-shortlinks	URL shortener utility

Taxsort MCP README