mcp-server-taxcode 1.1.0__tar.gz → 1.3.0__tar.gz

mcp_server_taxcode-1.3.0/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @christianclaudio

mcp_server_taxcode-1.3.0/.github/dependabot.yml

@@ -0,0 +1,58 @@
+version: 2
+updates:
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "sunday"
+      time: "09:30"
+      timezone: "America/New_York"
+    open-pull-requests-limit: 10
+    groups:
+      dependencies:
+        patterns:
+          - "*"
+      python-security:
+        applies-to: "security-updates"
+        patterns:
+          - "*"
+        update-types:
+          - "minor"
+          - "patch"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "sunday"
+      time: "09:30"
+      timezone: "America/New_York"
+    open-pull-requests-limit: 10
+    groups:
+      actions:
+        patterns:
+          - "*"
+      actions-security:
+        applies-to: "security-updates"
+        patterns:
+          - "*"
+        update-types:
+          - "minor"
+          - "patch"
+
+  - package-ecosystem: "docker"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "sunday"
+      time: "09:30"
+      timezone: "America/New_York"
+    open-pull-requests-limit: 10
+    groups:
+      docker-security:
+        applies-to: "security-updates"
+        patterns:
+          - "*"
+        update-types:
+          - "minor"
+          - "patch"

{mcp_server_taxcode-1.1.0 → mcp_server_taxcode-1.3.0}/.github/workflows/ci.yml

@@ -7,10 +7,15 @@ on:
     branches: [main]
   # Merges made by dependabot-automerge.yml use GITHUB_TOKEN, and pushes made
   # with GITHUB_TOKEN don't trigger push workflows, so the push trigger above
-  # misses them. The daily run tests main itself; schedule runs only on the
-  # default branch. The minute is off the hour to avoid peak scheduler load.
+  # misses them. The weekly run tests main itself on Sunday afternoon Eastern,
+  # after the Sunday morning Dependabot run (.github/dependabot.yml), and is the
+  # only scheduled run of the drift-check job (manual dispatch also runs it);
+  # schedule runs only on the default branch.
+  # timezone keeps it at 15:53 Eastern through daylight saving changes. The minute
+  # is off the hour to avoid peak scheduler load.
   schedule:
-    - cron: '29 9 * * *'
+    - cron: '53 15 * * 0'
+      timezone: "America/New_York"
   workflow_dispatch:
 
 concurrency:
@@ -35,7 +40,7 @@ jobs:
           persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884  # v10.3.0
+        uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2  # v10.3.3
         with:
           # Newest uv that meets pyproject.toml's [tool.uv] required-version (>=0.13.4, from
           # FastMCP's October 2026 certificate authority incident notice).
@@ -43,12 +48,12 @@ jobs:
           enable-cache: true
 
       - name: Set up Python
-        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0  # v7.1.0
         with:
-          python-version: "3.10"
+          python-version: "3.11"
 
       - name: Install dependencies
-        run: uv sync --locked --extra dev --python 3.10
+        run: uv sync --locked --extra dev --python 3.11
 
       - name: Check code formatting
         run: uv run ruff format --check .
@@ -65,7 +70,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
         with:
@@ -73,7 +78,7 @@ jobs:
           persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884  # v10.3.0
+        uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2  # v10.3.3
         with:
           # Newest uv that meets pyproject.toml's [tool.uv] required-version (>=0.13.4, from
           # FastMCP's October 2026 certificate authority incident notice).
@@ -81,7 +86,7 @@ jobs:
           enable-cache: true
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0  # v7.1.0
         with:
           python-version: ${{ matrix.python-version }}
 
@@ -105,7 +110,7 @@ jobs:
           persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884  # v10.3.0
+        uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2  # v10.3.3
         with:
           # Newest uv that meets pyproject.toml's [tool.uv] required-version (>=0.13.4, from
           # FastMCP's October 2026 certificate authority incident notice).
@@ -113,12 +118,12 @@ jobs:
           enable-cache: true
 
       - name: Set up Python
-        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0  # v7.1.0
         with:
-          python-version: "3.10"
+          python-version: "3.11"
 
       - name: Install dependencies
-        run: uv sync --locked --extra dev --python 3.10
+        run: uv sync --locked --extra dev --python 3.11
 
       - name: Verify tool contracts
         run: uv run python scripts/check_tool_contract.py
@@ -149,19 +154,19 @@ jobs:
           persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884  # v10.3.0
+        uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2  # v10.3.3
         with:
           # Newest uv that meets pyproject.toml's [tool.uv] required-version (>=0.13.4, from
           # FastMCP's October 2026 certificate authority incident notice).
           version-file: "pyproject.toml"
 
       - name: Set up Python
-        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0  # v7.1.0
         with:
-          python-version: "3.10"
+          python-version: "3.11"
 
       - name: Install dependencies
-        run: uv sync --locked --extra dev --python 3.10
+        run: uv sync --locked --extra dev --python 3.11
 
       - name: Build wheel and sdist
         run: uv build
@@ -198,6 +203,59 @@ jobs:
           fi
           echo "Image label matches ${EXPECTED}"
 
