potal-mcp-server 1.4.0 → 1.4.1

package/build/index.js

@@ -7,15 +7,15 @@
  * for cross-border purchases across 240 countries and territories.
  *
  * Tools (9):
- *   - calculate_landed_cost: Calculate total cost for international purchases
- *   - classify_product: AI-powered HS code classification
+ *   - calculate_landed_cost: Calculate total cost for international purchases (with 9-field classify support)
+ *   - classify_product: HS code classification via v3.3 GRI pipeline (9-field input)
  *   - check_restrictions: Import restriction & compliance check
- *   - screen_shipment: Comprehensive pre-shipment screening (cost + compliance)
+ *   - screen_shipment: Comprehensive pre-shipment screening (cost + compliance, 9-field classify)
  *   - screen_denied_party: Sanctions/denied-party screening (OFAC SDN + CSL, 21K entries)
  *   - lookup_fta: Free Trade Agreement lookup (63 FTAs)
  *   - list_supported_countries: Get all supported countries with tax info
  *   - generate_document: Generate trade documents (CI/PL/C/O)
- *   - compare_countries: Compare TLC across multiple destination countries
+ *   - compare_countries: Compare TLC across multiple destination countries (with 9-field classify)
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -23,11 +23,11 @@ import { z } from "zod";
 // ─── Configuration ──────────────────────────────────────────
 const POTAL_API_BASE = "https://www.potal.app/api/v1";
 const API_KEY = process.env.POTAL_API_KEY || "";
