Nhvr Tools

NHVR控制工具

用于澳大利亚重型车辆合规数据的Python SDK、MCP服务器和CLI。

 

nhvrcontrib-tools 让您快速访问疲劳规则、质量限制、尺寸限制、责任链职责、认证指南、许可证、违规类别和NHVR注册查询。

这个项目是一个独立的社区贡献。它不是由NHVR出版、运营或认可的。

HVNL改革说明：NHVR HVNL改革实施页面 修订后的HVNL预计将于2026年年中开始实施。NHVR的HVA过渡常见问题解答称，它正在努力实现 2026年7月1日，须经部长批准。这一转变也逐步用重型车辆认证（HVA）计划取代了NHVAS。

即将到来的 v0.4.0 发布使用：

• 分发名称： nhvrcontrib-tools
• Python导入路径： nhvrcontrib
• CLI命令： nhvr, nhvr-setup

快速开始

选择与您的用例相匹配的最小安装：

剧作家是可选的。基本导入、SDK使用、CLI帮助、CLI知识命令和MCP服务器启动都可以在没有它的情况下工作。

安装

nhvrcontrib-tools 是重命名的包的名称 v0.4.0 释放。如果该版本尚未在PyPI上发布，请从源代码或本地控制盘安装。

从源代码安装

git clone https://github.com/MBemera/nhvrcontrib-tools.git
cd nhvrcontrib-tools
pip install -e ".[dev]"

对于较小的源代码安装：

pip install -e .
pip install -e ".[cli]"
pip install -e ".[mcp]"

从车轮安装

python -m build
pip install dist/nhvrcontrib_tools-0.4.0-py3-none-any.whl

可选剧作家安装

pip install "nhvrcontrib-tools[scraper]"
playwright install chromium

如果缺少Playwright，特定于scraper的命令将返回可读的安装提示，而不是崩溃。

克劳德桌面和MCP

推荐设置

pip install "nhvrcontrib-tools[mcp]"
nhvr-setup

nhvr-setup 检查MCP依赖性，提供可选的Playwright指导，将NHVR API密钥存储在机器凭据管理器中，编写Claude Desktop配置，并验证服务器导入是否正确。

有用的设置命令：

nhvr-setup --help
nhvr-setup --print-config
nhvr-setup --yes --api-key "your-nhvr-api-key"

nhvr-setup 在非交互式shell中是安全的。如果没有stdin，它会打印配置代码段，而不是崩溃或静默覆盖文件。

来源和货币

每个响应都有注释，这样你就可以看到内容来自哪里：

• 内置知识工具返回缓存的摘要，其中包括 source_title, source_url, last_verified，以及 source_type: static_knowledgeMarkdown响应呈现 Source: 带有验证日期的页脚。
• 如果存在可靠的HVNL锚点（例如，责任链的主要职责是 sec.26C)，响应包括a section_reference 和一个 deep_link_url HVNL的昆士兰立法观点。Markdown输出更喜欢深度链接。
• 生活 nhvr_search_regulations 和 nhvr_scrape_page 回应包括 source_type: live_scrape 和一个 scraped_at UTC时间戳，以便调用者可以知道页面何时被提取。
• 当实时抓取失败时，搜索工具会返回一个静态回退，并明确标记为 source_type: static_fallback 和一个 fallback_reason，并且仍然揭示了潜在的起源。

将缓存的响应视为快速定向层。始终根据脚注中链接的当前官方NHVR和HVNL来源核实运营、安全或法律决定。

责任的使用

内置的知识工具返回带有出处脚注的缓存摘要：

• nhvr_get_fatigue_rules
• nhvr_get_mass_limits
• nhvr_get_dimension_limits
• nhvr_get_breach_categories
• nhvr_get_speed_limits
• nhvr_get_cor_duties
• nhvr_get_accreditation_info
• nhvr_get_permit_types
• nhvr_get_hml_info

实时访问工具取决于当前的NHVR系统或实时网络内容：

• nhvr_search_vehicle_registration
• nhvr_search_regulations
• nhvr_scrape_page

对现场端点的访问应在受众范围内，并在您的NHVR API密钥或操作批准发布的用例中进行。注册端点受到监控，旨在用于运营商车队管理，而不是批量提取。

手动克劳德桌面配置

Claude桌面配置路径：

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

使用相同的Python解释器 nhvrcontrib-tools[mcp] 安装：

{
  "mcpServers": {
    "nhvrcontrib-tools": {
      "command": "python3",
      "args": ["-m", "nhvrcontrib.server"]
    }
  }
}

桌面注册查找从计算机凭据管理器读取API密钥。对于CI、Docker或其他非桌面环境，请继续使用 NHVR_API_KEY.

直接运行MCP服务器