+      - name: Runtime image has the project and no build backend
+        # The builder installs the build backend to /tmp/build-backend, outside the venv the
+        # runtime stage copies, so no build-only package from docker/build-backend.txt may be
+        # in the image. packaging is left out on purpose: fastmcp-slim needs it at runtime
+        # (uv.lock).
+        run: |
+          PROJECT="$(grep -m 1 '^name = ' pyproject.toml | cut -d '"' -f 2)"
+          docker run --rm --entrypoint pip mcp-server-ci:test show "$PROJECT" > /dev/null
+          for pkg in hatchling uv-dynamic-versioning dunamai trove-classifiers tomlkit jinja2 \
+            MarkupSafe pathspec pluggy; do
+            if docker run --rm --entrypoint pip mcp-server-ci:test show "$pkg" > /dev/null 2>&1; then
+              echo "::error::build backend package $pkg is in the runtime image"
+              exit 1
+            fi
+          done
+          echo "Runtime image has $PROJECT and no build backend"
+
+      - name: Image serves MCP over stdio
+        # Starts the runtime image on its default stdio transport with no network, sends
+        # initialize, notifications/initialized and tools/list, and holds stdin open until
+        # the tools/list reply arrives so the check does not depend on shutdown-on-EOF timing.
+        # Replies are matched by JSON-RPC id, not by line order, and every non-empty stdout line
+        # must parse as exactly one JSON-RPC 2.0 message (stdio is newline-delimited).
+        run: |
+          set -euo pipefail
+          IN="$RUNNER_TEMP/mcp-in"
+          OUT="$RUNNER_TEMP/mcp-out"
+          mkfifo "$IN"
+          : > "$OUT"
+          timeout --kill-after=5 60 docker run -i --rm --network none mcp-server-ci:test < "$IN" > "$OUT" &
+          SERVER=$!
+          exec 3> "$IN"
+          MESSAGES='split("\n") | map(select(length > 0) | fromjson | if type == "object" and .jsonrpc == "2.0" then . else error("stdout line is not a JSON-RPC 2.0 message") end)'
+          wait_for_id() {
+            for _ in $(seq 1 150); do
+              if jq -Rse --argjson id "$1" "$MESSAGES | any(.[]; .id == \$id)" "$OUT" > /dev/null 2>&1; then
+                return 0
+              fi
+              sleep 0.2
+            done
+            echo "No reply with id $1 within 30s"; cat "$OUT"; exit 1
+          }
+          printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"ci-smoke","version":"0"}}}' >&3
+          wait_for_id 1
+          printf '%s\n' '{"jsonrpc":"2.0","method":"notifications/initialized"}' >&3
+          printf '%s\n' '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' >&3
+          wait_for_id 2
+          exec 3>&-
+          wait "$SERVER"
+          jq -Rse "$MESSAGES"' | map(select(.id == 1)) | length == 1 and .[0].result.protocolVersion == "2025-11-25"' "$OUT"
+          jq -Rse "$MESSAGES"' | map(select(.id == 2)) | length == 1 and (.[0].result.tools | type == "array" and length > 0)' "$OUT"
+          echo "Image answered initialize and tools/list over stdio"
+
       - name: Builder fails below the ca-certificates floor
         # Raising CA_CERTIFICATES_FLOOR above any real Debian version makes the installed
         # package older than the floor, whatever version the base image or trixie-security
@@ -223,3 +281,35 @@ jobs:
             exit 1
           fi
           echo "Builder stops at the ca-certificates floor check before any pip step"
+
+  drift-check:
+    name: Check API Drift
+    # Scheduled and manual runs only; pushes and pull requests skip it.
+    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
+    permissions:
+      contents: read
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2  # v10.3.3
+        with:
+          # Newest uv that meets pyproject.toml's [tool.uv] required-version (>=0.13.4, from
+          # FastMCP's October 2026 certificate authority incident notice).
+          version-file: "pyproject.toml"
+          enable-cache: true
+
+      - name: Set up Python
+        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0  # v7.1.0
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: uv sync --locked --extra dev --python 3.11
+
+      - name: Run OpenAPI drift detection
+        run: uv run python scripts/check_openapi_drift.py

{mcp_server_taxcode-1.1.0 → mcp_server_taxcode-1.3.0}/.github/workflows/release.yml

@@ -26,7 +26,7 @@ jobs:
           persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884  # v10.3.0
+        uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2  # v10.3.3
         with:
           # Newest uv that meets pyproject.toml's [tool.uv] required-version (>=0.13.4, from
           # FastMCP's October 2026 certificate authority incident notice).
@@ -34,9 +34,9 @@ jobs:
           enable-cache: false
 
       - name: Set up Python
-        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0  # v7.1.0
         with:
-          python-version: "3.10"
+          python-version: "3.11"
 
       - name: Build Wheel & Source Dist
         run: uv build
@@ -94,10 +94,10 @@ jobs:
           name: dist
 
       - name: Publish to PyPI via OIDC
-        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33  # v1.14.2
+        uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086  # v1.14.3
 
       - name: Create GitHub Release
