taxsort-mcp

taxsort-mcp

個人の税務取引分類（米国の Schedule A と C）向けのMCPサーバーです。FastMCPを基盤とし、Tollbooth DPYC™ Lightning マイクロペイメントで収益化しています。

お客様を煩わせない™（DPYC™）— 起業家精神あふれるビットコイン支持者向けの API 収益化

The Phantom Tollbooth（Norton Juster 作、Jules Feiffer 挿絵、1961 年）に着想を得ています。

概要

銀行の CSV エクスポート（SoFi、Chase、Schwab、US Bank、PayPal、Coinbase）をインポートし、Claude AI を使って取引を IRS の税務カテゴリに分類し、分類を確認・上書きし、IRS の項目ごとにまとめた税務サマリーを作成し、API の利用コストを追跡します。

ツール

ドメインツールで本人確認に使うのは、利用者の npub のみです。接続によって本人であることが証明されます。各リクエストに npub の鍵で署名する方法（NIP-98）か、request_npub_proof / receive_npub_proof を通じて許可を得た OAuth ホルダー接続のいずれかです。利用者は、最長 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	1 件の分類を削除し、未分類に戻します
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	フィードバックの issue 作成に使用する GitHub トークンを取得します
create_feedback_issue	バグ報告、機能リクエスト、フィードバック用の GitHub issue を作成します
list_feedback_issues	このパトロンが送信したフィードバックの issue を一覧表示します

標準 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：0 から始まるページネーション

金額フィルター式

ルール（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)（2 つのルールを使用した範囲）、gte 50。

二重分類

• save_classifications — フロントエンドから一括書き込みを行います。{id, category, subcategory, ...} オブジェクトの JSON 配列を受け取ります。AI による分類と手動レビュー時に使用します。
• delete_classification — 1 件の分類を元に戻します。分類を 1 件削除し、その取引を未分類の状態に戻します。

アーキテクチャ

• 純粋な MCP — カスタム REST エンドポイントはありません。Horizon は Streamable HTTP（JSON-RPC 2.0）を公開します
• Web アプリ — frontend/（Cloudflare Pages 上の React + Vite、https://taxsort-app.pages.dev）が同じ MCP ツールを呼び出します
• 環境変数は 1 つ — TOLLBOOTH_NOSTR_OPERATOR_NSEC。Neon データベースは Authority によって自動的にプロビジョニングされます。BTCPay、Anthropic API キー、任意の GitHub トークン（フィードバック issue 用）は 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

ドメインスキーマは、vault が初めて使用されたときに自動的に作成されます。

オペレーターのオンボーディング

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 を返します。DM に返信してから、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™ ソーシャルコントラクトの一部です — AI エージェントが Bitcoin Lightning 経由で利用した分を支払う、収益化された MCP サービスのネットワークです。

ネットワーク内の他のオペレーター

リポジトリ	概要
tollbooth-dpyc	共有 Python SDK — ボールト、認証、料金設定、Lightning、Nostr ID
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。Copyright 2026 Lonnie VanZandt。