California Tax Appeals

@pipeworx/california-tax-appeals

カリフォルニア州税務不服審判局（OTA）の意見書 — 法令の引用やトピックで、発行済みの4,254件の意見書（先例・非先例、2018～2026年）を検索するか、OTAの引用番号を指定して特定の意見書の全文と引用された規定を取得できます。

Pipeworx の一部です。AI エージェントを1,875以上の稼働中のデータソースに接続するMCPゲートウェイです。独立した非公式の連携であり、上流プロバイダーとの提携、同社による承認、または同社からの公開はありません。

ツール

• ca_ota_search(query, category?, precedential_only?, limit?) — トピックのキーワード（例：「居住地」「無実の配偶者」）または法令の引用（例：「17014」）で意見書を検索します。引用番号、タイトル、日付、税区分（フランチャイズ税／所得税または事業税）、先例としての効力の有無、OTA 独自の1行の「争点」タグを、日付の新しい順に返します。検索対象は一覧のメタデータ（タイトルと「争点」タグ）のみです。OTA は全文検索を提供していません。
• ca_ota_opinion_lookup(cite) — OTA の引用番号（例：「2020-OTA-263P」）で意見書を1件取得します。リアルタイムで取得し、意見書の全文、発行日、OTA 内部の事件番号、税区分、先例としての効力の有無、および本文で見つかった法令の引用（R&TC／Cal. Code Regs.／IRC。可能な範囲）を返します。

認証

キー不要です。登録も不要です。OTA が公開している意見書を読み取るだけです。

データソース

• https://ota.ca.gov/opinions/ — このパックのベイクスクリプト（scripts/bake-index.mjs）がスクレイピングし、年別および先例意見書の一覧ページをすべて検出するためのランディングページです。
• 年別の一覧ページ。例：https://ota.ca.gov/2024-franchise-income-tax-opinions/ および https://ota.ca.gov/2024-business-tax-opinions/ — その年・税区分に発行された先例・非先例の意見書をすべて掲載しています。
• 全年を対象とする先例意見書のページ。例： https://ota.ca.gov/all-precedential-franchise-and-income-tax-opinions/ — 年別ページに掲載されていない年をカバーするため、こちらも取得します。
• 個別の意見書PDF（例： https://ota.ca.gov/wp-content/uploads/sites/54/2021/06/19064883_Mazer_Opinion_Revised_090420_P.pdf） — ca_ota_opinion_lookup の呼び出しごとにリアルタイムで取得し、 shared/src/pdf-text.ts でテキストを抽出します。

形状と既知の制限

ota.ca.gov（WordPress/WP Engine、TablePress テーブル）にはJSON 検索バックエンドがありません。意見の一覧ページはすべてテーブル全体を静的 HTML として表示し、DataTables プラグインはクライアント側でのみページ分割を行います（実際に確認済み：これらのページにあるすべての DataTable('#tablepress-NNN', {...}) 初期化呼び出しに、ajax／serverSide オプションはありません）。そのため、このパックでは検索エンドポイントをプロキシするのではなく、OTA 独自の一覧ページから引用情報付きのテーブルを作成します。取得するページの正確な一覧と、コードを変更せずに新しい年を検出する方法については、scripts/bake-index.mjs の先頭コメントをご覧ください。

ルートの CLAUDE.md にある作成済みデータに関する規則（fleet #2754）に従い、インデックス（4,254 行、約 1.6MB）は KV に保存し、ゲートウェイのモジュールスコープには保存しません。scripts/sync-gateway-static-json.mjs によってアップロードされ、workers/gateway/src/pack-baked-indexes.json に登録されたうえで、args._bakedIndex として注入されます。

ca_ota_search が検索するのは一覧ページのメタデータのみです。対象は意見のタイトルと、OTA 独自の一行の「Issues」タグ（例：「Residency (R&TC 17014; Reg. 17014)」）です。意見の全文にのみ記載され、「Issues」タグには含まれない法令は、検索では見つかりません。意見の全文を読むには、特定の引用情報を指定して ca_ota_opinion_lookup を使用してください。

「事件番号」とは OTA 独自の引用情報（例：「2020-OTA-263P」。末尾の「P」は先例としての地位を示します）を指します。OTA が意見を引用する際に使う番号であり、PDF 内部の8桁の「OTA Case No.」事件番号ではありません。この番号は PDF 本文内にのみ記載され、ca_ota_opinion_lookup のレスポンスで ota_case_no として取得できます。これはライブで読み取られ、インデックスには登録されていません。引用情報を検索する際、末尾の先例マーカーは省略できます。見つからないと報告する前に、ca_ota_opinion_lookup は両方の形式を試します。意見によっては、OTA 独自の別の末尾文字（例：「...SCP」は Summary Conclusion of Proceedings を表します）が付くものもあり、その場合は正確に入力する必要があります。

