hs-code-classifier-mcp 1.0.17 → 1.0.18

package/dist/tools/validate.js

@@ -0,0 +1,104 @@
+import { queryHSPing, AxiosError } from '../services/hsping-client.js';
+import { validateWithAI } from '../services/claude-client.js';
+import { ResponseFormat } from '../schemas/validate.js';
+import { nowISO, LEGAL_DISCLAIMER } from '../constants.js';
+function normalizeHsCode(code) {
+    return code.replace(/[\s.]/g, '');
+}
+function buildMarkdown(out) {
+    const lines = [
+        `## HS Code Validation`,
+        `**Verdict:** ${out.verdict}`,
+        `**HS Code Checked:** ${out.hs_code_checked}`,
+        `**Product Match Score:** ${(out.product_match_score * 100).toFixed(0)}%`,
+        `**Risk Level:** ${out.risk_level}`,
+        out.mismatch_reason ? `**Mismatch Reason:** ${out.mismatch_reason}` : '',
+        out.correct_code_suggestion ? `**Suggested Correct Code:** ${out.correct_code_suggestion}` : '',
+        `**Country:** ${out.country}`,
+        `**Source:** ${out.source} (v${out.version})`,
+        `**Agent Action:** ${out.agent_action}`,
+        `**Checked At:** ${out.checked_at}`
+    ].filter(Boolean);
+    lines.push(`\n---\n*${out._disclaimer}*`);
+    return lines.join('\n');
+}
+export async function runValidate(params) {
+    const normalizedCode = normalizeHsCode(params.hs_code);
+    let hspingData;
+    try {
+        hspingData = await queryHSPing(params.product_description, params.country);
+    }
+    catch (err) {
+        if (err instanceof AxiosError) {
+            return {
+                output: null,
+                error: {
+                    error: `HSPing API error: HTTP ${err.response?.status ?? 'timeout'}`,
+                    likely_cause: 'HSPing API is temporarily unavailable or HSPING_API_KEY is invalid',
+                    agent_action: 'Retry validation once after 30 seconds. If error persists, check status at kordagencies.com.',
+                    category: 'upstream_unavailable',
+                    retryable: true,
+                    retry_after_ms: 30000,
+                    fallback_tool: 'hs_validate_code',
+                    trace_id: Math.random().toString(36).slice(2, 10)
+                }
+            };
+        }
+        return {
+            output: null,
+            error: {
+                error: err instanceof Error ? err.message : String(err),
+                likely_cause: 'Unexpected error querying tariff database',
+                agent_action: 'Retry once. If error persists, contact support at ojas@kordagencies.com.',
+                category: 'upstream_unavailable',
+                retryable: true,
+                retry_after_ms: 120000,
+                fallback_tool: 'hs_validate_code',
+                trace_id: Math.random().toString(36).slice(2, 10)
+            }
+        };
+    }
+    const aiResult = await validateWithAI(normalizedCode, params.product_description, params.country, hspingData.results);
+    const sourceResult = hspingData.results[0];
+    const out = {
+        verdict: aiResult.verdict,
+        agent_action: aiResult.agent_action,
+        hs_code_checked: normalizedCode,
+        product_match_score: aiResult.product_match_score,
+        ...(aiResult.mismatch_reason ? { mismatch_reason: aiResult.mismatch_reason } : {}),
+        ...(aiResult.correct_code_suggestion ? { correct_code_suggestion: aiResult.correct_code_suggestion } : {}),
+        risk_level: aiResult.risk_level,
+        source: sourceResult
+            ? sourceResult.source
+            : 'HSPing API (api.hsping.com) -- no direct match found for product',
+        source_url: 'https://api.hsping.com',
+        version: sourceResult ? sourceResult.version : 'N/A',
+        country: params.country,
+        checked_at: nowISO(),
+        analysis_type: 'AI-powered mismatch detection -- NOT a simple database lookup',
+        token_count: 0,
+        _disclaimer: LEGAL_DISCLAIMER
+    };
+    if (out.verdict === 'MISMATCH') {
+        out.hold_reason = aiResult.mismatch_reason || 'HS code ' + normalizedCode + ' does not match product description in ' + params.country + ' tariff schedule';
+        out.retry_after = null;
+        out.escalation_path = aiResult.correct_code_suggestion
+            ? 'Use suggested code ' + aiResult.correct_code_suggestion + ' instead and verify with customs broker before submitting declaration'
+            : 'Escalate to licensed customs broker to identify correct HS code before submitting declaration';
+    }
+    else if (out.verdict === 'OUTDATED') {
+        out.hold_reason = 'HS code ' + normalizedCode + ' has been updated or reclassified in the ' + params.country + ' tariff schedule';
+        out.retry_after = null;
+        out.escalation_path = aiResult.correct_code_suggestion
+            ? 'Use updated code ' + aiResult.correct_code_suggestion + ' -- verify current classification with customs authority before submitting'
+            : 'Verify current HS code classification with customs authority or broker before submitting declaration';
+    }
+    out.token_count = Math.ceil(JSON.stringify(out).length / 4);
+    return { output: out };
+}
+export function formatValidateResponse(out, format) {
+    if (format === ResponseFormat.MARKDOWN)
+        return buildMarkdown(out);
+    return JSON.stringify(out, null, 2);
+}
+//# sourceMappingURL=validate.js.map

package/dist/tools/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../src/tools/validate.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,YAAY,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,KAAK;IACpB,qBAAqB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC9D,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE;QAC5B,IAAI,EAAE,MAAM,CAAC;QACb,UAAU,EAAE,MAAM,CAAC;QACnB,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,MAAM,CAAC;QAClB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC,CAAC;IACH,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACrH;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,YAAY,GAAG,WAAW,GAAG,WAAW,CAAC;IAClD,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IAC5C,wBAAwB,EAAE,MAAM,CAAC;IACjC,WAAW,CAAC,EAAE,YAAY,EAAE,CAAC;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,GAAG,SAAS,GAAG,UAAU,GAAG,UAAU,CAAC;IACvD,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,UAAU,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,OAAO,CAAC;IACZ,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C,cAAc,EAAE;QAAE,QAAQ,EAAE,OAAO,CAAA;KAAE,CAAC;IACtC,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,SAAS,EAAE,OAAO,EAAE,CAAC;IACrB,OAAO,EAAE,OAAO,EAAE,CAAC;CACpB"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hs-code-classifier-mcp",
-  "version": "1.0.17",
+  "version": "1.0.18",
   "description": "HS code classifier for AI agents. Classifies products to official 6-digit tariff codes before customs declarations or duty calculations. VERIFIED verdict in one call.",
   "type": "module",
   "main": "dist/index.js",