taxcode

📦 mcp-server-taxcode

連邦、準州、複数州の税法に対応する、エンタープライズグレードのModel Context Protocol（MCP）サーバーです。
米国連邦（IRC/CFR）、プエルトリコ（Act 60/Ley 1）、全50州およびコロンビア特別区を網羅する法令カタログを提供し、居住者判定とキャピタルゲインの計算モデルを備えています。

警告

税務または法律に関する助言ではありません／税務または法律に関する助言を構成するものではありません
EN: このソフトウェアとそのツールは、情報提供および調査のみを目的として、計算モデル、ヒューリスティックなチェック、非公式な要約を提供します。このサーバーが返す内容は、正式な法律または税務に関する助言、公式な法律意見、あるいは監査における代理を構成するものではありません。非公式な翻訳と要約に拘束力はありません。制定時の言語による公式の法令および行政上の資料が優先されます。
ES: このソフトウェアとそのツールは、情報提供および調査のみを目的として、計算モデル、ヒューリスティックなチェック、非公式な要約を提供します。このサーバーが返す内容は、正式な法律または税務に関する助言、公式な法律意見、あるいは監査における代理を構成するものではありません。非公式な翻訳と要約に拘束力はありません。制定時の言語による公式の法令および行政上の資料が優先されます。

🏗️ アーキテクチャ：FastMCP 4 サーバーの構成

graph TD
    Client["AI Agent / MCP Host<br>(Claude, Cursor, Antigravity, Snowflake Cortex)"]
    Gateway["FastMCP Root Gateway<br>(stdio / streamable-http)"]
    ParentMW["Parent Middleware<br>(Audit Logging, Timing, Secret Redaction, ReadOnly Gate)"]
    SysSub["System Sub-server (mount: 'system')<br>• system_get_health_status<br>• taxcode://system/reference/capabilities"]
    StatSub["Statutes Sub-server (mount: 'statutes')<br>• statutes_lookup_statute<br>• statutes_search_tax_code<br>• statutes_list_publications<br>• taxcode://statutes/{jurisdiction}/{section}"]
    CompSub["Compliance Sub-server (mount: 'compliance')<br>• compliance_evaluate_pr_bona_fide_residency<br>• compliance_calculate_built_in_gain_sourcing<br>• compliance_evaluate_georgia_residency<br>• compliance_evaluate_state_residency"]
    DuckDB["DuckDB In-Memory & File Engine<br>(117 Statutes, 18 Publications, Full-Text Search, Temporal Versions)"]

    Client <-->|"JSON-RPC (tools/list, tools/call)"| Gateway
    Gateway --> ParentMW
    ParentMW --> SysSub
    ParentMW --> StatSub
    ParentMW --> CompSub
    StatSub <-->|"Point-in-Time & Full-Text Queries"| DuckDB
    CompSub <-->|"Deterministic Statutory Calculations"| DuckDB

🚀 主な機能

• 複数の管轄区域に対応した信頼性の高い法令カタログ：
  • 連邦法（US）：IRC § 1、§ 24、§ 32、§ 61、§ 62、§ 63、§ 865、§ 911、§ 933、§ 937、§ 957、§ 1411、§ 6012、§ 6688、26 CFR § 1.937-1/2/3、およびIRS刊行物（Pub. 17、Pub. 54、Pub. 501、Pub. 505、Pub. 570、Pub. 1321）。
  • プエルトリコ（PR）：Act 60-2019（居住者個人投資家、輸出サービスおよびオポチュニティゾーンの定義、Sec. 6020.10の年次報告）、Ley 1-2011（Sec. 1031.02の免税規定、Sec. 1062.01の賃金源泉徴収、Sec. 1062.03のサービス対価に対する源泉徴収を含む）、Act 22-2012の旧バージョン、および行政刊行物（CC RI 21-10、CC RI 25-12、CC RI 26-13、DA 21-04、DA 23-04、BI RI 26-02）。
  • 米国50州すべて＋コロンビア特別区：所得税のない州（AK、FL、NV、NH、SD、TN、TX、WA、WY）、フラット税制の州（AZ、CO、GA、ID、IL、IN、IA、KS、KY、MI、MS、NC、PA、UT）、累進税率／付加税のある管轄区域（AL、AR、CA、CT、DE、DC、HI、LA、ME、MD、MA、MN、MO、MT、NE、NJ、NM、NY、ND、OH、OK、OR、RI、SC、VT、VA、WV、WI）を網羅した包括的な法定定義と税額計算。雇用主の便宜に関するルール（NY、PA、NJ、CT、DE、NE）および地方税の上乗せ（MD、IN、OH、NY）も含みます。
