houki-nta-mcp

# houki-nta-mcp

> 国税庁（NTA）公式サイトの基本通達・改正通達・事務運営指針・文書回答事例・タックスアンサー・質疑応答事例を SQLite + FTS5 で全文検索する MCP server。日本の税務実務における「行政側の解釈・運用」を機械可読化する。法律本文（法・政令・省令）は別 MCP `@shuji-bonji/houki-egov-mcp` の責務。

houki-hub family の一員として「**国税庁という発出元組織**」を束ねる軸で設計されている。Architecture E（複数独立 MCP + 共有ライブラリ + Skill）に従い、family 横断の業法独占規定の注意喚起・citation 標準化・orchestration は `houki-research-skill`（Claude Skill）に委ねる。

## When to use

- 通達の条項を引きたい（例: 消基通 5-1-9、所基通 2-4の2、法基通 1-3の2-N）
- 「インボイス」「軽減税率」「電子帳簿」など実務テーマで通達・QA・タックスアンサーを横断検索したい
- 改正通達（一部改正通達）の本文と添付 PDF（kind 分類済 / pdf-reader-mcp 連携 hint 付き）を取得したい
- 国税局・税務署が依拠する事務運営指針（jimu-unei）を確認したい
- 過去の文書回答事例（bunshokaitou）から類似事案を引きたい
- タックスアンサー（一般納税者向け解説、約 750 件）を網羅的に検索したい

## When NOT to use

- **法律本文・政令・省令の取得** → `@shuji-bonji/houki-egov-mcp`（e-Gov 法令 API）
- **判決・最高裁判例の検索** → `@shuji-bonji/houki-court-mcp`（構想中）
- **国税不服審判所の裁決** → `@shuji-bonji/houki-saiketsu-mcp`（構想中）
- **労務系の通達・通知** → `@shuji-bonji/houki-mhlw-mcp`（厚労省、計画中）
- **税務相談そのもの** → 税理士法 52 条の独占業務。LLM が業として回答すべきではない（詳細は `houki-research-skill` 参照）

本 MCP は「**情報取得**」だけを担う。判断・助言・アドバイスは LLM 側のレイヤーで適切な業法上の留保を付けて行うこと。

## Setup prerequisites

初回利用時は SQLite キャッシュへの bulk download が必須。**未投入の状態で `nta_search_*` を呼ぶと空配列 + hint メッセージが返る**ので、先に以下のいずれかを案内すること:

```bash
# 推奨: 6 大コンテンツを一括投入（約 1.5〜2 時間 / fail rate 0% / 計 2,710+ 件）
houki-nta-mcp --bulk-download-everything

# 種別ごとに段階的に
houki-nta-mcp --bulk-download-all          # 基本通達 4 種
houki-nta-mcp --bulk-download-kaisei       # 改正通達
houki-nta-mcp --bulk-download-jimu-unei    # 事務運営指針
houki-nta-mcp --bulk-download-bunshokaitou # 文書回答事例
houki-nta-mcp --bulk-download-tax-answer   # タックスアンサー
houki-nta-mcp --bulk-download-qa           # 質疑応答事例
```

`nta_get_*` 系は DB 未投入でもライブ fetch にフォールバックするが、応答時間は 1 秒前後 → DB hit なら ~10ms。

## Legal positioning

本 MCP が扱うコンテンツは **法源としての強さに差** がある。LLM はこの違いを尊重して回答を組み立てること。

| 種別 | 国民の拘束 | 裁判所の拘束 | 税務署員の拘束 | 性質 |
|---|---|---|---|---|
| 基本通達・改正通達 | × | × | ○ | 行政内部文書（最高裁 S43.12.24） |
| 事務運営指針 | × | × | ○ | 国税局・税務署の業務指針 |
| 文書回答事例 | × | × | △ | 個別事案への文書回答（同種事案の参考） |
| タックスアンサー | × | × | × | 一般納税者向け解説、参考資料 |
| 質疑応答事例 | × | × | × | 国税庁による参考解説 |

各 tool レスポンスには `legal_status: { binds_citizens, binds_courts, binds_tax_office, note }` が付く。**「税務署はこう運用しているが、納税者・裁判所には拘束力がない」** ことを明示する設計。

