taxsort-mcp

taxsort-mcp

用于个人税务交易分类（美国 Schedule A 和 C）的 MCP 服务。基于 FastMCP 构建，通过 Tollbooth DPYC™ 闪电网络小额支付实现变现。

别骚扰您的客户™（DPYC™）— 面向创业型比特币倡导者的 API 变现方案

灵感来自 Norton Juster 所著、Jules Feiffer 插画的《The Phantom Tollbooth》（1961 年）：《The Phantom Tollbooth》。

功能

导入银行 CSV 导出文件（SoFi、Chase、Schwab、US Bank、PayPal、Coinbase），使用 Claude AI 将交易归入 IRS 税务类别，审核并覆盖分类，按 IRS 行项目汇总生成税务摘要，并跟踪 API 使用成本。

工具

领域工具只使用服务使用者的 npub 作为身份标识，不需要其他信息：连接本身即可证明身份，可以通过 npub 密钥为每个请求签名（NIP-98），也可以通过 OAuth 持有者连接获得授权；后者需通过 request_npub_proof / receive_npub_proof 获取授权。服务使用者可自行选择授权有效期，最长为 30 天。

会话

工具	说明
create_session	为某个年份创建税务会话
list_sessions	列出您的会话
get_session	查看会话详情和统计信息
session_heartbeat	发送在线状态心跳；返回会话中其他活跃用户

验证与解锁

工具	说明
request_npub_proof	通过 Secure Courier DM 开始 npub 验证；返回一个 nonce（标准工具）
receive_npub_proof	使用该 nonce 完成 npub 验证；随后连接将持有该 npub（标准工具）
verify_passphrase	验证密码短语，以解锁超时会话
request_unlock	会话超时后请求解锁
check_unlock	检查解锁响应是否有效

导入

工具	说明
import_csv	导入 CSV — 可幂等执行，并保留用户编辑内容
get_import_stats	查看导入来源、日期范围和有歧义的记录数量

交易

工具	说明
get_transactions	按类别、月份、账户、日期范围、搜索条件或仅未分类筛选
get_transactions_paged	在服务端筛选、分组、排序并分页显示交易
save_classifications	批量写入来自 FE 的分类（JSON 数组）
delete_classification	移除单个分类，将其恢复为未分类状态
clear_transactions	删除会话中的所有交易和分类
delete_account_transactions	删除某个已导入账户的所有交易
reset_classifications	删除所有分类，但保留已导入的交易
get_amount_neighbors	获取 ±N 天内金额相同的交易（用于检测重复项）

账户

工具	说明
get_accounts	列出会话中的所有账户及其类型和交易数量
set_account_type	设置账户类型：bank、card、investment 或 loan

摘要

工具	说明
get_summary	按 IRS 行项目、类别、月份和账户分组汇总支出

规则

工具	说明
get_rules	获取服务使用者的分类规则
save_rule	创建一条规则：描述模式 + 可选金额筛选条件 → 子类别
delete_rule	按 ID 删除规则
apply_rules	将所有规则重新应用于未分类交易
count_rule_matches	实时预览符合规则模式的交易数量

自定义类别

工具	说明
get_custom_categories	获取该用户定义的自定义类别
save_custom_category	添加自定义类别或子类别
delete_custom_category	删除自定义类别

分享

工具	描述
create_share_token	生成令牌，与配偶共享会话
load_share_token	通过令牌加载共享会话

AI 顾问

工具	描述
ask_advisor	向财务顾问咨询如何使用 TaxSort
ask_tax_researcher	向税法研究员咨询 IRS 条款

API 使用情况与反馈

工具	描述
report_api_usage	报告 FE 分类使用的 Anthropic API 用量，以跟踪成本
get_api_usage_stats	获取汇总的 API 使用统计数据，用于成本分析
get_anthropic_key	获取用于 FE 驱动分类的 Anthropic API 密钥
get_github_token	获取用于创建反馈问题的 GitHub 令牌
create_feedback_issue	为错误报告、功能请求或反馈创建 GitHub 问题
list_feedback_issues	列出此用户提交的反馈问题

标准 DPYC™（来自 tollbooth-dpyc wheel）

register_standard_tools() 会挂载该 wheel 的完整工具集，包括 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、定价模型和优惠券工具、request_adoption、report_issue 以及委托的 oracle_* 工具。请参阅 tollbooth-dpyc README 查看列表。

服务端分页

