houki-nta-mcp

# Houki NTA MCP Server

[![CI](https://github.com/shuji-bonji/houki-nta-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/shuji-bonji/houki-nta-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Node](https://img.shields.io/badge/Node-%3E%3D22-brightgreen)](https://nodejs.org/)

**実装する前に、国税庁の取扱いが条文とどう違うかを確かめる**ための MCP server。国税庁（NTA）公式サイトの **基本通達・改正通達・事務運営指針・文書回答事例・タックスアンサー・質疑応答事例** をローカル SQLite に取り込み、FTS5 で全文検索し、「法律で決まっている」と「通達でそうなっている」を混ぜずに、`legal_status`（通達は国民を拘束しない旨）と根拠条文への案内と鮮度を添えて返します。

法律本文（法・政令・省令）は別 MCP の [`@shuji-bonji/houki-egov-mcp`](https://github.com/shuji-bonji/houki-egov-mcp) が担当します。通達の応答からは `next_actions` で houki-egov-mcp の `get_law` へ戻れます。

> **🔗 4 つを併用したい方へ** — `houki-egov-mcp` (法令本文) と `pdf-reader-mcp` (添付 PDF 抽出) と組み合わせた **install → 設定 → 実例 4 ユースケース** をまとめた統合ガイドを用意しています。
>
> 👉 **[docs/HOUKI-FAMILY-INTEGRATION.md](docs/HOUKI-FAMILY-INTEGRATION.md)**

## 主な機能

- **6 大コンテンツに対応**: 基本通達 4 種 + 改正通達・事務運営指針・文書回答事例・タックスアンサー・質疑応答事例
- **14 ツール提供**: 取得 + FTS5 全文検索 + PDF メタ取得 + 略称解決
- **高速応答**: bulk DL 済なら DB から即時応答（~10ms）。未投入のときの動きは取得ツールごとに違います（[取得ツールが DB をどう使うか](#取得ツールが-db-をどう使うか)）
- **正規化済み検索**: Normalize-everywhere 原則で全角・半角ゆらぎを吸収（数字・英字・ハイフン・チルダ・空白。実装は houki-hub family 共通の `@shuji-bonji/houki-abbreviations`）
- **改正検知**: SHA-1 content_hash で個別文書の変化を検知、4 パターン集計（新規 / 更新 / 削除 / 移動）
- **HP 構造変更耐性 (v0.6.0 / v0.9.4)**: 9 種別 baseline で履歴管理 + `--health-check` CLI で週次 canary 検証 + `--check-baseline-drift` で `menu.htm` を真の正典として世代移行 (`sozoku2` / `hyoka_new` 等) を**事前検知** + soft-404 (`/error/404.htm` 着地) を `fetchNtaPage` で自動 fail させる二重防御
- **添付 PDF kind 分類 (v0.7.0)**: タイトルから 6 種別（新旧対照表 / 別紙・別表 / Q&A / 参考資料 / 通知・連絡 / その他）に自動分類。Markdown 出力は kind 優先度ソートの表 + `pdf-reader-mcp` 呼び出し例つき
- **`hasPdf` 検索フィルタ + `nta_inspect_pdf_meta` (v0.7.1)**: PDF 付きの重要文書だけを抽出 / PDF メタだけを軽量に返す軽量 API を提供
- **kind 別 `reader_hints` + `extract_tables` 推奨 (v0.7.2)**: 添付 PDF の kind ごとに `pdf-reader-mcp` 呼び出し例を生成。`comparison`（新旧対照表）/ `attachment`（別紙・別表）は `pdf-reader-mcp@0.3.0+` の `extract_tables` で表構造を保持したまま抽出するよう誘導。「新旧**対応**表」など表記ゆれにも対応。v0.6.0 期に投入された DB レコードでも kind は応答時に動的補完
- **レスポンスに `freshness` 付き**: 利用者（LLM）が staleness を判定できる
- **法的位置付けを明示**: 各レスポンスに `legal_status` フィールド（通達 = 税務署員のみ拘束、QA = 参考情報、等）

### データフロー全体俯瞰

国税庁 HP の 6 大コンテンツを bulk DL で SQLite cache に投入し、MCP tool はローカル DB を先に引いて応答します。DB に無かったときの動きは取得ツールごとに違うので、[取得ツールが DB をどう使うか](#取得ツールが-db-をどう使うか)を参照してください。

```mermaid
flowchart TB
  subgraph NTA["国税庁 HP (www.nta.go.jp)"]
    direction TB
    N1["基本通達 4 種<br/>消基通 / 所基通<br/>法基通 / 相基通"]
    N2["改正通達"]
    N3["事務運営指針"]
    N4["文書回答事例"]
    N5["タックスアンサー"]
    N6["質疑応答事例"]
  end

  subgraph DL["bulk DL 層 (CLI)"]
    DLA["--bulk-download-everything<br/>または個別 --bulk-download-*"]
  end

  subgraph DBLayer["SQLite cache<br/>~/.cache/houki-nta-mcp/cache.db"]
    direction TB
    DB1["document<br/>(本文 + content_hash)"]
    DB2["section / clause<br/>(章節構造)"]
    DB3["FTS5 全文検索<br/>(Normalize-everywhere)"]
  end

  subgraph Tools["14 MCP tool"]
    direction TB
    T1["nta_get_* × 6<br/>nta_search_* × 6"]
    T2["nta_inspect_pdf_meta<br/>resolve_abbreviation"]
  end

  NTA -->|"scrape + parse<br/>(週次 health-check で監視)"| DLA
  DLA -->|"normalize + insert"| DBLayer
  DBLayer -->|"DB-first ~10ms"| Tools
  NTA -.->|"live fallback ~700ms<br/>(DB 未投入時のみ)"| Tools
  Tools -->|"freshness / legal_status<br/>を埋め込んで応答"| LLM(["LLM / Claude"])

  classDef nta fill:#fff3cd,stroke:#ffc107,color:#333
  classDef db fill:#d4edda,stroke:#28a745,color:#333
  classDef tool fill:#cce5ff,stroke:#0066cc,color:#333
  classDef cli fill:#e2d6f3,stroke:#7952b3,color:#333
  class NTA nta
  class DBLayer db
  class Tools tool
  class DL cli
```

## 提供ツール（14 ツール）

| Tool                         | 用途                                                                                                                             |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `nta_get_tsutatsu`           | 通達本文を取得（DB → 無ければ国税庁サイト、4 通達対応）                                                                          |
| `nta_search_tsutatsu`        | 通達を FTS5 全文検索（`freshness` 付き）                                                                                         |
| `nta_get_kaisei_tsutatsu`    | 改正通達を docId で取得（DB のみ。本文 + kind 分類付き PDF 表）                                                                  |
| `nta_search_kaisei_tsutatsu` | 改正通達を FTS5 検索（`hasPdf` フィルタ・`freshness`）                                                                           |
| `nta_get_jimu_unei`          | 事務運営指針を取得（DB のみ）                                                                                                    |
| `nta_search_jimu_unei`       | 事務運営指針を FTS5 検索（`hasPdf` フィルタ・`freshness`）                                                                       |
| `nta_get_bunshokaitou`       | 文書回答事例を取得（DB のみ）                                                                                                    |
| `nta_search_bunshokaitou`    | 文書回答事例を FTS5 検索（`hasPdf` フィルタ・`freshness`）                                                                       |
| `nta_get_tax_answer`         | タックスアンサー本文を取得（DB → 無ければ国税庁サイト）                                                                          |
| `nta_search_tax_answer`      | タックスアンサーを FTS5 全文検索（`hasPdf` フィルタ・`freshness`）                                                               |
| `nta_get_qa`                 | 質疑応答事例の本文を取得（DB → 無ければ国税庁サイト）                                                                            |
| `nta_search_qa`              | 質疑応答事例を FTS5 全文検索（`topic` で税目の絞り込み・`freshness` 付き）                                                                |
| `nta_inspect_pdf_meta`       | 指定文書の添付 PDF メタ + `pdf-reader-mcp` 呼び出し例（kind 別 / extract_tables 推奨）だけを返す軽量 API (v0.7.1, v0.7.2 で拡張) |
| `resolve_abbreviation`       | 略称→エントリ解決（houki-abbreviations 経由）                                                                                    |

### 取得ツールが DB をどう使うか

取得ツール 6 つは、ローカル DB を先に引く点は同じですが、**DB に無かったときの動きが 2 通りに分かれます**（v0.16.0 / Issue #29）。

| ツール | DB を先に引く | DB に無いとき | DB へ書き戻す | 応答の `source` |
| --- | --- | --- | --- | --- |
| `nta_get_tsutatsu` | 引く | 国税庁サイトから取得 | 書き戻す | `"db"` / `"live"` |
| `nta_get_qa` | 引く | 国税庁サイトから取得 | 書き戻す | `"db"` / `"live"` |
| `nta_get_tax_answer` | 引く | 国税庁サイトから取得 | 書き戻す | `"db"` / `"live"` |
| `nta_get_kaisei_tsutatsu` | 引く | `DOC_NOT_FOUND` を返す | — | 付かない |
| `nta_get_jimu_unei` | 引く | `DOC_NOT_FOUND` を返す | — | 付かない |
| `nta_get_bunshokaitou` | 引く | `DOC_NOT_FOUND` を返す | — | 付かない |

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

`nta_get_qa` と `nta_get_tax_answer` が DB から返せるのは、**`structured_json` を持つ行**だけです。この列は v0.16.0 で増えたので、v0.15.x までに投入した行は持っていません。持っていない行は国税庁サイトから取得して書き戻すので、1 度引けば次からは DB から返ります。`--bulk-download-qa` / `--bulk-download-tax-answer` を実行しても埋まります（この 2 種別では、構造を持たない行は条件付き GET を使わずに取り直します）。

### 国税庁の索引から消えた文書（v0.17.0 / Issue #30）

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

代わりに `document.orphaned_at` に「索引から消えたことを最初に確認した日時」を入れ、応答で現行の文書と区別できるようにしています。

| 応答 | 付くもの |
| --- | --- |
| `nta_search_*`（5 種別） | 各件に `index_status: "removed_from_index"` と `orphaned_at`、`search_notes` に「N 件のうち M 件は索引から外れています」の 1 行 |
| `nta_get_*`（5 種別） | `index_status` / `orphaned_at` / `notice`（Markdown 形式では「索引の状態」の行と注記） |

検索結果から除外はしません。除外すると、過去の期間を調べたい利用者が引けなくなります。

印の付け外しは `--bulk-download-*` のときに行います。

- 索引に戻っていれば印を外します（国税庁サイトの一時的な不整合や、世代ディレクトリの移行中に消えたように見える場合があるため）
- 索引にある文書と題名が一致する行には印を付けません（`sozoku` → `sozoku2` のような世代移行で doc_id が変わっただけの文書を、消えたと数えないため）
- 索引の取得に失敗した税目がある実行では、判定そのものを行いません（その税目の文書が丸ごと「消えた」と判定されるため）

### 対応通達（4 種）

| 通達             | 略称   | TOC スタイル | clause 番号体系                                |
| ---------------- | ------ | ------------ | ---------------------------------------------- |
| 消費税法基本通達 | 消基通 | shohi        | 3 階層 `1-4-13の2`                             |
| 所得税基本通達   | 所基通 | shotoku      | 2 階層 `2-4の2` / 共通通達 `183~193共-1`       |
| 法人税基本通達   | 法基通 | hojin        | 3 階層、節の2 を含む `1-3の2-N`                |
| 相続税法基本通達 | 相基通 | sozoku       | flat 構造、ナカグロ複数条共通 `1の3・1の4共-1` |

clause 番号は **Normalize-everywhere** で全角→半角統一されているため、ユーザーが半角・全角どちらで入力してもヒットします。全角英字（`ＮＩＳＡ` → `NISA`、`ｅ－Ｔａｘ` → `e-Tax`）も v0.15.0 から半角に揃います。

v0.14.2 以前に作った DB は、v0.15.0 で最初にサーバーを起動したときに一度だけ入れ直されます。国税庁サイトへの再アクセスは発生しません。

### 検索キーワードの文字数（v0.10.1、Issue #18）

全文検索は SQLite FTS5 の trigram tokenizer を使うため、**3 文字未満の語は索引に乗りません**。v0.10.0 までは「役員」「退職」のような 2 文字語がそのまま 0 件になり、通常の「該当なし」と区別できませんでした。v0.10.1 からは次のように扱います。

| 語の長さ | 扱い |
|------|------|
| 3 文字以上 | FTS5 で全文検索します（これまでどおり） |
| 2 文字 | 3 文字以上の語と一緒なら、FTS5 のヒットを「本文かタイトルにその 2 文字語を含むもの」に絞り込みます。2 文字語だけのときは、本文とタイトルの部分一致（`LIKE`）で検索します（FTS5 の rank は付かないため score は低めになります） |
| 1 文字 | 検索条件から外します |

2 文字語や 1 文字語を含むクエリでは、応答に `search_notes`（文字列の配列）が付き、どう扱ったかを文で示します。0 件のときも `search_notes` が付くので、LLM / Skill 層は「仕様上ヒットしなかった」のか「本当に該当がない」のかを判別できます。

### 検索が 0 件のとき（v0.13.0、Issue #23）

文書系の検索 5 ツール（`nta_search_qa` / `nta_search_tax_answer` / `nta_search_kaisei_tsutatsu` / `nta_search_jimu_unei` / `nta_search_bunshokaitou`）は、結果が 0 件になった理由を分けて返します。v0.12.0 までは、どの場合も「`--bulk-download-*` で DB 投入済みか確認してください」という同じ `hint` だったため、文書が入っている DB でも投入をやり直すよう案内していました。

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

その