houki-hub

Appearance

nta_search_bunshokaitou の仕様 ​

INFO

houki-nta-mcp v0.27.1 の specs/current/nta_search_bunshokaitou/spec.md から自動生成しました（仕様 ID 8 件・2026-10-12）。手で編集しないでください。再生成は node scripts/generate-reference.mjs specs です。

文書回答事例をキーワードで検索する

使いどころ・引数・実測の呼び出し例は、ツールのページにあります。

最後に仕様が変わったのは v0.26.0 の「ローカル DB を開けないときの読むだけのツールと書き戻すツールの応答、--bulk-download-tax-answer が索引を保存できないときの終わり方（nta #144・#145）」（2026-10-06 承認）です。それまでの経緯は承認の履歴にあります。

利用者と得られる結果 ​

この機能の利用者と、利用者が渡すもの・得られる結果を示します。

  • MCP クライアント（Claude などの LLM、または CLI から呼ぶ人）。keyword を渡して、ローカル DB に入っている国税庁の文書回答事例（本庁と国税局の両方）のうちキーワードに合うものの一覧（docId・題名・抜粋）を受け取る。本文は nta_get_bunshokaitou に docId を渡して読む

入力 ​

呼び出すときに渡す値です。

引数必須内容
keyword必須検索キーワード。例: "電子帳簿"、"適格請求書"、"災害損失"。空白で区切ると AND 検索。3 文字以上の語を推奨。空文字・空白だけは不可
taxonomy任意税目フォルダ名（URL のフォルダ名）で絞り込む。例: "shotoku" / "hojin" / "sozoku" / "gensen" / "joto-sanrin" / "shohi" / "zoyo" / "hyoka" / "shozei" / "sonota"。国税局のページの別表記（"souzoku" / "gensenshotoku" / "joto_sanrin"）でもよい。列挙で検査せず、DB に無い値は available_taxonomies で正しい値を返す（SPEC-NTA-SEARCH-RULES-018）
limit任意返す件数。既定 10。1 以上 50 以下の整数
hasPdf任意添付 PDF の有無で絞り込む。true は PDF 付きだけ、false は PDF 無しだけ、省略時は絞らない

検索の対象はローカル DB だけである。事前に houki-nta-mcp --bulk-download-bunshokaitou で文書回答事例を DB に入れておく必要がある。国税庁サイトには取りに行かない。

扱わないこと ​

この機能が意図して扱わないことです。

  • 文書の本文を返すこと（結果は docId・題名・抜粋まで。本文は nta_get_bunshokaitou）
  • 国税庁サイトに取りに行くこと（DB に無い文書は、--bulk-download-bunshokaitou をもう一度実行して取り込む）
  • 発出日や国税局で絞り込むこと（絞り込めるのは taxonomy と hasPdf だけ。国税局の文書は docId の先頭（tokyo/… など）で見分ける）
  • 索引から消えた文書を結果から除くこと（印を付けて返すだけ。未決 5）
  • 回答が今の法令でも成り立つかを判定すること（legal_status は文書回答事例が個別事案への回答で一般的な法的拘束力を持たないことを示すだけ）

処理の流れ ​

呼び出しを受けてから応答を返すまでに、何をどの順で確かめるかを示します。図の中の番号は「できること」の仕様 ID の末尾 3 桁です。

仕様項目 ​

この機能の仕様項目を、仕様 ID ごとに並べています。見出しは仕様項目を 1 文で表したもので、条件・応答の細部・例は「詳細」を開くと読めます。仕様 ID はそれぞれ受入テストと対応していて、テストの無い ID があると各リポジトリの CI が止まります。

SPEC-NTA-SEARCH-BUNSHOKAITOU-001 文書回答事例が DB に 1 件も無いときは検索できないことをエラーで返す ​

詳細

