MCP Tariff Server

A Model Context Protocol (MCP) server that provides AI assistants with access to international trade and tariff information.

Features

• findCommodity: Search for commodity codes by keyword and receive hierarchical harmonized system codes

Quick Start

Prerequisites

• Node.js 18+ OR Bun 1.0+

Installation

With npm:

npm install

With Bun:

bun install

Configuration

Copy .env.example to .env and configure:

cp .env.example .env

Key environment variables:

• TARIFF_API_URL: Base URL for the external tariff API
• MCP_SERVER_NAME: Name of the MCP server (default: tariff-mcp)
• MCP_SERVER_VERSION: Version of the MCP server

Running the Server

Development Mode

# With npm
npm run dev

# With Bun  
bun run dev

Production Mode

# With npm
npm run build
npm start

# With Bun
bun run build
bun start

MCP Mode (for MCP clients)

# With npm
npm run mcp

# With Bun
bun run mcp

Testing

Run the comprehensive test suite:

# Run all tests
bun test

# Run tests in watch mode
bun test --watch

# Run specific test file
bun test tests/CommodityService.test.ts

# Run with verbose output
bun test --verbose

The test suite includes:

• Unit Tests: Core transformation logic
• Integration Tests: End-to-end API transformation
• Real-world Examples: Actual API response handling

MCP Tool: findCommodity

Search for commodity codes with hierarchical results.

Input Schema

{
  "searchText": "string (required)",
  "countryCode": "string (optional, defaults to 'TR')",
  "languageCode": "string (optional, defaults to 'TR')", 
  "measureType": "string (optional, 'import' or 'export', defaults to 'import')"
}

Example Usage

{
  "name": "findCommodity",
  "arguments": {
    "searchText": "gloves",
    "countryCode": "TR",
    "languageCode": "EN",
    "measureType": "import"
  }
}

Response Format

Returns a hierarchical structure of commodity codes with:

• HS codes at different levels (4, 6, 8, 10 digit)
• Parent-child relationships
• Descriptions and categories
• Leaf node indicators
• Search suggestions

Integration with MCP Clients

Claude Desktop

Add to your MCP configuration:

With Node.js:

{
  "mcpServers": {
    "tariff": {
      "command": "npx",
      "args": ["tsx", "/path/to/tariff-mcp/src/index.ts"],
      "env": {
        "TARIFF_API_URL": "your-api-url"
      }
    }
  }
}

With Bun:

{
  "mcpServers": {
    "tariff": {
      "command": "bun",
      "args": ["/path/to/tariff-mcp/src/index.ts"],
      "env": {
        "TARIFF_API_URL": "your-api-url"
      }
    }
  }
}

Other MCP Clients

The server implements the standard MCP protocol and should work with any compliant MCP client.

Development

Project Structure

src/
├── server.ts          # MCP server implementation
├── index.ts           # Main entry point
├── tools/             # MCP tool implementations
│   └── CommodityLookupTool.ts
├── services/          # Business logic
│   ├── CommodityService.ts
│   └── TariffAPIClient.ts
└── types/             # TypeScript interfaces
    └── index.ts

Building

bun run build

Testing

The server can be tested manually by running it and sending MCP protocol messages via stdin/stdout.

License

ISC