転送エラー（200 以外のステータス）、または一覧と PDF の不一致（インデックスでは PDF があるとされる引用情報で 404 が返る場合）が発生すると、上流のステータスを明示してエラーをスローします。found: false が黙って返されることはありません。PDF が存在していても抽出に失敗した場合（まれな例として、テキストを含まないスキャン PDF など）は、エラーをスローする代わりに、警告を出して full_text: null にします。意見のメタデータ（タイトル、日付、決定の種類、「Issues」タグ）は、一覧ページから引き続き取得できます。

新たに発行された意見を取り込むため、定期的に node scripts/bake-index.mjs > src/ca-ota-index-data.ts を再実行してください。インデックスの件数が疑わしいほど少ない場合（意見が2,000件未満、または取得した一覧ページが15ページ未満）は書き込みを拒否します。これにより、OTA のマークアップ変更によって不完全なデータが黙って作成され、そのまま公開されるのを防ぎます。

クイックスタート

MCP クライアント（Claude Desktop、Cursor、Windsurf など）に追加してください。

{
  "mcpServers": {
    "california-tax-appeals": {
      "url": "https://gateway.pipeworx.io/california-tax-appeals/mcp"
    }
  }
}

このエンドポイントが実際に提供するもの

https://gateway.pipeworx.io/california-tax-appeals/mcp の tools/list は、上の表にあるツールに加えて、Pipeworx 共通のメタツール（ask_pipeworx、discover_tools、search_within、remember／recall など、ゲートウェイ全体で使えるツール群）を返します。そのため、表示されるツール数はこの表より多くなります。現在、単一パックのエンドポイントには、そのパック独自のツールとともに、共通ツールが約30個表示されます。接続の initialize レスポンスに正確な対象範囲が示されており、その日の時点での正式な情報源となります。

これは意図的な設計であり、偶然に多重化されているわけではありません。メタツールを使えば、ask_pipeworx がカタログ全体を検索して、このパックでは対応していない質問にも答えられます。別の MCP サーバーを追加する必要はありません。現時点では、メタツールなしでパックのエンドポイントをマウントする方法はありません。追加のスキーマによって増えるコンテキストコストがルーティングの利点を上回る場合は、複数のパックのエンドポイントではなく、フルゲートウェイに一度だけ接続してください。

このパックのツールだけでなく、すべてのパックのツールを直接表示するには、Pipeworx のフルゲートウェイに接続してください。

{
  "mcpServers": {
    "pipeworx": {
      "url": "https://gateway.pipeworx.io/mcp"
    }
  }
}

どちらの URL も、同じゲートウェイと同じ1,875以上のデータソースに接続します。異なるのは、どのパックのツールが直接一覧表示されるかだけです。どちらからでも ask_pipeworx を使えば、すべてのツールにアクセスできます。

MCP クライアントがない場合は、HTTP 経由で呼び出せます

curl -X POST https://gateway.pipeworx.io/v1/tools/ca_ota_search \
  -H 'Content-Type: application/json' \
  -d '{"query":"residency"}'

最初の呼び出しではアカウントは不要です。任意のツールを確認するには、GET https://gateway.pipeworx.io/v1/tools/ca_ota_search を使用します。ツールを探すには、{"query":"..."} を指定して POST https://gateway.pipeworx.io/v1/tools/search_packs を使用します。

スタンドアロン（ゲートウェイアカウント不要）

このパッケージはローカルの stdio MCP サーバーとしても動作します。Pipeworx アカウントもゲートウェイ経由のやり取りも不要です。

{
  "mcpServers": {
    "california-tax-appeals": {
      "command": "npx",
      "args": ["-y", "@pipeworx/mcp-california-tax-appeals"]
    }
  }
}

または、直接実行して起動を確認できます。

npx -y @pipeworx/mcp-california-tax-appeals

stdin/stdout 経由で MCP を使用し、このパックのツールのみを対象に initialize／tools/list／tools/call に応答します。上記のゲートウェイ接続で追加される共有メタツールは含まれません。同じソース、同じツールで、ask_pipeworx によるルーティングはありません。

ask_pipeworx の使用

ツールを直接呼び出す代わりに、平易な英語で質問できます。これは上記のパックエンドポイントとゲートウェイ全体のどちらでも動作します。

ask_pipeworx({ question: "your question about California Tax Appeals data" })

ゲートウェイが適切なツールを選び、引数を自動的に入力します。

詳細

• ドキュメントとガイド
• pipeworx.io

ライセンス

MIT