DB に文書回答事例が 1 件も無いとき（DB のファイルが無い・版の記録が無い・版が合わない・開けないときを含む）は、「該当なし」の検索結果ではなく、エラー DOC_NOT_FOUND を返す。応答に results は付けない。

  • error は「ローカル DB に文書回答事例が 1 件も無いため、検索できません（「該当なし」という結果ではありません）」
  • tool は nta_search_bunshokaitou
  • hint は DB の状態ごとの文（SPEC-NTA-DB-SCHEMA-029。<種別> は 文書回答事例、フラグは --bulk-download-bunshokaitou）。どの文も開こうとした DB のパスを含む
  • next_actions の先頭は action: "cli_bulk_download"、example.command は --bulk-download-bunshokaitou を付けた案内のコマンド（SPEC-NTA-DB-SCHEMA-027）。版が新しい・読めない DB と、開けない DB では入れない（SPEC-NTA-DB-SCHEMA-021・029）
  • 開けない DB では retryable: false と detail.cause も付ける（SPEC-NTA-DB-SCHEMA-029。v0.25.x では SPEC-NTA-COMMON-ERRORS-006 の INTERNAL_ERROR だった）

他の種別の文書（質疑応答事例など）だけが DB にあっても、文書回答事例が無ければこのエラーになる。

例: 環境変数を付けずに起動し（ホームディレクトリが /Users/bonji）、0 バイトの ~/.cache/houki-nta-mcp/cache.db で { keyword: "適格請求書" } を渡すと、hint は ローカル DB（~/.cache/houki-nta-mcp/cache.db）にはまだ何も投入されていません。`npx -y @shuji-bonji/houki-nta-mcp@latest --bulk-download-bunshokaitou` で文書回答事例を投入してください（v0.24.x では MCP サーバーが開いている DB（/Users/bonji/.cache/houki-nta-mcp/cache.db）に文書回答事例（doc_type="bunshokaitou"）が入っていません。…）。

SPEC-NTA-SEARCH-BUNSHOKAITOU-002 税目の範囲に文書が無いときは税目の一覧と投入コマンドを案内する ​

詳細

DB に文書回答事例はあるが、taxonomy で絞った範囲（別表記を含む。SPEC-NTA-SEARCH-BUNSHOKAITOU-003）に 1 件も無いときは、エラーにせず results: [] を返す。

  • hint に、DB の文書回答事例の件数と、taxonomy="<指定した値>" の文書が無いこと、taxonomy を外すか available_taxonomies の値を指定するよう書く
  • available_taxonomies に、DB の文書回答事例が持つ税目の値の一覧を入れる（別表記もそのまま入る）。例: ["souzoku", "sozoku", "zoyo"]
  • 指定した税目が本庁の索引にある税目（shotoku / gensen / joto-sanrin / sozoku / zoyo / hyoka / hojin / shohi / shozei / sonota、またはその別表記）なら、hint の末尾に追加の投入コマンドを書く。コマンドは --bulk-download-bunshokaitou --bunsho-taxonomy=<本庁の表記> を付けた案内のコマンド（SPEC-NTA-DB-SCHEMA-027）。国税局の別表記で指定したときは本庁の表記に直して書く（gensenshotoku → --bunsho-taxonomy=gensen）
  • 本庁の索引に無い値（例: zzz）で指定したときは、投入コマンドは書かない（available_taxonomies は付ける）

例: 環境変数を付けずに起動し、sozoku と zoyo の文書だけがある DB で { keyword: "贈与", taxonomy: "gensenshotoku" } を渡すと、hint の末尾は `npx -y @shuji-bonji/houki-nta-mcp@latest --bulk-download-bunshokaitou --bunsho-taxonomy=gensen` で追加できます（v0.24.x では houki-nta-mcp --bulk-download-bunshokaitou --bunsho-taxonomy=gensen）。

SPEC-NTA-SEARCH-BUNSHOKAITOU-003 税目の別表記をまとめて検索し、その旨を search_notes に書く ​

詳細

国税局のページは本庁と違う税目フォルダ名を使うことがあるので、taxonomy に次の組のどれかの値を指定したときは、同じ組の値を持つ文書をまとめて検索する。組のどちらの値で指定しても結果は同じである。

