feat(ics2): add ics2_check tool (registerTool + output schema) — EU ICS2 stop-words — v2.9.0

Adds the 22nd tool: ics2_check (EU ICS2 goods-description stop-words checker,
reference only). Proxies the new GET /api/ics2-check so the result + _source come
from REST; registered via registerTool with a full outputSchema + structuredContent
+ a citation derived from the result _source. No binary verdict. server.json +
package.json → 2.9.0; README tool list/count → 22.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: SoapyRED

README.md

@@ -10,14 +10,14 @@
 
 FreightUtils is the neutral freight reference layer for AI agents — authoritative dangerous-goods, customs, location and freight-calculation data an agent can call and cite, from primary sources (ADR 2025 / UNECE, HS 2022 / WCO, IATA-regulated airline prefixes). Neutral by design: no freight to sell and no carrier to push, so an agent can trust it as ground truth regardless of who carries the load.
 
-This [Model Context Protocol](https://modelcontextprotocol.io/) server gives AI agents access to 21 freight calculation and reference tools, covering road, air, and sea freight. Built by a UK ADR-certified freight transport planner.
+This [Model Context Protocol](https://modelcontextprotocol.io/) server gives AI agents access to 22 freight calculation and reference tools, covering road, air, and sea freight. Built by a UK ADR-certified freight transport planner.
 
 **Website:** https://www.freightutils.com
 **API Docs:** https://www.freightutils.com/api-docs
 
 ---
 
-## Tools (21)
+## Tools (22)
 
 ### Calculators
 | Tool | Description |
@@ -44,6 +44,7 @@ This [Model Context Protocol](https://modelcontextprotocol.io/) server gives AI
 | `hs_code_lookup` | 6,940 Harmonized System tariff codes (HS 2022) |
 | `uk_duty_calculator` | UK import duty and VAT (live GOV.UK Trade Tariff data) |
 | `incoterms_lookup` | Incoterms 2020 — all 11 rules with risk/cost transfer points |
+| `ics2_check` | Flag EU ICS2 unacceptable goods-description terms (stop-words) before filing an ENS — reference only |
 
 ### Reference Data
 | Tool | Description |
@@ -138,14 +139,14 @@ You should see three ticks and `All checks passed`:
 ```
 FreightUtils MCP Diagnostic
 ───────────────────────────
-package: freightutils-mcp@2.8.0
+package: freightutils-mcp@2.9.0
 health:  https://www.freightutils.com/api/mcp/health
 
 [1/3] Backend health (https://www.freightutils.com/api/mcp/health)
-      ✓ status=ok mcp_version=2.8.0 tools_registered=21 (143ms)
+      ✓ status=ok mcp_version=2.9.0 tools_registered=22 (143ms)
 
 [2/3] MCP handshake (in-process via InMemoryTransport)
-      ✓ server freightutils-mcp@2.8.0 initialized; tools/list returned 21 tools
+      ✓ server freightutils-mcp@2.9.0 initialized; tools/list returned 22 tools
 
 [3/3] End-to-end tool call (cbm_calculator l=120 w=80 h=100)
       ✓ cbm_calculator → total=0.96 m³ (expected 0.96) (218ms)

package.json

@@ -1,6 +1,6 @@
 {
   "name": "freightutils-mcp",
-  "version": "2.8.0",
+  "version": "2.9.0",
   "mcpName": "io.github.SoapyRED/freightutils",
   "description": "Neutral freight reference and calculation tools for AI agents — ADR dangerous goods, HS codes, airline codes, UN/LOCODE, Incoterms and freight math from authoritative sources.",
   "author": "FreightUtils <contact@freightutils.com>",

server.json

@@ -7,7 +7,7 @@
     "url": "https://github.com/SoapyRED/freightutils-mcp",
     "source": "github"
   },
-  "version": "2.8.0",
+  "version": "2.9.0",
   "remotes": [
     {
       "type": "streamable-http",
@@ -18,7 +18,7 @@
     {
       "registryType": "npm",
       "identifier": "freightutils-mcp",
-      "version": "2.8.0",
+      "version": "2.9.0",
       "transport": {
         "type": "stdio"
       }

src/tools.ts

@@ -832,6 +832,48 @@ Use to confirm a container/AWB/IMO number is well-formed, or to extract identifi
   },
 };
 
+// ─────────────────────────────────────────────────────────────
+//  ICS2 Stop-Words Checker (EU ICS2 goods-description terms)
+//  registerTool with full output schema + structuredContent; proxies
+//  /api/ics2-check so the result + _source come from REST. Reference only.
+// ─────────────────────────────────────────────────────────────
+
+const ics2Check: ToolDef = {
+  name: 'ics2_check',
+  description: `Check a goods description against the official EU ICS2 stop-words list — terms the European Commission deems too vague/generic to be accepted in an entry summary declaration (ENS) goods-description field (data element 18 05 000 000).
+
+Pass description=<goods description>; returns the flagged terms (each with a note: standalone term = automatic rejection, embedded = make the description more specific), a clean boolean, a caveat, and a _source citing the EU list + legal basis.
+
+Use to QA a goods description BEFORE filing an ENS — for customs/documentation teams, brokers, forwarders' documentation side, and agents building filing pipelines. STRICTLY a reference check: NOT an ENS filing, NOT a customs-compliance determination, NOT legal advice. The list is non-exhaustive and updated periodically; clean does NOT guarantee acceptance. No binary accepted/rejected verdict. Distinct from hs_code_lookup (commodity codes) and uk_duty_calculator (duty/VAT).`,
+
+  schema: z.object({
+    description: z.string().describe('The goods description to check against the EU ICS2 stop-words list.'),
+  }).strict(),
+
+  outputSchema: {
+    description: z.string(),
+    flagged: z.array(z.object({ term: z.string(), note: z.string() })),
+    clean: z.boolean(),
+    caveat: z.string(),
+    _source: z.object({
+      type: z.string(), authority: z.string(), dataset: z.string(), legal_basis: z.string(),
+      list_in_force: z.string(), source_url: z.string(), licence: z.string(),
+      retrieved: z.string(), non_exhaustive: z.boolean(), retrieved_via: z.string(),
+    }),
+    disclaimer: z.string(),
+  },
+
+  annotations: readOnlyAnnotations('ICS2 Stop-Words Checker'),
+
+  handler: async (args) => apiGet('ics2-check', { description: args.description }),
+
+  citation: (result: unknown) => {
+    const r = result as { _source?: { authority?: string; legal_basis?: string; list_in_force?: string } };
+    const s = r._source ?? {};
+    return `Source: EU ICS2 stop-words list — ${s.authority ?? 'European Commission DG TAXUD'} (${s.legal_basis ?? 'Commission Delegated Regulation (EU) 2015/2446'}), in force ${s.list_in_force ?? '2026-05-04'} — checked by freightutils.com`;
+  },
+};
+
 // ─────────────────────────────────────────────────────────────
 //  Export all tools
 // ─────────────────────────────────────────────────────────────
@@ -857,5 +899,6 @@ export const ALL_TOOLS: ToolDef[] = [
   vehicleLookup,
   emissionsCalculator,
   identifierValidator,
+  ics2Check,
   getSubscribeLink,
 ];