Tariff Everywhere


各地关税

tariff-everywhere banner

A. 协调关税表 （HTS）查找工具。从美国国际贸易委员会搜索关税代码、税率和产品分类。

四种使用方法：

🌐 直接跳转到web应用程序： https://tariff-everywhere.fly.dev/

______________________________________________________________________

先决条件

Docker（推荐）

所有东西都在容器中运行——你的机器上不需要安装Python。

1. 安装 适用于您的操作系统
2. 验证它是否正在运行：

   docker --version

没有Docker

如果你不想使用Docker，你需要：

• Python 3.12+
• pip（Python自带）

______________________________________________________________________

快速入门（Docker）

1.克隆仓库

git clone https://github.com/francisfuzz/tariff-everywhere.git
cd tariff-everywhere

2.构建Docker镜像

docker build -t hts-local .

这将在容器内安装所有Python依赖项。您只需执行一次（或在拉取更新后再次执行）。

3.下载关税数据

第一次运行从USITC公共API获取所有99章，并将它们存储在本地SQLite数据库中。这大约需要15-20秒，需要互联网连接。

docker run --rm -v "$(pwd)/data:/app/data" hts-local scripts/ingest.py

您应该看到如下输出：

Creating database schema...
Fetching HTS data from all 99 chapters (parallel)...
  Fetched 99 chapters (0 errors)
Inserting data into database...
Loaded 134019 entries across 99 chapters in 7.5s

数据保存到 data/hts.db 在你的机器上。除非您想刷新数据，否则不需要再次运行此程序。

注： 如果再次运行摄取，脚本将跳过重复条目，因此您将看到 Loaded 0 entries 而且 Skipped 134019 duplicates --这是正常的，意味着您的数据库受到保护，不会出现重复。

4.试试看

# Search for products by keyword
docker run --rm -v "$(pwd)/data:/app/data" hts-local hts.py search "copper wire"

# Look up a specific tariff code
docker run --rm -v "$(pwd)/data:/app/data" hts-local hts.py code 7408.11.30

# List all entries in a chapter
docker run --rm -v "$(pwd)/data:/app/data" hts-local hts.py chapter 74

# List all 99 chapters with entry counts
docker run --rm -v "$(pwd)/data:/app/data" hts-local hts.py chapters

# See all available commands
docker run --rm -v "$(pwd)/data:/app/data" hts-local hts.py --help

以下是它在行动中的样子：

CLI demo showing tariff-everywhere search and code lookup commands

每个命令都支持 --json 机器可读输出标志：

docker run --rm -v "$(pwd)/data:/app/data" hts-local hts.py search "titanium" --json

______________________________________________________________________

快速入门（无Docker）

1.克隆并设置虚拟环境

git clone https://github.com/francisfuzz/tariff-everywhere.git
cd tariff-everywhere

python3 -m venv venv
source venv/bin/activate   # On Windows: venv\Scripts\activate
pip install -r requirements.txt

2.下载关税数据

python scripts/ingest.py

3.使用CLI

python hts.py search "copper wire"
python hts.py code 7408.11.30
python hts.py chapter 74
python hts.py chapters

Python库使用

您还可以直接从Python代码中导入HTS查找函数：

from tariff_everywhere import lookup_code, search_hts

entry = lookup_code("7408.11.30")
print(entry["description"], entry["general_rate"])

for result in search_hts("copper wire", limit=5):
    print(result["hts_code"], result["description"])

查看完整 Python API指南 用于设置、返回值结构、错误处理和CSV/JSON导出示例。

______________________________________________________________________

连接到克劳德桌面（MCP服务器）

MCP（模型上下文协议）服务器允许Claude Desktop直接使用HTS数据。配置后，您可以向Claude提出以下问题 _“铜线的关税是多少？”_ 它将从您的本地数据库中查找答案。

注： MCP服务器在您的机器上本地运行（通过Docker）。它不会暴露网络端口，也无法远程访问——您的资费数据在您的设备上保持私密。

先决条件

• 完成 快速开始 上面的步骤（构建映像并下载数据）
• 安装 Claude桌面应用程序

步骤1——找到您的绝对数据路径

Claude Desktop配置需要 绝对路径 给你的 data/ 目录。从repo根目录运行此命令以获取它：

echo "$(pwd)/data"

复制输出——下一步你需要它。它看起来像：

/Users/yourname/projects/tariff-everywhere/data

步骤2--编辑Claude桌面配置

打开Claude Desktop配置文件：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• 窗户： %APPDATA%\Claude\claude_desktop_config.json
• Linux： ~/.config/Claude/claude_desktop_config.json

如果文件不存在，请创建它。添加 hts 服务器条目，替换 /absolute/path/to/tariff-everywhere/data 使用上面复制的路径：

{
  "mcpServers": {
    "hts": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "/absolute/path/to/tariff-everywhere/data:/app/data",
        "hts-local",
        "mcp_server.py"
      ]
    }
  }
}

是否已配置其他MCP服务器？ 添加 "hts": { ... } 阻塞现有的 "mcpServers" object——不要替换整个文件。

步骤3--重新启动克劳德桌面

退出并重新打开Claude Desktop。HTS工具现在应该出现在工具菜单中（聊天输入区域中的锤子图标）。