• スニペット検索、IDによる全文取得：statutes_search_tax_code は全文を照合してランク付けしますが、短いスニペット（一致した最初の用語の前後最大300文字）と、各結果の id、引用、タイトル、管轄区域、年、有効性、内容ラベルを返します。全文を取得するには、id を citation_or_section として statutes_lookup_statute に渡します。
• ページングによる応答サイズの制限：法令関連の各ツールの結果は、JSONで32,000文字未満に収まります。statutes_lookup_statute は長文を、テキストフィールドごとに最大8,000文字のページで返します（text_page にはオフセットと全文の長さが示されます。次のページを取得するには、next_cursor を page_cursor として渡します）。statutes_search_tax_code と statutes_list_publications は、1回の呼び出しでの limit を1～25件に制限し、次のページを取得するための offset と next_offset を提供します。taxcode://statutes/{jurisdiction}/{section} リソース（例：taxcode://statutes/US/933）も同じ8,000文字のページと上限を使用します。最後のページでない場合、ページの末尾に次のページのURIが示され、そのURIには ?page_cursor= クエリが付いています。
• バージョン管理されたデータファイル：すべての法令および刊行物の行は、管轄区域ごとの src/taxcode_mcp/data/ 内のJSONファイルに保存され、各行にソースレコードが付属します。docs/ 内のドキュメントはこれらのファイルから生成されます（CONTRIBUTING.md を参照）。
• 法令の時系列バージョン管理：superseded_year によるフィルタリングと、降順の履歴表示（tax_year パラメーター）を使って、指定時点の法令を検索できます。
• 決定論的なコンプライアンスエンジン：
  • evaluate_pr_bona_fide_residency：IRC § 937 の滞在日数（183日、3年間で549日、米国で90日）、納税上の住所、およびより密接な関係のテストを評価します。
  • calculate_built_in_gain_sourcing：移転前後の保有期間に基づき、Section 937／Act 60 のキャピタルゲインを割り当てます。
  • evaluate_state_residency：米国50州すべてとコロンビア特別区（計51の管轄区域）を対象に、州間の法定滞在日数カウント、恒久的な居住場所（PPA）、ドミサイル監査リスクのフラグ付け、納税額の計算を行います。
• プロファイルとオプトイン式のToolSearch：
  • ドメインマウント型プロファイル：full、system、statutes、compliance、readonly。
  • 業務別の許可リスト型プロファイル：researcher（法令＋通達）、advisor（国境をまたぐ居住地判定＋BIG計算）。
• ツールの肥大化ゼロ：MCP 2.0の注釈（readOnlyHint=True）を明示した、読み取り専用の軽量なMCPツールをちょうど8つ公開します。

⚙️ 設定

HTTP トランスポートと認証

Stdio がデフォルトで、トークンは不要です。HTTP トランスポートは、ローカルサーバーは localhost のみにバインドし、すべての接続を認証するという MCP のガイダンスに従います。

• 127.0.0.1、::1、localhost（--host のデフォルトは 127.0.0.1）では、HTTP は TAXCODE_MCP_AUTH_TOKEN の有無にかかわらず実行されます。トークンがない場合、リクエストが認証されていないことを示す警告が表示されます。
• その他のホスト（0.0.0.0、::、LAN アドレス）では、TAXCODE_MCP_AUTH_TOKEN が設定されているか、TAXCODE_MCP_ALLOW_UNAUTHENTICATED_BIND=1 によって未認証のバインドが許可されない限り、サーバーは起動を拒否します。後者の場合は警告として記録されます。たとえば、認証を代行するゲートウェイの背後で使用できます。
• トークンを設定すると、すべての HTTP リクエストに Authorization: Bearer <token> が必要です。トークンがない場合や正しくない場合、HTTP 401 が返されます。
• デフォルトの（ステートフル）HTTP モードでは、30 分間アイドル状態のセッションは期限切れになります。次のリクエストには HTTP 404 が返され、クライアントは新しいセッションを開始する必要があります。FastMCP の session_idle_timeout（http_app() に設定）または FASTMCP_HTTP_SESSION_IDLE_TIMEOUT（秒単位。期限切れにしない場合は none）で変更できます。FastMCP 4.1.0 リリースおよび #5229を参照してください。

# Local HTTP, loopback only
taxcode-mcp --transport streamable-http

# Public HTTP with a token
TAXCODE_MCP_AUTH_TOKEN="$(openssl rand -hex 32)" \
  taxcode-mcp --transport streamable-http --host 0.0.0.0 --allowed-host mcp.example.com