get_transactions_paged 会完全在服务端执行筛选、分组、排序和分页。这比获取所有交易后在客户端处理更高效。

• group_by：none、category、subcategory、account、month
• group_sort：asc 或 desc（控制分组顺序）
• sort_col + sort_dir：各组内的行排序
• page + page_size：从零开始的分页

金额筛选表达式

规则（save_rule、count_rule_matches）支持使用 amount_operator 和 amount_value 进行复合筛选：

运算符	含义
lt	小于（<-95 匹配金额超过 $95 的支出）
lte	小于或等于
gt	大于（gte 50 匹配金额为 $50 及以上的交易）
gte	大于或等于
eq	完全匹配（不支持 !33 形式的否定 — 请使用 neq）
neq	不等于

示例：<-95（金额超过 $95 的支出）、[0..10)（通过两条规则表示范围）、gte 50。

双重分类

• save_classifications — 从前端批量写入。接受由 {id, category, subcategory, ...} 对象组成的 JSON 数组。用于 AI 分类和人工审核。
• delete_classification — 撤销单项分类。移除一项分类，使该交易恢复为未分类状态。

架构

• 纯 MCP — 无自定义 REST 端点。Horizon 提供 Streamable HTTP（JSON-RPC 2.0）
• Web 应用 — frontend/（React + Vite，部署于 Cloudflare Pages，https://taxsort-app.pages.dev）调用相同的 MCP 工具
• 单个环境变量 — TOLLBOOTH_NOSTR_OPERATOR_NSEC。Neon 数据库由 Authority 自动配置。BTCPay、Anthropic API 密钥和可选的 GitHub 令牌（用于反馈问题）通过 Secure Courier 提供
• 按 npub 隔离 — 每位用户的交易、规则和会话均以其 Nostr 公钥为键
• NeonVault — 所有持久化操作均通过 Neon 的 HTTP SQL API 完成（使用 httpx，无 asyncpg）
• Tollbooth DPYC™ — 预充值 Lightning 余额、经 Authority 认证的购买、由约束条件驱动的定价

开始使用

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

首次使用保险库时，会自动创建领域架构。

运营者入驻

1. 生成 Nostr 密钥对，设置 TOLLBOOTH_NOSTR_OPERATOR_NSEC
2. 部署到 Horizon
3. 由某个 Authority 接纳：在你自己的 MCP 上调用 request_adoption(authority_npub=..., service_url=...)，并使用运营者的 nsec 签名；Authority 的所有者会批准请求
4. 通过 Secure Courier 交付凭据（request_credential_channel(sender_npub=<operator npub>, service=...) 会返回一个 nonce；回复该私信，然后调用 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™ 社交契约

属于 DPYC™ 社交契约的一部分——这是一个由货币化 MCP 服务组成的网络，AI Agent 通过 Bitcoin Lightning 为所用服务付费。

网络中的其他运营者

Repo	功能
tollbooth-dpyc	共享 Python SDK — vault、身份验证、定价、Lightning、Nostr 身份
dpyc-community	治理注册表 — 成员资格、公告、威胁模型
dpyc-oracle	社区服务台 — 免费入驻与成员查询
tollbooth-authority	认证基础设施 — Schnorr 签名证书
tollbooth-sample	示例运营者（标准模板）— 天气统计参考实现
tollbooth-pricing-studio	iOS 定价模型编辑器／运营者控制台
cypher-mcp	货币化图谱问答 — 在 Neo4j/AuraDB 上运行命名 Cypher 模板
schwab-mcp	Charles Schwab 经纪业务数据 — 持仓、报价、期权、订单
thebrain-mcp	TheBrain 知识图谱 — 思想、链接、附件
excalibur-mcp	X (Twitter) 发帖 — 使用 OAuth2 实现社交媒体自动化
optionality-mcp	期权交易练习游戏
goodearth-mcp	面向小型农场的区域气候分析
beesknees-mcp	The Bee's Knees — 多人竞速争夺蜂后
roastify-mcp	Roastify 咖啡目录与包装设计图
ChartRemotely-mcp	远程将证券添加到桌面图表中
tollbooth-web	面向运营者前端的共享浏览器 SDK
tollbooth-oauth2-collector	OAuth2 回调处理程序 — 倡导者服务
tollbooth-shortlinks	URL 缩短工具

---

许可证

Apache License 2.0。版权所有 2026 Lonnie VanZandt。