---
url: /houki-hub/mcp/houki-nta.md
description: 国税庁サイトの基本通達・改正通達・事務運営指針・文書回答事例・タックスアンサー・質疑応答事例を取得・全文検索する MCP サーバー
---

# houki-nta-mcp

国税庁（NTA）公式サイトの **基本通達・改正通達・事務運営指針・文書回答事例・タックスアンサー・質疑応答事例** を
ローカル SQLite に取り込み、FTS5 で全文検索する MCP サーバーです。
法律本文（法・政令・省令）は [houki-egov-mcp](/mcp/houki-egov) が担当します。

* npm: [`@shuji-bonji/houki-nta-mcp`](https://www.npmjs.com/package/@shuji-bonji/houki-nta-mcp)（0.27.1）
* リポジトリ: [shuji-bonji/houki-nta-mcp](https://github.com/shuji-bonji/houki-nta-mcp)
* 動作環境: Node.js 22 以上

## 扱うコンテンツ

| コンテンツ | 内容 | `legal_status` |
| --- | --- | --- |
| 基本通達 4 種 | 消費税法基本通達・所得税基本通達・法人税基本通達・相続税法基本通達 | 税務職員を拘束する行政内部の解釈指針。国民・裁判所は拘束しない |
| 改正通達 | 各年の改正通達と添付 PDF（新旧対照表など） | 同上 |
| 事務運営指針 | 税務執行の運営方針 | 同上 |
| 文書回答事例 | 事前照会に対する国税庁・国税局の回答 | 個別の事案への回答。一般的な法的拘束力はない |
| タックスアンサー | 一般向けの税務 Q\&A | 参考情報 |
| 質疑応答事例 | 国税庁が公表する解釈事例 | 参考情報 |

すべての応答に `legal_status` が付きます。通達に書いてあることを「法律で決まっている」と言い換えないためです。
通達と解説資料がほかの種類の文書（法律・政令・裁決・判例など）と比べて誰を拘束するかは、[文書の種類と拘束力](/guide/document-types) にまとめています。

## 基本通達と、解釈の対象になる法律

通達は国民と裁判所を拘束しないので、根拠は法律の条文で確かめる必要があります。
基本通達 4 種が解釈している法律と、その政令・省令は次のとおりです。いずれも [houki-egov-mcp](/mcp/houki-egov) の `get_law` に `law_name` として渡すと本文を引けます（2026-09-11 に `search_law` で 12 件とも見つかることを確認）。

| 基本通達 | 法律 | 政令 | 省令 |
| --- | --- | --- | --- |
| 消費税法基本通達 | 消費税法 | 消費税法施行令 | 消費税法施行規則 |
| 所得税基本通達 | 所得税法 | 所得税法施行令 | 所得税法施行規則 |
| 法人税基本通達 | 法人税法 | 法人税法施行令 | 法人税法施行規則 |
| 相続税法基本通達 | 相続税法 | 相続税法施行令 | 相続税法施行規則 |

v0.11.0 から、この対応が応答に入ります（[houki-nta-mcp#20](https://github.com/shuji-bonji/houki-nta-mcp/issues/20)）。

| ツール | 付くフィールド | 中身 |
| --- | --- | --- |
| `nta_get_tsutatsu` | `base_laws` | その通達の法律・政令・省令の配列。Markdown 応答では出典の後に「解釈の対象になる法律: …」の行が入ります |
| `nta_search_tsutatsu` | `base_laws_by_tsutatsu` | 検索結果に現れた通達ごとの対応表。対応は通達単位なので、hit ごとではなく応答に 1 回だけ置きます |

どちらの応答にも `next_actions` が付き、`example` に houki-egov-mcp の `get_law` に渡す法律名が入っています。検索では通達ごとに 1 件です。
通達の項と法律の条の対応は一律ではないため、応答にもこの表にも条番号は入りません。通達の本文にある「法第57条の2第4項」のような参照を読んで、`get_law` の `article` を指定してください。

## ツール

引数の詳細と実測の呼び出し例はツールのページに、ツールが何をし、何を扱わないかは仕様書ページにあります。一覧は[ツールリファレンス](/reference/mcp/houki-nta/)にもあります。

| ツールのページ | 一言 | 仕様書ページ |
| --- | --- | --- |
| [`nta_search_tsutatsu`](/reference/mcp/houki-nta/nta_search_tsutatsu) | 基本通達を全文検索します | [仕様](/specs/houki-nta/nta_search_tsutatsu) |
| [`nta_get_tsutatsu`](/reference/mcp/houki-nta/nta_get_tsutatsu) | 基本通達の本文を取得します | [仕様](/specs/houki-nta/nta_get_tsutatsu) |
| [`nta_search_kaisei_tsutatsu`](/reference/mcp/houki-nta/nta_search_kaisei_tsutatsu) | 改正通達を検索します | [仕様](/specs/houki-nta/nta_search_kaisei_tsutatsu) |
| [`nta_get_kaisei_tsutatsu`](/reference/mcp/houki-nta/nta_get_kaisei_tsutatsu) | 改正通達を取得します。添付 PDF は種別（新旧対照表・別紙・Q\&A など）に分類して表で返します | [仕様](/specs/houki-nta/nta_get_kaisei_tsutatsu) |
| [`nta_search_jimu_unei`](/reference/mcp/houki-nta/nta_search_jimu_unei) | 事務運営指針を検索します | [仕様](/specs/houki-nta/nta_search_jimu_unei) |
| [`nta_get_jimu_unei`](/reference/mcp/houki-nta/nta_get_jimu_unei) | 事務運営指針を取得します | [仕様](/specs/houki-nta/nta_get_jimu_unei) |
| [`nta_search_bunshokaitou`](/reference/mcp/houki-nta/nta_search_bunshokaitou) | 文書回答事例を検索します | [仕様](/specs/houki-nta/nta_search_bunshokaitou) |
| [`nta_get_bunshokaitou`](/reference/mcp/houki-nta/nta_get_bunshokaitou) | 文書回答事例を取得します | [仕様](/specs/houki-nta/nta_get_bunshokaitou) |
| [`nta_search_tax_answer`](/reference/mcp/houki-nta/nta_search_tax_answer) | タックスアンサーを検索します | [仕様](/specs/houki-nta/nta_search_tax_answer) |
| [`nta_get_tax_answer`](/reference/mcp/houki-nta/nta_get_tax_answer) | タックスアンサーを取得します | [仕様](/specs/houki-nta/nta_get_tax_answer) |
| [`nta_search_qa`](/reference/mcp/houki-nta/nta_search_qa) | 質疑応答事例を検索します | [仕様](/specs/houki-nta/nta_search_qa) |
| [`nta_get_qa`](/reference/mcp/houki-nta/nta_get_qa) | 質疑応答事例を取得します | [仕様](/specs/houki-nta/nta_get_qa) |
| [`nta_inspect_pdf_meta`](/reference/mcp/houki-nta/nta_inspect_pdf_meta) | 文書に添付された PDF の一覧に、種別と読み方（表として取る / 本文として読む / 先頭を見て決める、紙面の組み方）を付けて返します。`save: true` で PDF を保存して絶対パスを返し、`next_actions` に pdf-reader-mcp の呼び出し例と、他の PDF 読み取りツール向けの 1 件を置きます。本文は読みません（v0.19.0） | [仕様](/specs/houki-nta/nta_inspect_pdf_meta) |
| [`resolve_abbreviation`](/reference/mcp/houki-nta/resolve_abbreviation) | 略称の解決を診断します | [仕様](/specs/houki-nta/resolve_abbreviation) |

検索ツールは `hasPdf` で PDF 付きの文書だけに絞れ、応答に `freshness`（取り込みからの経過）が付きます。`nta_search_qa` は `topic`（`shotoku`・`shohi` などの税目）で絞り込めます（v0.13.0 から）。

引数は `tools/list` の inputSchema どおりに渡してください。v0.14.0 から、inputSchema に無い引数は `INVALID_ARGUMENT` になります。`nta_search_tsutatsu` の `type` と `domain` は、絞り込みに使われていなかったので v0.14.0 で削除しました。

文書回答事例の `taxonomy` は URL の税目フォルダ名です。国税局のページは本庁と違う名前を使うことがある（相続税は `sozoku` と `souzoku`、源泉所得税は `gensen` と `gensenshotoku`、譲渡所得・山林所得は `joto-sanrin` と `joto_sanrin`）ため、v0.14.0 からはどちらを指定しても両方を検索します。

キーワードが略称辞書に載っている場合の扱いは次のとおりです（v0.11.1 から）。

| キーワード | 例 | 検索のしかた |
| --- | --- | --- |
| 略称そのもの | 「消基通」「消法」 | 元の語と正式名（消費税法基本通達・消費税法）の両方で検索します |
| 通称 | 「インボイス」「軽減税率」「適格請求書発行事業者」 | 元の語で検索し、0 件のときだけ正式名（消費税法）で検索し直します。そのときは `search_notes` にその旨が入ります |

通称で常に正式名まで広げると、「消費税法」という語が出てくるだけの文書が混ざり、キーワードを含む文書が `limit` から押し出されるためです（[houki-nta-mcp#21](https://github.com/shuji-bonji/houki-nta-mcp/issues/21)）。

## 質疑応答事例の関係法令通達

質疑応答事例は国税庁の参考資料で、誰も拘束しません。回答の根拠は、各ページの【関係法令通達】に挙がっている法律と通達で確かめます。
v0.12.0 から、`nta_get_qa` を `format: "json"` で呼ぶと、この欄を法令と通達に分けて返します（[houki-nta-mcp#22](https://github.com/shuji-bonji/houki-nta-mcp/issues/22)）。

| フィールド | 中身 |
| --- | --- |
| `related_laws` | 法令の参照。`law_name`・`article`・`paragraph`・`item`（別表の場合は `appendix`）と、原文の `raw` |
| `related_tsutatsu` | 通達の参照。`name`・`clause` と、原文の `raw` |
| `next_actions` | houki-egov-mcp の `get_law` と `nta_get_tsutatsu` に渡す引数の例 |
| `notice` / `basisDate` | ページ下部の国税庁の注記と、その基準日（例: `2025-08-01`） |

「所得税法第27条、第34条、第37条」のように法令名を省いて続く条番号は、直前の法令名を補って読みます。枝番号の号（「法人税法第2条第12号の8」）は、v0.14.0 から `item: "12の8"` の文字列で入り、`next_actions` の `get_law` にも渡ります（houki-egov-mcp v0.6.0 以上が必要です）。【関係法令通達】の原文は、これまでどおり `relatedLaws` に残ります。

次の参照は `related_laws` や `related_tsutatsu` には入りますが、`next_actions` は付きません。

| 参照 | 理由 |
| --- | --- |
| 租税条約 | e-Gov の法令 API では引けないため |
| 「旧」「改正前」の付いた条文 | どの時点の条文かが応答から決まらず、`get_law` の `at` に渡す日付を示せないため |
| 条番号の無い法令 | `get_law` に渡す条を決められないため |
| 基本通達 4 種以外の通達（租税特別措置法関係通達など） | `nta_get_tsutatsu` が扱わないため |

v0.12.0 で取り込んだ 1,834 件の【関係法令通達】を区切ると 5,059 個の参照になり、そのうち 94.2% を法令か通達として読み取れました。読み取れなかった参照は、`relatedLaws` の原文にだけ残ります。

::: info v0.11.1 までに作った DB
ページ下部の注記は、v0.11.1 までは【関係法令通達】（その欄が無いページでは【回答要旨】）に混ざっていました。v0.11.1 までに作ったローカル DB では、「異なる課税関係が生ずる」のような注記の文言で、ほぼ全件の質疑応答事例がヒットします。`houki-nta-mcp --bulk-download-qa --refresh` で取り込み直してください。取り込み直すとほぼ全件の本文が変わるため、最後に「構造変質の疑い」の警告が出ますが、解析方法を変えたためで、国税庁のページが変わったわけではありません。
:::

## 検索が 0 件のとき

文書系の検索 5 ツール（`nta_search_qa`・`nta_search_tax_answer`・`nta_search_kaisei_tsutatsu`・`nta_search_jimu_unei`・`nta_search_bunshokaitou`）は、0 件になった理由を分けて返します（v0.13.0 から。[houki-nta-mcp#23](https://github.com/shuji-bonji/houki-nta-mcp/issues/23)）。

| DB の状態 | 応答 |
| --- | --- |
| その種別の文書が DB に 1 件も無い | エラー `DOC_NOT_FOUND`。「該当なし」という検索結果ではないことを示します。`hint` に MCP サーバーが開いている DB ファイルのパスと投入コマンドが入ります |
| 税目の絞り込みの範囲に文書が無い | `results: []`。`available_taxonomies` に、DB にある税目の一覧が入ります |
| `hasPdf` の条件に合う文書が無い | `results: []`。`hasPdf` を外すよう案内します |
| 文書はあるが、キーワードに合わない | `results: []`。`hint` に「該当なし」と検索した件数（例: 「DB の質疑応答事例 1,841 件に」）が入ります |

LLM が `results: []` を受け取ったときは「国税庁の資料にこの語を含む文書は無い」と読めますが、`DOC_NOT_FOUND` のときは検索そのものができていないので、そう答えてはいけません。
その種別を投入していない、`--bulk-download-everything` の途中でその種別だけ失敗した、bulk download を実行したシェルと MCP サーバーとで環境変数 `HOUKI_NTA_DB_PATH` / `XDG_CACHE_HOME` が違う、のいずれかです。

v0.12.0 までは、どの場合も「DB 投入済みか確認してください」という同じ `hint` だったため、文書が入っている DB でも投入をやり直すよう案内していました。
また、v0.12.0 までの `nta_search_qa` は `domain` を指定すると必ず 0 件でした。v0.13.0 からは `domain: "tax"` は絞り込まずに検索し、税目で絞るときは `topic` を使います。

## docId が見つからないとき

取得系の 3 ツール（`nta_get_kaisei_tsutatsu`・`nta_get_jimu_unei`・`nta_get_bunshokaitou`）は DB だけを見ます。指定された docId が DB に無いとき、理由を 2 つに分けて返します（v0.14.1 から）。

| DB の状態 | 応答 |
| --- | --- |
| その種別の文書が DB に 1 件も無い | 「ローカル DB に◯◯が 1 件も無いため、docId=… を取得できません」。`hint` に DB ファイルのパスと環境変数、`next_actions` に投入コマンド（`action` は `cli_bulk_download`） |
| 文書はあるが、その docId が無い | 「◯◯ docId=… は見つかりません」。`available_doc_ids`（新しい順に 30 件。`docId`・`title`・`issuedAt`）と、検索ツールへの `next_actions` |

v0.14.0 までは、どちらの場合も「DB に未投入です」と返して投入コマンドを案内していたため、docId を打ち間違えただけの利用者にも投入をやり直すよう勧めていました。検索が 0 件のときの分け方（上の節）と同じ考え方です。

LLM は `next_actions[0].action` を見て、`cli_bulk_download` なら投入を案内し、検索ツール（`nta_search_*`）なら `available_doc_ids` から選ぶか検索して docId を探し直します。

## ローカル DB

国税庁は、通達や質疑応答事例を機械可読な形で配布していません。公開されているのは HTML のページだけです。
houki-nta-mcp のローカル DB は、そのページを 1 件ずつ取得し、章・節・条や文書の単位に構造化して保存したものです。
この DB が、国税庁の資料を構造化した唯一の形です。[houki-egov-mcp](/mcp/houki-egov) と違い、その場で呼べる API はありません。

### 早見表

| 項目 | 内容 |
| --- | --- |
| 取得元 | 国税庁サイトの HTML ページを 1 ページずつ。機械可読な配布データはありません |
| DB ファイル | `${XDG_CACHE_HOME:-~/.cache}/houki-nta-mcp/cache.db`（`--db-path=<path>` か `HOUKI_NTA_DB_PATH` で変えられます） |
| テーブル | 基本通達は `tsutatsu` `chapter` `section` `clause`、ほかの 5 種別は `document`。全文検索の索引は `clause_fts` `document_fts`（FTS5 trigram） |
| 鮮度の持ち方 | 行ごとの `fetched_at`。応答の `freshness` は、その検索が見た範囲の最古・最新と経過日数です |
| 更新の粒度 | 節（基本通達）と文書（ほかの 5 種別）ごと。再実行では条件付き GET を使い、変わっていないページは取得しません |
| DB が要るツール | 14 のうち 9（検索 6 つと、改正通達・事務運営指針・文書回答事例の取得 3 つ）。`nta_get_tsutatsu` `nta_get_qa` `nta_get_tax_answer` は DB が無くても動きます |
| 版が上がったとき | 起動時に自動で移行します。国税庁サイトへの再アクセスはありません（v0.15.0・v0.16.0・v0.17.0 の 3 回） |

各項目の詳細は以下の各節にあります。

### ローカル DB を作っていないとき

検索はできません。取得は 6 つとも DB を先に引きますが、DB に無かったときの動きが 2 通りに分かれます。

| ツール | ローカル DB を作っていないとき |
| --- | --- |
| `nta_search_tsutatsu` `nta_search_qa` `nta_search_tax_answer` `nta_search_bunshokaitou` `nta_search_jimu_unei` `nta_search_kaisei_tsutatsu` | その種別が DB に 1 件も無ければエラー `DOC_NOT_FOUND` を返します。「該当なし」ではありません |
| `nta_get_tsutatsu` `nta_get_qa` `nta_get_tax_answer` | 国税庁サイトから取得して DB に書き戻します。応答の `source` が `"db"` か `"live"` かで、どちらから返したか分かります |
| `nta_get_kaisei_tsutatsu` `nta_get_jimu_unei` `nta_get_bunshokaitou` `nta_inspect_pdf_meta` | `DOC_NOT_FOUND` を返し、投入するコマンドを案内します（`nta_inspect_pdf_meta` は添付 PDF の一覧を DB の文書から読むため） |
| `resolve_abbreviation` | DB を使いません |

```mermaid
flowchart TB
  L["LLM"]
  S["検索<br/>6 ツール"]
  G1["通達・質疑応答事例・<br/>タックスアンサーの取得"]
  G2["改正通達・事務運営指針・<br/>文書回答事例の取得など"]
  DB[("cache.db")]
  SITE[("国税庁<br/>サイト")]
  E["DOC_NOT_FOUND<br/>投入コマンドの案内"]
  L --> S & G1 & G2
  S & G1 & G2 --> DB
  G1 -->|DB に<br/>無いとき| SITE
  SITE -->|書き戻す| DB
  S -->|種別が<br/>0 件| E
  G2 -->|DB に<br/>無いとき| E
```

改正通達・事務運営指針・文書回答事例の 3 つが国税庁サイトへ取りに行かないのは、docId から個別ページの URL を組み立てるのに税目フォルダの世代差（`sozoku` と `sozoku2` など）を解く必要があるためです。

v0.15.0 までは、`nta_get_qa` と `nta_get_tax_answer` が DB を引かずに毎回国税庁サイトから取得していました。v0.16.0 で `nta_get_tsutatsu` と同じ形に揃えています（[houki-nta-mcp #29](https://github.com/shuji-bonji/houki-nta-mcp/issues/29)）。

::: info v0.15.0 以前に作った DB のとき
質疑応答事例とタックスアンサーを DB から返すには、本文だけでなく段落や節の構造も保存しておく必要があります。この保存は v0.16.0 から始まったので、それ以前に作った DB では最初の 1 回だけ国税庁サイトから取得し、その結果を DB に入れます。2 回目からは DB から返ります。`--bulk-download-qa` と `--bulk-download-tax-answer` を回しても埋まります。
:::

### 作り方

DB を作る・最新にする・作り直す流れは次のとおりです。各コマンドの説明はこの後に続きます。

```mermaid
flowchart TB
  S(["初めて使う"]) --> Q["--quickstart<br/>通達 1 本・約 3〜5 分"]
  S --> ALL["--bulk-download-everything<br/>6 種別・約 100 分"]
  Q --> DB[("cache.db")]
  ALL --> DB
  DB --> R1["--refresh-stale=N<br/>古いものを一覧"]
  R1 --> R2["--refresh-stale=N --apply<br/>古いものを取り直す"]
  R2 --> DB
  DB --> RF["--bulk-download-everything<br/>--refresh で全部取り直す"]
  RF --> DB
  V(["パッケージを<br/>上げる"]) -->|起動時に移行| DB
```

初めて入れたときは、通達 1 本だけを入れて動くことを確かめてください（v0.18.0）。

```sh
npx -y @shuji-bonji/houki-nta-mcp@latest --quickstart
```

消費税法基本通達 1 本を約 3〜5 分で取り込みます。終わると、その通達に対して `nta_search_tsutatsu` と `nta_get_tsutatsu` が使えます。別の通達にしたいときは `--quickstart --tsutatsu=所得税基本通達` のように指定します。`--tsutatsu` に渡せるのは、基本通達 4 種（消費税法基本通達・所得税基本通達・法人税基本通達・相続税法基本通達）の正式名だけです。略称（`消基通` など）やほかの通達の名前を渡すと、取り込みを始めずに、使える値を表示してエラー（終了コード 2）で終わります（[SPEC-NTA-CLI-BULK-DOWNLOAD-011](/specs/houki-nta/cli_bulk_download#spec-nta-cli-bulk-download-011)）。

6 種別をまとめて取り込むときは次を実行します。国税庁サイトを 1 ページずつ取りに行くので約 100 分かかります。開始前に、種別ごとの件数と所要時間の目安を表示します。

```sh
npx -y @shuji-bonji/houki-nta-mcp@latest --bulk-download-everything
```

必要な種別だけを先に入れることもできます。所要時間は `--help` の記載です。`--help` は「まず試す → 種別を足す → 全部入り → 保守」の順に並んでいます。

| コマンド | 対象 | 目安 |
| --- | --- | --- |
| `--quickstart` | 通達 1 本（既定: 消基通。`--tsutatsu=<正式名>` で変更。基本通達 4 種だけ） | 約 3〜5 分 |
| `--bulk-download-everything` | 6 種別すべて。開始前に目安を表示 | 約 100 分 |
| `--bulk-download-all` | 基本通達 4 種（消基通・所基通・法基通・相基通） | 10〜15 分 |
| `--bulk-download` | `--tsutatsu=<正式名>` で指定した 1 つの通達（基本通達 4 種だけ） | — |
| `--bulk-download-kaisei` | 改正通達（基本通達 4 種分の一覧） | — |
| `--bulk-download-jimu-unei` | 事務運営指針 | — |
| `--bulk-download-bunshokaitou` | 文書回答事例 | 全税目で 30 分超 |
| `--bulk-download-tax-answer` | タックスアンサー 約 850 件 | 約 15 分 |
| `--bulk-download-qa` | 質疑応答事例 9 税目・2,000 件超 | — |

### 税目を絞って投入する

文書回答事例・タックスアンサー・質疑応答事例は件数が多いので、税目で絞ると短時間で終わります。渡せる値は次のとおりです。

| フラグ | 使える値 |
| --- | --- |
| `--bunsho-taxonomy`（文書回答事例） | `shotoku` / `gensen` / `joto-sanrin` / `sozoku` / `zoyo` / `hyoka` / `hojin` / `shohi` / `shozei` / `sonota`（国税局の表記 `souzoku` / `gensenshotoku` / `joto_sanrin` も可） |
| `--tax-answer-taxonomy`（タックスアンサー） | `shotoku` / `gensen` / `joto` / `sozoku` / `hojin` / `shohi` / `inshi` / `osirase` |
| `--qa-topic`（質疑応答事例） | `shotoku` / `gensen` / `joto` / `sozoku` / `hyoka` / `hojin` / `shohi` / `inshi` / `hotei` |

```sh
# 消費税と所得税の文書回答事例だけ
npx -y @shuji-bonji/houki-nta-mcp@latest --bulk-download-bunshokaitou --bunsho-taxonomy=shohi,shotoku

# 消費税のタックスアンサーだけ
npx -y @shuji-bonji/houki-nta-mcp@latest --bulk-download-tax-answer --tax-answer-taxonomy=shohi
```

v0.14.2 から、一覧に無い値を渡すと、何も投入せずに使える値を表示して終了します（終了コード 1）。`--help` にも同じ一覧が出ます。v0.14.1 までは値を見ていなかったため、税目を打ち間違えても 0 件のまま正常終了していました（[houki-nta-mcp#25](https://github.com/shuji-bonji/houki-nta-mcp/issues/25)）。

`--bunsho-taxonomy` の絞り込みは本庁の索引（`/law/bunshokaito/01.htm`）の節に対して行うので、`sozoku` と `souzoku` のどちらを渡しても同じ節の文書が入ります。その節には国税局のページへのリンクも並ぶため、DB には両方の表記が入ります。

### 元データが変わったときに何が起きるか

国税庁サイトのページは、書き換えられることも、索引から外れることもあります。
bulk download を実行し直すと、国税庁の索引と DB を突き合わせて、種別ごとに 4 つに分けて数えます。

```mermaid
flowchart TB
  N["国税庁サイトの索引"]
  P["ページを 1 件ずつ取得する"]
  DB[("cache.db<br/>tsutatsu / chapter / section / clause / document")]
  C{"索引と DB を突き合わせる"}
  A["新規: 索引にあって DB に無かった"]
  B["更新: content_hash が変わった"]
  D["索引から消えた: DB にあって索引に無い"]
  E["移動の推定: 消えたものと新規でタイトルが一致する"]
  R["索引から消えた文書は DB に残し、印を付ける"]

  N --> P
  P --> DB
  P --> C
  C --> A
  C --> B
  C --> D
  C --> E
  D --> R
  R --> DB
```

索引から消えた文書を削除しないのは、国税庁サイトから外れても、過去の課税期間の判断では意味を持つ通達があるためです。

消えた文書は印を付けて残し、検索と取得の応答で現行の文書と区別できます（v0.17.0）。詳しくは[国税庁の索引から消えた文書](#国税庁の索引から消えた文書)を参照してください。

「更新」が索引の件数の 50% を超えると、bulk download の最後に「構造変質の疑い」の警告が出ます。
国税庁がページの作りを一斉に変えたか、houki-nta-mcp の解析方法が変わったか、どちらかが起きたことを示します。
houki-nta-mcp 側で解析を変えた直後は、国税庁のページが変わっていなくてもこの警告が出ます。

### 取り直す

節ごとに `fetched_at` を持っているので、古いものだけを選んで取り直せます。まず対象を一覧で確かめ、それから実行します。

```sh
# 30 日以上古い節を一覧する（この時点では何も取得しません）
npx -y @shuji-bonji/houki-nta-mcp@latest --refresh-stale=30

# 実際に取り直す
npx -y @shuji-bonji/houki-nta-mcp@latest --refresh-stale=30 --apply
```

::: danger --refresh は既存のデータを消します
全部を入れ直すときは `--refresh` を付けます。既存のデータを消してから取り直すので、最初の投入と同じだけ時間がかかります。

```sh
npx -y @shuji-bonji/houki-nta-mcp@latest --bulk-download-everything --refresh
```

:::

`--refresh` を付けずに再実行したときは、国税庁サイトが `304 Not Modified` を返す節を飛ばすので短時間で終わります。
本文の解析だけをやり直したいとき（v0.10.0 以前の DB に算式画像のプレースホルダを入れる場合など）は `--refresh` を使います。

### 国税庁の索引から消えた文書

bulk download を再実行したときに国税庁の索引から消えていた文書を、DB からは消しません。索引から外れても、過去の課税期間の判断では依然として意味を持つ通達があるためです。

代わりに、消えたことを最初に確認した日時を記録し、応答で現行の文書と区別できるようにしています（v0.17.0）。

| 応答 | 付くもの |
| --- | --- |
| `nta_search_*` | 各件に `index_status: "removed_from_index"` と `orphaned_at`。`search_notes` に「N 件のうち M 件は索引から外れています」の 1 行 |
| `nta_get_*` | `index_status` と `orphaned_at` に加えて `notice`（現在の取扱いは最新の通達で確認する旨） |

検索結果から除外はしません。過去の期間を調べたい利用者が引けなくなるためです。印は `--bulk-download-*` を実行したときに付け外しします。索引に戻っていれば外れ、税目フォルダの世代移行で URL が変わっただけの文書には付きません。

印が付いた文書の `sourceUrl` は 404 になることがあります。本文はローカル DB に残っているので、`nta_get_*` では読めます。

### 置き場所

既定は `${XDG_CACHE_HOME:-~/.cache}/houki-nta-mcp/cache.db` です。
`--db-path=<path>` か、環境変数 `HOUKI_NTA_DB_PATH` で変えられます。

bulk download を実行したシェルと MCP サーバーとで `HOUKI_NTA_DB_PATH` や `XDG_CACHE_HOME` が違うと、
投入したはずの種別が `DOC_NOT_FOUND` になります。検索の応答の `hint` には、MCP サーバーが開いている DB ファイルのパスが入ります。

### パッケージを更新したとき

DB はパッケージの更新で消えません。保存の形が変わったときは、起動時に移行します。

| 版 | 起きること |
| --- | --- |
| v0.15.0 | v0.14.2 以前に作った DB は、最初の起動時に一度だけ文字列を入れ直します（全角英字の正規化）。国税庁サイトへの再アクセスはありません |
| v0.16.0 | 質疑応答事例とタックスアンサーの構造を保存する列が増えます。既存の行は空のままで、`nta_get_qa` / `nta_get_tax_answer` が引いたときか、次の `--bulk-download-qa` / `--bulk-download-tax-answer` で埋まります。移行そのものでは国税庁サイトへ行きません |
| v0.17.0 | 索引から消えたことを記録する列が増えます。既存の行は「索引にある」状態で残ります。印が付くのは次の `--bulk-download-*` のときで、移行そのものでは国税庁サイトへ行きません |

各版で何が変わったかは、リポジトリの [CHANGELOG](https://github.com/shuji-bonji/houki-nta-mcp/blob/main/CHANGELOG.md) にあります。

## 国税庁サイトの変更への備え

国税庁サイトは URL の世代が変わることがあります（`sozoku` → `sozoku2`、`hyoka` → `hyoka_new` など）。
`--health-check` で取得先が生きているかを確かめ、`--check-baseline-drift` で `menu.htm` を正典に世代移行を事前に検知します。
存在しないページが 404 ではなく `/error/404.htm` に着地する場合も、本文として取り込まずに失敗として扱います。

## PDF Agent Stack との組み合わせ

改正通達の新旧対照表は PDF で提供されます。houki-nta-mcp は PDF の本文を読みません。`nta_inspect_pdf_meta` が、PDF ごとの読み方（`read_strategy`: 表として取る / 本文として読む / 先頭を見て決める、`layout_note`: 紙面の組み方）と、`save: true` で保存したファイルの絶対パス（`saved[].path`）を返します。

読み手は決めていません。[pdf-reader-mcp](https://shuji-bonji.github.io/pdf-agent-stack/ja/mcp/pdf-reader) があれば、`next_actions` の呼び出し例（保存済みなら `extract_tables` に `file_path`、未保存なら `read_url` に `url`）をそのまま渡せます。無ければ、`saved[].path` か `url` を使っている PDF 読み取りツールに渡し、`layout_note` のとおりに読みます（v0.19.0。経緯は [houki-nta-mcp #36](https://github.com/shuji-bonji/houki-nta-mcp/issues/36) と `docs/DECISIONS.md` の 2026-09-21）。

利用範囲と通達の法的な位置づけは[免責事項と利用範囲](/guide/disclaimer)と、リポジトリの [DISCLAIMER.md](https://github.com/shuji-bonji/houki-nta-mcp/blob/main/DISCLAIMER.md) を参照してください。

houki-nta-mcp は family の中で最も長く開発しており、他の MCP サーバーの参照実装になっています
（正規化を取り込み時と検索時の両方で通す、`freshness` と `legal_status` を必ず付ける、取得先の変更を検知する、など）。