Docker

イメージのデフォルトコマンドは stdio なので、そのまま stdio サーバーとして動作します。

docker run -i --rm -e TAXCODE_API_KEY=your-api-key ghcr.io/christianclaudio/mcp-server-taxcode:latest

コンテナーから Streamable HTTP を提供するには、コンテナー内で 0.0.0.0 にバインドし、トークンを渡します。

docker run --rm -p 8000:8000 \
  -e TAXCODE_API_KEY=your-api-key \
  -e TAXCODE_MCP_AUTH_TOKEN=your-long-random-token \
  ghcr.io/christianclaudio/mcp-server-taxcode:latest \
  --transport streamable-http --host 0.0.0.0 --port 8000 --allowed-host mcp.example.com

🔌 AI アシスタントと IDE の統合ガイド

このサーバーは、標準の stdio または streamable-http を介して、主要な AI アシスタント、IDE、CLI ツールすべてとすぐに連携できます。

サーバーは PyPI で mcp-server-taxcode として公開されているため、クローンや環境の手動管理をせずに uvx mcp-server-taxcode で直接実行できます。または、ローカルにクローンして uv run --directory /path/to/mcp-server-taxcode taxcode-mcp で実行できます。

{
  "mcpServers": {
    "taxcode": {
      "command": "uvx",
      "args": ["mcp-server-taxcode"]
    }
  }
}

{
  "mcpServers": {
    "taxcode": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/mcp-server-taxcode", "taxcode-mcp"]
    }
  }
}

claude mcp add taxcode -- uvx mcp-server-taxcode

{
  "mcpServers": {
    "taxcode": {
      "command": "uvx",
      "args": ["mcp-server-taxcode"]
    }
  }
}

{
  "mcpServers": {
    "taxcode": {
      "command": "uvx",
      "args": ["mcp-server-taxcode"]
    }
  }
}

{
  "mcpServers": {
    "taxcode": {
      "command": "uvx",
      "args": ["mcp-server-taxcode"]
    }
  }
}

{
  "mcpServers": {
    "taxcode": {
      "command": "uvx",
      "args": ["mcp-server-taxcode"]
    }
  }
}

📚 正式ドキュメントとライブドキュメント MCP

MCP サーバーの開発、強化、拡張を行う際は、公式のフレームワークおよびプロトコルのリファレンスを参照してください。

• FastMCP 4 フレームワークリファレンス：https://gofastmcp.com/llms.txt — サーバーの構成（mount）、階層型ミドルウェア、変換（ToolTransform、ToolSearch）、ライフスパン、インメモリテストクライアントについて説明しています。
• Model Context Protocol 仕様：https://modelcontextprotocol.io/llms.txt — 公式仕様（2026-07-28）、ワイヤーレベルの JSON-RPC スキーマ、アノテーション、トランスポートのフレーミングについて説明しています。

ライブドキュメント MCP エンドポイント（SSE / Streamable HTTP）

AI コーディングエージェントをライブドキュメントサーバーに直接接続できます。

• FastMCP ドキュメントサーバー：https://gofastmcp.com/mcp（ツール：search_fast_mcp、query_docs_filesystem_fast_mcp、submit_feedback）
• Anthropic MCP ドキュメントサーバー：https://modelcontextprotocol.io/mcp（ツール：search_model_context_protocol、query_docs_filesystem_model_context_protocol、submit_feedback）

{
  "mcpServers": {
    "fastmcp-docs": { "type": "sse", "url": "https://gofastmcp.com/mcp" },
    "mcp-official-docs": { "type": "sse", "url": "https://modelcontextprotocol.io/mcp" }
  }
}

🏃 ローカル開発と検証

# 1. Install dependencies from the lockfile
uv sync --locked --extra dev

# 2. Run unit tests with 100% coverage requirement
uv run pytest

# 3. Static type checks & linting
uv run mypy --strict src/
uv run ruff check .
uv run ruff format --check .

# 4. Tool contract, protocol & drift assertions
uv run python scripts/check_tool_contract.py
uv run python scripts/check_openapi_drift.py
uv run python scripts/build_catalog.py --check   # data files, source manifest, generated docs
uv run pytest tests/test_protocol.py
uv run pytest tests/test_e2e_live.py -m e2e   # on demand; default CI uses -m 'not e2e'
./scripts/check_conformance.sh

# 5. AI code review gate (CodeRabbit)
coderabbit review --agent --uncommitted

📄 ライセンス

Apache License 2.0 の下でライセンスされています。詳細は LICENSE を参照してください。