税目本庁の表記国税局の別表記
相続税sozokusouzoku
源泉所得税gensengensenshotoku
譲渡所得・山林所得joto-sanrinjoto_sanrin
  • 結果の各要素の taxonomy は DB に入っている値のまま（sozoku で検索しても、国税局の文書は souzoku で返る）
  • まとめて検索したときは、search_notes に「taxonomy="sozoku" は、同じ税目の別表記 "souzoku" の文書もまとめて検索しました」という趣旨の 1 行を入れる
  • 別表記の無い税目（例: zoyo）や taxonomy を省いたときは、この行は入れない（他に注記が無ければ search_notes 自体を付けない）
  • キーワードに合う文書が無いとき（SPEC-NTA-SEARCH-BUNSHOKAITOU-004）の hint の件数も、別表記の文書を含めて数える

SPEC-NTA-SEARCH-BUNSHOKAITOU-004 キーワードに合う文書が無いときは件数付きの「該当なし」を返す ​

詳細

DB に文書回答事例があり、taxonomy と hasPdf の範囲にも文書はあるが、キーワードに合うものが無いときは、エラーにせず results: [] を返す。hint は「該当なし。DB の文書回答事例（<絞り込みの条件>）<件数> 件に「<keyword>」に合う文書はありません。別のキーワードで試してください」の形で、件数は絞り込んだ範囲の件数である。

例: taxonomy: "sozoku" で DB に sozoku 1 件・souzoku 1 件があるとき、hint は「該当なし。DB の文書回答事例（taxonomy="sozoku"）2 件に「量子暗号通信」に合う文書はありません。別のキーワードで試してください」。絞り込みを指定しなければ「（…）」の部分は付かず、hasPdf を指定すれば hasPdf=true のように条件に加わる。

SPEC-NTA-SEARCH-BUNSHOKAITOU-005 hasPdf の条件に合う文書が無いときは hasPdf を外すよう案内する ​

詳細

taxonomy の範囲（別表記を含む。taxonomy を省いたときは DB の文書回答事例全体）には文書があるが、hasPdf の条件に合う文書が 1 件も無いときは、エラーにせず results: [] を返す。

  • hint は DB の文書回答事例（taxonomy="<指定した値>"）<件数> 件に、PDF 付きの文書はありません。hasPdf を外して検索してください。hasPdf: false なら「PDF 無しの文書はありません」。taxonomy を省いたときは （taxonomy="…"） の部分を書かない。件数は別表記を含めた taxonomy の範囲の件数
  • keyword と legal_status も付く

SPEC-NTA-SEARCH-BUNSHOKAITOU-002（税目の範囲に文書が無い）に当たるときは、そちらを返す。

SPEC-NTA-SEARCH-BUNSHOKAITOU-006 0 件のときの freshness は、0 件の理由ごとに範囲を変える ​

詳細

0 件のとき（SPEC-NTA-SEARCH-BUNSHOKAITOU-002・004・005）の freshness（形は SPEC-NTA-SEARCH-RULES-017）は、次の範囲で判定する。

  • 税目の範囲に文書が無いとき（002）: DB の文書回答事例全体
  • hasPdf の条件に合う文書が無いとき（005）と、キーワードに合う文書が無いとき（004）: taxonomy で絞った範囲（別表記を含む）。hasPdf では絞らない。taxonomy を省いたときは DB の文書回答事例全体

SPEC-NTA-SEARCH-BUNSHOKAITOU-007 limit は 1 以上 50 以下の整数で、範囲の外は INVALID_ARGUMENT にして丸めない ​

詳細

tools/list の inputSchema の limit は type: "integer"、minimum: 1、maximum: 50 を持つ（SPEC-NTA-COMMON-ERRORS-012）。0・負の数・小数・51 以上・数値でない値を渡すと、inputSchema の検査で INVALID_ARGUMENT（tool: "nta_search_bunshokaitou"、detail.issues[0].path: "limit"）を返し、DB を引かない。1 件や 50 件に丸めたり、切り捨てたりしない。既定の 10 件は変えない。

例: { keyword: "適格請求書", limit: 0 } は code: "INVALID_ARGUMENT"、detail.issues は [{ path: "limit", message: "1 以上で指定してください" }] で、DB は引かない（v0.21.3 では 1 件に丸めていた）。limit: 100 は [{ path: "limit", message: "50 以下で指定してください" }]（v0.21.3 では 50 件）。limit: 2.5 と limit: "10" は 整数で指定してください。limit: 50 は検査を通り、最大 50 件を返す。

