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，即可获取全文。
• 分页限制响应长度：每个法规定工具的结果均不超过 32,000 个 JSON 字符。statutes_lookup_statute 会分页返回长文本，每个文本字段最多 8,000 个字符（text_page 提供偏移量和全文长度；将 next_cursor 作为 page_cursor 传回即可获取下一页）。statutes_search_tax_code 和 statutes_list_publications 会将每次调用的 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 天、三年内 549 天、美国境内 90 天）、税务住所和更紧密联系测试。
  • calculate_built_in_gain_sourcing：按迁居前后持有期间分配 Section 937 / Act 60 资本利得。
  • evaluate_state_residency：计算多州法定居留天数、永久住所（PPA）、住所审计风险标记，并计算美国全部 50 个州和哥伦比亚特区的纳税义务（共 51 个司法管辖区）。
• 配置文件和可选 ToolSearch：
  • 按领域挂载的配置文件：full、system、statutes、compliance、readonly。
  • 按工作类型划分的允许列表配置文件：researcher（法规定 + 通函）、advisor（跨境居留 + BIG 计算）。
• 精简工具集：仅公开 8 个精简的只读 MCP 工具，并明确设置 MCP 2.0 注解（readOnlyHint=True）。

⚙️ 配置

HTTP 传输与身份验证

Stdio 是默认传输方式，无需令牌。HTTP 传输遵循 MCP 指南：本地服务仅绑定到 localhost，并对每个连接进行身份验证：

• 在 127.0.0.1、::1 或 localhost 上（--host 默认为 127.0.0.1），无论是否设置 TAXCODE_MCP_AUTH_TOKEN，HTTP 都会运行；未设置时会发出警告，说明请求未经身份验证。
• 在任何其他主机（0.0.0.0、::、局域网地址）上，除非设置了 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 编码 Agent 直接连接到实时文档服务：

• 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。