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

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

Schema migration runs automatically on startup.

Operator Onboarding

1. Generate a Nostr keypair, set TOLLBOOTH_NOSTR_OPERATOR_NSEC
2. Deploy to Horizon
3. Register with Authority: register_operator(npub=..., service_url=...)
4. Deliver credentials via Secure Courier:

   {
     "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

---

License

Apache License 2.0. Copyright 2026 Lonnie VanZandt.