California Tax Appeals

@pipeworx/california-tax-appeals

加利福尼亚州税务上诉办公室（OTA）意见——可在 4,254 份已发布意见（具有先例效力和不具有先例效力，2018–2026 年）中按法规引文或主题搜索，也可按 OTA 引文检索某份具体意见的全文及引用条款。

Pipeworx 的一部分（Pipeworx）——连接 AI Agent 与 1875+ 个实时数据源的 MCP 网关。这是一个独立、非官方的集成，与上游提供方无关联、未获其认可，也非由其发布。

工具

• ca_ota_search(query, category?, precedential_only?, limit?) — 按主题关键词（例如“居住地”“无过错配偶”）或法规引文（例如“17014”）查找意见。返回引文、标题、日期、税务类别（特许经营税/所得税或商业税）、先例效力状态，以及 OTA 自行编写的一行“争议事项”标签，按时间从新到旧排列。仅搜索列表元数据（标题 + 争议事项标签）——OTA 不提供全文搜索。
• ca_ota_opinion_lookup(cite) — 根据 OTA 引文（例如“2020-OTA-263P”）实时获取一份意见。返回意见全文、确切发布日期、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 上传，并作为 args._bakedIndex 注入（在 workers/gateway/src/pack-baked-indexes.json 中注册）。

ca_ota_search 只搜索列表元数据——意见标题和 OTA 自己的一行“Issues”标签（例如“Residency (R&TC 17014; Reg. 17014)”）。如果某项法规只在意见的正文中被引用，而不在 Issues 标签中，搜索就不会找到它；请使用 ca_ota_opinion_lookup 并提供具体引证来阅读该意见的全文。

“案号” = OTA 自己的引证（例如“2020-OTA-263P”，末尾的“P”表示 Precedential 状态）——也就是 OTA 自己引用意见时使用的编号，而不是 PDF 内部的 8 位“OTA Case No.”案卷编号（该编号只出现在 PDF 正文中，并会在 ca_ota_opinion_lookup 的响应中以 ota_case_no 字段呈现；此字段为实时读取，不在索引中）。查询引证时可以省略末尾的先例标记；ca_ota_opinion_lookup 会先后尝试两种格式，再报告未找到。有些意见带有其他 OTA 后缀字母（例如，Summary Conclusion of Proceedings 的“...SCP”）——这些后缀必须准确输入。

传输失败（非 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 都会连接到同一个网关和相同的 1875+ 个数据源。唯一的区别是哪个工具包的工具会被直接列出；无论使用哪个 URL，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。查找工具：POST https://gateway.pipeworx.io/v1/tools/search_packs，并传入 {"query":"..."}。

独立运行（无需网关账户）

此软件包也可以作为本地 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