Houki Nta Mcp

Houki NTA MCP Server

[](https://github.com/shuji-bonji/houki-nta-mcp/actions/workflows/ci.yml) [](LICENSE) [](https://nodejs.org/)

国税庁（NTA）公式サイトの 基本通達・改正通達・事務運営指針・文書回答事例・タックスアンサー・質疑応答事例 をローカル SQLite に取得し、FTS5 で全文検索する MCP server。

法律本文（法・政令・省令）は別 MCP の @shuji-bonji/houki-egov-mcp が担当します。

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

主な機能

• 6 大コンテンツに対応: 基本通達 4 種 + 改正通達・事務運営指針・文書回答事例・タックスアンサー・質疑応答事例
• 14 ツール提供: 取得（DB-first → live fallback） + FTS5 全文検索 + PDF メタ取得 + 略称解決
• 高速応答: bulk DL 済なら DB から即時応答（~10ms）。未投入なら live fetch（~700ms/件）でフォールバック
• 正規化済み検索: Normalize-everywhere 原則で全角・半角ゆらぎを吸収
• 改正検知: 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-first → live fallback で応答します。

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

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

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

  subgraph Tools["14 MCP tool"]
    direction TB
    T1["nta_get_* × 6nta_search_* × 6"]
    T2["nta_inspect_pdf_metaresolve_abbreviation"]
  end

  NTA -->|"scrape + parse(週次 health-check で監視)"| DLA
  DLA -->|"normalize + insert"| DBLayer
  DBLayer -->|"DB-first ~10ms"| Tools
  NTA -.->|"live fallback ~700ms(DB 未投入時のみ)"| Tools
  Tools -->|"freshness / legal_statusを埋め込んで応答"| 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-first → live fallback、4 通達対応） | | nta_search_tsutatsu | 通達を FTS5 全文検索（freshness 付き） | | nta_get_kaisei_tsutatsu | 改正通達を docId で取得（本文 + kind 分類付き PDF 表） | | nta_search_kaisei_tsutatsu | 改正通達を FTS5 検索（hasPdf フィルタ・freshness） | | nta_get_jimu_unei | 事務運営指針を取得 | | nta_search_jimu_unei | 事務運営指針を FTS5 検索（hasPdf フィルタ・freshness） | | nta_get_bunshokaitou | 文書回答事例を取得 | | nta_search_bunshokaitou | 文書回答事例を FTS5 検索（hasPdf フィルタ・freshness） | | nta_get_tax_answer | タックスアンサー本文を取得 | | nta_search_tax_answer | タックスアンサーを FTS5 全文検索（hasPdf フィルタ・freshness） | | nta_get_qa | 質疑応答事例の本文を取得 | | nta_search_qa | 質疑応答事例を FTS5 全文検索（freshness 付き） | | nta_inspect_pdf_meta | 指定文書の添付 PDF メタ + pdf-reader-mcp 呼び出し例（kind 別 / extract_tables 推奨）だけを返す軽量 API (v0.7.1, v0.7.2 で拡張) | | resolve_abbreviation | 略称→エントリ解決（houki-abbreviations 経由） |

対応通達（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 で全角→半角統一されているため、ユーザーが半角・全角どちらで入力してもヒットします。

使い方の例

// nta_get_tsutatsu — DB-first lookup（bulk DL 済みなら即時応答 ~10ms）
{ "name": "消基通", "clause": "1-4-13の2" }
// → "## 1-4-13の2（分割があった場合の課税事業者選択届出書の効力等）..."
//    + 出典 URL + 取得時刻 + legal_status の note + source: 'db' | 'live'

// 所基通（2 階層 clause / の付き）
{ "name": "所基通", "clause": "2-4の2" }

// 所基通源泉（チルダ複数条共通）
{ "name": "所基通", "clause": "183~193共-1" }

// 相基通（ナカグロ複数条共通）
{ "name": "相基通", "clause": "1の3・1の4共-5" }

// nta_search_tsutatsu — FTS5 全文検索（4 通達横断、freshness 付き）
{ "keyword": "電子帳簿", "limit": 10 }
// → { hits: [...], freshness: { staleness, oldest_fetched_at, ... }, legal_status: ... }

// nta_get_kaisei_tsutatsu — 改正通達取得
{ "docId": "0026003-067" }
// → "# 消費税法基本通達の一部改正について（法令解釈通達）" + 発出日 + 宛先 + 本文
//   + 「## 添付 PDF (N 件)」表（🔄 新旧対照表 / 📎 別紙・別表 等で kind 分類済）
//   + pdf-reader-mcp の read_text 呼び出し例 JSON
//    PDF 本文は pdf-reader-mcp に委譲

// nta_get_tax_answer — 番号で取得（先頭桁から税目自動判定）
{ "no": "6101" }
// → "# No.6101 消費税の基本的なしくみ ..." sections + 法令時点 + 出典

// nta_get_qa — 質疑応答事例を取得
{ "topic": "shohi", "category": "02", "id": "19" }
// → "# 個人事業者が所有するゴルフ会員権の譲渡 ## 【照会要旨】 ... ## 【回答要旨】 ..."

// 管轄外（消法 = 消費税法本体）→ houki-egov-mcp に誘導
{ "name": "消法", "clause": "9" }
// → { error: "...houki-egov の管轄...", hint: "houki-egov-mcp で取得してください" }

初回セットアップ（bulk DL）

通達本体・改正通達・事務運営指針・文書回答事例・タックスアンサー・質疑応答事例を事前に bulk DL してローカル SQLite (FTS5) に投入します。1 度実行すれば DB から即時応答（fetch なし）。

コマンドの呼び出し形式

bulk DL コマンドは利用形態に応じて以下の 3 形式があります。以降の例は A. グローバルインストール済み の形式で記載しています。B / C を使う場合は同様に置き換えてください。

| 利用形態 | コマンド形式 | 前提 | | ------------------------------ | ---------------------------------------------------------------------- | ------------------------------------------------------ | | A. グローバル install 済み | houki-nta-mcp --bulk-download-everything | npm install -g @shuji-bonji/houki-nta-mcp 実行済み | | B. npx 経由（都度実行） | npx -y @shuji-bonji/houki-nta-mcp --bulk-download-everything | Node.js / npm がインストール済みなら追加準備不要 | | C. ローカルクローン | node /path/to/houki-nta-mcp/dist/index.js --bulk-download-everything | git clone + npm install + npm run build 実行済み |

> [!TIP] > Claude Desktop / Claude Code で MCP サーバとして登録する場合は別問題で、mcp_servers 設定の npx -y @shuji-bonji/houki-nta-mcp (= 形式 B) を使います（後述「Claude Desktop / Claude Code への登録例」を参照）。bulk DL は MCP サーバ起動とは別プロセス で人間が実行するため、ここではどの形式でも構いません。

# 推奨: 6 種別を一括投入（約 50 分。--bunsho-taxonomy / --tax-answer-taxonomy / --qa-topic で短縮可）

# A. グローバル install 済み
houki-nta-mcp --bulk-download-everything --bunsho-taxonomy=shotoku

# B. npx 経由
npx -y @shuji-bonji/houki-nta-mcp --bulk-download-everything --bunsho-taxonomy=shotoku

# C. ローカルクローン
node /path/to/houki-nta-mcp/dist/index.js --bulk-download-everything --bunsho-taxonomy=shotoku

# 個別実行（以下は形式 A の例。B / C は上記対応表で置き換え）
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           # 質疑応答事例

# 30 日以上古い節を再取得（差分更新）
houki-nta-mcp --refresh-stale=30 --apply

# 9 種別の代表 URL を canary 検証（HP 構造変更検知）
houki-nta-mcp --health-check

# menu.htm を真の正典として CANARY_TARGETS の世代移行を事前検知（canary より前段の予兆検知 / v0.9.4+）
houki-nta-mcp --check-baseline-drift

| コンテンツ | 件数の目安 | 投入時間 | | ----------------- | ----------------- | -------------------------- | | 通達本体 (4 通達) | 約 2,800 clauses | 10-15 分 | | 改正通達 | 約 125 docs | 5-10 分 | | 事務運営指針 | 約 32 docs | 約 1 分 | | 文書回答事例 | 数百〜2,000+ docs | 約 30 分超（絞り込み推奨） | | タックスアンサー | 約 750 docs | 約 14 分 | | 質疑応答事例 | 約 1,840 docs | 約 35 分 |

DB は ${XDG_CACHE_HOME:-~/.cache}/houki-nta-mcp/cache.db。詳細は [docs/DATABASE.md](docs/DATABASE.md)。

投入済みかどうかを素早く確認する

nta_search_* の応答が空 (results: [] + --bulk-download-* で DB 投入済みか確認してください のヒント) の場合、対象 docType が未投入の可能性があります。投入有無は以下で確認できます。

# 各 docType の件数を一発で確認 (DB が無ければ投入前)
sqlite3 "$HOME/.cache/houki-nta-mcp/cache.db" \
  "SELECT doc_type, COUNT(*) FROM document GROUP BY doc_type ORDER BY doc_type;"

期待される doc_type 名 → 対応 bulk DL コマンド:

| doc_type | bulk DL コマンド | 備考 | | -------------- | ---------------------------------------------------- | ----------------------------------------------------- | | tsutatsu | --bulk-download-all | 通達本体 4 種を一括（消基通・所基通・法基通・相基通） | | kaisei | --bulk-download-kaisei | 改正通達 | | jimu-unei | --bulk-download-jimu-unei | 事務運営指針 | | bunshokaitou | --bulk-download-bunshokaitou [--bunsho-taxonomy=…] | 文書回答事例（taxonomy 指定で短縮） | | tax-answer | --bulk-download-tax-answer | タックスアンサー | | qa-jirei | --bulk-download-qa [--qa-topic=…] | 質疑応答事例（topic 指定で短縮） |

--bulk-download-everything は上記すべてを順番に実行する短絡コマンドです。

bunsho-taxonomy / tax-answer-taxonomy / qa-topic で範囲を絞らない場合、bunshokaitou と qa-jirei は数千件単位になるため、初回は taxonomy/topic を絞って投入することを推奨します。

# 例: 所得税関連だけを bulk DL（数十分 → 数分に短縮）

# A. グローバル install 済み
houki-nta-mcp --bulk-download-bunshokaitou --bunsho-taxonomy=shotoku
houki-nta-mcp --bulk-download-qa --qa-topic=shotoku

# B. npx 経由
npx -y @shuji-bonji/houki-nta-mcp --bulk-download-bunshokaitou --bunsho-taxonomy=shotoku
npx -y @shuji-bonji/houki-nta-mcp --bulk-download-qa --qa-topic=shotoku

# C. ローカルクローン
node /path/to/houki-nta-mcp/dist/index.js --bulk-download-bunshokaitou --bunsho-taxonomy=shotoku
node /path/to/houki-nta-mcp/dist/index.js --bulk-download-qa --qa-topic=shotoku

推奨運用フロー

スクレイピング主体のため、国税庁 HP の構造変更で bulk DL や parse が静かに壊れるリスクがあります。検知・可視化のため、以下を組み合わせて運用するのを推奨:

flowchart LR
  subgraph Monthly["月次（重い処理 / ~51 分）"]
    M1["--bulk-download-everything6 種別を順次投入+ baseline 履歴記録"]
  end

  subgraph Weekly["週次（軽い処理 / 数秒〜数十秒）"]
    direction TB
    W1["--check-baseline-driftmenu.htm 突合(v0.9.4+, ~0.1 秒)"]
    W2["--health-check --strict9 種別 canary fetch+parse(~10 秒)"]
  end

  DB[("SQLite cache.db")]
  R(["MCP レスポンス+ freshness(fresh / stale / outdated)"])

  M1 -->|"normalize + insert"| DB
  DB -->|"DB-first 応答"| R
  W1 -.->|"drift 検出時baseline URL 更新を上申"| M1
  W2 -.->|"parser 失敗時HP 構造変更を検知"| M1
  R -.->|"stale なら再 bulk DL を促す"| M1

  classDef monthly fill:#cce5ff,stroke:#0066cc
  classDef weekly fill:#d4edda,stroke:#28a745
  classDef response fill:#fff3cd,stroke:#ffc107
  class Monthly monthly
  class Weekly weekly
  class R response

設計の要点: 重い bulk-download-everything は 月次、軽い health-check / check-baseline-drift は 週次で階層化。週次の 2 つは Lv-3a (soft-404) と Lv-3b (menu.htm drift) の二重防御で、canary が落ちる前に baseline 更新を促せます (詳細は [docs/RESILIENCE.md](docs/RESILIENCE.md) §5.9-5.11)。

> [!NOTE] > 以下の表およびコマンド例は、前述「コマンドの呼び出し形式」の 形式 A (グローバル install 済み) を前提に記載しています。B (npx) / C (ローカルクローン) を使う場合は同様に置き換えてください。

| 頻度 | コマンド | 用途 | | ------------ | ------------------------------------------ | -------------------------------------------------------------------------------------- | | 月 1 回 | houki-nta-mcp --bulk-download-everything | 4 パターン集計 + baseline 永続化 | | 週 1 回 | houki-nta-mcp --health-check | 9 種別の代表 URL を canary fetch + parse | | 週 1 回 | houki-nta-mcp --check-baseline-drift | menu.htm を正典として世代移行 (sozoku2 等) を事前検知 (v0.9.4+、canary より早期) | | 週 1 回 (CI) | GitHub Actions cron | --health-check --strict で自動検知 + --check-baseline-drift で drift 警告 (別 job) |

cron 設定例:

# A. グローバル install 済み（npm install -g 済 / `which houki-nta-mcp` で絶対パス確認）
# 月初に bulk DL（毎月 1 日 03:00 JST）
0 3 1 * *  /usr/local/bin/houki-nta-mcp --bulk-download-everything > ~/.cache/houki-nta-mcp/last-bulk.log 2>&1
# 月曜に health-check（毎週月曜 09:00 JST）
0 9 * * 1  /usr/local/bin/houki-nta-mcp --health-check >> ~/.cache/houki-nta-mcp/health.log 2>&1

# B. npx 経由（PATH に node が通っている前提。/opt/homebrew/bin など環境ごとに調整）
0 3 1 * *  /opt/homebrew/bin/npx -y @shuji-bonji/houki-nta-mcp --bulk-download-everything > ~/.cache/houki-nta-mcp/last-bulk.log 2>&1
0 9 * * 1  /opt/homebrew/bin/npx -y @shuji-bonji/houki-nta-mcp --health-check >> ~/.cache/houki-nta-mcp/health.log 2>&1

# C. ローカルクローン
0 3 1 * *  /opt/homebrew/bin/node /path/to/houki-nta-mcp/dist/index.js --bulk-download-everything > ~/.cache/houki-nta-mcp/last-bulk.log 2>&1
0 9 * * 1  /opt/homebrew/bin/node /path/to/houki-nta-mcp/dist/index.js --health-check >> ~/.cache/houki-nta-mcp/health.log 2>&1

> [!TIP] > cron は環境変数を継承しないので、houki-nta-mcp / npx / node は 絶対パスで指定してください。which houki-nta-mcp / which npx / which node で確認できます。

レスポンスに freshness フィールドが付き、staleness (fresh/stale/outdated) で再 bulk DL の必要性を判断できます。設計詳細は [docs/RESILIENCE.md](docs/RESILIENCE.md)。

通達の法的位置付け（重要）

通達は 行政内部文書 であり、国民・裁判所には直接的な法的拘束力を持ちません（最高裁 昭和43.12.24 墓地埋葬法事件）。ただし税務署員は職務命令として守る義務があり、実務上は事実上の規範 として機能します。

┌──────────────────────────────────────────────────┐
│ 法律 (国会制定)              → 全員に拘束力     │
│ 政令・省令・告示             → 同上             │
│ ─── こ

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [shuji-bonji](https://github.com/shuji-bonji)
- **Source:** [shuji-bonji/houki-nta-mcp](https://github.com/shuji-bonji/houki-nta-mcp)
- **License:** MIT
- **Homepage:** https://www.npmjs.com/package/@shuji-bonji/houki-nta-mcp

Install and usage instructions live in the source repository linked above.