Houki NTA MCP Server

国税庁（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

主な機能

• 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): 9 種別 baseline で履歴管理 + --health-check CLI で週次 canary 検証
• 添付 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 = 参考情報、等）

提供ツール（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

コンテンツ	件数の目安	投入時間
通達本体 (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。

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

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 が静かに壊れるリスクがあります。検知・可視化のため、以下を組み合わせて運用するのを推奨:

[!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 回 (CI)	GitHub Actions cron	--health-check --strict で自動検知

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。

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

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

┌──────────────────────────────────────────────────┐
│ 法律 (国会制定)              → 全員に拘束力     │
│ 政令・省令・告示             → 同上             │
│ ─── ここまでが houki-egov-mcp ─── │
│ 通達 (行政内部)              → 税務署員のみ拘束 │
│ 質疑応答事例                 → 参考情報         │
│ タックスアンサー             → 一般向け解説     │
│ ─── ここが houki-nta-mcp ─── │
└──────────────────────────────────────────────────┘

各レスポンスには legal_status フィールドが付与され、種別ごとの拘束力（binds_citizens / binds_courts / binds_tax_office）が明示されます。LLM はこの情報を尊重して回答を組み立てる前提です。

なぜ通達まで取得するのか

法律本文だけでは判断できないケースが多数あります。例えば消費税の軽減税率:

• 法律（消費税法 4 条）「飲食料品の譲渡には軽減税率を適用」
• 政令: 飲食料品の定義
• 基本通達 5-1-9: 「社内会議で出した飲食料品」「会議室への提供」「テイクアウト」の区分
• 質疑応答事例: 個別事例（「テレワーク手当に含まれる飲料水」等）

会計・経理・税務系プロダクトを開発する場合、通達レベルまで参照しないと正しい判定ができない ことが多く、houki-nta-mcp はその領域をカバーします。

インストール

// claude_desktop_config.json
{
  "mcpServers": {
    "houki-egov": {
      "command": "npx",
      "args": ["-y", "@shuji-bonji/houki-egov-mcp"]
    },
    "houki-nta": {
      "command": "npx",
      "args": ["-y", "@shuji-bonji/houki-nta-mcp"]
    }
  }
}

法律本文と通達の両方を引けるよう、両方を併用することを推奨します。

初回 bulk DL の注意

• MCP サーバ起動とは別プロセス で npx -y @shuji-bonji/houki-nta-mcp --bulk-download-everything を事前実行することを推奨（計 50 分前後）。
• pdf-reader-mcp を併用すると、改正通達の添付 PDF（新旧対照表など）も内容取得できます。v0.7.0 以降は kind 分類で「どの PDF を最優先で読むべきか」が Markdown 出力に明示され、v0.7.2 + pdf-reader-mcp v0.3.0 以降では comparison / attachment 系の PDF に対して extract_tables 呼び出し例を自動で出力します（表構造を保持したまま改正後/改正前を分離）。

prerelease (alpha) チャンネル

"args": ["-y", "@shuji-bonji/houki-nta-mcp@next"]   // alpha 系を追従
"args": ["-y", "@shuji-bonji/houki-nta-mcp@latest"] // 安定版（既定）

ローカル開発

git clone git@github.com:shuji-bonji/houki-nta-mcp.git
cd houki-nta-mcp
npm install
npm run build
npm test

// 開発中の動作確認 (.mcp.json)
{
  "mcpServers": {
    "houki-nta-local": {
      "command": "node",
      "args": ["/absolute/path/to/houki-nta-mcp/dist/index.js"]
    }
  }
}

エラー応答 (houki-hub family contract)

本 MCP のエラー応答は houki-hub family 共通契約に従います。code 文字列は family 全体で統一された語彙を使用するため、houki-egov-mcp / pdf-reader-mcp と併用しても LLM・Skill 層は一貫したロジックで解釈できます。

• docs/ERROR-CODES.md — 共通エラーコード語彙の正典 (houki-research-skill)
• docs/ERROR-HANDLING.md — 解釈ポリシー / next_actions テンプレ

実装は houki-egov-mcp の src/errors.ts をリファレンスとしつつ、本 MCP では共通パッケージ (houki-abbreviations 等) への依存を持たず独立して実装します。

{
  "error": "通達 docId=0025004-999 が見つかりません",
  "code": "TSUTATSU_NOT_FOUND",
  "hint": "nta_search_tsutatsu で正しい docId を検索してください",
  "next_actions": [
    { "action": "nta_search_tsutatsu", "reason": "キーワード検索で該当通達を探せます", "example": { "keyword": "適格請求書" } }
  ],
  "retryable": false
}

ドキュメント

• 🌐 docs/HOUKI-FAMILY-INTEGRATION.md — houki-hub family 4 つを連携した統合利用ガイド (Claude Desktop / Claude Code 向け install→設定→実例 4 ユースケース)
• docs/DESIGN.md — 設計原則・houki-hub family 内の位置付け・ツール設計
• docs/DATABASE.md — SQLite + FTS5 スキーマ・テーブル仕様・マイグレーション履歴
• docs/DATA-SOURCES.md — 国税庁公開コンテンツの URL 構造・スクレイピング方針・ライセンス
• docs/RESILIENCE.md — HP 構造変更検知の 5 層フレームワーク・運用フロー
• docs/PHASE4-PDF.md — Phase 4: PDF メタデータ強化と pdf-reader-mcp 連携の責務分離
• docs/PHASE4-PDF-FIXTURES.md — kind 別代表 PDF カタログ + Phase 4-3 実機テスト結果
• 🚧 docs/PHASE6.md — Phase 6 計画書: 運用品質と発信の底上げ (v1.0.0 への道) — search relevance ranking / bulk DL 差分更新 / houki-hub-doc + llms.txt 公開
• llms.txt — LLM 向け summary（family routing / setup / legal positioning）
• DISCLAIMER.md — 通達の法的位置付け・利用範囲
• CONTRIBUTING.md — 貢献方法
• CHANGELOG.md — リリースノート

業法との関係

本 MCP は 一次情報の取得・提示のみ を担います。分析は LLM、判断は利用者（または有資格者）の責任です。

業としての税務代理・税務書類作成・税務相談（税理士法 52 条）への利用は想定外 です。詳細は DISCLAIMER.md 参照。

ライセンス

MIT — 個人利用・学習用途のフォーク・改変・再配布を自由に許可します。

国税庁コンテンツの著作権は 国（国税庁） にあり、再配布・改変は政府標準利用規約（第 2.0 版）の範囲内で可能です。本 MCP は出典 URL を必ず付与する設計とし、利用者は元情報を確認できます。

houki-hub MCP family

パッケージ	役割	状態
@shuji-bonji/houki-abbreviations	略称辞書（共有ライブラリ）	✅ 公開済
@shuji-bonji/houki-egov-mcp	e-Gov 法令 API クライアント。法律・政令・省令・規則・告示の本文取得	✅ 公開済
@shuji-bonji/houki-nta-mcp	国税庁の通達・改正通達・事務運営指針・文書回答事例・Q&A・タックスアンサー（このリポジトリ）	✅ 公開済
@shuji-bonji/houki-mhlw-mcp	厚労省の通達・通知・指針	📅 計画中
@shuji-bonji/houki-saiketsu-mcp	裁決全般。初版は国税不服審判所 (kfs.go.jp、約 1,950 件)。将来的に公正取引委員会・特許庁審判部・各省庁不服審査会 等へ拡張	💭 構想中
@shuji-bonji/houki-court-mcp	判例全般。初版は民事判決オープンデータ API。将来的に courts.go.jp の全公開判例（最高裁・高裁・地裁）へ拡張	💭 構想中
@shuji-bonji/houki-hub	meta-package（一括 install）	📅 計画中

family 全体のドキュメントサイト（houki-hub.mikuro.net / 構築中）で各 MCP の詳細を順次公開予定です。

💡 houki-nta-mcp 単体ではなく houki-egov-mcp + pdf-reader-mcp と連携させて使う方法 は docs/HOUKI-FAMILY-INTEGRATION.md にまとめてあります。Claude Desktop / Claude Code の設定例から、新旧対照表 PDF を extract_tables で表構造のまま抽出する実例まで、一から順に追えるガイドです。

ただし、業としての使用（税理士法 52 条が定める独占業務） については想定外であり、作者は一切の責任を負いません。DISCLAIMER.md を必ずご確認ください。