Wipo Pearl

@pipeworx/wipo-pearl

科学、技术和知识产权法律术语——搜索一个术语，即可获取 10 种语言中经验证的对应词条，每个词条都附有可靠性评级、定义语境、使用说明和来源。需要平台密钥，也提供少量免密备用额度。

属于 Pipeworx——一个将 AI Agent 连接到 1843+ 个实时数据源的 MCP 网关。这是一个独立的非官方集成，与上游提供方无关联，未获其认可，也未由其发布。

工具

• pearl_search_terms(term, source_language?, target_languages?, subject_field?, abbreviation?, exact_search?, limit?) — 搜索术语；返回匹配的概念记录（概念 ID、匹配的术语文本、学科领域）。
• pearl_concept(concept_id, lang_code?) — 获取一个概念 ID（来自 pearl_search_terms）对应的完整数据库记录：按语言分组的对应词条，每个词条都附有可靠性评级、定义语境、使用说明和来源。
• pearl_subject_fields() — 其他两个工具可接受的 29 个学科领域代码和 10 个语言代码的参考列表。无需参数。

身份验证

平台密钥（PLATFORM_WIPO_KEY），支持通过 _apiKey 使用自带密钥覆盖。 与大多数平台密钥不同，存储的值是 JSON 字符串 — {"client_id":"...","client_secret":"..."} — 而不是单独的令牌，因为 WIPO Business Partner Portal 签发的是由 client_id/secret 组成的应用凭据，而非单个密钥。每次调用都会对其进行 JSON.parse，并通过 OAuth2 client_credentials 交换获取有效期较短的 Bearer JWT；令牌不会在调用之间缓存。

激活需要通过两道关卡，而非一道——注册应用并不等于能够调用 API。 Business Partner Portal （b2b.wipo.int）会在注册后立即签发 client_id/client_secret，但应用还必须订阅“WIPO Pearl API”产品/计划，且该订阅须经 WIPO 审核批准后才能使用——这并非即时完成，也无法保证获批。如果订阅步骤尚未获批，即使凭据能在 OAuth2 令牌端点正常通过身份验证，调用 Pearl API 本身仍可能收到 403；此工具包的错误消息会明确说明原因，而非笼统地显示“禁止访问”，因此不会让人误以为是我们的服务中断。如果完全没有凭据（平台密钥或自带密钥），调用会回退到 WIPO 自己提供的少量免密额度——其门户说明，注册前“每天可请求 5 次”——这只适用于一次性的冒烟测试，绝不适用于通过共享网关处理生产流量。

数据来源

• 世界知识产权组织（WIPO），WIPO Pearl 术语数据库——涵盖阿拉伯语、中文、英语、法语、德语、日语、韩语、葡萄牙语、俄语和西班牙语的 250,000+ 个经验证术语，横跨 29 个学科领域。

给下一位维护者的说明

• 没有凭据时，两个工具的可访问性并不相同。 pearl_search_terms 底层的搜索路由会对无密钥请求返回实际的 200 响应（受上述“每天 5 次请求”限额限制）。 在构建此工具包期间，每次无密钥尝试调用 pearl_concept 底层详情路由时，均返回了统一的 500 Internal Server Error。该路由似乎需要 OAuth2 凭据；缺少凭据时，上游会抛出错误，而不是返回规范的 401/403。若在没有有效凭据时调用该路由，请预期它会显得“不可用”；实际上并非如此，只是它与同级路由的访问限制不同。
• 无密钥请求限额按调用方 IP 计算，而不是共用一个全局额度——已通过测试确认：从一条网络路径耗尽限额后（返回 429 “Rate limit exceeded! You reached the limit of 5 requests per 1440 minutes”），从另一条出口发出的相同请求仍返回 200。不要因为某条路径的限额已用尽，就认为整个 API 都不可用。
• **产品页面是一个 Gravitee 开发者门户 SPA，其渲染后的 HTML 中不包含端点信息。**实时入口点、OAuth2 令牌端点、完整的请求/响应约定，以及主题字段和语言表格，均来自门户自身的后端 REST API 和文档页面（其 assets/config.json、/apis/<id>、/apis/<id>/pages 以及整个门户的 FAQ 页面）——具体页面请参阅 src/index.ts 文件头。没有专门的主题字段或语言端点；这两张表来自产品自身的“Data Models”文档页面，而非 API 调用，因此 pearl_subject_fields 是静态数据，而不是代理。
• 已认证的 /records/{id} 调用的响应结构是根据产品的 OpenAPI 规范推断得出的，并未通过实测确认——构建此工具包时没有可用的凭据进行测试。如果实际响应与文档所述结构不匹配，pearl_concept 会抛出明确的 upstream_parse 错误（其中会标明 URL 和正文长度），而不会静默返回空结果，因此首次实际调用时就会暴露不匹配问题，不会悄然遗漏。
• 搜索响应中的 hits/count 是 JSON 字符串（"70"，而非 70），尽管规范将它们声明为整数——代码使用 Number() 进行解析。
• 测试发现，上游自身的 limit/count 查询参数并不可靠：两者都未设置的请求返回了完整的命中集（45–70 多条记录），而非规范中声明的默认 5 条。本工具包仍会同时传递这两个参数，并在客户端截断结果，因此无论上游是否遵循其中任一参数，响应大小都有上限。

