Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@jp-invoice-check Check this Japanese invoice for required items and per-rate tax rounding mistakes."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An Agent Skill, CLI and MCP server that checks a Japanese qualified invoice (適格請求書): the six required items, reduced-rate marks, totals per rate, and the rule that consumption tax is rounded once per invoice per rate.
Japan's invoice system requires six items on every qualified invoice, and the tax must be rounded once per invoice for each rate, not line by line (NTA pamphlet: 「端数処理は一請求書当たり、税率ごとに1回ずつ」). A language model that writes an invoice tends to compute tax per line and add it up. On the example below that gives 597 yen instead of 599 for the 10% items and 285 instead of 286 for the 8% items.
This package computes instead of guessing:
checks the six items and returns each as true/false (required_items)
recomputes tax per rate for floor, half-up and ceil rounding (the method is the issuer's choice) and tells you which one the invoice used
names the per-line rounding mistake (E_TAX_LINE_ROUNDING) separately from other wrong tax
flags 8% items without a reduced-rate mark, and reduced marks on 10% items
normalizes the registration number (full-width, hyphens) and checks T + 13 digits and the corporate-number check digit
reads ISO dates, 2026年10月28日, 令和8年10月28日, and periods
Every message comes in English and Japanese. Python standard library only. No network. MIT.
Copy this folder into your skills folder (for Claude: ~/.claude/skills/jp-invoice-check/). SKILL.md tells the agent to put the invoice into JSON and run the checker instead of computing tax itself.
Related MCP server: jp-pint-mcp
python -m jpinvoice examples/ok.json # exit 0
python -m jpinvoice examples/line_rounding_mistake.json # exit 1, lists the errors
python -m jpinvoice invoice.json --rounding floor # require one rounding methodfrom jpinvoice import check_invoice, expected_tax
expected_tax(5997, 10) # 599 (exclusive, floor)
expected_tax(1000, 10, "inclusive") # 90
check_invoice(invoice)["errors"] # [{level, code, field, message, message_ja}, ...]{"mcpServers": {"jp-invoice-check": {"command": "python", "args": ["-m", "jpinvoice.server"], "cwd": "/path/to/jp-invoice-check"}}}Tool | Input | Returns |
|
|
|
|
|
|
|
|
|
All tools are read-only.
E_REGNO_MISSING E_REGNO_FORMAT E_ISSUER_NAME_MISSING E_DATE_MISSING E_DATE_INVALID E_ITEMS_MISSING E_ITEM_DESCRIPTION_MISSING E_RATE_INVALID E_REDUCED_NOT_MARKED E_REDUCED_RATE_MISMATCH E_TOTAL_BY_RATE_MISSING E_TOTAL_MISMATCH E_TAX_MISSING E_TAX_LINE_ROUNDING E_TAX_MISMATCH E_BUYER_MISSING; warnings W_REGNO_NORMALIZED W_REGNO_CHECK_DIGIT W_TOTAL_WITHOUT_ITEMS.
Offline. It does not check whether a registration number is registered today; use the NTA publication site for that.
The check digit rule used is the corporate-number rule. For a sole proprietor's number a mismatch is reported only as a warning.
Simplified invoices (適格簡易請求書), return invoices and other special cases are not covered.
This is a checking tool, not tax advice.
Tests: python -m unittest discover -s tests (18 tests)
適格請求書(インボイス)を検査する Agent Skill・コマンド・MCPサーバーです。
記載事項6つ(発行者名と登録番号・取引年月日・取引内容と軽減税率の印・税率ごとの合計と税率・税率ごとの消費税額・買い手の名称)を1つずつ判定
消費税は「1つの請求書につき税率ごとに1回」端数処理。品目ごとに端数処理して足す誤り(AIがよくする)を E_TAX_LINE_ROUNDING で知らせます。切捨て・四捨五入・切上げのどれを使ったかも返します
8%の品目に※などの印がない、10%なのに印がある、を検出
登録番号を整え(全角・ハイフン)、「T+13桁」と法人番号の検査用数字を確認
西暦・和暦(令和・平成)・期間の日付に対応
外部通信なし(登録が今も有効かは国税庁の公表サイトで確認してください)・Python標準ライブラリのみ・MIT。税務の助言ではありません。
Check a Japanese qualified invoice against the six required items of the National Tax Agency (issuer name + registration number, date, description with reduced-rate marks, total per rate, tax per rate, buyer name) and the rounding rule: consumption tax is rounded ONCE per invoice per rate, not per line. Catches the common mistake of summing per-line rounded tax. Input: issuer{name, registration_number}, date, buyer{name}, price_basis (exclusive|inclusive), items[{description, amount, rate 10|8, reduced}], totals[{rate, amount, tax}], optional rounding (floor|half_up|ceil). Returns ok, errors and warnings (code, field, message in English and Japanese), required_items, by_rate (expected tax for each rounding). Offline: it does not check whether the number is currently registered. 適格請求書の6項目と端数処理を検査。
| Name | Required | Description | Default |
|---|---|---|---|
| invoice | Yes | The invoice as described above |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the read-only, idempotent, non-destructive annotations, the description discloses the offline limitation, the specific rounding behavior it enforces, the common mistake it catches, and the structure of returned errors, warnings, required items, and per-rate expected tax. This is substantial behavioral context that annotations alone do not provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core check and then systematically covers required items, rounding, input shape, returns, and the offline limitation. It is dense and useful, though the final Japanese sentence largely repeats the opening purpose and the long parenthetical item list is heavy, so it is not maximally concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex validation tool with no output schema and a nested input object, the description supplies both the domain rules and the return-value structure. It clarifies the offline scope, the six required items, rounding behavior, and output fields, leaving no major operational gap for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema reports 100% description coverage, the top-level schema only describes the invoice object as 'as described above.' The real parameter semantics live in the description, which defines issuer fields, date, buyer, price_basis enum values, items with rate and reduced flag, totals by rate, and optional rounding options. This is essential and adds meaning well beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: checking a Japanese qualified invoice against six required NTA items and the per-rate rounding rule. It explicitly distinguishes itself from registration verification by noting it is offline and does not check whether the registration number is currently valid, which separates it from the jp_invoice_registration_number sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear context for when to use the tool: validating qualified invoice fields and catching the per-line versus per-invoice rounding error. It also clarifies an important exclusion by saying it does not verify current registration status, implicitly routing that need elsewhere. It does not explicitly compare against jp_invoice_tax, so it falls short of full alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Normalize (full-width, spaces, hyphens) and check the format 'T' + 13 digits, and the corporate-number check digit (correct for corporations). Returns normalized, valid_format, corporate_check_digit_ok, messages. Offline: registration status is not checked.
| Name | Required | Description | Default |
|---|---|---|---|
| number | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds real value beyond them: what normalization is applied, that only corporate check digits are correct, exactly which fields come back, and the important limitation that registration status is not verified.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single dense sentence covering normalization, validation, and return fields, followed by the offline caveat. Every clause earns its place and nothing is buried.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, yet the description enumerates the returned fields, so an agent knows what to expect. Only the meaning of 'messages' and failure behavior are left unstated, a minor gap for a single-parameter validator.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% for the single 'number' parameter, so the description must carry it, and it does: accepted input may be full-width, spaced, or hyphenated, and must normalize to 'T' + 13 digits. It stops short of giving an example value or describing the error/message content.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb pair (normalize, check) and a precise resource: 'T' + 13 digits plus the corporate check digit. It is clearly narrower than siblings jp_invoice_check and jp_invoice_tax, but it never names or contrasts them explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the scope statement and the closing caveat 'Offline: registration status is not checked', which hints at when to reach for something else. However, no sibling is named and there is no explicit when-to-use/when-not-to-use routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tax = round(total x rate) once for the whole invoice. price_basis exclusive: total x rate/100; inclusive: total x rate/(100+rate). rounding floor|half_up|ceil (default floor).
| Name | Required | Description | Default |
|---|---|---|---|
| rate | Yes | ||
| amount | Yes | ||
| rounding | No | ||
| price_basis | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely useful behavioral detail beyond that: the exact exclusive vs inclusive formulas and the default rounding mode of floor. It stops short of stating what the response contains.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense clauses, front-loaded with the core formula and then the branch conditions and default. No filler, no repetition of schema enums verbatim, and the default is called out inline.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description must define the return value, and it only implies that the tax figure is returned without saying whether the tax-inclusive total is also included or what type/units to expect. For a pure calculator with no output schema, that leaves a real gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description carries the full burden and mostly does: it explains how rate is applied, what price_basis exclusive/inclusive mean mathematically, and that rounding defaults to floor. Only amount ('total') and the meaning of the 10 vs 8 enum values are left implicit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a concrete computation ('Tax = round(total x rate) once for the whole invoice') for a specific resource, Japanese consumption tax on a single invoice. It is clearly distinguishable from jp_invoice_check and jp_invoice_registration_number, though it never names a verb like 'compute' or 'calculate' explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: the title's 'one rate on one invoice' hints that multi-rate invoices need multiple calls, but the description never says when to use this versus the sibling tools or what the prerequisites are. An agent can infer the context but gets no explicit routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0jp_invoice_checkjp_invoice_registration_numberjp_invoice_taxScored across 3 tools
Each tool has a distinct role: full invoice validation, registration-number format/check-digit validation, and tax calculation. The broad jp_invoice_check overlaps conceptually with the other two because it also considers registration number and rounding, but the descriptions make the intended boundaries mostly clear.
All names use snake_case and the jp_invoice_ prefix, which is predictable and readable. The suffixes are not a strict verb_noun pattern (check vs registration_number/tax), but there is no mixed convention.
Three tools are well-scoped for this narrow domain: full invoice check, registration-number handling, and tax calculation. Each tool earns its place without obvious bloat or thinness.
The set covers core offline invoice validation, registration-number format/check digit, and tax rounding. Minor gaps remain, such as no live registration-status lookup and no dedicated helper for aggregating item totals by rate, but these are stated limitations or workable manually.
Verify Japanese companies, invoice-issuer registrations and addresses against government open data.
Validate EU, UK, AU VAT numbers for AI agents. EU ViDA e-invoicing compliance.
Search Japanese corporations and verify invoice numbers using official National Tax Agency data.
Pay-per-call document and web tools for AI agents: PDF parsing and OCR (Japanese-strong), web and structured extraction, invoice verification, company profiles and PDF utilities. x402 (USDC on Base), no API key; failed calls are never charged.