-const USER_AGENT = "potal-mcp-server/1.3.0";
+const USER_AGENT = "potal-mcp-server/1.4.1";
 // ─── Server Instance ────────────────────────────────────────
 const server = new McpServer({
     name: "potal",
-    version: "1.3.0",
+    version: "1.4.1",
 });
 async function callPotalApi(endpoint, method = "GET", body) {
     const url = `${POTAL_API_BASE}${endpoint}`;
@@ -110,7 +110,8 @@ server.tool("calculate_landed_cost", "Calculate the total landed cost for a prod
     "Returns a detailed breakdown of import duties, VAT/GST, customs fees, and " +
     "the final total price the buyer will pay. Supports 240 countries and territories. " +
     "Includes China CBEC tax, Mexico IEPS, Brazil cascading tax, India IGST, " +
-    "and processing fees for 12 countries.", {
+    "and processing fees for 12 countries. " +
+    "When providing productName for auto-classification, include material for accurate HS code results.", {
     price: z.number().describe("Product price in USD. Example: 49.99"),
     origin: z
         .string()
@@ -132,10 +133,22 @@ server.tool("calculate_landed_cost", "Calculate the total landed cost for a prod
         .string()
         .optional()
         .describe("Name of the product for automatic HS Code classification. Examples: Cotton T-Shirt, Laptop, Running Shoes"),
+    material: z
+        .string()
+        .optional()
+        .describe("Primary material — needed for accurate HS classification. Examples: cotton, leather, steel, polyester, rubber"),
     productCategory: z
         .string()
         .optional()
         .describe("Product category for classification. Examples: electronics, apparel, footwear, accessories, food"),
+    processing: z
+        .string()
+        .optional()
+        .describe("Manufacturing/processing method. Examples: woven, knitted, forged, molded"),
+    composition: z
+        .string()
+        .optional()
+        .describe("Material composition. Example: '100% cotton', '70% polyester 30% cotton'"),
     hsCode: z
         .string()
         .optional()
@@ -151,16 +164,28 @@ server.tool("calculate_landed_cost", "Calculate the total landed cost for a prod
             ],
         };
     }
-    const result = await callPotalApi("/calculate", "POST", {
+    const body = {
         price: params.price,
         origin: params.origin,
         destinationCountry: params.destinationCountry,
-        shippingPrice: params.shippingPrice,
-        zipcode: params.zipcode,
-        productName: params.productName,
-        productCategory: params.productCategory,
-        hsCode: params.hsCode,
-    });
+    };
+    if (params.shippingPrice !== undefined)
+        body.shippingPrice = params.shippingPrice;
+    if (params.zipcode)
+        body.zipcode = params.zipcode;
+    if (params.productName)
+        body.productName = params.productName;
+    if (params.material)
+        body.material = params.material;
+    if (params.productCategory)
+        body.productCategory = params.productCategory;
+    if (params.processing)
+        body.processing = params.processing;
+    if (params.composition)
+        body.composition = params.composition;
+    if (params.hsCode)
+        body.hsCode = params.hsCode;
+    const result = await callPotalApi("/calculate", "POST", body);
     if (!result.success) {
         return {
             content: [
@@ -183,11 +208,19 @@ server.tool("calculate_landed_cost", "Calculate the total landed cost for a prod
     };
 });
 // ─── Tool: classify_product ──────────────────────────────────
-server.tool("classify_product", "Classify a product into an HS (Harmonized System) code for customs. " +
-    "Uses AI-powered classification with keyword matching fallback. " +
-    "Returns HS code, description, chapter, and confidence level.", {
+server.tool("classify_product", "Classify a product into an HS (Harmonized System) code for customs using the v3.3 GRI pipeline. " +
+    "Supports 9-field input for maximum accuracy. material is REQUIRED for the v3.3 pipeline — " +
+    "without it, classification will fail with 400 error. " +
+    "Returns HS code, description, confidence, decision path, and GRI rules applied.", {
     productName: z.string().describe("Product name or description. Example: 'cotton t-shirt', 'laptop computer', 'running shoes'"),
-    productCategory: z.string().optional().describe("Product category hint. Example: 'apparel', 'electronics', 'footwear'"),
+    material: z.string().describe("Primary material — REQUIRED for v3.3 pipeline. Example: 'cotton', 'leather', 'steel', 'polyester', 'rubber', 'wood', 'glass'"),
+    productCategory: z.string().optional().describe("Product category for classification. Example: 'apparel', 'electronics', 'footwear', 'kitchenware', 'toys'"),
+    originCountry: z.string().optional().describe("Country of origin (ISO 2-letter code). Example: 'CN', 'DE', 'US', 'JP'"),
+    description: z.string().optional().describe("Detailed product description for better accuracy. Example: 'Men's woven dress shirt with long sleeves and button front'"),
+    processing: z.string().optional().describe("Manufacturing/processing method. Example: 'woven', 'knitted', 'forged', 'molded', 'printed', 'assembled'"),
+    composition: z.string().optional().describe("Material composition with percentages. Example: '100% cotton', '70% polyester 30% cotton', '18/8 stainless steel'"),
+    weightSpec: z.string().optional().describe("Product weight specification. Example: '500g', '2kg', '150gsm'"),
+    price: z.number().optional().describe("Unit price in USD. Used for price-break HS rules (e.g. 'valued over $X'). Example: 49.99"),
     hsCode: z.string().optional().describe("Known HS code to override classification. Example: '6109.10'"),
 }, async (params) => {
     if (!API_KEY) {
@@ -195,11 +228,27 @@ server.tool("classify_product", "Classify a product into an HS (Harmonized Syste
             content: [{ type: "text", text: "❌ POTAL API key not configured." }],
         };
     }
-    const result = await callPotalApi("/classify", "POST", {
+    const body = {
         productName: params.productName,
-        productCategory: params.productCategory,
-        hsCode: params.hsCode,
-    });
+        material: params.material,
+    };
+    if (params.productCategory)
+        body.category = params.productCategory;
+    if (params.originCountry)
+        body.origin_country = params.originCountry;
+    if (params.description)
+        body.description = params.description;
+    if (params.processing)
+        body.processing = params.processing;
+    if (params.composition)
+        body.composition = params.composition;
+    if (params.weightSpec)
+        body.weight_spec = params.weightSpec;
+    if (params.price !== undefined)
+        body.price = params.price;
+    if (params.hsCode)
+        body.hsCode = params.hsCode;
+    const result = await callPotalApi("/classify", "POST", body);
     if (!result.success) {
         return {
             content: [{ type: "text", text: `❌ Classification failed: ${result.error}` }],
@@ -273,11 +322,15 @@ server.tool("check_restrictions", "Check import restrictions for a product in a
 // ─── Tool: screen_shipment ──────────────────────────────────
 server.tool("screen_shipment", "Comprehensive shipment screening: calculates landed cost, checks restrictions, " +
     "and identifies trade remedies — all in one call. Use this for a complete " +
-    "pre-shipment compliance and cost analysis.", {
+    "pre-shipment compliance and cost analysis. Include material for accurate HS classification.", {
     price: z.number().describe("Product price in USD"),
     origin: z.string().length(2).describe("Origin country ISO2"),
     destinationCountry: z.string().length(2).describe("Destination country ISO2"),
     productName: z.string().describe("Product name for classification"),
+    material: z.string().optional().describe("Primary material — needed for accurate classification. Example: 'cotton', 'steel', 'leather'"),
+    productCategory: z.string().optional().describe("Product category. Example: 'apparel', 'electronics'"),
+    processing: z.string().optional().describe("Processing method. Example: 'woven', 'forged'"),
+    composition: z.string().optional().describe("Material composition. Example: '100% cotton'"),
     shippingPrice: z.number().optional().describe("Shipping cost in USD"),
     hsCode: z.string().optional().describe("Known HS code"),
 }, async (params) => {
@@ -286,16 +339,27 @@ server.tool("screen_shipment", "Comprehensive shipment screening: calculates lan
             content: [{ type: "text", text: "❌ POTAL API key not configured." }],
         };
     }
+    const calcBody = {
+        price: params.price,
+        origin: params.origin,
+        destinationCountry: params.destinationCountry,
+        productName: params.productName,
+    };
+    if (params.material)
+        calcBody.material = params.material;
+    if (params.productCategory)
+        calcBody.productCategory = params.productCategory;
+    if (params.processing)
+        calcBody.processing = params.processing;
+    if (params.composition)
+        calcBody.composition = params.composition;
+    if (params.shippingPrice !== undefined)
+        calcBody.shippingPrice = params.shippingPrice;
+    if (params.hsCode)
+        calcBody.hsCode = params.hsCode;
     // Run calculate and restrictions in parallel
     const [calcResult, restrictResult] = await Promise.all([
-        callPotalApi("/calculate", "POST", {
-            price: params.price,
-            origin: params.origin,
-            destinationCountry: params.destinationCountry,
-            productName: params.productName,
-            shippingPrice: params.shippingPrice,
-            hsCode: params.hsCode,
-        }),
+        callPotalApi("/calculate", "POST", calcBody),
         callPotalApi("/restrictions", "POST", {
             hsCode: params.hsCode || "",
             destinationCountry: params.destinationCountry,
@@ -414,16 +478,27 @@ server.tool("lookup_fta", "Look up Free Trade Agreements between two countries.
         };
     }
     const d = result.data?.data || result.data;
+    const ftaInfo = d.fta || d;
+    const hasFta = ftaInfo.applicable || ftaInfo.hasFta || ftaInfo.hasFTA || false;
     const lines = [
         "## FTA Lookup Result\n",
         `- **Route**: ${params.origin} → ${params.destination}`,
-        `- **FTA Found**: ${d.hasFTA ? '✅ Yes' : '❌ No FTA'}`,
+        `- **FTA Found**: ${hasFta ? '✅ Yes' : '❌ No FTA'}`,
     ];
-    if (d.hasFTA && d.agreements) {
-        for (const fta of Array.isArray(d.agreements) ? d.agreements : [d.agreements]) {
-            lines.push(`- **Agreement**: ${fta.name || fta.agreement || 'N/A'}`);
-            if (fta.preferentialRate !== undefined) {
-                lines.push(`- **Preferential Rate**: ${fta.preferentialRate}%`);
+    if (hasFta) {
+        lines.push(`- **Agreement**: ${ftaInfo.name || d.fta?.name || 'N/A'}`);
+        lines.push(`- **Code**: ${ftaInfo.code || d.fta?.code || 'N/A'}`);
+        if (ftaInfo.preferentialMultiplier !== undefined && ftaInfo.preferentialMultiplier !== null) {
+            const pctReduction = ((1 - ftaInfo.preferentialMultiplier) * 100).toFixed(0);
+            lines.push(`- **Preferential Rate**: ${ftaInfo.preferentialMultiplier === 0 ? 'Duty-free (0%)' : `${pctReduction}% reduction`}`);
+        }
+        if (d.rulesOfOrigin) {
+            lines.push(`\n### Rules of Origin`);
+            lines.push(`- **Certificate Type**: ${d.rulesOfOrigin.certificateType || 'N/A'}`);
+            if (d.rulesOfOrigin.rules?.length) {
+                for (const rule of d.rulesOfOrigin.rules) {
+                    lines.push(`- ${rule.criterion || rule.type}: ${rule.description || rule.note || ''}`);
+                }
             }
         }
     }
@@ -490,8 +565,8 @@ server.tool("generate_document", "Generate trade documents for a shipment: Comme
     }
     const result = await callPotalApi("/documents", "POST", {
         type: args.documentType,
-        exporter: args.exporterName,
-        importer: args.importerName,
+        exporter: { name: args.exporterName, country: args.originCountry },
+        importer: { name: args.importerName, country: args.destinationCountry },
         origin: args.originCountry,
         destination: args.destinationCountry,
         items: [{
@@ -516,11 +591,13 @@ server.tool("generate_document", "Generate trade documents for a shipment: Comme
 // ─── Tool: compare_countries ────────────────────────────────
 server.tool("compare_countries", "Compare Total Landed Cost across multiple destination countries for the same product. " +
     "Useful for finding the cheapest import route or comparing duty rates between countries. " +
-    "Returns a side-by-side comparison of costs.", {
+    "Returns a side-by-side comparison of costs. Include material for accurate classification.", {
     productName: z.string().describe("Product name/description"),
     price: z.number().describe("Product price in USD"),
     originCountry: z.string().describe("Origin/export country (ISO 2-letter code, e.g. 'CN')"),
     destinationCountries: z.array(z.string()).describe("List of destination countries to compare (ISO 2-letter codes, e.g. ['US', 'GB', 'DE', 'JP'])"),
+    material: z.string().optional().describe("Primary material for accurate classification. Example: 'cotton', 'steel'"),
+    productCategory: z.string().optional().describe("Product category. Example: 'apparel', 'electronics'"),
     hsCode: z.string().optional().describe("HS code (6+ digits)"),
     shippingPrice: z.number().optional().describe("Shipping cost in USD (default: 0)"),
 }, async (args) => {
@@ -531,14 +608,20 @@ server.tool("compare_countries", "Compare Total Landed Cost across multiple dest
     }
     const results = [];
     for (const country of args.destinationCountries.slice(0, 10)) {
-        const result = await callPotalApi("/calculate", "POST", {
+        const body = {
             price: args.price,
             shippingPrice: args.shippingPrice || 0,
             origin: args.originCountry,
             destinationCountry: country,
             productName: args.productName,
-            hsCode: args.hsCode || undefined,
-        });
+        };
+        if (args.material)
+            body.material = args.material;
+        if (args.productCategory)
+            body.productCategory = args.productCategory;
+        if (args.hsCode)
+            body.hsCode = args.hsCode;
+        const result = await callPotalApi("/calculate", "POST", body);
         if (result.success && result.data) {
             results.push({ country, data: result.data });
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "potal-mcp-server",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "mcpName": "io.github.soulmaten7/potal",
   "description": "Calculate total landed costs for cross-border commerce. 240 countries, 257M+ tariff records, 131K government tariff schedules, 1.36M product-HS mappings, 63 FTAs, 9-field 100% HS Code accuracy (GRI Pipeline), sanctions screening (21K+ entries). MCP server for Claude, Cursor, and any MCP-compatible AI.",
   "type": "module",