@harmon/mcp

Model Context Protocol (MCP) server for the Harmon customs intelligence API. Wave 2.2 of the Harmon growth plan.

Lets any MCP-compatible client (Claude Desktop, Cursor, etc.) call Harmon's public endpoints as tools:

| Tool | What it does | | ----------------------------------- | ------------------------------------------------------------------------------------------------ | | harmon_estimate_landed_cost | Duty + VAT + total landed cost for a single HS-coded product between two countries. | | harmon_get_customs_data_freshness | Per-source freshness for every customs table Harmon ships (de-minimis, VAT, FTA, ADD/CVD, etc.). |

No API key needed — both tools target the public Harmon endpoints (the same ones documented at withharmon.com/developer). Rate-limited per IP at the server.

Install (Claude Desktop)

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "harmon": {
      "command": "npx",
      "args": ["-y", "@harmon/mcp"],
      "env": {
        "HARMON_API_BASE": "https://withharmon.com/api"
      }
    }
  }
}

Restart Claude Desktop. Ask: "Use Harmon to estimate the duty on a $49.99 cotton T-shirt shipping from the US to Germany under HS 6109100010."

Run locally

cd mcp
npm install      # only if you're hacking on the server itself
npm run build    # transpiles src/ → dist/
HARMON_API_BASE=https://withharmon.com/api node bin/harmon-mcp.js
# the server reads JSON-RPC 2.0 from stdin and writes responses to stdout.

Protocol coverage

Implements the minimal MCP surface:

• initialize (returns serverInfo + capabilities)
• notifications/initialized
• tools/list
• tools/call

This avoids the @modelcontextprotocol/sdk dependency — keeping the install footprint tiny and reducing supply-chain attack surface for a tool that runs locally with the user's network access.

Tests

From the repo root:

npx vitest run mcp/__tests__/

12 unit tests cover argument validation, URL building, JSON-RPC method dispatch, error envelopes, and notification (no-id) handling.

Adding a tool

1. Add a ToolDefinition to TOOL_DEFINITIONS in src/tools.ts.
2. Implement an async handler matching (args, ctx) => Promise<ToolResult>.
3. Register it in TOOL_HANDLERS.
4. Add a test in __tests__/tools.test.ts.

Argument validation is hand-rolled (zod would add ~50KB to the install). Keep validators in tools.ts next to their handler.