SPEC-NTA-SEARCH-BUNSHOKAITOU-008 keyword が空文字・空白だけのときはDBを引かずに INVALID_ARGUMENT を返す ​

詳細

空文字は inputSchema の minLength: 1 の検査（SPEC-NTA-COMMON-ERRORS-013）で止まり、INVALID_ARGUMENT（tool: "nta_search_bunshokaitou"、detail.issues: [{ path: "keyword", message: "空文字は指定できません" }]）を返す。空白（半角スペース・全角スペース・タブ・改行）だけのときは、ツールの処理がDBを引く前に、SPEC-NTA-COMMON-ERRORS-014 の形の INVALID_ARGUMENT（tool: "nta_search_bunshokaitou"、error: "keyword が空です"、detail.issues: [{ path: "keyword", message: "空白だけは指定できません" }]、hint に探したい語を渡すよう書く）を返す。

例: keyword: "" は code: "INVALID_ARGUMENT"・detail.issues[0].message: "空文字は指定できません"。keyword: "　"（全角スペース）と keyword: " \n" は code: "INVALID_ARGUMENT"・error: "keyword が空です"。どれもDBは引かない。

v0.21.3 では空の keyword に results: [] と「該当なし」の hint（SPEC-NTA-SEARCH-BUNSHOKAITOU-004 の形）を返していたが、空の keyword は探していないので、004 の対象から外れる。

実装する人に向けた情報 ​

ここから下は、この機能を実装する人と、仕様の変更を追う人に向けた節です。使い方を知りたいだけなら、読まなくて構いません。

検討中のこと ​

仕様を書き起こしたときに見つかった項目のうち、扱いを Issue で検討しているものです。ここに挙げたことは、今後の版で変わることがあります。開くと、元の仕様書の記述をそのまま読めます。

仕様書の「未決」の節

初版起こしで見つけた、意図か不具合かを人が決める項目です。決まったら「できること」に ID を振るか、specs/changes/ の差分にします。

意図か不具合かの判断が要る項目は houki-nta-mcp の Issue に移し、ここには題と Issue の番号だけを残します。今の振る舞いのままでよくテストが無いだけの項目は、受入テストを書いてから「できること」に ID を振ります。

承認の履歴 ​

この機能の仕様が、いつ、どの変更で承認されたかを新しい順に並べています。各リポジトリの npx spec-ids history nta_search_bunshokaitou と同じ内容です。変更の名前から、変更の理由と前後の振る舞いを書いた文書（GitHub）を開けます。

承認の履歴（11 件）
承認日版変更仕様 PR
2026-10-06v0.26.0ローカル DB を開けないときの読むだけのツールと書き戻すツールの応答、--bulk-download-tax-answer が索引を保存できないときの終わり方（nta #144・#145）#152
2026-10-05v0.25.0ローカル DB の場所を、応答・起動時のログ・--status で確かめられるようにし、保存したタックスアンサーの索引を読めないことをログに残す（nta #138・#137、T6）#142
2026-10-03v0.24.00.22.0 の取り込みで直し漏れた specs/current の文を、取り込んだ本文に合わせる（#123）#132
2026-10-01v0.22.0引数の検査を inputSchema に書き、丸めずに INVALID_ARGUMENT にする（T1）#117
2026-09-27v0.21.1索引から消えた文書の印に、取得系 4 ツールの仕様 ID を振り、検索系 4 ツールのテストを足す#91
2026-09-27v0.21.1絞り込んで 0 件になったときの応答と、freshness の段階に仕様 ID を振る#90
2026-09-27v0.21.1キーワードの扱い（短い語・略称と通称の展開・全角の揃え方）を、検索系 6 ツールの応答として確かめる#86
2026-09-27v0.21.1検索でヒットしたときの応答の形に仕様 ID を振る#85
2026-09-26v0.21.1「未決」のうち判断が要る 45 件を Issue に移す#74
2026-09-26v0.21.1全 14 ツールの spec.md に「処理の流れ」の節を足す#63
2026-09-26—初版#63

関連ページ ​

このページの元になった文書と、あわせて読むページです。

本サイトの内容は調査の出発点であり、法的助言ではありません。個別の事案は資格を持つ専門家に相談してください。免責事項と利用範囲

MIT Licensed | © shuji-bonji