快速开始

添加到你的 MCP 客户端（Claude Desktop、Cursor、Windsurf 等）：

{
  "mcpServers": {
    "wipo-pearl": {
      "url": "https://gateway.pipeworx.io/wipo-pearl/mcp"
    }
  }
}

此端点实际提供的内容

https://gateway.pipeworx.io/wipo-pearl/mcp 上的 tools/list 会返回上表中的工具，以及 Pipeworx 共享元工具——ask_pipeworx、 discover_tools、search_within、remember/recall 和网关级工具集中的其他工具。因此，你看到的工具数量会多于表格所列：目前，单个工具包端点除了自身工具外，还会列出大约 30 个共享工具。连接的 initialize 响应会说明其确切范围，也是判断当天情况的权威依据。

这是有意为之，并非意外复用了多个工具包。元工具可让范围受限的连接回答此工具包无法涵盖的问题——通过 ask_pipeworx，它可以在整个目录中路由——无需再添加第二个 MCP 服务。目前无法挂载不含这些元工具的工具包端点；如果额外的架构定义耗费的上下文超过路由带来的价值，请连接完整网关，而不是连接多个工具包端点。

或者连接完整的 Pipeworx 网关，直接列出所有工具包的工具，而不只是此工具包的工具：

{
  "mcpServers": {
    "pipeworx": {
      "url": "https://gateway.pipeworx.io/mcp"
    }
  }
}

两个 URL 都会连接到同一个网关和同一批 1843+ 个数据源。唯一的区别是，哪个工具包的工具会被直接列出；无论连接哪个端点，ask_pipeworx 都能访问所有工具。

没有 MCP 客户端？通过 HTTP 调用

curl -X POST https://gateway.pipeworx.io/v1/tools/pearl_search_terms \
  -H 'Content-Type: application/json' \
  -d '{"term":"satellite","limit":5}'

首次调用无需账号。查看任意工具：GET https://gateway.pipeworx.io/v1/tools/pearl_search_terms。查找工具：使用 {"query":"..."} 向 https://gateway.pipeworx.io/v1/tools/search_packs 发送 POST 请求。

独立运行（无需网关账号）

此软件包也可以作为本地 stdio MCP 服务运行——无需 Pipeworx 账号，也无需经由网关往返：

{
  "mcpServers": {
    "wipo-pearl": {
      "command": "npx",
      "args": ["-y", "@pipeworx/mcp-wipo-pearl"]
    }
  }
}

或者直接运行它，确认服务已启动：

npx -y @pipeworx/mcp-wipo-pearl

它通过 stdin/stdout 使用 MCP 协议，并仅针对本工具包的工具响应 initialize/tools/list/tools/call——不包含上方网关连接所添加的任何共享元工具。来源相同，工具相同，但没有 ask_pipeworx 路由。

使用 ask_pipeworx

除了直接调用工具，你也可以用日常语言提问——上方的工具包端点和完整网关都支持此功能：

ask_pipeworx({ question: "your question about Wipo Pearl data" })

网关会选择合适的工具并自动填入参数。

更多信息

• 文档和指南
• pipeworx.io

许可证

MIT