## Tools (14 tools, v0.7.1 時点)

### 検索系（FTS5 全文検索、bulk DL 前提、レスポンスに `freshness` フィールド付き）
- `nta_search_tsutatsu`: 基本通達 4 種（消基通・所基通・法基通・相基通）を横断検索
- `nta_search_kaisei_tsutatsu`: 改正通達を検索（**v0.7.1**: `hasPdf` で PDF 付き文書だけに絞り込み可）
- `nta_search_jimu_unei`: 事務運営指針を検索（**v0.7.1**: `hasPdf` 対応）
- `nta_search_bunshokaitou`: 文書回答事例を検索（**v0.7.1**: `hasPdf` 対応）
- `nta_search_tax_answer`: タックスアンサー（約 750 件）を検索（**v0.7.1**: `hasPdf` 対応）
- `nta_search_qa`: 質疑応答事例（9 税目 / 約 1,840 件）を検索（**v0.7.1**: `hasPdf` 対応、現状は HTML のみで PDF を持たない）

### 取得系（6 つともローカル DB を先に引く。DB に無いときの動きは 2 通り。v0.16.0 / Issue #29）
DB に無ければ国税庁サイトから取得して書き戻す（応答に `source`: `"db"` / `"live"`）:
- `nta_get_tsutatsu`: 通達本文を略称＋条項で取得（Normalize-everywhere で全角・半角ゆらぎを吸収）。**v0.21.0 / Issue #54**: 基本通達 4 種とも国税庁サイトから取れる。消基通以外は目次から候補ページを選び、1 回の呼び出しで 10 ページまで取る。目次は DB に保存して使い回す。bulk download 済みの通達は DB に無い条項を `ARTICLE_NOT_FOUND`（`available_clauses` 付き）で返し、国税庁サイトへは取りに行かない
- `nta_get_tax_answer`: タックスアンサー番号（先頭桁で税目自動判定）
- `nta_get_qa`: 質疑応答事例を topic/category/id で取得

DB に無ければ `DOC_NOT_FOUND` を返す（docId から URL を組み立てるのに税目フォルダの世代差を解く必要があるため、国税庁サイトへは取りに行かない。エラーに `--bulk-download-*` の案内が付く）:
- `nta_get_kaisei_tsutatsu`: 改正通達を docId で取得（本文 + kind 分類付き添付 PDF 表 + pdf-reader-mcp 呼び出し例）
- `nta_get_jimu_unei`: 事務運営指針を docId で取得
- `nta_get_bunshokaitou`: 文書回答事例を docId で取得（本庁系・国税局系の 2 系統）

### 索引から消えた文書 (v0.17.0 / Issue #30)
国税庁の索引から消えた文書は DB から消さず、`document.orphaned_at` に印を付けて残す（過去の課税期間の判断では依然として意味を持つため）。検索結果からも除外しない。
- `nta_search_*` の各件: `index_status: "removed_from_index"` + `orphaned_at`、`search_notes` に件数の 1 行
- `nta_get_*`: `index_status` + `orphaned_at` + `notice`
- 印は `--bulk-download-*` のときに付け外しする。索引に戻れば外れる

### PDF 軸 (Phase 4-2, v0.7.1)
- `nta_inspect_pdf_meta`: docType + docId で指定文書の添付 PDF メタだけを返す軽量 API。本文を含まないので軽い。`reader_hints.examples` に pdf-reader-mcp の `read_text` 呼び出し例 JSON が入る

### 補助
- `resolve_abbreviation`: 略称解決（`@shuji-bonji/houki-abbreviations` 経由、管轄外なら他 MCP に誘導 hint）

## Family routing

houki-nta-mcp 単独で完結しないユースケースは family の他 MCP を併用する:

| ユースケース | 推奨フロー |
|---|---|
| 軽減税率の根拠を法律から実務まで | `houki-egov` (消費税法 29 条等) → `houki-nta` (消基通・QA) |
| 通達と判決を突き合わせたい | `houki-nta` (基本通達) → `houki-court` (判例) |
| 不服申立の事例を探したい | `houki-saiketsu` (国税不服審判所) → `houki-nta` (関連通達) |
| 略称が houki-nta 管轄外 | `resolve_abbreviation` → 他 MCP への誘導 hint を返す |

