@sugukuru/mcp-houjin-bangou 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,86 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+本プロジェクトの変更履歴。`Keep a Changelog` 形式、`Semantic Versioning` 準拠。
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-05-10
+
+### Added (v0.1.1 quality hardening)
+
+- `fast-check` property-based tests
+  - `tests/unit/check-digit.property.test.ts`: 5 properties, 4000 generated cases
+  - `tests/unit/invoice-number.property.test.ts`: 4 properties, 2500 generated cases
+  - `tests/unit/normalizer.property.test.ts`: 5 properties, 5000 generated cases
+- `tinybench` benchmark suite (`pnpm bench`)
+  - check digit validation
+  - invoice number normalization
+  - company name normalization
+  - NTA CSV parser
+- v0.2.0 UI Resources preparation
+  - `src/ui/corporate-card/`
+  - `src/ui/search-results/`
+  - Vite single-file build (`pnpm build:ui`)
+  - CSP hash injection (`pnpm build:csp`)
+  - `ui://corporate-card/mcp-app.html` and `ui://search-results/mcp-app.html` registered as resources
+  - `lookup_corporate_by_number` and `search_corporate_by_name` expose `_meta.ui.resourceUri`
+- Release readiness audit fixes
+  - Server Card and runtime `initialize` capability alignment (`listChanged=true`)
+  - npm Trusted Publishing / GitHub OIDC (removed `NPM_TOKEN` dependency)
+  - CycloneDX SBOM workflow
+
+### Verified
+
+- 2026-05-10: NTA live smoke passed with approved application ID
+  - local validation: `7000012050002` OK
+  - `/4/num`: count=1, first=`7000012050002 国税庁`
+  - `/4/name`: count=2, divide=1/1
+  - result: `NTA live smoke: OK`
+
+### Added (v0.3.0 準備層)
+
+- `src/domain/invoice-number.ts`: T番号 (T+13桁) Branded type + 正規化検証 (全角/半角/ハイフン/小文字T 対応)
+- `src/domain/invoice-codes.ts`: 事業者処理区分 (01/02/03/04/99) + 人格区分 (1/2) + 国内外区分 (1/2/3) + 応答形式 (01/11/21) の辞書
+- `tests/unit/invoice-number.test.ts`: 18 ケース
+- `docs/adr/0012-invoice-api-integration.md`: 適格請求書発行事業者 Web-API 統合計画 (Ver.1.0 仕様差異マトリクス含む)
+- `docs/deployment/nta-application-response.md`: 国税庁 アプリケーションID 発行申請の返信ガイド (Option A/B)
+- `docs/deployment/excel-application-fields.md`: Excel 申請書の完全な埋め込み案
+- `docs/deployment/email-template-option-a.md`: メール返信テンプレート (Option A)
+
+## [0.1.0] - 2026-05-22
+
+### Added
+
+- **MCP 公式 7 機能すべて活性化** (Tools / Prompts / Resources / Resource Templates / Completion / Logging / Pagination)
+- 5 MCP Tools
+  - `lookup_corporate_by_number` (T1): 13桁の法人番号で検索 (国税庁 `/4/num` API、最大10件)
+  - `search_corporate_by_name` (T2): 法人名で検索 (国税庁 `/4/name` API、ページング対応)
+  - `validate_corporate_number` (T3): チェックデジット検証 (ローカル計算、API 不要)
+  - `get_attribution` (T6): 政府標準出典文（公共データ利用規約 第1.0版 + Web-API 機能利用規約 別添1 第6条）
+  - `normalize_company_name` (T7): 国税庁 `target=1` 未対応の7パターン表記揺れ補完
+- 3 MCP Prompts (v0.2.0 予定から前倒し、ADR-0011)
+  - `business-card-to-database`: 名刺OCR → 正規化 → NTA照会 → CRM レコード
+  - `sales-list-enrichment`: 営業リスト一括 enrichment
+  - `customer-master-dedup`: 顧客マスタ重複検知・名寄せ
+- MCP Resources + Resource Templates (`corp://{corporate_number}`, `attribution://houjin-bangou`)
+- MCP Completion (`completion/complete` で会社名の auto-complete、T7 駆動 + Prompt 引数の enum 補完)
+- MCP Logging (`notifications/message`、RFC 5424 severity、機密情報自動 redact)
+- MCP Pagination (opaque cursor、国税庁 `divide`/`divideSize` との変換)
+- Server Card at `/.well-known/mcp.json` (SEP-2127 Draft 先行実装)
+- Streamable HTTP transport (stateless mode)
+- Zod strict schema + `attribution` 必須化 + "When NOT to use" description
+- プロンプトインジェクション防御層 (Rug Pull / Tool Shadowing / Tool Poisoning、6 層)
+- OpenTelemetry W3C TraceContext 対応 (SEP-414 準備層)
+- Application ID redaction + rate limiter (1 RPS + exponential backoff 30s→1m→5m→30m)
+- GitHub Actions: ci / release / codeql / dependency-review / api-health-check (週次 keepalive)
+- 旧字体→新字体 辞書 45+ パターン (髙/齋/﨑/邉/澤/國/團/寳/應/靑/權/氣/專/單/學/樂/...)
+- 3 Prompts 用の動作テストと Completion 補完テスト
+
+### Attribution / 出典
+
+- 国税庁 法人番号 Web-API 機能 Ver.4.0 (政府標準利用規約 = 公共データ利用規約 第1.0版)
+- 国税庁法人番号公表サイト (https://www.houjin-bangou.nta.go.jp/)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sugukuru K.K. (スグクル株式会社)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ja.md

@@ -0,0 +1,196 @@
+# @sugukuru/mcp-houjin-bangou
+
+> **国税庁 法人番号 Web-API を MCP (Model Context Protocol) 経由で使える公式推奨準拠・セキュアなサーバー。**
+> MCP 公式 7 機能すべて活性化 + 名刺OCR等の実務データで使える表記揺れ正規化。
+
+[![npm version](https://img.shields.io/npm/v/@sugukuru/mcp-houjin-bangou.svg)](https://www.npmjs.com/package/@sugukuru/mcp-houjin-bangou)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+🌐 English README: [README.md](README.md)
+
+## これは何か
+
+Claude Desktop / Cursor / VS Code Copilot 等の MCP ホストから、以下が可能になります:
+
+1. **法人番号 (13桁) で検索** — 最大10件カンマ区切り対応
+2. **法人名で検索** — 国税庁内蔵の `target=1` あいまい検索 (ひらがな↔カタカナ・英大小・中点削除) を自動活用
+3. **表記揺れを正規化** — 国税庁の `target=1` が拾えない 7 パターンを補完
+4. **チェックデジット検証** — ローカル計算、API 呼出なし
+5. **出典文取得** — 国税庁 Web-API 利用規約別添1 第6条 + 公共データ利用規約 第1.0版 準拠
+
+5 つの Tool すべてが **Resources / Resource Templates / Completion / Logging / Pagination / Server Card** と統合されています。薄い API ラッパーではなく、MCP 公式 primitive に沿った実装として組んでいます。
+
+## クイックスタート
+
+### 1. 国税庁アプリケーション ID を取得
+
+https://www.invoice-kohyo.nta.go.jp/web-api/pre-reg/ から無料で発行されます (メール経由)。
+
+**重要**: 同じ ID で **適格請求書発行事業者公表システム Web-API** も利用可能です (v0.3.0 でサポート予定)。
+
+### 2. Claude Desktop に追加
+
+`~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "houjin-bangou": {
+      "command": "npx",
+      "args": ["-y", "@sugukuru/mcp-houjin-bangou"],
+      "env": {
+        "NTA_APPLICATION_ID": "あなたのID"
+      }
+    }
+  }
+}
+```
+
+### 3. Claude Desktop を再起動して試す
+
+本番 ID が届いたら、まずローカルで live smoke を実行してください。
+
+```bash
+NTA_APPLICATION_ID=あなたのID pnpm smoke:live
+```
+
+ID はログに出力されません。`/4/num` と `/4/name` の両方を確認します。
+live smoke では、仕様書サンプル番号ではなく、本番 API で実在する法人番号 `7000012050002` を使います。
+
+> 株式会社スグクルの法人番号 5111101000006 の本店所在地と登記日を教えて
+
+> 「（株）高橋商事」の表記揺れを正規化して、国税庁で全候補を検索して
+
+## Tools 一覧
+
+| Tool | 用途 | API | メモ |
+|---|---|---|---|
+| `lookup_corporate_by_number` | 法人番号で検索 | NTA `/4/num` | 最大10件カンマ区切り (仕様準拠) |
+| `search_corporate_by_name` | 法人名で検索 | NTA `/4/name` | ページング・都道府県・法人種別フィルタ |
+| `validate_corporate_number` | チェックデジット検証 | — | ローカル計算、API 呼出なし |
+| `normalize_company_name` | 表記揺れ正規化 | — | 国税庁 `target=1` が拾えない 7 パターン補完 |
+| `get_attribution` | 出典文取得 | — | 利用規約 別添1 第6条 + 公共データ利用規約 第1.0版 |
+
+## 設計姿勢
+
+### MCP 公式 7 機能すべてを活性化
+
+本プロジェクトは MCP 公式 7 機能を使います:
+
+- **Tools** × 5
+- **Prompts** × 3 (`business-card-to-database` / `sales-list-enrichment` / `customer-master-dedup`) — 名刺OCRから CRM 登録、営業リスト一括 enrichment、顧客マスタ重複検知の実務ワークフローをテンプレート化
+- **Resources** (`attribution://houjin-bangou`)
+- **UI Resources** (`ui://corporate-card/mcp-app.html`, `ui://search-results/mcp-app.html`) — v0.2.0 の表示層準備
+- **Resource Templates** (`corp://{corporate_number}` — 法人番号を URI として法人情報取得)
+- **Completion** — `株式会社スグク…` まで打った瞬間に T7 normalizer が候補を返す IDE 補完UX、Prompt 引数の enum 補完も対応
+- **Logging** — RFC 5424 severity の構造化ログを `notifications/message` で配信
+- **Pagination** — 2000件超過時の opaque cursor (国税庁 `divide`/`divideSize` と変換)
+- **Server Card** — `/.well-known/mcp.json` で発見可能性 (SEP-2127 Draft + Transport WG Dec 2025)
+
+### 国税庁 `target=1` あいまい検索を尊重
+
+以下の揺れは、**国税庁 API が既に内蔵**している (第二編 §4.6.2):
+
+- ひらがな → カタカナ
+- 英小文字 → 英大文字
+- 中点 (・) と全角スペースの削除
+
+これらは重複実装しません。代わりに T7 は国税庁が**拾えない** 7 パターンに特化:
+
+1. **(株)/㈱/株式会社/（株）の位置揺れ** — 前株 ↔ 後株 ↔ 省略 の 3 パターン展開
+2. **法人種別の正規化・分離** — 株式・有限・合同・合名・合資・一般社団・特定非営利活動 等
+3. **英語法人名 → 日本語候補** — K.K. / Kabushiki Kaisha / Co.,Ltd. / Inc. / LLC 検出
+4. **半角/全角英数字の正規化** (Unicode NFKC)
+5. **旧字体 → 新字体** (髙→高・齋→斎・﨑→崎 等)
+6. **異体字セレクタ (IVS) 除去**
+7. **空白類の揃え** (タブ・連続スペース・全角/半角)
+
+### セキュリティ First
+
+- **Read-only のみ** — `destructiveHint: false` 全ツール明示
+- **アプリケーション ID は環境変数のみ** — ツール引数経由で受け取らない (プロンプトインジェクション防御)
+- **ログ redaction** — `id=***`, bearer, PII を自動マスク
+- **Rate limit 1 RPS + 指数バックオフ** — 別添1 第9条第1項三号 (短時間大量アクセス禁止) 遵守
+- **プロンプトインジェクション防御 6 層** — 詳細は [`docs/security/prompt-injection-defense.md`](docs/security/prompt-injection-defense.md)
+- **Supply chain**: `pnpm-lock.yaml` コミット / Dependabot weekly / CodeQL / `pnpm publish --provenance`
+
+### 仕様書に準拠、引用可能
+
+- すべての設計決定に国税庁仕様書 (第一編・第二編・第六編) の節番号で根拠を明示
+- MCP 公式仕様 (2025-11-25) + SEP を引用
+- `docs/adr/0001-0010.md` が Michael Nygard 形式で主要決定を記録
+
+## ロードマップ
+
+| バージョン | 予定 | 目玉 |
+|---|---|---|
+| **v0.2.0** | 2026-05 | 5 Tool + MCP 7 機能 + Server Card |
+| v0.2.0 | 2026-06 | MCP **Prompts** (名刺→DB / 営業リストenrichment / 顧客マスタ重複) + UI Resources |
+| v0.3.0 | 2026-07 | **適格請求書発行事業者 API 統合** (T番号対応、`/num` `/diff` `/valid` 3エンドポイント、CSV/XML/**JSON** 対応) — 同じ ID で利用可、v0.2.0 で T番号 Branded type + 正規化は準備済 (ADR-0012) |
+| v0.5.0 | 2026-09 | Hosted 版 + **Enterprise-Managed Authorization** (SEP-990) + **OAuth Client Credentials** + **Tasks** primitive (SEP-1699) |
+| v1.0.0 | 2026-10 | 6-host verification + Anthropic Directory submission + Skills 移行検討 |
+
+## ユースケース: 名刺OCR → CRM 自動登録 (v0.2.0 目玉)
+
+```
+ステップ 1: ユーザーが名刺 OCR テキストを Claude に貼り付け
+ステップ 2: Prompt `business-card-to-database` が以下を実行:
+   normalize_company_name(raw_text)
+   → search_corporate_by_name(candidates[0])
+   → 正確な法人番号・本店住所・法人種別を取得
+ステップ 3: LLM が出典付きで CRM レコードを生成
+ステップ 4: ユーザーがレビュー & DB 投入 (Human-in-the-Loop)
+```
+
+エンタープライズ向けの Document AI 連携・セキュア DB 書込フロー構築は OSS のスコープ外で、スグクル株式会社のプロフェッショナルサービスで対応します。詳細: https://sugukuru.co.jp
+
+## ドキュメント
+
+- [ADR (設計決定記録)](docs/adr/)
+- [プロンプトインジェクション防御](docs/security/prompt-injection-defense.md)
+- [プライバシーポリシー](docs/policy/privacy-policy.md)
+- [利用規約](docs/policy/terms-of-service.md)
+- [セキュリティ](SECURITY.md)
+- [コントリビュートガイド](CONTRIBUTING.md)
+- [行動規範](CODE_OF_CONDUCT.md)
+
+## 検証
+
+本プロジェクトでは、テストとベンチマークも公開インターフェースの一部として扱います。
+
+```bash
+pnpm typecheck
+pnpm test
+pnpm bench
+pnpm publish --dry-run --no-git-checks --access public
+```
+
+現在のローカル検証スナップショット:
+
+| Check | Result |
+|---|---:|
+| Unit + integration tests | 154 passing |
+| Property-based generated cases | 11,500+ |
+| `computeCheckDigit` | 約 18.8M ops/sec |
+| `isValidCheckDigit` | 約 10.1M ops/sec |
+| `normalizeCompanyName` | 約 344k ops/sec |
+| `parseNtaCsv` | 約 389k ops/sec |
+| npm dry-run tarball | 250.6 kB / 151 files |
+
+## 出典
+
+本プロジェクトは **国税庁法人番号システム Web-API 機能** を利用しています。
+
+> **このサービスは、国税庁法人番号システム Web-API 機能を利用して取得した情報をもとに作成しているが、サービスの内容は国税庁によって保証されたものではない。**
+
+出典: **国税庁法人番号公表サイト** (https://www.houjin-bangou.nta.go.jp/)
+ライセンス: **公共データ利用規約 第1.0版**
+API バージョン: **Ver.4.0**
+
+## ライセンス
+
+MIT © 2026 スグクル株式会社 (鹿児島)
+
+## About スグクル
+
+スグクル株式会社は鹿児島のインドネシア人材特定技能 1 号派遣会社です。人事労務・ビザ申請・農業コンプライアンスの AI 化を進めています。本プロジェクトは **Sugukuru OSS Lab** シリーズの 1 本目です。今後 `mcp-jp-subsidy-hub` (補助金統合 MCP)、`mcp-immigration-ja` (入管手続 MCP) 等をリリース予定。

package/README.md

@@ -0,0 +1,198 @@
+# @sugukuru/mcp-houjin-bangou
+
+> **Model Context Protocol server for Japan's National Corporate Number (法人番号) Web-API by the National Tax Agency.**
+> Full activation of all 7 MCP primitives + deterministic company-name normalization for real-world fuzzy data.
+
+[![npm version](https://img.shields.io/npm/v/@sugukuru/mcp-houjin-bangou.svg)](https://www.npmjs.com/package/@sugukuru/mcp-houjin-bangou)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![CI](https://github.com/sugukurukabe/mcp-houjin-bangou/actions/workflows/ci.yml/badge.svg)](https://github.com/sugukurukabe/mcp-houjin-bangou/actions/workflows/ci.yml)
+[![MCP Spec 2025-11-25](https://img.shields.io/badge/MCP-2025--11--25-blue)](https://modelcontextprotocol.io/specification/2025-11-25)
+
+🇯🇵 日本語版 README: [README.ja.md](README.ja.md)
+
+## What this is
+
+An MCP server that lets Claude Desktop, Cursor, VS Code Copilot, and any MCP-compatible client:
+
+1. **Look up** a Japanese corporation by its 13-digit National Corporate Number (up to 10 at once)
+2. **Search** by name with NTA's built-in fuzzy matching (hiragana↔katakana, case, dot deletion auto-handled)
+3. **Normalize** fuzzy company names for the 7 patterns NTA's `target=1` fuzzy search *doesn't* cover
+4. **Validate** check digits locally without consuming API quota
+5. **Attribute** — returns the mandatory citation text per NTA ToS Article 6
+
+All 5 tools come with **MCP Resources**, **Resource Templates** (`corp://{corporate_number}`), **Completion**, **Logging**, **Pagination**, and a **Server Card** at `/.well-known/mcp.json`. The implementation follows the official MCP primitives rather than treating this as a thin API wrapper.
+
+## Quick start
+
+### Claude Desktop
+
+1. Get a free NTA application ID from https://www.invoice-kohyo.nta.go.jp/web-api/pre-reg/ (same ID works for the 適格請求書発行事業者 API too).
+
+2. Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "houjin-bangou": {
+      "command": "npx",
+      "args": ["-y", "@sugukuru/mcp-houjin-bangou"],
+      "env": {
+        "NTA_APPLICATION_ID": "YOUR_ID_HERE"
+      }
+    }
+  }
+}
+```
+
+3. Restart Claude Desktop. Try:
+
+After receiving the NTA application ID, first run the live smoke check locally:
+
+```bash
+NTA_APPLICATION_ID=your-id pnpm smoke:live
+```
+
+The ID is never printed. The command verifies both `/4/num` and `/4/name`.
+The live smoke uses a known real NTA corporate number (`7000012050002`), not the fictional numbers shown in NTA sample documents.
+
+> "株式会社スグクルの法人番号と本店所在地を教えて"
+
+### Cursor / VS Code
+
+See [`examples/`](examples/) for host-specific configs.
+
+## Tools
+
+| Tool | Purpose | API | Notes |
+|---|---|---|---|
+| `lookup_corporate_by_number` | Look up by 13-digit number | NTA `/4/num` | Up to 10 numbers at once (spec-enforced) |
+| `search_corporate_by_name` | Search by company name | NTA `/4/name` | Pagination, prefecture/kind filters, fuzzy/exact/english modes |
+| `validate_corporate_number` | Check digit validation | — | Local, no API call, no quota cost |
+| `normalize_company_name` | Fuzzy name normalization | — | 7 patterns beyond NTA's `target=1` built-in fuzzy |
+| `get_attribution` | Required citation text | — | Per NTA ToS Article 6 + 公共データ利用規約 v1.0 |
+
+## Design stance
+
+### 1. All 7 MCP primitives activated (not just Tools)
+
+The server activates:
+
+- **Tools** × 5 (above)
+- **Prompts** × 3 (`business-card-to-database`, `sales-list-enrichment`, `customer-master-dedup`) — pre-built workflow templates for real-world B2B use cases
+- **Resources** (`attribution://houjin-bangou`)
+- **UI Resources** (`ui://corporate-card/mcp-app.html`, `ui://search-results/mcp-app.html`) — v0.2.0 display layer preparation
+- **Resource Templates** (`corp://{corporate_number}` — fetch a corporation as a resource)
+- **Completion** — type `株式会社スグク…` and get suggestions from T7 normalizer in real-time; prompt argument enum completion also supported
+- **Logging** — structured RFC 5424 severity logs via `notifications/message`
+- **Pagination** — opaque cursors for the 2000+ result case (NTA spec mandates `divide`/`divideSize`)
+- **Server Card** — `/.well-known/mcp.json` per SEP-2127 Draft + Transport WG (Dec 2025) direction
+
+### 2. NTA fuzzy search awareness
+
+We **read the NTA spec §4.6.2** and found that `target=1` already handles:
+
+- hiragana ↔ katakana
+- upper / lower case
+- middle dot (·) / full-width space deletion
+
+…so we skip these. Instead, `normalize_company_name` covers the 7 patterns NTA **doesn't**:
+
+1. `(株)` / `㈱` / `株式会社` / `（株）` position swap (前株 ↔ 後株 ↔ 省略)
+2. Corporate kind classification (株式 / 有限 / 合同 / 合名 / 合資 / 一般社団 / 特定非営利活動)
+3. English → Japanese corp-name mapping (K.K. / Kabushiki Kaisha / Co.,Ltd. / Inc. / LLC)
+4. NFKC normalization (half/full-width alphanumeric)
+5. Old-character → new-character (髙→高, 齋→斎, 﨑→崎, …)
+6. IVS (Ideographic Variation Selectors) removal
+7. Whitespace canonicalization
+
+### 3. Security by design
+
+- **Read-only** — no write/delete/exec tools, `destructiveHint: false` everywhere
+- **Application ID** from env only (never as a tool argument)
+- **Log redaction** of `id=***`, bearer tokens, PII
+- **Rate limit** 1 RPS + exponential backoff (avoids NTA 403 per ToS Article 9.1.3)
+- **Prompt injection defense** layered across 6 levels — see [`docs/security/prompt-injection-defense.md`](docs/security/prompt-injection-defense.md)
+- **Supply chain**: pnpm-lock committed, Dependabot weekly, CodeQL, `pnpm publish --provenance`
+
+### 4. Spec-compliant at every level
+
+- Every design decision cites NTA spec section (第一編・第二編・第六編)
+- Every MCP feature cites its 2025-11-25 spec or SEP
+- `docs/adr/0001-0010.md` records every major decision in Michael Nygard format
+
+## Roadmap
+
+| Version | ETA | Highlights |
+|---|---|---|
+| **v0.2.0** | 2026-05 | 5 tools + 7 primitives + Server Card |
+| v0.2.0 | 2026-06 | MCP **Prompts** (business-card → DB / sales-list enrichment / customer-master dedup) + UI Resources |
+| v0.3.0 | 2026-07 | Integration with **Qualified Invoice Issuer** (T番号) API — same application ID, doubles B2B KYC value |
+| v0.5.0 | 2026-09 | Hosted edition + **Enterprise-Managed Authorization** (SEP-990) + **OAuth Client Credentials** + **Tasks** primitive (SEP-1699) for diff ingestion |
+| v1.0.0 | 2026-10 | 6-host verification + Anthropic Directory submission + Skills (SEP-2076/2640) evaluation |
+
+## Use case: business card OCR → CRM
+
+Planned for v0.2.0 as the flagship MCP Prompt:
+
+```
+Step 1. User pastes business card OCR text into Claude
+Step 2. Prompt `business-card-to-database` invokes:
+   normalize_company_name(raw_text)
+   → search_corporate_by_name(candidates[0])
+   → Returns verified corporate number + address + kind
+Step 3. LLM synthesizes a CRM record with attribution
+Step 4. User reviews & inserts into their DB (HITL)
+```
+
+Enterprise integration (Document AI + secure DB write) is out of scope for the OSS and handled by Sugukuru's professional services — see [Sugukuru Inc.](https://sugukuru.co.jp).
+
+## Documentation
+
+- [Architecture Decision Records](docs/adr/)
+- [Prompt Injection Defense](docs/security/prompt-injection-defense.md)
+- [Privacy Policy](docs/policy/privacy-policy.md)
+- [Terms of Service](docs/policy/terms-of-service.md)
+- [SECURITY](SECURITY.md)
+- [CONTRIBUTING](CONTRIBUTING.md)
+- [CODE OF CONDUCT](CODE_OF_CONDUCT.md)
+
+## Verification
+
+This project treats tests and benchmarks as part of the public interface.
+
+```bash
+pnpm typecheck
+pnpm test
+pnpm bench
+pnpm publish --dry-run --no-git-checks --access public
+```
+
+Current local verification snapshot:
+
+| Check | Result |
+|---|---:|
+| Unit + integration tests | 154 passing |
+| Property-based generated cases | 11,500+ |
+| `computeCheckDigit` | ~18.8M ops/sec |
+| `isValidCheckDigit` | ~10.1M ops/sec |
+| `normalizeCompanyName` | ~344k ops/sec |
+| `parseNtaCsv` | ~389k ops/sec |
+| npm dry-run tarball | 250.6 kB / 151 files |
+
+## Attribution
+
+This project uses the **National Corporate Number System Web-API** provided by the National Tax Agency of Japan.
+
+> **このサービスは、国税庁法人番号システム Web-API 機能を利用して取得した情報をもとに作成しているが、サービスの内容は国税庁によって保証されたものではない。**
+
+Source: **国税庁法人番号公表サイト** (https://www.houjin-bangou.nta.go.jp/)
+License: **公共データ利用規約 第1.0版** (Japanese Public Data License v1.0)
+API Version: **Ver.4.0**
+
+## License
+
+MIT © 2026 Sugukuru K.K. (鹿児島 / Kagoshima, Japan)
+
+## About Sugukuru
+
+Sugukuru Inc. is an Indonesian-specialist human-resource dispatch company in Kagoshima, Japan, sending Specified Skilled Worker (特定技能) staff to farms nationwide. We build AI-enabled backoffice tools for immigration, agriculture, and small-business compliance. This is the first OSS in our **Sugukuru OSS Lab** series. Stay tuned for `mcp-jp-subsidy-hub`, `mcp-immigration-ja`, and more.

package/dist/api/csv-parser.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 国税庁 Web-API Ver.4.0 の CSV レスポンスを JSON 化
+ * Parse NTA Web-API Ver.4.0 CSV responses into JSON
+ *
+ * 根拠 / Source:
+ *   国税庁仕様書 第二編 別紙1 リソース定義書 (36 項目、CSV 順序は同表に準拠)
+ *   レスポンス形式: type=02 (CSV/UTF-8/JIS 第一〜第四水準)
+ *
+ * 1行目: ヘッダー (lastUpdateDate, count, divideNumber, divideSize)
+ * 2行目以降: 法人データ (30列 = 項番7〜36)
+ *
+ * CSVエスケープ:
+ *   - フィールド値はダブルクォーテーション（"）で囲まれる
+ *   - 値内の " は "" にエスケープ
+ */
+import type { Corporation } from '../domain/corporate-number.js';
+export interface NtaResponseHeader {
+    lastUpdateDate: string;
+    count: number;
+    divideNumber: number;
+    divideSize: number;
+}
+export interface ParsedNtaResponse {
+    header: NtaResponseHeader;
+    corporations: Corporation[];
+}
+/**
+ * NTA CSV をパースして構造化
+ *
+ * @param csvText UTF-8 でデコード済みの CSV 本体
+ */
+export declare function parseNtaCsv(csvText: string): ParsedNtaResponse;
+/**
+ * CSV 1行をフィールド配列に分解 (RFC 4180、ダブルクォート + "" エスケープ対応)
+ */
+export declare function parseCsvLine(line: string): string[];
+//# sourceMappingURL=csv-parser.d.ts.map

package/dist/api/csv-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"csv-parser.d.ts","sourceRoot":"","sources":["../../src/api/csv-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAEjE,MAAM,WAAW,iBAAiB;IAChC,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,iBAAiB,CAAC;IAC1B,YAAY,EAAE,WAAW,EAAE,CAAC;CAC7B;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,iBAAiB,CAmC9D;AAQD;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAsCnD"}