-        uses: softprops/action-gh-release@efb35369e0ad2afab669f228072c1b0d510eae64  # v3.0.3
+        uses: softprops/action-gh-release@8a0cd651e5b2365bd640854a3fa5dfc70e4875f3  # v3.0.4
         with:
           files: |
             dist/*.whl
@@ -122,7 +122,7 @@ jobs:
           persist-credentials: false
 
       - name: Log in to GitHub Container Registry
-        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f  # v4.6.0
+        uses: docker/login-action@8aa5831fb8d48d8f76594c7ddde61ae58019f550  # v4.8.0
         with:
           registry: ghcr.io
           username: ${{ github.actor }}

{mcp_server_taxcode-1.1.0 → mcp_server_taxcode-1.3.0}/AGENTS.md

@@ -46,11 +46,11 @@ Host configuration JSON for these doc servers (`mcp_config.json` and other deskt
 - `src/<name>_mcp/client.py` — async HTTP client; `ssrf.py` — SSRF / DNS-rebinding guard; `errors.py` — exceptions and secret redaction; `middleware.py` — parent and child middleware; `config.py` — settings.
 - `src/taxcode_mcp/data/` — the single source of truth for statute and publication rows: `jurisdictions.json` (catalog order), `statutes/<code>.json`, `publications/<code>.json`, `manifest/<code>.json` (one source record per row), and `rates/<code>.json` (the compliance tools' rate tables, one per state in `RATE_TABLE_MODELS`). `src/taxcode_mcp/catalog.py` loads and validates them; `db.py` seeds DuckDB from the rows, and `tools/compliance.py` reads every rate from the rate tables. Row layout, manifest fields and how to add a row: `CONTRIBUTING.md` (Adding or changing a row).
 - `scripts/build_catalog.py` — rewrites the data files in canonical form and generates `docs/<code>/*.md`, `docs/<code>/llms-full.txt` (one jurisdiction's full text), `docs/llms.txt` and `docs/llms-full.txt` (the index of the per-jurisdiction files) from them; `--check` (run in CI and by `tests/test_catalog.py`) fails on a schema or canonical-form error (rate tables included, and a missing or stray rate table), an incomplete or mismatched manifest entry, or docs that differ from the generated output. Never edit generated docs by hand.
-- `src/taxcode_mcp/paging.py` — hard response cap (32,000 characters of JSON) and paging for the statutes tools: `statutes_lookup_statute` pages long text (`page_cursor` / `next_cursor`), search and publications clamp `limit` to 1..25 items per call (`offset` / `next_offset`), and the `taxcode://statutes/{jurisdiction}/{section}{?page_cursor}` resource returns the same 8,000-character pages, ending a non-final page with the full URI of the next one (`...?page_cursor=`). The template has no `statutes/` segment of its own: the `statutes` mount namespace supplies it.
+- `src/taxcode_mcp/paging.py` — hard response cap (32,000 characters of JSON) and paging for the statutes tools: `statutes_lookup_statute` pages long text (`page_cursor` / `next_cursor`), search and publications clamp `limit` to 1..25 items per call (`offset` / `next_offset`), and the `taxcode://statutes/{jurisdiction}/{section*}{?page_cursor}` resource returns the same 8,000-character pages, ending a non-final page with the full URI of the next one (`...?page_cursor=`). The template has no `statutes/` segment of its own: the `statutes` mount namespace supplies it.
 - `scripts/check_tool_contract.py` — source of truth for the expected tool set and annotations. Do not hard-code tool counts elsewhere.
 - `scripts/check_openapi_drift.py`, `scripts/check_conformance.sh` + `conformance-baseline.yml` — drift and protocol conformance.
 - `tests/` — offline unit, layered-composition, and protocol tests; `test_e2e_live.py` is opt-in (`-m e2e`).
-- `.github/workflows/` — `ci.yml`, `drift-monitor.yml`, `dependabot-automerge.yml`, and `release.yml` (on a `v*` tag: build with full history, verify the wheel version matches the tag, publish to PyPI via OIDC, create the GitHub Release from `scripts/release_notes.py`, build and push the container image to GHCR, attest build provenance for both wheel and container digests, and publish `server.json` to the MCP Registry). `ci.yml`'s `docker-build` job builds the image on every PR and checks its `io.modelcontextprotocol.server.name` label matches `server.json`.
+- `.github/workflows/` — `ci.yml`, `dependabot-automerge.yml`, and `release.yml` (on a `v*` tag: build with full history, verify the wheel version matches the tag, publish to PyPI via OIDC, create the GitHub Release from `scripts/release_notes.py`, build and push the container image to GHCR, attest build provenance for both wheel and container digests, and publish `server.json` to the MCP Registry). `ci.yml`'s `docker-build` job builds the image on every PR and checks its `io.modelcontextprotocol.server.name` label matches `server.json`.
 - `scripts/release_notes.py` — release body from squash commits since the previous `v*` tag. `scripts/check_version.py` — runs after `uv build` and reads the version from the single wheel in `dist/` (the file that ships, as release.yml's tag check does); fails on `0.0.0` (no git metadata) or `0.0.1.devN` (no reachable tag, a shallow checkout).
 - `server.json` (MCP Registry metadata), `Dockerfile`, `pyproject.toml`, `fastmcp.json`.
 - `COOKBOOK.md` — private maintainer runbook (release SOP, drift, testing, composition, payload hardening, naming recipes). Template-only.
@@ -142,6 +142,7 @@ When translating an API documentation page, `llm.txt`, or OpenAPI specification
    - The `Dockerfile` must use a multi-stage build (`python:3.14-slim AS builder` $\rightarrow$ runtime, pulled from Docker Hub and pinned by digest) creating and executing under non-root `USER mcp` with virtual environment `/opt/venv`. The runtime stage carries `LABEL io.modelcontextprotocol.server.name` equal to the `server.json` `name` (MCP Registry OCI ownership check), and the default command stays stdio.
    - Trust stores follow FastMCP's [certificate authority incident notice (October 2026)](https://github.com/PrefectHQ/fastmcp/blob/main/SECURITY.md#certificate-authority-incident-october-2026): both stages upgrade the OS `ca-certificates` package and fail the build below the patched Debian version (`ARG CA_CERTIFICATES_FLOOR`, declared once), the builder does so before any pip runs because pip trusts the OS store as well as its bundled certifi, the builder bootstraps pip 26.2.2, and `certifi>=2026.10.19` is a direct dependency. `tests/test_dockerfile.py` and CI's `docker-build` job enforce the order and the floor.
    - The pip bootstrap is hash-pinned in `docker/pip-bootstrap.txt` and installed with `--require-hashes`, so it does not depend on the TLS trust of the base image's older pip and certifi; whoever raises the pip floor updates that pin and its sha256 from PyPI (`https://pypi.org/pypi/pip/<version>/json`, the `py3-none-any` wheel's `digests.sha256`), because Dependabot does not track the file.
+   - Runtime dependencies install from `uv.lock`, so the image runs the versions CI tests: the builder installs uv from `docker/uv-bootstrap.txt` (hash-pinned, `--require-hashes`, into `/tmp/uv` outside the venv, so the runtime image has no uv), runs `uv export --locked --no-dev --no-emit-project --format requirements.txt` (base dependencies only, a hash for every package, and the build fails if `uv.lock` is stale), installs that file with pip in hash-checking mode, then installs the project build backend from `docker/build-backend.txt` (hash-pinned hatchling, uv-dynamic-versioning, and every transitive build dependency, `--require-hashes --only-binary=:all:`, into `/tmp/build-backend` outside the venv, so the runtime image has no build backend) and the project with `PYTHONPATH=/tmp/build-backend pip install --no-deps --no-build-isolation .`. Never install the project with its dependencies (`pip install .`), which resolves them fresh at build time. Dependabot's weekly `uv` updates bump the uv pin and rewrite its sha256 values, writing one for every wheel and the sdist published for that version. Whoever changes `[tool.uv] required-version` keeps the uv pin within it, and a hand bump takes a sha256 for every wheel and the sdist from `https://pypi.org/pypi/uv/<version>/json` (`digests.sha256`); the manylinux x86_64 and aarch64 wheels are the ones the image build installs. The build-backend pins are the `build-backend` dependency group in `pyproject.toml` (exact versions inside the `[build-system]` ranges, not installed by default), so `uv.lock` carries their closure with hashes. After `uv lock`, `uv run python scripts/gen_build_backend.py` rewrites `docker/build-backend.txt` from `uv.lock` (`--check` reports drift instead), and `tests/test_build_backend_lock.py` fails if the file, the lock or the ranges disagree. Dependabot does not track that file (no `pip` ecosystem entry covers `docker/` in `.github/dependabot.yml`). `tests/test_dockerfile.py` enforces the install steps and the pins.
    - Lowering `CA_CERTIFICATES_FLOOR` with `--build-arg` is unsupported; the build-arg exists only so CI can raise it for the negative floor check, and CI and the release workflow never pass it otherwise.
 4. **Registry Metadata Constraint**:
    - In `server.json`, the root `description` must be **strictly $\le$ 100 characters** to pass MCP Registry schema validation (longer strings trigger HTTP 422 errors).
@@ -210,6 +211,6 @@ coderabbit review --agent --uncommitted
 
 ## 🔄 CI & Releases
 
-CI is defined in `.github/workflows/ci.yml` (jobs: `lint-and-types`, `test` on Python 3.10–3.14, `tool-contract`, `build-check`, `docker-build` (builds the image without pushing, checks its MCP server-name label against `server.json`, and checks that the builder stage fails at its `ca-certificates` floor check, before any pip step, when the floor is above the installed version)). It runs on pushes and pull requests to `main`, daily on `main` at 09:29 UTC (`schedule`), and on manual dispatch (`workflow_dispatch`); the daily run exists because merges by `dependabot-automerge.yml` use `GITHUB_TOKEN`, and pushes made with `GITHUB_TOKEN` don't trigger push workflows, so those merges get no `push` run. Run the commands above before opening a PR. Scheduled upstream drift runs in `drift-monitor.yml`. `dependabot-automerge.yml` turns on squash auto-merge only for Dependabot PRs whose highest update is minor or patch; major updates wait for a human review. Docker base image updates (`package-ecosystem` `docker`) never auto-merge and always wait for a human review: Dependabot's docker ecosystem can move the image tag, not just its digest (for example `python:3.12-slim` to `python:3.14-slim`, a Python runtime upgrade that Dependabot labels a minor update), so the job logs a notice and leaves the PR open.
+CI is defined in `.github/workflows/ci.yml` (jobs: `lint-and-types`, `test` on Python 3.11–3.14, `tool-contract`, `build-check`, `docker-build` (builds the image without pushing, checks its MCP server-name label against `server.json`, checks that the runtime image has the project and none of the build-only packages (runtime dependencies such as `packaging` stay), checks that the image answers `initialize` and `tools/list` over stdio with no network, and checks that the builder stage fails at its `ca-certificates` floor check, before any pip step, when the floor is above the installed version), and `drift-check` (the same OpenAPI drift check as its own job; scheduled and manual runs only)). It runs on pushes and pull requests to `main`, weekly on `main` on Sunday at 15:53 America/New_York (`schedule` with `timezone`, after the Sunday 09:30 America/New_York Dependabot run in `.github/dependabot.yml`), and on manual dispatch (`workflow_dispatch`); the weekly run exists because merges by `dependabot-automerge.yml` use `GITHUB_TOKEN`, and pushes made with `GITHUB_TOKEN` don't trigger push workflows, so those merges get no `push` run. Run the commands above before opening a PR. `dependabot-automerge.yml` turns on squash auto-merge only for Dependabot PRs whose highest update is minor or patch; major updates wait for a human review. Docker base image updates (`package-ecosystem` `docker`) never auto-merge and always wait for a human review: Dependabot's docker ecosystem can move the image tag, not just its digest (for example `python:3.12-slim` to `python:3.14-slim`, a Python runtime upgrade that Dependabot labels a minor update), so the job logs a notice and leaves the PR open.
 
 `release.yml` runs on `v*` tag pushes only: it creates the GitHub Release, then builds the container image, pushes it to GHCR, attests it, and publishes to the MCP Registry. In the template repo the image is built only (no push), and the attest and registry jobs skip. Release procedure (tag-based versioning, release notes, pre-tag checks): **`COOKBOOK.md`** Recipes 1–2; product-repo migration steps: Recipe 9.

{mcp_server_taxcode-1.1.0 → mcp_server_taxcode-1.3.0}/CONTRIBUTING.md

@@ -17,17 +17,17 @@ Statute and publication rows live only in the data files under `src/taxcode_mcp/
 | File | Holds |
 | --- | --- |
 | `jurisdictions.json` | Jurisdiction codes in catalog order. Rows load in this order, then in file order. |
-| `statutes/<code>.json` | One jurisdiction's statute rows (`us.json`, `pr.json`, `ga.json`, ...). `text_en` and `text_es` are lists of lines, joined with a newline when loaded. |
+| `statutes/<code>.json` | One jurisdiction's statute rows (`us.json`, `pr.json`, `can.json`, `ga.json`, ...). `text_en`, `text_es` and optional `text_fr` (required on `CAN` rows, stored in `statutes_fr`) are lists of lines, joined with a newline when loaded. |
 | `publications/<code>.json` | Publications whose `id` starts with `<code>-`. |
 | `manifest/<code>.json` | One source record per statute and publication row and per rate table of that jurisdiction. |
-| `rates/<code>.json` | The rate table the compliance tools compute a state's tax from. See "Changing a rate table" below. |
+| `rates/<code>.json` | The rate table the compliance tools compute a state's or country's tax from (`RATE_TABLE_MODELS` and `COUNTRY_RATE_TABLES` in `src/taxcode_mcp/catalog.py`). See "Changing a rate table" below. |
 
 Every manifest entry has every field below. A value we don't have is the explicit string `"not_recorded"`, never a missing key and never a guess.
 
 | Field | Meaning |
 | --- | --- |
 | `kind`, `id` | `statute` or `publication` and the row's `id`, or `rate_table` and `<code>-rates`. |
-| `url` | Must equal the row's (or rate table's) `source_url`. |
+| `url` | Must equal the row's (or rate or federal table's) `source_url`. |
 | `edition` | Which text the source at `url` is: `as_enacted` (the law as passed), `amended_compilation` (a compilation with later amendments folded in, such as an OGP "según enmendada" text), or `"not_recorded"`. |
 | `official` | `true` when the URL is on the issuing government body's own site, `false` for a third-party site, or `"not_recorded"`. It says nothing about whether the stored text is official. |
 | `licence` | Reuse terms of the source, or `"not_recorded"`. |
@@ -36,7 +36,9 @@ Every manifest entry has every field below. A value we don't have is the explici
 | `enacting_law` | Law that enacted or last amended the text, or `"not_recorded"`. |
 | `effective_date` | Date the text took effect (`YYYY-MM-DD`), or `"not_recorded"`. |
 | `verification` | `verified_verbatim` (checked word for word against the fetched source; needs `retrieved` and `content_sha256`), `summary` (the stored text is a summary, not a copy), or `"not_recorded"`. |
-| `year_sources` | Optional, `rate_table` entries only, as the last field. A list of the sources for figures of other tax years than `url`'s, `tax_year` ascending. Each has exactly `tax_year`, `values` (the table values it confirms, keyed by their path in `params`, such as `rates[0].rate` or `deduction_mfj_2025`; each must equal the table's value), `url` (https), `official` (`true`), `retrieved` and `content_sha256` (`"not_recorded"` when the bytes could not be kept). |
+| `french_source` | Optional, `statute` entries only, after `verification`, and required when the row has `text_fr`. An object with `url` (https) and `content_sha256` (64 lowercase hex digits) for the fetched French source artifact. |
+| `verification_note` | Optional, and only on a `rate_table` whose `verification` is `not_recorded`, after `verification` and before `year_sources`. A non-empty string saying why that table could not be confirmed. A checked table does not carry it. |
+| `year_sources` | Optional, `rate_table` and `federal_table` entries only, as the last field. A list of the sources for figures of other tax years or corroborating second sources on `url`'s year, `tax_year` ascending. Each has exactly `tax_year`, `values` (the table values it confirms, keyed by their path in `params`, such as `rates[0].rate`, `deduction_mfj_2025` or `years[0].brackets[4].rate`, or for the federal table in its document, such as `years[6].single`; each must equal the table's value), `url` (https), `official` (`true`), `retrieved` and `content_sha256` (`"not_recorded"` when the bytes could not be kept). |
 
 To add or change a row:
 
@@ -49,7 +51,7 @@ A new jurisdiction also needs its code in `jurisdictions.json` and, for its name
 
 ## Changing a rate table
 
-Every deduction, exemption, bracket, rate and per-year value the compliance tools use lives in `src/taxcode_mcp/data/rates/<code>.json`, one file per state that has one (`RATE_TABLE_MODELS` in `src/taxcode_mcp/catalog.py`). FL and TX have none. Never add a rate as a Python literal.
+Every deduction, exemption, bracket, rate and per-year value the compliance tools use lives in `src/taxcode_mcp/data/rates/<code>.json`, one file per state that has one plus country tables in `COUNTRY_RATE_TABLES` (`RATE_TABLE_MODELS` in `src/taxcode_mcp/catalog.py`). FL and TX have none. Never add a rate as a Python literal.
 
 - `model` names the shape of `params` and which formula reads it. It must match `RATE_TABLE_MODELS`.
 - Amounts and rates are floats (`1000.0`, not `1000`), because tool output prints them as stored.
@@ -57,8 +59,12 @@ Every deduction, exemption, bracket, rate and per-year value the compliance tool
 - Each `rates` step also carries its prose: a `flat_by_year` step (CO, NC) its whole `rate_desc`, and a `georgia` step the `law` that set that year's rate, which both Georgia answers cite. Georgia's flat rate starts with tax year 2024, so an earlier tax year gets the oldest step and its answers say they are an estimate.
 - Each table has a `source_url` and a `rate_table` entry in `manifest/<code>.json` with the same `url`. A table whose numbers have not been checked against official text keeps `"not_recorded"` in both. Record a source only once it has been checked, and only an official one: `url` is the document the brackets were read from, `retrieved` the day it was fetched and `content_sha256` the hash of the fetched bytes (`"not_recorded"` when the bytes could not be kept).
 - `registry` tables keep their original keys. A `_YYYY` suffix holds the value from that tax year on, and the unsuffixed key covers the years before. Never copy a current value into an earlier year.
-- The `flat_with_surtax` table's `surtax` and the `capital_gains_excise` table's `capital_gains_deduction` follow the same convention: `surtax_2024` or `capital_gains_deduction_2024`, after the model's own fields with years ascending, holds the value from 2024 on, and the unsuffixed key keeps the earlier years. Registry deductions take `_2024`, `_2025` and `_2026`.
-- A graduated `registry` table says how it taxes income below its top bracket with exactly one of three keys. `brackets` is the state's official marginal schedule (`over` and `rate` only, the lowest step's `over` is `null`), and replaces the `top_*`, `zero_*` and `middle_*` keys. `middle_rate` is a single statutory rate for the middle band. `middle_rate_estimate: true` keeps the old stand-in of 65% of the top rate where no official schedule fits this model. Every `evaluate_state_residency` answer carries `middle_rate_is_estimate`; it is `true` only for such a table, whose `rate_description` then says so. Never add a new estimate where an official schedule exists.
+- The `flat_with_surtax` table's `surtax`, the `capital_gains_excise` table's `capital_gains_deduction` and the `brackets_cumulative` table's `brackets` and `exemption` follow the same convention: `surtax_2024`, `capital_gains_deduction_2024`, `brackets_2025` or `exemption_2025`, after the model's own fields with years ascending for each name, holds the value from that year on, and the unsuffixed key keeps the earlier years. The `capital_gains_excise` table's `tier` (`{"over": ..., "rate": ...}`, an additional rate on the taxable gains over `over`) takes only `tier_YYYY` keys and doesn't apply before the first one. The `georgia` table's `standard_deduction` and `retirement_exclusion` take `_YYYY` keys the same way (`standard_deduction_2026`, `retirement_exclusion_2027`), after `rates`, years ascending. A tax year after `GA_LAST_FIXED_YEAR` (the last year whose deduction and rate HB 463 of 2026 fixes) uses that year's figures and is labeled an estimate, because HB 463's later increases and rate cuts depend on revenue tests.
+- Registry deductions take `_2024`, `_2025` and `_2026`. Registry `brackets` and `rate_desc` take `brackets_YYYY` and `rate_desc_YYYY` for 2024 to 2030, and the four `credit_base_*` / `credit_phaseout_*` amounts take `_2025`. Each needs its unsuffixed key and comes after it, years ascending; `brackets_YYYY` is validated like `brackets` and doesn't count as one of the three graduated keys below. A tax year after `MS_LAST_ENACTED_RATE_YEAR`, `UT_LAST_CREDIT_AMOUNT_YEAR`, `NE_LAST_PUBLISHED_SCHEDULE_YEAR` or `OH_LAST_FIXED_SCHEDULE_YEAR` (tied by tests to the last year each table holds) carries that table's figures forward and is labeled an estimate in its rate prose.
+- A graduated `registry` table says how it taxes income below its top bracket with exactly one of two keys. `brackets` is the state's official marginal schedule (`over` and `rate` only, the lowest step's `over` is `null`), and replaces the `top_*`, `zero_*` and `middle_*` keys. `middle_rate` is a single statutory rate for the middle band. Every `evaluate_state_residency` answer carries `middle_rate_is_estimate` (always `false`; the former 65%-of-top stand-in is gone). Never invent a middle-band rate where an official schedule exists.
 - A `registry` table may take a nonrefundable credit off the computed tax, as Utah's taxpayer tax credit does, with all six `credit_*` keys: `credit_rate` times the filing status's `credit_base`, less `credit_phaseout_rate` times the taxable income over its `credit_phaseout` amount, never below zero. Model such a credit as a credit, not as a deduction.
 
+- The `canada_federal` model (`rates/can.json`, `COUNTRY_RATE_TABLES`) holds Canada's federal Part I schedule and `ITA s. 128.1` departure-tax parameters: consecutive ascending `years` (each with `tax_year`, graduated `brackets`, `credit_rate`, and `basic_personal_amount` carrying `maximum`, `minimum`, `phaseout_start` and `phaseout_end` for the `ITA s. 118(1.1)` phaseout between the fourth and fifth brackets) plus `capital_gains_inclusion_rate`, `sojourner_days`, `t1161_threshold`, `personal_use_reporting_threshold`, `personal_use_minimum` and `short_term_resident_months`, backed by `can-rates` and `year_sources` in `manifest/can.json`.
+- The federal standard deduction by tax year lives in `src/taxcode_mcp/data/federal/standard_deduction.json` (`years`, consecutive and ascending, each with `tax_year`, `single` and `mfj`), with a `federal_table` entry `us-standard-deduction` in `manifest/us.json` and a `year_sources` item for each year. A `flat_by_year` table whose `deduction` is the string `"federal_standard_deduction"` (CO) uses that table's figure for the tax year, or the nearest year it holds, with an estimate label. Other tables keep their own sourced amounts: a state's conformity to a federal figure is its own law.
+
 The files load and are validated when the server starts. `tests/test_compliance_golden.py` pins the exact output of every compliance tool over a wide input grid, so a rate change also updates those files (`uv run python tests/golden_compliance.py --write`) and the diff shows which answers moved.

{mcp_server_taxcode-1.1.0 → mcp_server_taxcode-1.3.0}/Dockerfile

@@ -34,8 +34,8 @@ WORKDIR /app
 RUN python -m venv /opt/venv
 ENV PATH="/opt/venv/bin:$PATH"
 
-COPY docker/pip-bootstrap.txt /tmp/pip-bootstrap.txt
-COPY pyproject.toml README.md LICENSE ./
+COPY docker/pip-bootstrap.txt docker/uv-bootstrap.txt docker/build-backend.txt /tmp/
+COPY pyproject.toml uv.lock README.md LICENSE ./
 COPY src/ src/
 
 # The build context has no .git, so uv-dynamic-versioning cannot read the tag and
@@ -45,13 +45,34 @@ ARG UV_DYNAMIC_VERSIONING_BYPASS
 ENV UV_DYNAMIC_VERSIONING_BYPASS=${UV_DYNAMIC_VERSIONING_BYPASS}
 
 # pip 26.2.2 updates the certificates pip bundles, per FastMCP's October 2026 certificate
-# authority incident notice. This image builds with pip, not uv, so pip carries the floor.
+# authority incident notice. This image installs with pip, not uv, so pip carries the floor.
 # https://github.com/PrefectHQ/fastmcp/blob/main/SECURITY.md#certificate-authority-incident-october-2026
 # The bootstrap installs pip from a hash-pinned wheel (docker/pip-bootstrap.txt, --require-hashes),
 # so it does not depend on the TLS trust of the base image's older pip and certifi; the maintainer
 # who raises the pip floor updates that pin and its sha256 (Dependabot does not track the file).
+#
+# Runtime dependencies come from uv.lock, so the image runs the versions CI tests. uv, hash-pinned
+# in docker/uv-bootstrap.txt and installed to /tmp/uv outside the venv (the runtime image gets no
+# uv), only exports the lock: the base dependencies, with no extras and not the project, as a
+# requirements file with a hash for every package. --locked fails the build if uv.lock is out of
+# date with pyproject.toml. pip installs that file in hash-checking mode. The project build backend
+# (hatchling, uv-dynamic-versioning, and their transitive deps) is hash-pinned in
+# docker/build-backend.txt and installed with --require-hashes --only-binary=:all: to
+# /tmp/build-backend, outside the venv, and is on PYTHONPATH only for
+# `pip install --no-deps --no-build-isolation .`. The runtime image copies only the venv, so it
+# gets the project and its runtime dependencies but no build backend. Neither runtime nor build
+# dependencies are resolved from PyPI by version range at build time.
+# https://docs.astral.sh/uv/concepts/projects/export/ and
+# https://pip.pypa.io/en/stable/topics/secure-installs/
+# https://pip.pypa.io/en/stable/cli/pip_install/ (--no-build-isolation, --require-hashes)
 RUN pip install --no-cache-dir --require-hashes --only-binary=:all: -r /tmp/pip-bootstrap.txt && \
-    pip install --no-cache-dir .
+    pip install --no-cache-dir --require-hashes --only-binary=:all: --target /tmp/uv -r /tmp/uv-bootstrap.txt && \
+    /tmp/uv/bin/uv export --locked --no-dev --no-emit-project --format requirements.txt \
+        -o /tmp/requirements.txt && \
+    pip install --no-cache-dir --require-hashes --only-binary=:all: -r /tmp/requirements.txt && \
+    pip install --no-cache-dir --require-hashes --only-binary=:all: --target /tmp/build-backend \
+        -r /tmp/build-backend.txt && \
+    PYTHONPATH=/tmp/build-backend pip install --no-cache-dir --no-deps --no-build-isolation .
 
 # ─── Stage 2: Runtime ─────────────────────────────────────────────────────────
 FROM python:3.14-slim@sha256:fbecd461fc72d21b2143c6eaba25143738079154a6d0ea3da3aec724f50eed4a AS runtime

{mcp_server_taxcode-1.1.0 → mcp_server_taxcode-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mcp-server-taxcode
-Version: 1.1.0
+Version: 1.3.0
 Summary: Enterprise Model Context Protocol (MCP) server for Tax Code
 Project-URL: Homepage, https://github.com/christianclaudio/mcp-server-taxcode
 Project-URL: Documentation, https://github.com/christianclaudio/mcp-server-taxcode#readme
@@ -16,24 +16,23 @@ Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Python: >=3.10
+Requires-Python: >=3.11
 Requires-Dist: certifi>=2026.10.19
 Requires-Dist: duckdb>=1.5.6
-Requires-Dist: fastmcp>=4.1.3
+Requires-Dist: fastmcp>=4.1.5
 Requires-Dist: httpx>=0.28.1
 Requires-Dist: mcp>=2.3.0
 Requires-Dist: pydantic-settings>=2.15.0
 Requires-Dist: pydantic>=2.13.5
 Provides-Extra: code-mode
-Requires-Dist: fastmcp[code-mode]>=4.1.3; extra == 'code-mode'
+Requires-Dist: fastmcp[code-mode]>=4.1.5; extra == 'code-mode'
 Provides-Extra: dev
-Requires-Dist: fastmcp[code-mode]>=4.1.3; extra == 'dev'
+Requires-Dist: fastmcp[code-mode]>=4.1.5; extra == 'dev'
 Requires-Dist: mypy>=2.4.0; extra == 'dev'
 Requires-Dist: opentelemetry-sdk>=1.45.1; extra == 'dev'
 Requires-Dist: pytest-asyncio>=1.4.0; extra == 'dev'
@@ -70,9 +69,9 @@ graph TD
     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}"]
+    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)"]
+    DuckDB["DuckDB In-Memory & File Engine<br>(235 Statutes, 42 Publications, Full-Text Search, Temporal Versions)"]
 
     Client <-->|"JSON-RPC (tools/list, tools/call)"| Gateway
     Gateway --> ParentMW
@@ -91,14 +90,15 @@ graph TD
   * **Federal (`US`)**: IRC § 1, § 24, § 32, § 61, § 62, § 63, § 865, § 911, § 933, § 937, § 957, § 1411, § 6012, § 6688, 26 CFR § 1.937-1/2/3, and IRS publications (Pub. 17, Pub. 54, Pub. 501, Pub. 505, Pub. 570, Pub. 1321).
   * **Puerto Rico (`PR`)**: Act 60-2019 (Resident Individual Investors, Export Services & Opportunity Zone definitions, Sec. 6020.10 annual reports), Ley 1-2011 (including Sec. 1031.02 exemptions and Sec. 1062.01 wage withholding and Sec. 1062.03 withholding on payments for services), Act 22-2012 predecessor versions, and administrative publications (CC RI 21-10, CC RI 25-12, CC RI 26-13, DA 21-04, DA 23-04, BI RI 26-02).
   * **All 50 US States + District of Columbia**: Comprehensive statutory definitions and tax computations covering no-income-tax states (AK, FL, NV, NH, SD, TN, TX, WA, WY), flat-tax regimes (AZ, CO, GA, ID, IL, IN, IA, KS, KY, MI, MS, NC, PA, UT), and graduated/surtax jurisdictions (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) including Convenience of the Employer rules (NY, PA, NJ, CT, DE, NE) and local piggyback taxes (MD, IN, OH, NY).
+  * **Canada federal (`CAN`)**: Income Tax Act ss. 2, 38, 114, 115, 117, 117.1, 118, 128.1, 153, 212 and 250 and Income Tax Regulations ss. 100, 102, 103, 105, 202, 805, 2600 and 2601, in the official English and French text of the Justice Canada consolidation (pinned laws-lois-xml commits; prior-year versions of ss. 117 and 118 from 2019), with unofficial Spanish summaries, plus CRA guidance (Folio S5-F1-C1, Forms T1161, T1243 and T1244, Leaving Canada). `statutes_lookup_statute` and `statutes_search_tax_code` take `lang="fr"`. `CA` stays California.
 * **Snippet Search, Full Text by Id**: `statutes_search_tax_code` matches and ranks on the full text but returns a short snippet (up to 300 characters around the first matched term) plus each result's `id`, citation, title, jurisdiction, year, validity and content labels. Pass an `id` to `statutes_lookup_statute` as `citation_or_section` for the full text.
-* **Bounded Responses with Paging**: Every statutes tool result stays under 32,000 characters of JSON. `statutes_lookup_statute` returns long text in pages of up to 8,000 characters per text field (`text_page` gives the offset and full lengths; pass `next_cursor` back as `page_cursor` for the next page). `statutes_search_tax_code` and `statutes_list_publications` clamp `limit` to 1..25 items per call, with `offset` and `next_offset` for the next page. The `taxcode://statutes/{jurisdiction}/{section}` resource (for example `taxcode://statutes/US/933`) uses the same 8,000-character pages and cap: a page that is not the last ends with the URI of the next one, which carries a `?page_cursor=` query.
+* **Bounded Responses with Paging**: Every statutes tool result stays under 32,000 characters of JSON. `statutes_lookup_statute` returns long text in pages of up to 8,000 characters per text field (`text_page` gives the offset and full lengths; pass `next_cursor` back as `page_cursor` for the next page). `statutes_search_tax_code` and `statutes_list_publications` clamp `limit` to 1..25 items per call, with `offset` and `next_offset` for the next page. The `taxcode://statutes/{jurisdiction}/{section*}` resource (for example `taxcode://statutes/US/933`, or `taxcode://statutes/IL/5/201` for a section id that contains `/`) uses the same 8,000-character pages and cap: a page that is not the last ends with the URI of the next one, which carries a `?page_cursor=` query. The `{section*}` wildcard matches multi-segment section ids; a percent-encoded form such as `5%2F201` also works.
 * **Versioned Data Files**: Every statute and publication row lives in per-jurisdiction JSON under `src/taxcode_mcp/data/` with a source record per row, and the docs under `docs/` are generated from them (see [`CONTRIBUTING.md`](CONTRIBUTING.md)).
 * **Temporal Statutory Versioning**: Point-in-time statutory lookup with `superseded_year` filtering and descending historical ordering (`tax_year` parameter).
 * **Deterministic Compliance Engines**:
   * `evaluate_pr_bona_fide_residency`: Evaluates IRC § 937 presence (183-day, 549-day 3-year, 90-day US), tax home, and closer connection tests.
   * `calculate_built_in_gain_sourcing`: Allocates Section 937 / Act 60 capital gains across pre-move and post-move holding periods.
-  * `evaluate_state_residency`: Multi-state statutory presence day-counter, permanent place of abode (PPA), domicile audit risk flags, and tax liability computation across all 50 US states and District of Columbia (51 jurisdictions total).
+  * `evaluate_state_residency`: Multi-state statutory presence day-counter, permanent place of abode (PPA), domicile audit risk flags, and tax liability computation across all 50 US states and District of Columbia (51 jurisdictions total). Optional `dependents`, Mississippi `spouse_agi` (MFJ combined returns; even split of the filing-status exemption and standard deduction; ignored for other states), and Utah `itemized_deductions` (federal itemized deductions excluding state income tax) refine KS/MS/OH/GA/UT liability; defaults keep prior results. `jurisdiction="CAN"` (or `"Canada"`) evaluates Canada federal residency (factual, 183-day sojourner, part-year emigrant, non-resident) and estimates federal Part I tax for 2019-2026; `event="emigration"` with `emigration_properties` adds the ITA s. 128.1 departure tax estimate and the T1161 reporting test.
 * **Profiles & Opt-in ToolSearch**:
   * Domain-mount profiles: `full`, `system`, `statutes`, `compliance`, `readonly`.
   * Job-shaped allowlist profiles: `researcher` (statutes + circulars), `advisor` (cross-border residency + BIG calculations).

{mcp_server_taxcode-1.1.0 → mcp_server_taxcode-1.3.0}/README.md

@@ -25,9 +25,9 @@ graph TD
     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}"]
+    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)"]
+    DuckDB["DuckDB In-Memory & File Engine<br>(235 Statutes, 42 Publications, Full-Text Search, Temporal Versions)"]
 
     Client <-->|"JSON-RPC (tools/list, tools/call)"| Gateway
     Gateway --> ParentMW
@@ -46,14 +46,15 @@ graph TD
   * **Federal (`US`)**: IRC § 1, § 24, § 32, § 61, § 62, § 63, § 865, § 911, § 933, § 937, § 957, § 1411, § 6012, § 6688, 26 CFR § 1.937-1/2/3, and IRS publications (Pub. 17, Pub. 54, Pub. 501, Pub. 505, Pub. 570, Pub. 1321).
   * **Puerto Rico (`PR`)**: Act 60-2019 (Resident Individual Investors, Export Services & Opportunity Zone definitions, Sec. 6020.10 annual reports), Ley 1-2011 (including Sec. 1031.02 exemptions and Sec. 1062.01 wage withholding and Sec. 1062.03 withholding on payments for services), Act 22-2012 predecessor versions, and administrative publications (CC RI 21-10, CC RI 25-12, CC RI 26-13, DA 21-04, DA 23-04, BI RI 26-02).
   * **All 50 US States + District of Columbia**: Comprehensive statutory definitions and tax computations covering no-income-tax states (AK, FL, NV, NH, SD, TN, TX, WA, WY), flat-tax regimes (AZ, CO, GA, ID, IL, IN, IA, KS, KY, MI, MS, NC, PA, UT), and graduated/surtax jurisdictions (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) including Convenience of the Employer rules (NY, PA, NJ, CT, DE, NE) and local piggyback taxes (MD, IN, OH, NY).
+  * **Canada federal (`CAN`)**: Income Tax Act ss. 2, 38, 114, 115, 117, 117.1, 118, 128.1, 153, 212 and 250 and Income Tax Regulations ss. 100, 102, 103, 105, 202, 805, 2600 and 2601, in the official English and French text of the Justice Canada consolidation (pinned laws-lois-xml commits; prior-year versions of ss. 117 and 118 from 2019), with unofficial Spanish summaries, plus CRA guidance (Folio S5-F1-C1, Forms T1161, T1243 and T1244, Leaving Canada). `statutes_lookup_statute` and `statutes_search_tax_code` take `lang="fr"`. `CA` stays California.
 * **Snippet Search, Full Text by Id**: `statutes_search_tax_code` matches and ranks on the full text but returns a short snippet (up to 300 characters around the first matched term) plus each result's `id`, citation, title, jurisdiction, year, validity and content labels. Pass an `id` to `statutes_lookup_statute` as `citation_or_section` for the full text.
-* **Bounded Responses with Paging**: Every statutes tool result stays under 32,000 characters of JSON. `statutes_lookup_statute` returns long text in pages of up to 8,000 characters per text field (`text_page` gives the offset and full lengths; pass `next_cursor` back as `page_cursor` for the next page). `statutes_search_tax_code` and `statutes_list_publications` clamp `limit` to 1..25 items per call, with `offset` and `next_offset` for the next page. The `taxcode://statutes/{jurisdiction}/{section}` resource (for example `taxcode://statutes/US/933`) uses the same 8,000-character pages and cap: a page that is not the last ends with the URI of the next one, which carries a `?page_cursor=` query.
+* **Bounded Responses with Paging**: Every statutes tool result stays under 32,000 characters of JSON. `statutes_lookup_statute` returns long text in pages of up to 8,000 characters per text field (`text_page` gives the offset and full lengths; pass `next_cursor` back as `page_cursor` for the next page). `statutes_search_tax_code` and `statutes_list_publications` clamp `limit` to 1..25 items per call, with `offset` and `next_offset` for the next page. The `taxcode://statutes/{jurisdiction}/{section*}` resource (for example `taxcode://statutes/US/933`, or `taxcode://statutes/IL/5/201` for a section id that contains `/`) uses the same 8,000-character pages and cap: a page that is not the last ends with the URI of the next one, which carries a `?page_cursor=` query. The `{section*}` wildcard matches multi-segment section ids; a percent-encoded form such as `5%2F201` also works.
 * **Versioned Data Files**: Every statute and publication row lives in per-jurisdiction JSON under `src/taxcode_mcp/data/` with a source record per row, and the docs under `docs/` are generated from them (see [`CONTRIBUTING.md`](CONTRIBUTING.md)).
 * **Temporal Statutory Versioning**: Point-in-time statutory lookup with `superseded_year` filtering and descending historical ordering (`tax_year` parameter).
 * **Deterministic Compliance Engines**:
   * `evaluate_pr_bona_fide_residency`: Evaluates IRC § 937 presence (183-day, 549-day 3-year, 90-day US), tax home, and closer connection tests.
   * `calculate_built_in_gain_sourcing`: Allocates Section 937 / Act 60 capital gains across pre-move and post-move holding periods.
-  * `evaluate_state_residency`: Multi-state statutory presence day-counter, permanent place of abode (PPA), domicile audit risk flags, and tax liability computation across all 50 US states and District of Columbia (51 jurisdictions total).
+  * `evaluate_state_residency`: Multi-state statutory presence day-counter, permanent place of abode (PPA), domicile audit risk flags, and tax liability computation across all 50 US states and District of Columbia (51 jurisdictions total). Optional `dependents`, Mississippi `spouse_agi` (MFJ combined returns; even split of the filing-status exemption and standard deduction; ignored for other states), and Utah `itemized_deductions` (federal itemized deductions excluding state income tax) refine KS/MS/OH/GA/UT liability; defaults keep prior results. `jurisdiction="CAN"` (or `"Canada"`) evaluates Canada federal residency (factual, 183-day sojourner, part-year emigrant, non-resident) and estimates federal Part I tax for 2019-2026; `event="emigration"` with `emigration_properties` adds the ITA s. 128.1 departure tax estimate and the T1161 reporting test.
 * **Profiles & Opt-in ToolSearch**:
   * Domain-mount profiles: `full`, `system`, `statutes`, `compliance`, `readonly`.
   * Job-shaped allowlist profiles: `researcher` (statutes + circulars), `advisor` (cross-border residency + BIG calculations).