横断的 orchestration は `houki-research-skill` が担う。本 MCP 単独では fetch + parse + return のみ。

## Resources

- Repository: https://github.com/shuji-bonji/houki-nta-mcp
- npm: https://www.npmjs.com/package/@shuji-bonji/houki-nta-mcp
- Family hub doc: https://github.com/shuji-bonji/houki-hub-doc (構築中)
- Sibling MCPs:
  - https://github.com/shuji-bonji/houki-egov-mcp (法令本文)
  - https://github.com/shuji-bonji/houki-abbreviations (略称辞書)
- Skill: https://github.com/shuji-bonji/houki-research-skill (計画中)

## Optional

### Schema notes

- DB は SQLite + FTS5（trigram tokenizer）。`document` テーブルに 5 種別（kaisei / jimu-unei / bunshokaitou / tax-answer / qa-jirei）を統一格納、基本通達のみ `clause` テーブルで条項単位に格納
- 全データは `Normalize-everywhere` 原則で正規化済（全角→半角、ゆらぎ吸収）
- `content_hash` (SHA-1) で改正検知、`fetched_at` で staleness 判定可
- DB パス: `${XDG_CACHE_HOME:-~/.cache}/houki-nta-mcp/cache.db`

### PDF kind classification (v0.7.0)

改正通達 / 事務運営指針 / 文書回答事例 / タックスアンサーの添付 PDF はタイトルから 6 種別に
自動分類される（`AttachedPdf.kind: PdfKind`）:

| kind | 用途 / 想定 LLM 行動 |
|---|---|
| `comparison` 🔄 | 新旧対照表・対比表（改正点を知りたい時に最優先で読む） |
| `attachment` 📎 | 別紙・別表・様式（通達本文の参照先） |
| `qa-pdf` ❓ | PDF 形式の Q&A・質疑応答 |
| `related` 📚 | 参考資料・関連資料 |
| `notice` 📢 | 通知・お知らせ・連絡（一般的には要約に含めない） |
| `unknown` 📄 | 上記いずれにもマッチしない |

`nta_get_kaisei_tsutatsu` 等の Markdown 出力は kind 優先度（comparison 最上位）でソートされた表
+ 末尾に `pdf-reader-mcp` の `read_text` 呼び出し例 JSON を含む。本文取得は完全に
[`@shuji-bonji/pdf-reader-mcp`](https://www.npmjs.com/package/@shuji-bonji/pdf-reader-mcp) に委譲する設計（責務分離）。

v0.6.0 までに bulk DL 済のレコード（`attached_pdfs_json` に kind が無い）も後方互換で読める。

### Resilience features (v0.6.0)

houki-nta-mcp は HP 構造変更を 3 層で検知・可視化する:

1. **Active 検知 (bulk DL 時)**: 4 パターン集計（`newDocs` / `updatedDocs` / `orphanedDocs` / `movedDocs`）
   + 二重 threshold（`MIN_ABS` 種別別 + `MIN_RATE: 1%`）+ count drift ±20% + 構造変質 50%
2. **Active 検知 (オンデマンド)**: `houki-nta-mcp --health-check` で 9 種別の代表 URL を canary fetch + parse 検証。
   `--strict` で fail があれば exit code 1（CI 用）
3. **Passive 検知 (利用時)**: `nta_search_*` レスポンスに `freshness` フィールドを付与
   - `staleness`: `fresh` (< 1 週間) / `stale` (< 1 ヶ月) / `outdated` (> 1 ヶ月)
   - `outdated` 時は `warning` で再 bulk DL を案内

baseline は `~/.cache/houki-nta-mcp/baseline-{doc_type}.json` に永続化（直近 12 件ローテーション、
9 種別 = 5 document type + 4 通達分離）。

**運用フロー**: 月 1 回 `--bulk-download-everything` + 週 1 回 `--health-check`。
詳細は repo の `docs/RESILIENCE.md` を参照。

ベンチマーク（v0.5.0 全件 bulk DL）: **2,710 件 / 51 分 / fail rate 0%**。