您应该看到五个可用的工具：

第四步——试试看

在Claude Desktop中开始一个新的对话，并问以下问题：

• _“活马的关税分类是什么？”_
• _“查找HTS代码0101.21.00”_
• _“显示第74章中的所有条目”_
• _“铜箔的税率是多少？”_

Claude将调用相应的HTS工具，并从您当地的数据库中返回关税数据。

故障排除

工具未出现在Claude Desktop中：

• 确保Docker桌面正在运行
• 验证到的绝对路径 data/ 是正确的 data/hts.db 存在
• 检查配置文件中的JSON语法错误（尾随逗号等）
• 更改任何配置后重新启动Claude Desktop

Claude的响应中出现“未找到hts.db”错误：

• 运行摄取步骤： docker run --rm -v "$(pwd)/data:/app/data" hts-local scripts/ingest.py

Docker容器错误：

• 重建映像： docker build -t hts-local .
• 检查Docker是否正在运行： docker ps

______________________________________________________________________

可浏览的Web界面（数据集）

HTS数据库作为实时可搜索的网络应用程序发布在 https://tariff-everywhere.fly.dev/ --无需设置，只需在浏览器中打开即可。

你可以在网页界面上做什么

• 按关键字搜索 --在产品描述中进行全文搜索（例如，“咖啡”、“铜”、“钛”）
• 按章节浏览 --点击章节查看所有关税条目（例如，第74章=“铜及其制品”）
• 精确代码查找 --按HTS代码过滤（例如。， 7408.11.30)
• 导出数据 --将搜索结果下载为CSV或JSON格式
• 全局搜索 --一次搜索全部99章
• 查看价格和规格 --查看每种产品的税率、单位和分类

在本地运行自己的数据集

如果你想在自己的机器上托管接口：

# 1. Build and ingest data (as usual)
docker build -t hts-local .
docker run --rm -v "$(pwd)/data:/app/data" hts-local scripts/ingest.py

# 2. Update chapter titles (real names instead of "Chapter 01")
python3 scripts/chapter_titles.py data/hts.db

# 3. Build the FTS5 search index (must use sqlite-utils for Datasette to detect it)
python3 -m sqlite_utils enable-fts data/hts.db hts_entries description --fts5 --replace

# 4. Serve locally on http://localhost:8321
docker run --rm -p 8321:8321 -v "$(pwd)/data:/app/data" -v "$(pwd)/metadata.json:/app/metadata.json" hts-local \
  -m datasette data/hts.db --metadata metadata.json --port 8321 --host 0.0.0.0 --setting default_page_size 50

然后打开 http://localhost:8321/ 在您的浏览器中。

部署到Fly.io（免费版）

要在Fly.io的免费层上部署自己的实例：

# 1. Install flyctl: https://fly.io/docs/hands-on/install-flyctl/
# 2. Log in: flyctl auth login
# 3. Deploy:

datasette publish fly data/hts.db \
  --app="my-hts-instance" \
  --metadata metadata.json \
  --install=datasette-search-all \
  --install=datasette-render-html \
  --setting default_page_size 50

您的实例将在 https://my-hts-instance.fly.dev/使用Fly.io的始终免费层（2个共享CPU，256 MB RAM），整个部署都是免费的。

______________________________________________________________________

保持数据最新

美国国际贸易委员会定期更新关税表。要检查更新并在数据发生更改时重新下载，请执行以下操作：

# Docker
docker run --rm -v "$(pwd)/data:/app/data" hts-local scripts/refresh.py

# Without Docker
python scripts/refresh.py

如果数据没有改变，你会看到 Already up to date. --否则，它将重新摄取所有99章。

______________________________________________________________________

运行测试

# Docker
docker run --rm hts-local -m pytest tests/ -v

# Without Docker (with venv activated)
python -m pytest tests/ -v

该测试套件使用内存中的SQLite数据库和夹具数据，不需要互联网连接或真实的数据库。

______________________________________________________________________

项目结构

tariff-everywhere/
├── hts.py                  # CLI: search, code, chapter, chapters commands
├── mcp_server.py           # MCP server: 5 tools, local stdio transport only
├── metadata.json           # Datasette config (titles, facets, descriptions)
├── scripts/
│   ├── ingest.py           # Download + load all 99 chapters into SQLite
│   ├── refresh.py          # Check for data updates, re-ingest if changed
│   ├── build_fts.py        # Build FTS5 search index (uses sqlite-utils)
│   ├── chapter_titles.py   # Enrich chapter descriptions with real HTS titles
│   └── hashing.py          # Compute content hashes for change detection
├── tests/
│   ├── conftest.py         # Shared test fixtures
│   ├── test_cli.py         # CLI tests
│   ├── test_mcp.py         # MCP server tests
│   ├── test_build_fts.py   # FTS index tests
│   ├── test_chapter_titles.py  # Chapter title enrichment tests
│   └── test_metadata.py    # Datasette metadata validation
├── data/                   # SQLite database (created by ingest, gitignored)
├── docs/                   # Design docs, Datasette plan
├── Dockerfile
├── requirements.txt
├── CLAUDE.md               # Development guidance for Claude Code
└── README.md               # This file

______________________________________________________________________

许可证

该项目使用来自 美国国际贸易委员会.