NorthData Companion Skill

本技能是通过以下任一方式使用 NorthData API 的最佳实践指南：

1. northdata CLI —— 一款命令行工具，通常在 Claude Code 或终端中使用。
2. NorthData MCP 服务器 —— 一组通过模型上下文协议（Model Context Protocol）暴露的工具，通常在 Claude Desktop / Cursor / 其他 MCP 客户端中使用。

两种接口均基于同一 NorthDataClient 实现，并遵循相同的信用额度保护机制（credit-guard discipline）。请根据当前环境可用性选择其一 —— 本技能同时覆盖两者。

检测可用接口

在做出选择前，请先确认哪些接口可达：

若两者均可用：优先使用 MCP（当运行于支持 MCP 的客户端中时），因其具备更清晰的工具遥测能力与结构化错误；优先使用 CLI（当运行于 Claude Code 或任意以 Shell 驱动的上下文中）。

你必须牢记的唯一规则

NorthData 按返回的公司数量计费，而非按 HTTP 请求次数计费。 单次执行 search --limit 100 最多消耗 100 个信用点。所有计费调用均需通过两级信用额度保护机制：

除非用户明确要求，否则切勿建议提升任一阈值。

默认工作流程（请严格按此顺序执行）

1. 从免费操作开始。 suggest、reference_*、billing 均不消耗信用点。利用它们查找目标公司、确认注册 ID、或检查剩余配额，再决定是否发起计费调用。
2. 对任何计费操作先执行“试运行”（dry-run）。 两种接口均支持 --dry-run（CLI）或 dry_run=true（MCP）。当参数尚不明确时，应首先使用该选项 —— 它将构造请求 URL，但不实际调用 API。
3. 一次 company 调用通常已足够。 它会返回所有者（owners）、法定代表人（representatives）、财务数据（financials）、报表（sheets）、事件（events）及联系方式扩展信息（contact extras）。除非你明确需要股东列表或某人的出生日期，否则无需额外调用 publications 或 person。
4. 关注信用日志。 执行计费调用后，可通过 credits（CLI）或 local_credit_log（MCP）查看本会话已消耗信用点；billing 则显示 NorthData 远程统计的用量。

工具参考

免费工具

计费工具

所有计费工具均支持 --dry-run / dry_run=true。

常见工作流

“查找公司 X 并告诉我它的相关信息”

1. suggest "Company X"（免费）—— 若存在多个匹配项，请从中选择最准确的一个。
2. company --register "<来自 suggest 的 register>" 或 --name "<精确名称>" --city "<城市>"（消耗 1 个信用点）。
3. 完成。所有者、法定代表人、财务数据、报表、事件等信息将在单次响应中一并返回。

“谁拥有或管理公司 X？”

company 在同一响应中即返回 owners（Gesellschafter）和 representatives（Geschäftsführer）。请勿链式调用多个工具 —— 一次 company 调用已完全满足需求。

如需某位特定人员（例如用于继任规划）的出生日期，请追加调用 person --first-name … --last-name … --city …（消耗 1 个信用点）。

“帮我查找符合以下条件的公司”

使用 search（高级搜索）。务必做到：

• 设置 segment_codes（NACE 分类）和 legal_forms —— 无过滤条件的搜索既昂贵又极少实用。
• 保持 limit 值较低（默认为 5）。仅在用户明确授权后方可提高。
• 首次使用时务必加上 --dry-run，以验证参数合理性。
• 地理筛选请组合使用 address 与 max_distance_km。
• 指标筛选：使用 revenue_min/max、earnings_min/max 可在消耗信用点前进一步缩小结果集。

示例（CLI）：

northdata search 
  --segment-codes "62|63" 
  --legal-forms "GmbH|UG" 
  --address "Munich" --max-distance-km 150 
  --revenue-min 5000000 --revenue-max 50000000 
  --limit 5 --dry-run

请先核对生成的 URL，确认无误后再移除 --dry-run 重新执行。

分页请通过上一次响应中的 nextPos 字段提取 pos 令牌实现。

“在消耗信用点前，如何验证一个注册 ID 是否有效？”

suggest 将免费返回标准格式的 register.uniqueKey 和 register.id。随后请将该 register.id 值原样传入 company 的 --register 参数。

“我当前共使用了多少信用点？”

• 远程总计（当前计费周期）：billing
• 仅本会话（本地日志）：credits / local_credit_log

常见陷阱

HTTP 404 "not found" 出现在 company --register 调用中

注册字符串（register string）必须严格匹配 NorthData 的格式。若 "HRB 296816/München" 返回 404，请尝试：

1. 先执行 suggest —— 复制响应中精确的 register.id（例如 "HRB 296816"）和 register.uniqueKey；
2. 退而采用 --name + --city 方式 —— 相比注册号匹配更宽松。

似乎只有 numberOfRequests 统计了唯一调用次数

NorthData 的 billing 接口返回的是每个计费周期内的去重请求数。相同公司、同一天内重复调用不会增加计数。而本地信用日志则记录每一次调用尝试（无论是否重复）。

search 未设置行业分类过滤器

切勿在 segment_codes 和 legal_forms 均为空的情况下执行 search。虽然信用保护机制允许该操作，但其成本/信息价值比极差。务必始终限定搜索范围。

注册字符串中的变音符号（Umlauts）

两种接口均自动完成 URL 编码。你可以直接传入 "München" —— 无需手动进行百分号编码（percent-encoding）。

--approve-high-cost / approve_high_cost=true

仅当用户已明确同意承担更高费用时方可设置。切勿预先设置该标志以“让调用成功”。

环境配置项

当用户遇到问题时

资源

• NorthData API 文档：https://github.com/northdata/api
• CLI 包：northdata-cli/（本仓库）
• MCP 服务器：northdata-mcp/（本仓库）