# stdio transport
python -m nhvrcontrib.server

# HTTP transport
NHVR_MCP_TRANSPORT=streamable_http \
NHVR_MCP_HOST=0.0.0.0 \
NHVR_MCP_PORT=8080 \
python -m nhvrcontrib.server

可用的MCP工具

命令行界面

安装：

pip install "nhvrcontrib-tools[cli]"

常用命令：

nhvr fatigue rules
nhvr fatigue rules --scheme bfm
nhvr mass limits --include-hml
nhvr mass hml
nhvr dimension limits
nhvr breach categories --type mass
nhvr cor duties --role operator
nhvr accreditation --module fatigue
nhvr permits --type oversize
nhvr rego ABC123
nhvr search "rest breaks"
nhvr --format json fatigue rules

搜索使用别名和轻量级模糊匹配。查询如下 bfm, afm, rest breaks, b-double mass, loader duty, executive due diligence, speed limiter，以及 oversize permits 比普通子字符串匹配更可靠地解析。如果没有强匹配，CLI会建议可能的主题，而不是返回死胡同。

静态标记响应以源页脚、源类型、可用的节引用和验证日期结尾。实时搜索和抓取响应添加了抓取时间戳和源类型行。JSON响应在结构上包含相同的出处字段。

开发包

from nhvrcontrib import NHVR

client = NHVR()

fatigue = client.fatigue_rules("bfm")
mass = client.mass_limits(include_hml=True)
dimensions = client.dimension_limits()
cor = client.cor_duties("operator")
permits = client.permit_types("oversize")

异步方法：

import asyncio
from nhvrcontrib import NHVR

client = NHVR()

rego = asyncio.run(client.search_registration("ABC123"))
search = asyncio.run(client.search("b-double mass"))
page = asyncio.run(client.scrape("https://www.nhvr.gov.au/road-access/mass-and-dimension/mass-limits"))

search_registration() 按以下顺序解析凭据：

1. api_key= 传递给 NHVR(...)
2. NHVR_API_KEY 环境变量
3. 由创建的系统凭据管理器条目 nhvr-setup

码头工人

默认映像运行MCP服务器 mcp 额外安装。它适用于MCP客户端，而不是交互式CLI。

塑造形象：

docker build -t nhvrcontrib-tools .

在标准上运行MCP

当容器直接连接到MCP客户端进程时，使用stdio模式：

docker run --rm -i nhvrcontrib-tools

通过HTTP运行MCP

docker run --rm \
  -p 8080:8080 \
  -e NHVR_MCP_TRANSPORT=streamable_http \
  -e NHVR_MCP_HOST=0.0.0.0 \
  -e NHVR_MCP_PORT=8080 \
  nhvrcontrib-tools

然后将支持MCP的客户端连接到端口 8080.

Docker环境变量

Docker关于报废的说明

默认映像不安装Playwright。这使得容器更小，并允许MCP在不依赖浏览器的情况下启动。特定于刮刀的操作会返回清晰的安装提示，而不是崩溃。

如果你需要在Docker中实时抓取NHVR，可以用以下方式扩展镜像：

pip install "nhvrcontrib-tools[scraper]"
playwright install chromium

您可能还需要基础映像所需的额外Playwright系统包。

故障排除

nhvr-setup 打印配置而不是写入

这通常意味着该命令在没有交互式stdin的情况下运行。跑 nhvr-setup 在普通终端中，或使用 nhvr-setup --yes 明确接受默认提示。

ModuleNotFoundError: fastmcp

额外安装MCP：

pip install "nhvrcontrib-tools[mcp]"

Scraper命令说需要Playwright

安装刮刀支架和浏览器：

pip install "nhvrcontrib-tools[scraper]"
playwright install chromium

注册查询表明需要API密钥

对于Docker、CI或shell的使用：

export NHVR_API_KEY="your-key"

对于桌面使用：

nhvr-setup --api-key "your-key"

或者直接用代码传递：

from nhvrcontrib import NHVR

client = NHVR(api_key="your-key")

搜索找不到主题

使用建议的主题之一，或直接抓取特定的NHVR页面：

nhvr scrape "https://www.nhvr.gov.au/road-access/access-permits"

发展

安装开发环境：

pip install -e ".[dev]"

运行本地检查：

ruff check .
git ls-files -z | xargs -0 detect-secrets-hook --baseline .secrets.baseline
pytest
python -m build
python -m twine check dist/*

数据源

内置知识基于官方NHVR和HVNL材料，包括：

• NHVR网站
• 重型车辆国家法律法规
• HVNL的昆士兰立法观点
• NHVR开发者门户

此存储库仍然是非官方的。始终根据当前的官方消息来源核实操作和法律要求。

许可证

麻省理工学院